Add aiff/flac and ogg opus support

extend media probing and strict validation to include aif/aiff/aifc
and flac, with new parsers/codecs and facade coverage.

enhance ogg parsing to recognize opus identification packets
alongside vorbis and report codec-specific bitrate behavior.

improve probe routing with lightweight header-prefix sniffing before
full reads to avoid unnecessary decoding for unsupported inputs.

expand mp4 signature detection for m4a-family brands and add tests
for m4a, flac, mp3 vbr/mono paths, ogg opus, and wav profiles.

Author: TamKungZ

CHANGELOG.md

@@ -5,6 +5,26 @@ 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.0.3] - 2026-03-05
+
+### Added
+- Added OGG Opus identification/probing support alongside Vorbis in [`OggParser`](src/main/java/me/tamkungz/codecmedia/internal/audio/ogg/OggParser.java).
+- Added AIFF/AIF/AIFC probing support with new parser/codec in [`AiffParser`](src/main/java/me/tamkungz/codecmedia/internal/audio/aiff/AiffParser.java) and [`AiffCodec`](src/main/java/me/tamkungz/codecmedia/internal/audio/aiff/AiffCodec.java).
+- Added FLAC probing support with STREAMINFO parsing in [`FlacParser`](src/main/java/me/tamkungz/codecmedia/internal/audio/flac/FlacParser.java) and [`FlacCodec`](src/main/java/me/tamkungz/codecmedia/internal/audio/flac/FlacCodec.java).
+- Added parser test coverage for MP3 VBR and mono channel-mode paths in [`Mp3ParserTest`](src/test/java/me/tamkungz/codecmedia/internal/audio/mp3/Mp3ParserTest.java).
+- Added parser test coverage for OGG Opus identification in [`OggParserTest`](src/test/java/me/tamkungz/codecmedia/internal/audio/ogg/OggParserTest.java).
+- Added WAV parser synthetic profile tests (mono/stereo, sample-rate, bit-depth combinations) in [`WavParserTest`](src/test/java/me/tamkungz/codecmedia/internal/audio/wav/WavParserTest.java).
+- Added parser test coverage for AIFF probing in [`AiffParserTest`](src/test/java/me/tamkungz/codecmedia/internal/audio/aiff/AiffParserTest.java).
+- Added facade test coverage for `.m4a` probe/strict-validate flows in [`CodecMediaFacadeTest`](src/test/java/me/tamkungz/codecmedia/CodecMediaFacadeTest.java).
+- Added parser/facade test coverage for `.flac` in [`FlacParserTest`](src/test/java/me/tamkungz/codecmedia/internal/audio/flac/FlacParserTest.java) and [`CodecMediaFacadeTest`](src/test/java/me/tamkungz/codecmedia/CodecMediaFacadeTest.java).
+
+### Changed
+- Improved probe routing in [`StubCodecMediaEngine`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java) to perform lightweight prefix-based type sniffing before full-file decode, reducing unnecessary full reads for unsupported/unknown inputs.
+- Extended probe and strict validation routing in [`StubCodecMediaEngine`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java) to include AIFF/AIF/AIFC.
+- Extended probe and strict validation routing in [`StubCodecMediaEngine`](src/main/java/me/tamkungz/codecmedia/internal/StubCodecMediaEngine.java) to include FLAC.
+- Expanded MP4 signature acceptance for M4A family brands in [`Mp4Parser.isLikelyMp4()`](src/main/java/me/tamkungz/codecmedia/internal/video/mp4/Mp4Parser.java).
+- Updated feature notes in [`README.md`](README.md) to reflect OGG Vorbis/Opus probing support and prefix-sniff probe behavior.
+
 ## [1.0.2] - 2026-03-02
 
 ### Added

README.md

@@ -13,8 +13,11 @@ CodecMedia is a Java library for media probing, validation, metadata sidecar per
 - Media engine facade via `CodecMedia.createDefault()`
 - Probing support for:
   - MP3
-  - OGG/Vorbis
+  - OGG/Vorbis/Opus
   - WAV (RIFF/WAVE)
+  - AIFF/AIF/AIFC (COMM-based parsing)
+  - M4A (MP4 audio profile)
+  - FLAC (STREAMINFO parsing)
   - PNG
   - JPEG
   - WebP
@@ -45,6 +48,7 @@ CodecMedia is a Java library for media probing, validation, metadata sidecar per
 ## 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).
 - Audio-to-audio conversion is not implemented yet for real transcode cases (for example `mp3 -> ogg`).
 - The only temporary audio conversion path is a stub `wav <-> pcm` route.

pom.xml

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

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

@@ -0,0 +1,35 @@
+package me.tamkungz.codecmedia.internal.audio.aiff;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import me.tamkungz.codecmedia.CodecMediaException;
+
+public final class AiffCodec {
+
+    private AiffCodec() {
+    }
+
+    public static AiffProbeInfo decode(Path input) throws CodecMediaException {
+        try {
+            byte[] bytes = Files.readAllBytes(input);
+            return decode(bytes, input);
+        } catch (IOException e) {
+            throw new CodecMediaException("Failed to decode AIFF: " + input, e);
+        }
+    }
+
+    public static AiffProbeInfo decode(byte[] bytes, Path sourceRef) throws CodecMediaException {
+        AiffProbeInfo info = AiffParser.parse(bytes);
+        validateDecodedProbe(info, sourceRef);
+        return info;
+    }
+
+    private static void validateDecodedProbe(AiffProbeInfo info, Path input) throws CodecMediaException {
+        if (info.sampleRate() <= 0 || info.channels() <= 0 || info.bitrateKbps() <= 0) {
+            throw new CodecMediaException("Decoded AIFF has invalid stream values: " + input);
+        }
+    }
+}
+

src/main/java/me/tamkungz/codecmedia/internal/audio/aiff/AiffCodec.java

@@ -0,0 +1,132 @@
+package me.tamkungz.codecmedia.internal.audio.aiff;
+
+import me.tamkungz.codecmedia.CodecMediaException;
+import me.tamkungz.codecmedia.internal.audio.BitrateMode;
+
+public final class AiffParser {
+
+    private AiffParser() {
+    }
+
+    public static AiffProbeInfo parse(byte[] bytes) throws CodecMediaException {
+        if (!isLikelyAiff(bytes)) {
+            throw new CodecMediaException("Not an AIFF file");
+        }
+
+        int offset = 12;
+        Integer channels = null;
+        Integer bitsPerSample = null;
+        Integer sampleRate = null;
+        Long frameCount = null;
+
+        while (offset + 8 <= bytes.length) {
+            String chunkId = readAscii(bytes, offset, 4);
+            int chunkSize = readBeInt(bytes, offset + 4);
+            if (chunkSize < 0) {
+                throw new CodecMediaException("Invalid AIFF chunk size: " + chunkSize);
+            }
+
+            int chunkDataStart = offset + 8;
+            if (chunkDataStart + chunkSize > bytes.length) {
+                throw new CodecMediaException("AIFF chunk exceeds file bounds: " + chunkId);
+            }
+
+            if ("COMM".equals(chunkId)) {
+                if (chunkSize < 18) {
+                    throw new CodecMediaException("AIFF COMM chunk too small");
+                }
+                channels = readBeShort(bytes, chunkDataStart);
+                frameCount = readBeUInt32(bytes, chunkDataStart + 2);
+                bitsPerSample = readBeShort(bytes, chunkDataStart + 6);
+                sampleRate = decodeExtended80ToIntHz(bytes, chunkDataStart + 8);
+            }
+
+            int padded = (chunkSize % 2 == 0) ? chunkSize : chunkSize + 1;
+            offset = chunkDataStart + padded;
+        }
+
+        if (channels == null || bitsPerSample == null || sampleRate == null || frameCount == null) {
+            throw new CodecMediaException("AIFF missing required COMM chunk fields");
+        }
+        if (channels <= 0 || bitsPerSample <= 0 || sampleRate <= 0 || frameCount < 0) {
+            throw new CodecMediaException("Invalid AIFF format values");
+        }
+
+        long durationMillis = (frameCount * 1000L) / sampleRate;
+        long byteRate = (long) sampleRate * channels * bitsPerSample / 8L;
+        int bitrateKbps = (int) ((byteRate * 8L) / 1000L);
+
+        return new AiffProbeInfo(durationMillis, bitrateKbps, sampleRate, channels, BitrateMode.CBR);
+    }
+
+    public static boolean isLikelyAiff(byte[] bytes) {
+        return bytes != null
+                && bytes.length >= 12
+                && bytes[0] == 'F'
+                && bytes[1] == 'O'
+                && bytes[2] == 'R'
+                && bytes[3] == 'M'
+                && bytes[8] == 'A'
+                && bytes[9] == 'I'
+                && bytes[10] == 'F'
+                && (bytes[11] == 'F' || bytes[11] == 'C');
+    }
+
+    private static int decodeExtended80ToIntHz(byte[] bytes, int offset) throws CodecMediaException {
+        if (offset + 10 > bytes.length) {
+            throw new CodecMediaException("Unexpected end of AIFF data");
+        }
+
+        int exp = ((bytes[offset] & 0x7F) << 8) | (bytes[offset + 1] & 0xFF);
+        long mantissa = 0;
+        for (int i = 0; i < 8; i++) {
+            mantissa = (mantissa << 8) | (bytes[offset + 2 + i] & 0xFFL);
+        }
+
+        if (exp == 0 || mantissa == 0) {
+            return 0;
+        }
+
+        int shift = exp - 16383 - 63;
+        long value;
+        if (shift >= 0) {
+            value = mantissa << Math.min(shift, 30);
+        } else {
+            value = mantissa >>> Math.min(-shift, 63);
+        }
+
+        if (value <= 0 || value > Integer.MAX_VALUE) {
+            throw new CodecMediaException("Unsupported AIFF sample rate encoding");
+        }
+        return (int) value;
+    }
+
+    private static String readAscii(byte[] bytes, int offset, int len) throws CodecMediaException {
+        if (offset + len > bytes.length) {
+            throw new CodecMediaException("Unexpected end of AIFF data");
+        }
+        return new String(bytes, offset, len, java.nio.charset.StandardCharsets.US_ASCII);
+    }
+
+    private static int readBeShort(byte[] bytes, int offset) throws CodecMediaException {
+        if (offset + 2 > bytes.length) {
+            throw new CodecMediaException("Unexpected end of AIFF data");
+        }
+        return ((bytes[offset] & 0xFF) << 8) | (bytes[offset + 1] & 0xFF);
+    }
+
+    private static int readBeInt(byte[] bytes, int offset) throws CodecMediaException {
+        if (offset + 4 > bytes.length) {
+            throw new CodecMediaException("Unexpected end of AIFF data");
+        }
+        return ((bytes[offset] & 0xFF) << 24)
+                | ((bytes[offset + 1] & 0xFF) << 16)
+                | ((bytes[offset + 2] & 0xFF) << 8)
+                | (bytes[offset + 3] & 0xFF);
+    }
+
+    private static long readBeUInt32(byte[] bytes, int offset) throws CodecMediaException {
+        return readBeInt(bytes, offset) & 0xFFFFFFFFL;
+    }
+}
+

src/main/java/me/tamkungz/codecmedia/internal/audio/aiff/AiffParser.java

@@ -0,0 +1,13 @@
+package me.tamkungz.codecmedia.internal.audio.aiff;
+
+import me.tamkungz.codecmedia.internal.audio.BitrateMode;
+
+public record AiffProbeInfo(
+        long durationMillis,
+        int bitrateKbps,
+        int sampleRate,
+        int channels,
+        BitrateMode bitrateMode
+) {
+}
+

src/main/java/me/tamkungz/codecmedia/internal/audio/aiff/AiffProbeInfo.java

@@ -0,0 +1,35 @@
+package me.tamkungz.codecmedia.internal.audio.flac;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import me.tamkungz.codecmedia.CodecMediaException;
+
+public final class FlacCodec {
+
+    private FlacCodec() {
+    }
+
+    public static FlacProbeInfo decode(Path input) throws CodecMediaException {
+        try {
+            byte[] bytes = Files.readAllBytes(input);
+            return decode(bytes, input);
+        } catch (IOException e) {
+            throw new CodecMediaException("Failed to decode FLAC: " + input, e);
+        }
+    }
+
+    public static FlacProbeInfo decode(byte[] bytes, Path sourceRef) throws CodecMediaException {
+        FlacProbeInfo info = FlacParser.parse(bytes);
+        validateDecodedProbe(info, sourceRef);
+        return info;
+    }
+
+    private static void validateDecodedProbe(FlacProbeInfo info, Path input) throws CodecMediaException {
+        if (info.sampleRate() <= 0 || info.channels() <= 0 || info.bitsPerSample() <= 0) {
+            throw new CodecMediaException("Decoded FLAC has invalid stream values: " + input);
+        }
+    }
+}
+

src/main/java/me/tamkungz/codecmedia/internal/audio/flac/FlacCodec.java

@@ -0,0 +1,91 @@
+package me.tamkungz.codecmedia.internal.audio.flac;
+
+import me.tamkungz.codecmedia.CodecMediaException;
+import me.tamkungz.codecmedia.internal.audio.BitrateMode;
+
+public final class FlacParser {
+
+    private FlacParser() {
+    }
+
+    public static FlacProbeInfo parse(byte[] bytes) throws CodecMediaException {
+        if (!isLikelyFlac(bytes)) {
+            throw new CodecMediaException("Not a FLAC file");
+        }
+
+        int offset = 4; // skip fLaC marker
+        boolean streamInfoFound = false;
+        int sampleRate = 0;
+        int channels = 0;
+        int bitsPerSample = 0;
+        long totalSamples = 0;
+
+        while (offset + 4 <= bytes.length) {
+            int header = bytes[offset] & 0xFF;
+            boolean last = (header & 0x80) != 0;
+            int blockType = header & 0x7F;
+            int length = ((bytes[offset + 1] & 0xFF) << 16)
+                    | ((bytes[offset + 2] & 0xFF) << 8)
+                    | (bytes[offset + 3] & 0xFF);
+            offset += 4;
+
+            if (length < 0 || offset + length > bytes.length) {
+                throw new CodecMediaException("Invalid FLAC metadata block length");
+            }
+
+            if (blockType == 0) { // STREAMINFO
+                if (length < 34) {
+                    throw new CodecMediaException("Invalid FLAC STREAMINFO block");
+                }
+                long packed = readUInt64BE(bytes, offset + 10);
+                sampleRate = (int) ((packed >>> 44) & 0xFFFFF);
+                channels = (int) (((packed >>> 41) & 0x7) + 1);
+                bitsPerSample = (int) (((packed >>> 36) & 0x1F) + 1);
+                totalSamples = packed & 0xFFFFFFFFFL;
+                streamInfoFound = true;
+            }
+
+            offset += length;
+            if (last) {
+                break;
+            }
+        }
+
+        if (!streamInfoFound || sampleRate <= 0 || channels <= 0 || bitsPerSample <= 0) {
+            throw new CodecMediaException("FLAC STREAMINFO is missing or invalid");
+        }
+
+        long durationMillis = totalSamples > 0 ? (totalSamples * 1000L) / sampleRate : 0;
+        int avgBitrateKbps = durationMillis > 0
+                ? (int) ((((long) bytes.length * 8L) * 1000L) / durationMillis / 1000L)
+                : 0;
+        int pcmEquivalentKbps = (int) (((long) sampleRate * channels * bitsPerSample) / 1000L);
+        int bitrateKbps = avgBitrateKbps > 0 ? avgBitrateKbps : pcmEquivalentKbps;
+
+        return new FlacProbeInfo("flac", sampleRate, channels, bitsPerSample, bitrateKbps, BitrateMode.VBR, durationMillis);
+    }
+
+    public static boolean isLikelyFlac(byte[] bytes) {
+        return bytes != null
+                && bytes.length >= 4
+                && bytes[0] == 'f'
+                && bytes[1] == 'L'
+                && bytes[2] == 'a'
+                && bytes[3] == 'C';
+    }
+
+    private static long readUInt64BE(byte[] bytes, int offset) throws CodecMediaException {
+        if (offset + 8 > bytes.length) {
+            throw new CodecMediaException("Unexpected end of FLAC data");
+        }
+        return ((long) (bytes[offset] & 0xFF) << 56)
+                | ((long) (bytes[offset + 1] & 0xFF) << 48)
+                | ((long) (bytes[offset + 2] & 0xFF) << 40)
+                | ((long) (bytes[offset + 3] & 0xFF) << 32)
+                | ((long) (bytes[offset + 4] & 0xFF) << 24)
+                | ((long) (bytes[offset + 5] & 0xFF) << 16)
+                | ((long) (bytes[offset + 6] & 0xFF) << 8)
+                | ((long) (bytes[offset + 7] & 0xFF));
+    }
+}
+

src/main/java/me/tamkungz/codecmedia/internal/audio/flac/FlacParser.java

@@ -0,0 +1,15 @@
+package me.tamkungz.codecmedia.internal.audio.flac;
+
+import me.tamkungz.codecmedia.internal.audio.BitrateMode;
+
+public record FlacProbeInfo(
+        String codec,
+        int sampleRate,
+        int channels,
+        int bitsPerSample,
+        int bitrateKbps,
+        BitrateMode bitrateMode,
+        long durationMillis
+) {
+}
+