Add embedded audio metadata support

add embedded metadata read/write support across audio formats by
treating in-file tags as canonical and sidecar values as fallback for
non-core keys.

extend metadata handling with MP3 ID3v1 read/write, AIFF text chunk
read/write, and OGG/FLAC comment parsing. remove stale sidecars after
writing embedded-capable formats to keep metadata sources consistent.

expand conversion routing with Java Sound audio transcoding targets
(wav/aiff/au) and add mp4/mov audio-track remux to m4a when codec
compatible.

update tests and docs for new metadata and conversion behavior, bump
version to 1.1.5, and package CHANGELOG.md into the jar.

Author: TamKungZ

CHANGELOG.md

@@ -5,6 +5,27 @@ 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.5] - 2026-03-17
+
+### Added
+- Added MP3 embedded ID3v1 metadata reader/writer via [`Mp3Id3v1Tag`](src/main/java/me/tamkungz/codecmedia/internal/audio/mp3/Mp3Id3v1Tag.java) and integrated it into engine metadata read/write flow in [`StubCodecMediaEngine`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java).
+- Added OGG Vorbis/Opus comment metadata reader via [`OggParser.readCommentMetadata()`](src/main/java/me/tamkungz/codecmedia/internal/audio/ogg/OggParser.java) and integrated it into [`StubCodecMediaEngine.readMetadata()`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java).
+- Added FLAC Vorbis comment metadata reader via [`FlacParser.readVorbisCommentMetadata()`](src/main/java/me/tamkungz/codecmedia/internal/audio/flac/FlacParser.java) and integrated it into [`StubCodecMediaEngine.readMetadata()`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java).
+- Added Java Sound audio transcoder [`JavaSoundAudioTranscodeConverter`](src/main/java/me/tamkungz/codecmedia/internal/convert/JavaSoundAudioTranscodeConverter.java) for JDK-only target formats (`wav`, `aiff`, `au`).
+- Added AIFF embedded text metadata read/write support (`NAME`, `AUTH`, `(c) `, `ANNO`) via [`AiffParser.readTextMetadata()`](src/main/java/me/tamkungz/codecmedia/internal/audio/aiff/AiffParser.java) and [`AiffParser.writeTextMetadata()`](src/main/java/me/tamkungz/codecmedia/internal/audio/aiff/AiffParser.java).
+- Added MP4/MOV to M4A audio-track remux route via [`Mp4MovToM4aRemuxConverter`](src/main/java/me/tamkungz/codecmedia/internal/convert/Mp4MovToM4aRemuxConverter.java) in the video-to-audio conversion hub path.
+
+### Changed
+- Updated audio-to-audio conversion routing in [`DefaultConversionHub`](src/main/java/me/tamkungz/codecmedia/internal/convert/DefaultConversionHub.java) to use Java Sound transcoding path (while preserving explicit WAV/PCM routing).
+- Expanded facade regression coverage in [`CodecMediaFacadeTest`](src/test/java/me/tamkungz/codecmedia/CodecMediaFacadeTest.java) for MP3 embedded metadata and OGG/FLAC metadata read paths.
+- Standardized metadata merge behavior in [`StubCodecMediaEngine.readMetadata()`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java) to treat embedded metadata as canonical and sidecar values as fallback (`putIfAbsent` for non-core keys).
+- Updated metadata write behavior in [`StubCodecMediaEngine.writeMetadata()`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java) so embedded-capable formats (`wav`, `mp3`, `aif`/`aiff`/`aifc`) write in-file metadata and remove stale sidecar files.
+- Expanded metadata regression coverage in [`CodecMediaFacadeTest`](src/test/java/me/tamkungz/codecmedia/CodecMediaFacadeTest.java) and parser-level AIFF coverage in [`AiffParserTest`](src/test/java/me/tamkungz/codecmedia/internal/audio/aiff/AiffParserTest.java).
+
+### Verified
+- Confirmed metadata and conversion/facade behavior with `mvn -Dtest=CodecMediaFacadeTest test`.
+- Confirmed AIFF embedded metadata parser and facade flows with `mvn -Dtest=AiffParserTest,CodecMediaFacadeTest test`.
+
 ## [1.1.4] - 2026-03-17
 
 ### Added

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 persistence (embedded LIST/INFO for WAV and sidecar for non-WAV), audio extraction, playback workflow handling, and conversion routing.
+CodecMedia is a Java library for media probing, validation, metadata persistence (embedded WAV/AIFF/MP3 where supported with sidecar fallback for other formats), audio extraction, playback workflow handling, and conversion routing.
 
 
 <p align="center">
@@ -39,18 +39,18 @@ CodecMedia is a Java library for media probing, validation, metadata persistence
   - 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 embedded WAV LIST/INFO support and sidecar persistence (`.codecmedia.properties`) for non-WAV inputs
+- Metadata read/write with embedded WAV LIST/INFO, AIFF text chunks (`NAME`/`AUTH`/`(c) `/`ANNO`), and MP3 ID3v1 support, plus sidecar persistence (`.codecmedia.properties`) for non-embedded fallback/compatibility paths
 - 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, 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)
+- Conversion hub routing with explicit unsupported routes, a real `wav <-> pcm` path (`WAV -> PCM` data-chunk extraction, `PCM -> WAV` wrapping), JDK Java Sound audio targets (`wav`/`aiff`/`au`), and MP4/MOV audio-track remux to `m4a` when codec-compatible
 
 ## 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 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.
+- `readMetadata(input)`: returns derived probe metadata plus embedded metadata where supported (WAV LIST/INFO, AIFF text chunks, MP3 ID3v1, OGG/FLAC comments), then merges sidecar entries as fallback when present.
+- `writeMetadata(input, metadata)`: validates and writes embedded metadata where supported (WAV LIST/INFO, AIFF text chunks, MP3 ID3v1); for embedded-capable formats, stale sidecar files are removed; sidecar remains for compatibility/non-embedded paths.
 - `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, routes WAV/AIFF-family playback through an internal Java sampled backend, and falls back to optional system default app launch.
@@ -60,8 +60,8 @@ CodecMedia is a Java library for media probing, validation, metadata persistence
 
 - 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` 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`).
+- `readMetadata` supports embedded metadata for WAV (LIST/INFO), AIFF text chunks, MP3 (ID3v1), and OGG/FLAC comments; it is **not** a full embedded tag extractor for advanced tag families (for example ID3v2 APIC/album art).
+- Audio-to-audio conversion is partially implemented with JDK Java Sound targets (`wav`/`aiff`/`au`); general compressed-target transcode cases (for example `mp3 -> ogg`) are still not implemented.
 - The currently implemented audio route is `wav <-> pcm`:
   - `wav -> pcm`: extracts raw PCM payload from WAV `data` chunk
   - `pcm -> wav`: wraps PCM into PCM WAV container

pom.xml

@@ -7,7 +7,7 @@
 
   <groupId>me.tamkungz.codecmedia</groupId>
   <artifactId>codecmedia</artifactId>
-  <version>1.1.4</version>
+  <version>1.1.5</version>
   <packaging>jar</packaging>
 
   <name>CodecMedia</name>
@@ -115,6 +115,34 @@
   <build>
     <plugins>
 
+      <!-- Include top-level docs in JAR -->
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <version>3.3.1</version>
+        <executions>
+          <execution>
+            <id>copy-root-changelog-into-jar</id>
+            <phase>process-resources</phase>
+            <goals>
+              <goal>copy-resources</goal>
+            </goals>
+            <configuration>
+              <outputDirectory>${project.build.outputDirectory}</outputDirectory>
+              <resources>
+                <resource>
+                  <directory>${project.basedir}</directory>
+                  <includes>
+                    <include>CHANGELOG.md</include>
+                  </includes>
+                  <filtering>false</filtering>
+                </resource>
+              </resources>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+
       <!-- Compiler -->
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>

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

@@ -30,6 +30,7 @@
 import me.tamkungz.codecmedia.internal.audio.flac.FlacParser;
 import me.tamkungz.codecmedia.internal.audio.flac.FlacProbeInfo;
 import me.tamkungz.codecmedia.internal.audio.mp3.Mp3Codec;
+import me.tamkungz.codecmedia.internal.audio.mp3.Mp3Id3v1Tag;
 import me.tamkungz.codecmedia.internal.audio.mp3.Mp3Parser;
 import me.tamkungz.codecmedia.internal.audio.mp3.Mp3ProbeInfo;
 import me.tamkungz.codecmedia.internal.audio.ogg.OggCodec;
@@ -592,16 +593,10 @@ public Metadata readMetadata(Path input) throws CodecMediaException {
         entries.put("mimeType", probe.mimeType());
         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);
-            }
+        String normalizedExtension = normalizeExtension(probe.extension());
+        Map<String, String> embeddedEntries = readEmbeddedMetadata(input, normalizedExtension);
+        for (Map.Entry<String, String> entry : embeddedEntries.entrySet()) {
+            entries.put(entry.getKey(), entry.getValue());
         }
 
         Path sidecar = metadataSidecarPath(input);
@@ -613,7 +608,9 @@ public Metadata readMetadata(Path input) throws CodecMediaException {
                 throw new CodecMediaException("Failed to read metadata sidecar: " + sidecar, e);
             }
             for (String key : properties.stringPropertyNames()) {
-                entries.putIfAbsent(key, properties.getProperty(key));
+                if (!isCoreMetadataKey(key)) {
+                    entries.putIfAbsent(key, properties.getProperty(key));
+                }
             }
         }
 
@@ -642,12 +639,37 @@ public void writeMetadata(Path input, Metadata metadata) throws CodecMediaExcept
                 byte[] wavBytes = Files.readAllBytes(input);
                 byte[] withMetadata = WavParser.writeInfoMetadata(wavBytes, metadata.entries());
                 Files.write(input, withMetadata);
+                deleteSidecarIfExists(input);
                 return;
             } catch (IOException e) {
                 throw new CodecMediaException("Failed to write WAV metadata: " + input, e);
             }
         }
 
+        if ("aif".equals(extension) || "aiff".equals(extension) || "aifc".equals(extension)) {
+            try {
+                byte[] aiffBytes = Files.readAllBytes(input);
+                byte[] withMetadata = AiffParser.writeTextMetadata(aiffBytes, metadata.entries());
+                Files.write(input, withMetadata);
+                deleteSidecarIfExists(input);
+                return;
+            } catch (IOException e) {
+                throw new CodecMediaException("Failed to write AIFF metadata: " + input, e);
+            }
+        }
+
+        if ("mp3".equals(extension)) {
+            try {
+                byte[] mp3Bytes = Files.readAllBytes(input);
+                byte[] withTag = Mp3Id3v1Tag.write(mp3Bytes, metadata.entries());
+                Files.write(input, withTag);
+                deleteSidecarIfExists(input);
+                return;
+            } catch (IOException e) {
+                throw new CodecMediaException("Failed to write MP3 metadata: " + input, e);
+            }
+        }
+
         Path sidecar = metadataSidecarPath(input);
         Properties properties = new Properties();
         Map<String, String> sorted = new TreeMap<>(metadata.entries());
@@ -975,6 +997,30 @@ private static Path metadataSidecarPath(Path input) {
         return input.resolveSibling(input.getFileName() + ".codecmedia.properties");
     }
 
+    private static void deleteSidecarIfExists(Path input) throws IOException {
+        Files.deleteIfExists(metadataSidecarPath(input));
+    }
+
+    private static boolean isCoreMetadataKey(String key) {
+        return "mimeType".equals(key) || "extension".equals(key) || "mediaType".equals(key);
+    }
+
+    private static Map<String, String> readEmbeddedMetadata(Path input, String normalizedExtension) throws CodecMediaException {
+        try {
+            byte[] bytes = Files.readAllBytes(input);
+            return switch (normalizedExtension) {
+                case "wav" -> WavParser.readInfoMetadata(bytes);
+                case "aif", "aiff", "aifc" -> AiffParser.readTextMetadata(bytes);
+                case "mp3" -> Mp3Id3v1Tag.read(bytes);
+                case "ogg" -> OggParser.readCommentMetadata(bytes);
+                case "flac" -> FlacParser.readVorbisCommentMetadata(bytes);
+                default -> Map.of();
+            };
+        } catch (IOException e) {
+            throw new CodecMediaException("Failed to read embedded metadata: " + input, e);
+        }
+    }
+
     private static String normalizeExtension(String format) {
         String value = format.trim().toLowerCase(Locale.ROOT);
         return value.startsWith(".") ? value.substring(1) : value;