How a Minecraft mod led me to build my own Java media library from scratch
I wasn’t trying to build another media converter.
What I actually wanted was something that could answer a much simpler question:
“Is this file really what it claims to be?”
That sounds obvious until you start looking at media files beyond their extensions.
A file named song.mp3 isn’t necessarily a valid MP3. Some players will happily play malformed files. Others won’t. Some libraries reject them entirely. Extensions don’t tell the whole story.
That realization eventually became CodecMedia.
It started while I was building a Minecraft mod.
I wanted to play MP3 files directly through OpenAL instead of Minecraft’s built-in audio system. To do that, I needed a low-level MP3 decoder, so I used Zoom JLayer, a pure Java decoder from the early 2000s.
It worked…
…until it didn’t.
Some MP3 files decoded perfectly. Others failed completely, even though they played fine in normal media players.
Instead of assuming it was a bug, I started reading JLayer’s source code.
That was when I discovered something I had never really thought about before.
Not every MP3 file is structured the same way.
Different bitrate modes, different frame layouts, optional headers, metadata blocks—everything is described by the bytes inside the file, not by its filename.
The more I looked, the more interesting it became.
Eventually I wasn’t trying to decode MP3 anymore.
I was trying to understand how media formats actually describe themselves.
That curiosity eventually expanded beyond MP3.
WAV.
FLAC.
OGG.
AIFF.
Each format has its own signature, internal structure, metadata layout, and validation rules.
Instead of relying on file extensions, I started reading the actual binary structures directly.
That became the foundation of CodecMedia.
Today, CodecMedia focuses primarily on probing and validating media files by parsing their actual byte structure.
Rather than asking “Does this filename end with .mp3?”, it asks questions like:
- Does the file contain a valid format signature?
- Is the container structure correct?
- Are the headers internally consistent?
- Can the streams actually be identified?
- Is the metadata structurally valid?
Because of that, CodecMedia can identify media types from the file itself instead of trusting the extension.
Using it is straightforward.
CodecMediaEngine engine = CodecMedia.createDefault();
ProbeResult probe = engine.probe(Path.of("song.mp3"));
System.out.println(probe.mimeType());
System.out.println(probe.durationMillis());
System.out.println(probe.streams().get(0).codec());
System.out.println(probe.streams().get(0).sampleRate());
If you want to verify that a file is structurally valid before processing it, validation is equally simple.
ValidationResult validation = engine.validate(
Path.of("song.mp3"),
new ValidationOptions(true, 64L * 1024L * 1024L)
);
System.out.println(validation.valid());
System.out.println(validation.errors());
CodecMedia currently understands formats including MP3, WAV, FLAC, OGG (Vorbis and Opus), AIFF/AIFC, and several others.
CodecMedia also contains basic media conversion features.
However, conversion is not its primary goal.
There are already excellent projects like FFmpeg that provide far more complete transcoding capabilities.
CodecMedia is designed differently.
Its primary purpose is to inspect, identify, and validate media by understanding the file’s binary format directly, while providing lightweight utilities around that information.
I don’t expect CodecMedia to replace existing media frameworks.
There are plenty of mature solutions available.
The reason I built it wasn’t because those tools weren’t good enough.
I built it because I wanted to understand what happens underneath them.
Reading binary structures, interpreting headers, validating file layouts, and implementing support myself taught me far more than simply calling an external library ever could.
CodecMedia is the result of that exploration.
If it also ends up being useful to someone else, that’s a nice bonus.
Maven Central: https://central.sonatype.com/artifact/me.tamkungz.codecmedia/codecmedia