Skip to content

Home

Jump to bottom
TamKungZ_ edited this page May 6, 2026 · 4 revisions

CodecMedia Java

CodecMedia Java is a Java 17 library for inspecting and handling media files.

The project focuses on practical media workflows that are implemented in Java or through JDK APIs:

  • Media probing
  • File validation
  • Basic metadata read/write
  • Limited conversion routes
  • Playback workflow routing

CodecMedia is not a complete transcoding framework. Unsupported routes fail explicitly instead of invoking external tools.

Project Status

Current version: 1.2.1

Minimum Java version: 17

Build tool: Maven

Runtime dependencies: none declared in pom.xml

Important notes:

  • The default implementation class is currently named StubCodecMediaEngine.
  • The implementation contains real parser, metadata, playback, and conversion behavior, but the engine is still being consolidated.
  • MP3 decoding through decoder=pure-java or decoder=layer3 is experimental.
  • General-purpose transcoding is not implemented.
  • Some image conversion routes depend on ImageIO reader/writer support available in the runtime.

Installation

Maven

<dependency>
  <groupId>me.tamkungz.codecmedia</groupId>
  <artifactId>codecmedia</artifactId>
  <version>1.2.1</version>
</dependency>

Gradle

dependencies {
    implementation("me.tamkungz.codecmedia:codecmedia:1.2.1")
}

Quick Start

import java.nio.file.Path;

import me.tamkungz.codecmedia.CodecMedia;
import me.tamkungz.codecmedia.CodecMediaEngine;
import me.tamkungz.codecmedia.options.ValidationOptions;

public class Example {
    public static void main(String[] args) throws Exception {
        CodecMediaEngine media = CodecMedia.createDefault();

        Path input = Path.of("src/test/resources/png_test.png");

        var probe = media.probe(input);
        System.out.println(probe.mimeType());
        System.out.println(probe.mediaType());
        System.out.println(probe.primaryCodec().orElse("unknown"));

        var validation = media.validate(input, ValidationOptions.defaults());
        System.out.println("valid=" + validation.valid());
    }
}

Main API

The public entry point is:

CodecMediaEngine media = CodecMedia.createDefault();

Main methods:

  • get(Path) - alias for probe(Path)
  • probe(Path) - detects media type, MIME type, extension, duration, streams, and tags
  • validate(Path, ValidationOptions) - validates file existence, size limits, and optional strict parser checks
  • readMetadata(Path) - reads base probe metadata plus supported embedded or sidecar metadata
  • writeMetadata(Path, Metadata) - writes supported embedded metadata or sidecar metadata
  • extractAudio(Path, Path, AudioExtractOptions) - copies supported audio input into an output directory
  • convert(Path, Path, ConversionOptions) - runs an implemented conversion route
  • play(Path, PlaybackOptions) - runs dry-run, Java sampled playback, or desktop-open playback

Supported Probe Formats

Audio:

  • mp3
  • ogg
  • wav
  • aif
  • aiff
  • aifc
  • flac
  • m4a

Images:

  • png
  • jpg
  • jpeg
  • webp
  • bmp
  • tif
  • tiff
  • heic
  • heif
  • avif

Video and containers:

  • mov
  • mp4
  • webm

Validation

Validation supports:

  • File existence checks
  • Maximum file size checks
  • Optional strict parser checks

Strict validation is available for:

  • mp3
  • ogg
  • wav
  • aif
  • aiff
  • aifc
  • flac
  • png
  • jpg
  • jpeg
  • mov
  • mp4
  • m4a
  • webm
  • webp
  • bmp
  • tif
  • tiff
  • heic
  • heif
  • avif

Strict validation currently reads the full file and is limited to files up to 32 MiB.

Metadata Support

readMetadata always includes base probe fields:

  • mimeType
  • extension
  • mediaType

Embedded metadata support:

  • WAV: read/write RIFF LIST/INFO
  • AIFF/AIF/AIFC: read/write NAME, AUTH, (c) , and ANNO text chunks
  • MP3: read/write ID3v1
  • OGG: read Vorbis/Opus comments
  • FLAC: read Vorbis comments

Sidecar metadata support:

  • Formats without embedded write support use <file>.codecmedia.properties.
  • Embedded metadata is treated as canonical where supported.
  • Sidecar values are merged as fallback values for non-core keys.

Conversion Support

Implemented conversion routes:

  • Same-format copy when source and target extensions match
  • Image-to-image conversion for png, jpg, jpeg, webp, bmp, tif, tiff, heic, heif, and avif
  • wav -> pcm
  • pcm -> wav
  • mp3 -> pcm
  • mp3 -> wav
  • Java Sound audio output to wav, aif, aiff, aifc, or au when supported by the runtime
  • mp4 -> m4a and mov -> m4a remux when an M4A-compatible audio track is present

Runtime-dependent behavior:

  • WebP image decode/encode requires ImageIO WebP support.
  • TIFF image decode/encode may require ImageIO TIFF support.
  • HEIF, HEIC, and AVIF image decode/encode require compatible ImageIO support.
  • Java Sound audio conversion depends on audio service providers available in the runtime.

Playback Support

Playback supports:

  • Dry-run mode for known media types
  • Java sampled playback for WAV/AIFF-family audio when Java Sound can open the file
  • Desktop-open fallback through java.awt.Desktop when enabled and supported by the platform

Known Limitations

  • Probe output is technical media information, not a complete metadata catalog.
  • ID3v2, album art/APIC extraction, and advanced tag families are not fully supported.
  • General compressed audio transcoding, such as mp3 -> ogg, is not implemented.
  • Generic video-to-audio conversion is not implemented, except MP4/MOV to M4A remux.
  • Video-to-video conversion is not implemented.
  • Audio-to-image album-art extraction is not implemented.
  • extractAudio does not transcode and does not select arbitrary streams.
  • TIFF probing reads the first IFD/image only.
  • WebP probing reports an assumed bit depth for VP8, VP8L, and VP8X when deeper profile metadata is not parsed.
  • Strict validation is limited to files up to 32 MiB.

Build From Source

git clone https://github.com/CodecMediaLib/codecmedia-java.git
cd codecmedia-java
mvn -Dgpg.skip=true clean verify

-Dgpg.skip=true is recommended for local development because the project signs release artifacts during verify.

Testing

Run the full test suite:

mvn -Dgpg.skip=true test

Run the same verify phase used by CI:

mvn -Dgpg.skip=true clean verify

Run focused tests:

mvn -Dgpg.skip=true -Dtest=CodecMediaFacadeTest test
mvn -Dgpg.skip=true -Dtest=CodecMediaPlayTest test
mvn -Dgpg.skip=true -Dtest=Mp3PcmWavConverterTest test

CI currently verifies Java 17 and Java 21.

Roadmap

Implemented:

  • Media probing for supported formats
  • Strict parser validation for supported formats
  • Embedded metadata read/write for WAV, AIFF-family files, and MP3 ID3v1
  • Embedded metadata read for OGG and FLAC comments
  • Sidecar metadata fallback
  • Limited conversion routes
  • Dry-run, Java sampled, and desktop-open playback workflows

Planned:

  • Generic video-to-audio conversion route
  • Audio-to-image album-art extraction route
  • Video-to-video conversion route
  • Broader audio transcoding support beyond Java Sound, WAV/PCM, and MP3 decode routes

TODO:

  • Document exact metadata key mapping for each embedded metadata format.
  • Document supported ImageIO plugin combinations for WebP, TIFF, HEIF, HEIC, and AVIF conversion.
  • Document release and publishing steps for maintainers.
  • Decide whether StubCodecMediaEngine should be renamed.

Links

License

CodecMedia Java is licensed under the Apache License 2.0.

Clone this wiki locally