API Reference and How to Use

The CodecMediaEngine contract exposes these methods:

7.1 get(Path input)

Alias of probe(input).

Use when you prefer shorter naming.

7.2 probe(Path input)

Detects format and returns technical stream/container info.

Returns ProbeResult fields:

• input
• mimeType
• extension
• mediaType
• durationMillis
• streams
• tags

Example:

var result = engine.probe(Path.of("src/test/resources/mp4_test.mp4"));
System.out.println(result.mimeType());
System.out.println(result.mediaType());
for (var s : result.streams()) {
    System.out.println("stream=" + s.index() + " kind=" + s.kind() + " codec=" + s.codec());
}

7.3 readMetadata(Path input)

Reads metadata from sidecar + derived probe context.

Important: current implementation is sidecar-oriented, not full embedded metadata extraction across all formats.

Example:

var metadata = engine.readMetadata(Path.of("target/example-output.jpg"));
System.out.println(metadata.entries());

7.4 writeMetadata(Path input, Metadata metadata)

Writes metadata to sidecar properties next to media file.

Example:

import java.util.Map;
import me.tamkungz.codecmedia.model.Metadata;

engine.writeMetadata(
    Path.of("target/example-output.jpg"),
    new Metadata(Map.of("title", "Demo", "author", "CodecMedia"))
);

7.5 extractAudio(Path input, Path outputDir, AudioExtractOptions options)

Extracts audio stream according to options.

Default options:

var defaults = AudioExtractOptions.defaults();
// targetFormat=m4a, bitrateKbps=192, streamIndex=0

Example:

import me.tamkungz.codecmedia.options.AudioExtractOptions;

var out = engine.extractAudio(
    Path.of("src/test/resources/mp4_test.mp4"),
    Path.of("target"),
    new AudioExtractOptions("m4a", 192, 0)
);
System.out.println(out.outputFile());
System.out.println(out.format());

7.6 convert(Path input, Path output, ConversionOptions options)

Runs conversion routing and converter execution.

Default helper:

var defaults = ConversionOptions.defaults("jpg");
// preset="balanced", overwrite=false

Example (image to image):

import me.tamkungz.codecmedia.options.ConversionOptions;

var converted = engine.convert(
    Path.of("src/test/resources/png_test.png"),
    Path.of("target/converted.jpg"),
    new ConversionOptions("jpg", "balanced", true)
);
System.out.println(converted.outputFile());
System.out.println(converted.format());
System.out.println(converted.reencoded());

7.7 play(Path input, PlaybackOptions options)

Starts playback/view action based on options.

PlaybackOptions.defaults() is:

• dryRun=false
• allowExternalApp=true

Example (safe dry-run):

import me.tamkungz.codecmedia.options.PlaybackOptions;

var play = engine.play(
    Path.of("src/test/resources/c-major-scale_test_audacity.mp3"),
    new PlaybackOptions(true, false)
);
System.out.println(play.started());
System.out.println(play.backend());
System.out.println(play.message());

7.8 validate(Path input, ValidationOptions options)

Validates file presence/size and optional strict parser-level checks.

ValidationOptions.defaults() is:

• strict=false
• maxBytes=500MB

Example:

import me.tamkungz.codecmedia.options.ValidationOptions;

var v = engine.validate(
    Path.of("target/converted.jpg"),
    new ValidationOptions(true, 64L * 1024L * 1024L)
);
System.out.println(v.valid());
System.out.println(v.warnings());
System.out.println(v.errors());