I wasn’t trying to build another media converter.
\nWhat I actually wanted was something that could answer a much simpler question:
\n“Is this file really what it claims to be?”
\nThat sounds obvious until you start looking at media files beyond their extensions.
\nA 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.
\nIt started while I was building a Minecraft mod.
\nI 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.
\nIt worked…
\n…until it didn’t.
\nSome MP3 files decoded perfectly. Others failed completely, even though they played fine in normal media players.
\nInstead of assuming it was a bug, I started reading JLayer’s source code.
\nThat was when I discovered something I had never really thought about before.
\nNot every MP3 file is structured the same way.
\nDifferent bitrate modes, different frame layouts, optional headers, metadata blocks—everything is described by the bytes inside the file, not by its filename.
\nThe more I looked, the more interesting it became.
\nEventually I wasn’t trying to decode MP3 anymore.
\nI was trying to understand how media formats actually describe themselves.
\nThat curiosity eventually expanded beyond MP3.
\nWAV.
\nFLAC.
\nOGG.
\nAIFF.
\nEach format has its own signature, internal structure, metadata layout, and validation rules.
\nInstead of relying on file extensions, I started reading the actual binary structures directly.
\nThat became the foundation of CodecMedia.
\nToday, CodecMedia focuses primarily on probing and validating media files by parsing their actual byte structure.
\nRather than asking “Does this filename end with .mp3?”, it asks questions like:
Because of that, CodecMedia can identify media types from the file itself instead of trusting the extension.
\nUsing it is straightforward.
\nCodecMediaEngine engine = CodecMedia.createDefault();\n\nProbeResult probe = engine.probe(Path.of("song.mp3"));\n\nSystem.out.println(probe.mimeType());\nSystem.out.println(probe.durationMillis());\nSystem.out.println(probe.streams().get(0).codec());\nSystem.out.println(probe.streams().get(0).sampleRate());\nIf you want to verify that a file is structurally valid before processing it, validation is equally simple.
\nValidationResult validation = engine.validate(\n Path.of("song.mp3"),\n new ValidationOptions(true, 64L * 1024L * 1024L)\n);\n\nSystem.out.println(validation.valid());\nSystem.out.println(validation.errors());\nCodecMedia currently understands formats including MP3, WAV, FLAC, OGG (Vorbis and Opus), AIFF/AIFC, and several others.
\nCodecMedia also contains basic media conversion features.
\nHowever, conversion is not its primary goal.
\nThere are already excellent projects like FFmpeg that provide far more complete transcoding capabilities.
\nCodecMedia is designed differently.
\nIts primary purpose is to inspect, identify, and validate media by understanding the file’s binary format directly, while providing lightweight utilities around that information.
\nI don’t expect CodecMedia to replace existing media frameworks.
\nThere are plenty of mature solutions available.
\nThe reason I built it wasn’t because those tools weren’t good enough.
\nI built it because I wanted to understand what happens underneath them.
\nReading binary structures, interpreting headers, validating file layouts, and implementing support myself taught me far more than simply calling an external library ever could.
\nCodecMedia is the result of that exploration.
\nIf it also ends up being useful to someone else, that’s a nice bonus.
\nMaven Central: https://central.sonatype.com/artifact/me.tamkungz.codecmedia/codecmedia
\n\n", "text": "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 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 ?\", 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. If you want to verify that a file is structurally valid before processing it, validation is equally simple. 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 GitHub: https://github.com/CodecMediaLib/codecmedia-java", "blog": { "name": "TamKungZ_ Blog", "url": "https://dev.tamkungz.me/blog", "indexJson": "https://dev.tamkungz.me/blog/index.json" } }