CodecMedia

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.

What can you do with CodecMedia?

• Extract audio from video in 3 lines
• Validate media files before upload
• Read metadata (duration, bitrate, format)
• Build media pipelines in pure Java

Approaches

• Zero-Dependency
• Self-Contained
• Multi-Platform

Features

• Media engine facade via CodecMedia.createDefault()
• Probing support for:
  • MP3
  • OGG/Vorbis/Opus
  • WAV (RIFF/WAVE)
  • AIFF/AIF/AIFC (COMM-based parsing)
  • M4A (MP4 audio profile)
  • FLAC (STREAMINFO parsing)
  • PNG
  • JPEG
  • WebP
  • BMP
  • TIFF
  • HEIC/HEIF/AVIF (basic BMFF parsing)
  • MOV (QuickTime container parsing)
  • MP4 (basic ISO BMFF parsing)
  • 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, 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, 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 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.
• 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 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
  • Optional PCM->WAV preset tuning via ConversionOptions.preset, for example: sr=22050,ch=1,bits=16
• Container/unknown conversion routes are intentionally unsupported unless explicitly mapped by the conversion route resolver.
• TIFF probe currently reads the first IFD/image only (multi-page TIFF traversal is not implemented in probe mode).
• WebP probe currently reports bitDepth as an assumed default (8) for VP8/VP8L/VP8X unless deeper profile metadata parsing is added.
• For OpenAL workflows that require OGG from MP3 input, use an external transcoder first (for example ffmpeg), then play the produced OGG.

Requirements

• Java 17+
• Maven 3.9+

Build

mvn clean verify

Fixture-Driven Tests

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 probe fixture test only:

mvn -Dtest=CodecMediaPlayTest test

Run facade-focused tests only:

mvn -Dtest=CodecMediaFacadeTest test

Full Test Suite

mvn test

License

This project is licensed under the Apache License 2.0.

---

by TamKungZ_