How a Minecraft mod led me to build my own Java media library from scratch
Source: Dev.to
Background
I was building a Minecraft mod that could play MP3 files directly through OpenAL instead of using Minecraft’s built‑in audio API. To stream audio that way, I needed a low‑level MP3 decoder. I liked digging into obscure or old‑school tools, so I found Zoom JLayer—a pure‑Java MP3 decoder from the early 2000s. It looked perfect, but it only worked on some MP3 files. Same extension, same player, completely different behavior.
Discovering JLayer
Digging into JLayer’s source (someone had dumped it on GitHub) revealed something I’d never really thought about before: MP3 files aren’t all the same. There are different bitrate modes (CBR, VBR), frame headers, side information, and other structures hidden inside the bytes. That sent me down a rabbit hole—where do these values actually come from? The answer: the bytes themselves.
Once I started reading raw bytes directly, I couldn’t stop. I began studying how media file formats work at the byte level. At the time, I shipped a custom fork of JLayer so the mod could work and moved on.
Building CodecMedia
Later I needed WAV support and format conversion. Java wrappers around FFmpeg exist, but they felt heavy—most depend on native binaries or large external toolchains. I wanted something different: zero dependencies, pure Java, and as lightweight as possible.
Thus I built CodecMedia. What started as a small personal utility for a Minecraft mod slowly turned into a media library that probes and validates file formats by parsing their actual byte structure directly—no native tools involved.
Usage
Add the dependency
me.tamkungz.codecmedia
codecmedia
1.1.1Probe an audio file
CodecMediaEngine engine = CodecMedia.createDefault();
ProbeResult probe = engine.probe(Path.of("song.mp3"));
System.out.println(probe.mimeType()); // audio/mpeg
System.out.println(probe.durationMillis()); // 213000
System.out.println(probe.streams().get(0).codec()); // mp3
System.out.println(probe.streams().get(0).sampleRate()); // 44100Validate before using
ValidationResult validation = engine.validate(
Path.of("song.mp3"),
new ValidationOptions(true, 64L * 1024L * 1024L)
);
System.out.println(validation.valid()); // true
System.out.println(validation.errors()); // []Supported Formats
CodecMedia currently supports probing for:
- MP3
- OGG/Vorbis/Opus
- WAV
- FLAC
- AIFF/AIFC
- …and more
It’s still a work in progress, and I’m learning more about media formats as I go. If you’re working in Java and need media probing without pulling in a native dependency, you might find it useful.
Conclusion
There are probably better tools out there, and many alternatives exist. I didn’t build CodecMedia just to have a tool that works; I built it to understand how it works—studying the formats, reading the bytes, and learning by actually building something real with that knowledge. CodecMedia is that experiment.