Add wav info metadata and sampled playback

read and write embedded RIFF LIST/INFO tags for wav inputs in the
engine metadata flow, while keeping sidecar metadata for non-wav files.
this improves metadata persistence consistency for wav files.

route wav/aiff-family playback through an internal java sampled backend
before optional desktop-open fallback to reduce reliance on external
app integration and improve playback behavior.

add regression tests for wav metadata round-trip and playback routing,
and update docs/changelog plus project version to 1.1.4

Author: TamKungZ

CHANGELOG.md

@@ -5,21 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.1.4] - 2026-03-16
+## [1.1.4] - 2026-03-17
+
+### Added
+- Added WAV embedded metadata round-trip handling (RIFF `LIST/INFO`) in [`WavParser`](src/main/java/me/tamkungz/codecmedia/internal/audio/wav/WavParser.java) and engine metadata flow in [`StubCodecMediaEngine`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java).
+- Added internal Java sampled playback route (`java-sampled`) for WAV/AIFF-family playback in [`StubCodecMediaEngine`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java).
+- Added playback routing regression coverage in [`StubCodecMediaEnginePlaybackRoutingTest`](src/test/java/me/tamkungz/codecmedia/internal/StubCodecMediaEnginePlaybackRoutingTest.java).
 
 ### Changed
 - Replaced temporary WAV/PCM stub converter with production path via [`WavPcmConverter`](src/main/java/me/tamkungz/codecmedia/internal/convert/WavPcmConverter.java), including real `wav -> pcm` data-chunk extraction and `pcm -> wav` container wrapping.
 - Updated conversion hub wiring in [`DefaultConversionHub`](src/main/java/me/tamkungz/codecmedia/internal/convert/DefaultConversionHub.java) to route WAV/PCM through the renamed real converter.
 - Added preset-driven PCM->WAV parameter parsing in [`WavPcmConverter.parsePcmWavParams()`](src/main/java/me/tamkungz/codecmedia/internal/convert/WavPcmConverter.java) supporting `sr=`, `ch=`, and `bits=`.
 - Updated facade regression behavior in [`CodecMediaFacadeTest`](src/test/java/me/tamkungz/codecmedia/CodecMediaFacadeTest.java) to assert real re-encode behavior and preset-based output stream properties for WAV/PCM route.
+- Updated metadata behavior to use embedded WAV `LIST/INFO` read/write for WAV inputs while keeping sidecar (`.codecmedia.properties`) persistence for non-WAV formats in [`StubCodecMediaEngine`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java).
+- Updated playback behavior in [`CodecMediaEngine.play()`](src/main/java/me/tamkungz/codecmedia/CodecMediaEngine.java) implementation path to prioritize internal Java sampled playback for WAV/AIFF family before desktop-open fallback.
 
 ### Fixed
 - Added defensive bounds checks for little-endian reads in [`WavPcmConverter.readLeInt()`](src/main/java/me/tamkungz/codecmedia/internal/convert/WavPcmConverter.java) and [`WavPcmConverter.readLeUnsignedShort()`](src/main/java/me/tamkungz/codecmedia/internal/convert/WavPcmConverter.java).
 - Added WAV `fmt ` validation before payload extraction in [`WavPcmConverter.extractWavDataChunk()`](src/main/java/me/tamkungz/codecmedia/internal/convert/WavPcmConverter.java), rejecting non-PCM WAV payload extraction.
 - Hardened chunk traversal and container construction against arithmetic overflow in [`WavPcmConverter.extractWavDataChunk()`](src/main/java/me/tamkungz/codecmedia/internal/convert/WavPcmConverter.java) and [`WavPcmConverter.wrapPcmAsWav()`](src/main/java/me/tamkungz/codecmedia/internal/convert/WavPcmConverter.java).
+- Fixed WAV metadata flow so write/read operations no longer rely on sidecar-only behavior for WAV files, improving in-file metadata persistence consistency.
+- Fixed playback routing so WAV/AIFF-family inputs no longer depend solely on desktop integration when internal sampled playback is available.
 
 ### Verified
 - Confirmed facade regression coverage with `mvn -Dtest=CodecMediaFacadeTest test`.
+- Confirmed WAV metadata parser behavior with `mvn -Dtest=WavParserTest test`.
+- Confirmed engine metadata and playback routing behavior with `mvn -Dtest=CodecMediaFacadeTest,StubCodecMediaEnginePlaybackRoutingTest test`.
 
 ## [1.1.3] - 2026-03-16
 

README.md

@@ -6,7 +6,7 @@
 [![Java](https://img.shields.io/badge/Java-17%2B-ED8B00?logo=openjdk&logoColor=white)](https://openjdk.org/)
 [![Maven](https://img.shields.io/badge/Maven-3.9%2B-C71A36?logo=apachemaven&logoColor=white)](https://maven.apache.org/)
 
-CodecMedia is a Java library for media probing, validation, metadata sidecar persistence, audio extraction, playback workflow simulation, and conversion routing.
+CodecMedia is a Java library for media probing, validation, metadata persistence (embedded LIST/INFO for WAV and sidecar for non-WAV), audio extraction, playback workflow handling, and conversion routing.
 
 
 <p align="center">
@@ -39,28 +39,28 @@ CodecMedia is a Java library for media probing, validation, metadata sidecar per
   - WebM (EBML container parsing)
 - Validation with size limits and strict parser checks for MP3/OGG/WAV/AIFF/FLAC/PNG/JPEG/WebP/BMP/TIFF/HEIC/HEIF/AVIF/MOV/MP4/WebM
 - MOV/MP4/WebM probe tags now include richer video metadata when present (for example `displayAspectRatio`, `bitDepth`, `videoBitrateKbps`, `audioBitrateKbps`)
-- Metadata read/write with sidecar persistence (`.codecmedia.properties`)
+- Metadata read/write with embedded WAV LIST/INFO support and sidecar persistence (`.codecmedia.properties`) for non-WAV inputs
 - In-Java extraction and conversion file operations
 - Image-to-image conversion in Java for: `png`, `jpg`/`jpeg`, `webp`, `bmp`, `tif`/`tiff`, `heic`/`heif`/`avif`
-- Playback API with dry-run support and optional desktop-open backend
+- Playback API with dry-run support, internal Java sampled backend for WAV/AIFF family, and optional desktop-open fallback
 - Conversion hub routing with explicit unsupported routes and a real `wav <-> pcm` path (`WAV -> PCM` data-chunk extraction, `PCM -> WAV` wrapping)
 
 ## API Behavior Summary
 
 - `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.
+- `readMetadata(input)`: returns derived probe metadata plus embedded LIST/INFO tags for WAV, and sidecar entries for non-WAV when present.
+- `writeMetadata(input, metadata)`: validates and writes embedded LIST/INFO tags for WAV, and writes a sidecar properties file next to non-WAV inputs.
 - `extractAudio(input, outputDir, options)`: validates audio input and writes extracted output into `outputDir`.
 - `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.
+- `play(input, options)`: supports dry-run playback, routes WAV/AIFF-family playback through an internal Java sampled backend, and falls back to 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).
 - Probe routing now performs a lightweight header-prefix sniff before full decode to reduce unnecessary full-file reads for clearly unsupported/unknown inputs.
-- `readMetadata` currently uses sidecar metadata persistence; it is **not** a full embedded tag extractor (for example ID3 album art/APIC).
+- `readMetadata` supports embedded LIST/INFO for WAV plus sidecar metadata persistence for non-WAV inputs; it is **not** a full embedded tag extractor for other formats (for example ID3 album art/APIC).
 - Audio-to-audio conversion is not implemented yet for general real transcode cases (for example `mp3 -> ogg`).
 - The currently implemented audio route is `wav <-> pcm`:
   - `wav -> pcm`: extracts raw PCM payload from WAV `data` chunk

pom.xml

@@ -7,7 +7,7 @@
 
   <groupId>me.tamkungz.codecmedia</groupId>
   <artifactId>codecmedia</artifactId>
-  <version>1.1.3</version>
+  <version>1.1.4</version>
   <packaging>jar</packaging>
 
   <name>CodecMedia</name>

src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java

@@ -14,6 +14,13 @@
 import java.util.Properties;
 import java.util.TreeMap;
 
+import javax.sound.sampled.AudioInputStream;
+import javax.sound.sampled.AudioSystem;
+import javax.sound.sampled.Clip;
+import javax.sound.sampled.LineEvent;
+import javax.sound.sampled.LineUnavailableException;
+import javax.sound.sampled.UnsupportedAudioFileException;
+
 import me.tamkungz.codecmedia.CodecMediaEngine;
 import me.tamkungz.codecmedia.CodecMediaException;
 import me.tamkungz.codecmedia.internal.audio.aiff.AiffCodec;
@@ -76,7 +83,23 @@ public final class StubCodecMediaEngine implements CodecMediaEngine {
 
     private static final long STRICT_VALIDATION_MAX_BYTES = 32L * 1024L * 1024L;
     private static final int PROBE_PREFIX_BYTES = 128 * 1024;
-    private final ConversionHub conversionHub = new DefaultConversionHub();
+    private final ConversionHub conversionHub;
+    private final JavaSampledPlaybackBackend javaSampledPlaybackBackend;
+    private final DesktopPlaybackBackend desktopPlaybackBackend;
+
+    public StubCodecMediaEngine() {
+        this(new DefaultConversionHub(), new JdkJavaSampledPlaybackBackend(), new AwtDesktopPlaybackBackend());
+    }
+
+    StubCodecMediaEngine(
+            ConversionHub conversionHub,
+            JavaSampledPlaybackBackend javaSampledPlaybackBackend,
+            DesktopPlaybackBackend desktopPlaybackBackend
+    ) {
+        this.conversionHub = conversionHub;
+        this.javaSampledPlaybackBackend = javaSampledPlaybackBackend;
+        this.desktopPlaybackBackend = desktopPlaybackBackend;
+    }
 
     @Override
     public ProbeResult get(Path input) throws CodecMediaException {
@@ -570,6 +593,17 @@ public Metadata readMetadata(Path input) throws CodecMediaException {
         entries.put("extension", probe.extension());
         entries.put("mediaType", probe.mediaType().name());
 
+        if ("wav".equals(normalizeExtension(probe.extension()))) {
+            try {
+                Map<String, String> wavInfo = WavParser.readInfoMetadata(Files.readAllBytes(input));
+                for (Map.Entry<String, String> infoEntry : wavInfo.entrySet()) {
+                    entries.putIfAbsent(infoEntry.getKey(), infoEntry.getValue());
+                }
+            } catch (IOException e) {
+                throw new CodecMediaException("Failed to read WAV metadata: " + input, e);
+            }
+        }
+
         Path sidecar = metadataSidecarPath(input);
         if (Files.exists(sidecar)) {
             Properties properties = new Properties();
@@ -602,6 +636,18 @@ public void writeMetadata(Path input, Metadata metadata) throws CodecMediaExcept
             }
         }
 
+        String extension = normalizeExtension(extractExtension(input));
+        if ("wav".equals(extension)) {
+            try {
+                byte[] wavBytes = Files.readAllBytes(input);
+                byte[] withMetadata = WavParser.writeInfoMetadata(wavBytes, metadata.entries());
+                Files.write(input, withMetadata);
+                return;
+            } catch (IOException e) {
+                throw new CodecMediaException("Failed to write WAV metadata: " + input, e);
+            }
+        }
+
         Path sidecar = metadataSidecarPath(input);
         Properties properties = new Properties();
         Map<String, String> sorted = new TreeMap<>(metadata.entries());
@@ -699,15 +745,38 @@ public PlaybackResult play(Path input, PlaybackOptions options) throws CodecMedi
             return new PlaybackResult(true, "dry-run", probe.mediaType(), "Playback simulation successful");
         }
 
-        if (effective.allowExternalApp() && Desktop.isDesktopSupported()) {
+        CodecMediaException javaSampledFailure = null;
+        if (probe.mediaType() == MediaType.AUDIO && supportsJavaSampledExtension(probe.extension())) {
             try {
-                Desktop.getDesktop().open(input.toFile());
+                javaSampledPlaybackBackend.play(input);
+                return new PlaybackResult(true, "java-sampled", probe.mediaType(), "Started playback using javax.sound.sampled");
+            } catch (CodecMediaException e) {
+                javaSampledFailure = e;
+            }
+        }
+
+        if (effective.allowExternalApp() && desktopPlaybackBackend.isSupported()) {
+            try {
+                desktopPlaybackBackend.open(input);
                 return new PlaybackResult(true, "desktop-open", probe.mediaType(), "Opened with system default application");
             } catch (IOException | RuntimeException e) {
+                if (javaSampledFailure != null) {
+                    throw new CodecMediaException(
+                            "Failed to start internal Java sampled playback and external application fallback: " + input,
+                            e
+                    );
+                }
                 throw new CodecMediaException("Failed to open media with system player/viewer: " + input, e);
             }
         }
 
+        if (javaSampledFailure != null) {
+            throw new CodecMediaException(
+                    "No playback backend available after Java sampled attempt: " + javaSampledFailure.getMessage(),
+                    javaSampledFailure
+            );
+        }
+
         throw new CodecMediaException("No playback backend available. Try dryRun=true or allowExternalApp=true");
     }
 
@@ -916,6 +985,14 @@ private static String baseName(String fileName) {
         return dot > 0 ? fileName.substring(0, dot) : fileName;
     }
 
+    private static boolean supportsJavaSampledExtension(String extension) {
+        String normalized = normalizeExtension(extension);
+        return "wav".equals(normalized)
+                || "aif".equals(normalized)
+                || "aiff".equals(normalized)
+                || "aifc".equals(normalized);
+    }
+
     private static MediaType mediaTypeByExtension(String extension) {
         return switch (normalizeExtension(extension)) {
             case "mp3", "ogg", "wav", "aif", "aiff", "aifc", "pcm", "m4a", "aac", "flac" -> MediaType.AUDIO;
@@ -924,4 +1001,44 @@ private static MediaType mediaTypeByExtension(String extension) {
             default -> MediaType.UNKNOWN;
         };
     }
+
+    interface JavaSampledPlaybackBackend {
+        void play(Path input) throws CodecMediaException;
+    }
+
+    interface DesktopPlaybackBackend {
+        boolean isSupported();
+
+        void open(Path input) throws IOException;
+    }
+
+    private static final class JdkJavaSampledPlaybackBackend implements JavaSampledPlaybackBackend {
+        @Override
+        public void play(Path input) throws CodecMediaException {
+            try (AudioInputStream audioInputStream = AudioSystem.getAudioInputStream(input.toFile())) {
+                Clip clip = AudioSystem.getClip();
+                clip.open(audioInputStream);
+                clip.addLineListener(event -> {
+                    if (event.getType() == LineEvent.Type.STOP || event.getType() == LineEvent.Type.CLOSE) {
+                        clip.close();
+                    }
+                });
+                clip.start();
+            } catch (UnsupportedAudioFileException | LineUnavailableException | IOException | RuntimeException e) {
+                throw new CodecMediaException("Java sampled playback failed for " + input + ": " + e.getMessage(), e);
+            }
+        }
+    }
+
+    private static final class AwtDesktopPlaybackBackend implements DesktopPlaybackBackend {
+        @Override
+        public boolean isSupported() {
+            return Desktop.isDesktopSupported();
+        }
+
+        @Override
+        public void open(Path input) throws IOException {
+            Desktop.getDesktop().open(input.toFile());
+        }
+    }
 }