Add playback support and multi-format probing

Extend the default engine to support probing for wav, png, jpeg, and mp4/m4a formats.
Introduce strict validation to allow handling of additional media types without relying solely on file extensions.

Add a new get(Path) alias for probe(Path) to simplify access patterns.

Introduce playback APIs with dry-run behavior and optional desktop-open backend support.

Replace direct stub conversion logic with conversion hub routing.
Add explicit unsupported-route errors and include a temporary wav<->pcm stub path.

Update facade and fixture-based tests to cover probing, validation, playback, and conversion route behavior.
Refresh README documentation to reflect updated features and current limitations.

BREAKING CHANGE: CodecMediaEngine now requires implementations for get(Path) and play(Path, PlaybackOptions) in custom engines.

Author: TamKungZ

README.md

@@ -1,24 +1,43 @@
 # CodecMedia
 
-CodecMedia is a Java library for media probing, validation, metadata sidecar persistence, audio extraction, and file conversion workflows.
+CodecMedia is a Java library for media probing, validation, metadata sidecar persistence, audio extraction, playback workflow simulation, and conversion routing.
+
+<p align="center">
+  <img src="https://www.tamkungz.me/assets-image/CodecMedia_Full_Logo.png" width="70%" alt="CodecMedia Logo">
+</p>
 
 ## Features
 
-- Media probing facade via `CodecMedia.createDefault()`
-- MP3 frame parsing support
-- OGG/Vorbis page parsing support
-- Validation with size limits and strict parser checks for MP3/OGG
+- Media engine facade via `CodecMedia.createDefault()`
+- Probing support for:
+  - MP3
+  - OGG/Vorbis
+  - WAV (RIFF/WAVE)
+  - PNG
+  - JPEG
+  - MP4 (basic ISO BMFF parsing)
+- Validation with size limits and strict parser checks for MP3/OGG/WAV/PNG/JPEG/MP4
 - Metadata read/write with sidecar persistence (`.codecmedia.properties`)
-- In-Java audio extraction and conversion file operations (no external tools required)
+- In-Java extraction and conversion file operations (no external transcoder required for current stub flows)
+- Playback API with dry-run support and optional desktop-open backend
+- Conversion hub routing with explicit unsupported routes and a stub `wav <-> pcm` path
 
 ## API Behavior Summary
 
-- `probe(input)`: detects media/container characteristics and stream info for supported formats.
-- `readMetadata(input)`: returns derived probe metadata plus sidecar metadata entries when present.
+- `get(input)`: alias of `probe(input)` for convenience.
+- `probe(input)`: detects media/container characteristics and returns technical stream info for supported formats.
+- `readMetadata(input)`: returns derived probe metadata plus sidecar entries when present.
 - `writeMetadata(input, metadata)`: validates and writes metadata to a sidecar properties file next to the input.
 - `extractAudio(input, outputDir, options)`: validates audio input and writes extracted output into `outputDir`.
-- `convert(input, output, options)`: writes conversion output and enforces `overwrite` behavior.
-- `validate(input, options)`: validates existence, max size, and optionally strict parser-level checks.
+- `convert(input, output, options)`: performs routed conversion behavior and enforces `overwrite` handling.
+- `play(input, options)`: supports dry-run playback and optional system default app launch.
+- `validate(input, options)`: validates existence, max size, and optional strict parser-level checks.
+
+## Notes and Limitations
+
+- Current probing focuses on **technical media info** (mime/type/streams/basic tags).
+- `readMetadata` currently uses sidecar metadata persistence; it is **not** a full embedded tag extractor (for example ID3 album art/APIC).
+- Current audio-to-audio conversion is mostly unsupported except a temporary stub copy route for `wav <-> pcm`.
 
 ## Requirements
 
@@ -31,21 +50,29 @@ CodecMedia is a Java library for media probing, validation, metadata sidecar per
 mvn clean test
 ```
 
-## Play/Probe Fixture Test
+## Fixture-Driven Tests
 
-The repository includes a fixture-driven test that probes real audio files under `src/test/resources`:
+Fixtures are in `src/test/resources`, including:
 
 - `c-major-scale_test_ableton-live.wav`
 - `c-major-scale_test_audacity.mp3`
 - `c-major-scale_test_ffmpeg.ogg`
 - `c-major-scale_test_web-convert_mono.mp3`
+- `mp4_test.mp4`
+- `png_test.png`
 
-Run only this test:
+Run probe fixture test only:
 
 ```bash
 mvn -Dtest=CodecMediaPlayTest test
 ```
 
+Run facade-focused tests only:
+
+```bash
+mvn -Dtest=CodecMediaFacadeTest test
+```
+
 ## Full Test Suite
 
 ```bash

src/main/java/me/tamkungz/codecmedia/CodecMediaEngine.java

@@ -4,23 +4,102 @@
 import me.tamkungz.codecmedia.model.ConversionResult;
 import me.tamkungz.codecmedia.model.ExtractionResult;
 import me.tamkungz.codecmedia.model.Metadata;
+import me.tamkungz.codecmedia.model.PlaybackResult;
 import me.tamkungz.codecmedia.model.ProbeResult;
 import me.tamkungz.codecmedia.model.ValidationResult;
 import me.tamkungz.codecmedia.options.AudioExtractOptions;
 import me.tamkungz.codecmedia.options.ConversionOptions;
+import me.tamkungz.codecmedia.options.PlaybackOptions;
 import me.tamkungz.codecmedia.options.ValidationOptions;
 
+/**
+ * Core media engine contract used by {@link CodecMedia}.
+ * <p>
+ * The current default implementation focuses on practical probing/validation workflows and
+ * light-weight conversion routing. For richer embedded metadata (for example MP3 album cover/APIC),
+ * callers should treat {@link #probe(Path)} output as technical media info rather than full tag extraction.
+ */
 public interface CodecMediaEngine {
 
+    /**
+     * Convenience alias of {@link #probe(Path)}.
+     *
+     * @param input media file path
+     * @return probe result describing detected media characteristics
+     * @throws CodecMediaException when probing fails
+     */
+    ProbeResult get(Path input) throws CodecMediaException;
+
+    /**
+     * Detects media format and returns technical stream/container information.
+     *
+     * @param input media file path
+     * @return probe result containing mime, extension, media type, streams, and basic tags
+     * @throws CodecMediaException when the file is missing or parsing fails
+     */
     ProbeResult probe(Path input) throws CodecMediaException;
 
+    /**
+     * Reads metadata associated with the file.
+     * <p>
+     * In the default stub implementation this reads sidecar metadata plus base probe fields,
+     * not full embedded tag catalogs for every format.
+     *
+     * @param input media file path
+     * @return metadata entries
+     * @throws CodecMediaException when reading fails
+     */
     Metadata readMetadata(Path input) throws CodecMediaException;
 
+    /**
+     * Writes metadata associated with the file.
+     * <p>
+     * In the default stub implementation this writes a sidecar properties file.
+     *
+     * @param input media file path
+     * @param metadata metadata entries to persist
+     * @throws CodecMediaException when validation or writing fails
+     */
     void writeMetadata(Path input, Metadata metadata) throws CodecMediaException;
 
+    /**
+     * Extracts audio from an input media file into the given output directory.
+     *
+     * @param input source media file
+     * @param outputDir target directory for extracted output
+     * @param options extraction options; implementation defaults may be used when {@code null}
+     * @return extraction result describing output file and format
+     * @throws CodecMediaException when extraction is unsupported or fails
+     */
     ExtractionResult extractAudio(Path input, Path outputDir, AudioExtractOptions options) throws CodecMediaException;
 
+    /**
+     * Converts media according to the requested options.
+     *
+     * @param input source media file
+     * @param output output media file path
+     * @param options conversion options; implementation defaults may be used when {@code null}
+     * @return conversion result
+     * @throws CodecMediaException when route is unsupported or conversion fails
+     */
     ConversionResult convert(Path input, Path output, ConversionOptions options) throws CodecMediaException;
 
+    /**
+     * Starts playback/viewing for supported media.
+     *
+     * @param input source media file
+     * @param options playback options controlling dry-run and external app behavior
+     * @return playback result including backend and started status
+     * @throws CodecMediaException when playback cannot be started
+     */
+    PlaybackResult play(Path input, PlaybackOptions options) throws CodecMediaException;
+
+    /**
+     * Validates file existence and optional strict format constraints.
+     *
+     * @param input media file path
+     * @param options validation options; implementation defaults may be used when {@code null}
+     * @return validation result with warnings/errors
+     */
     ValidationResult validate(Path input, ValidationOptions options) throws CodecMediaException;
 }