checkmp3(1) identify MP3s that do not follow the MP3 format


checkmp3 [-q number] [-e] [-p] [-v[v]] [-a] [-b [byte_count]]
[-i] [-s[s|f]] [-h] [file]


checkmp3 helps to identify in explicit detail MP3s that do not correctly follow the MP3 format. It also looks for invalid frame headers, missing frames, etc., and generates useful statistics. This can be useful when building a high-quality mp3 archive...


Checks the mp3 from stem to stern (default). If any other flags are present, it will not be enabled, and will instead behave as though the '-b' switch is present.
-b [byte_count]
If a frame is not found by byte_count bytes, quit, and return an error. If byte_count is not specified, it will search until the first valid frame and quit.
While id3v2 support is under development, this flag will allow you to have checkmp3 record a frame error when a id3v2 tag is found.
Print help including the version.
Check to see if there is a ID3 tag, and if so, display the info.
-q number
Determines the mininum number of contiguous frames that must be present for an error NOT to occur. Analyzing random data will find spurious MP3 headers, but finding number sequential headers are even harder to find.
Shows just the essentials (what you get without the -v option) on a single line for easy parsing. The fields are separated by tabs, and the name/value pairs are separated by spaces.
Sends the mp3 to stdout (for CGI applications). If an additional 's' is there, then no output is made, just errors are reported (super silent). With the 'f' used, only valid frames are sent to stdout ('f'ixing the mp3 is attempted). Also, it is important to note that the id3 tag will not be included in the 'f'ixed mp3. If you want it included, you have to include the '-i' option.
Lists details about the mp3 in name -> value order. Adding an extra 'v' at the end gives details about each frame. Extremly verbose!


To check an mp3 run:

    $ checkmp3 file.mp3
To fix a broken mp3 run:

    $ checkmp3 -sf file.mp3 > fixed-file.mp3


  • There may be a problem with 'fixing' VBR files. Anyone else have any bad experiences? I guess mpg123 doesn't like it when checkmp3 fixed the VBR mp3, although I am inclined to think that it may be a problem with mpg123...
  • With a valid mp3 with no id3 tag, using the -a -sf flags will give you an identical mp3. However not using the -sf flag, but instead using the -s flag will give you a much smaller mp3 (This should be fixed).
  • CRC16 checksumming is not implemented.


Eric Bullen <ericb at>