DEV Community

Cover image for How a Minecraft mod led me to build my own Java media library from scratch
TamKungZ_
TamKungZ_

Posted on

How a Minecraft mod led me to build my own Java media library from scratch

#gamedev #java #programming #sideprojects

I was building a Minecraft mod — one that could play MP3 files directly through OpenAL instead of using Minecraft's built-in audio API.

To stream audio that way, I needed something that could decode MP3 at a low level. I like digging into obscure or old-school tools, so I found Zoom JLayer — a pure-Java MP3 decoder from the early 2000s. It looked perfect.

Except it only worked on some MP3 files.

That bugged me. Same extension. Same player. Completely different behavior.

So I dug into JLayer's source code (someone had dumped it on GitHub) and saw 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?

Turns out — 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 though, I just shipped a custom fork of JLayer so the mod could work and moved on.

Later, I needed WAV support. Then format conversion.

I looked at Java wrappers around FFmpeg — they exist — but they all felt heavy. Most depend on native binaries or large external toolchains. I wanted something different: zero dependencies, pure Java, and as lightweight as possible.

So 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.

What it looks like

Add the dependency:

<dependency>
    <groupId>me.tamkungz.codecmedia</groupId>
    <artifactId>codecmedia</artifactId>
    <version>1.1.1</version>
</dependency>
Enter fullscreen mode Exit fullscreen mode

Probe 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()); // 44100
Enter fullscreen mode Exit fullscreen mode

Validate 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()); // []
Enter fullscreen mode Exit fullscreen mode

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. But if you're working in Java and need media probing without pulling in a native dependency, you might find it useful.

Note: There are probably better tools out there for this. And yes, there are many alternatives.

But I didn't build CodecMedia just to have a tool that works. I built it because I wanted to understand how it works — to study the formats, read the bytes, and learn by actually building something real with that knowledge.

CodecMedia is that experiment.

👉 Maven Central

👉 GitHub

Top comments (0)