mp3x: a lightweight MP3 scanner

mp3x: a lightweight MP3 scanner

mp3x is a lightweight command-line scanner for MP3 files, which reports length and other metadata in an easily parsed way. In addition, it provides basic support for displaying and setting ID3 tags (all of id3v1, id3v2, id3v2.4). mp3x is not an MPEG decoder, and cannot be used to play MP3 files.

The program is intended to be similar in style to the wc(1) program, in that it displays information about the input file in a format which is intended to be stable and parseable.

For example:

$ mp3x test01-1-3.mp3
TIT2=Whistle 1
TPE1=Norman Gray
20  522 test01-1-3.mp3


$ mp3x -ntT test01-1-3.mp3
20   522   0:00.522

or (from v0.4)

$ mp3x -Fjson test01-1-3.mp3
{ "nframes": 20,
  "duration": 522,
  "filename": "test01-1-3.mp3",
  "duration-hms": "0:00.522",
  "id3": {
    "TRCK": "1",
    "TALB": "Whistling",
    "TYER": "2010",
    "TIT2": "Whistle 1",
    "TPE1": "Norman Gray"

or (from v0.5)

$ mp3x -Fsexp test01-1-3.mp3
((nframes . 20)
 (duration . 522)
 (filename . "test/other/test01-1-3.mp3")
 (duration-hms . "0:00.522")
  (TCON . "Speech")
  (TRCK . "1")
  (TALB . "Whistling")
  (TYER . "2010")
  (TDRC . "2010")
  (TIT2 . "Whistle 1")
  (TPE1 . "Norman Gray")))

The principal goals of this program are:

The program is intended to remain lightweight, and no major changes are planned. The program can help with basic editing of ID3 information: that turns out to be handy, but it's not regarded as core.

The program does not rely on any external library. If the iconv library is present, it is used to better display non-ASCII text; if it is not present, the program does its best (which is usually good enough in practice).

The antecedents of this program are that I wanted the length-of-an-MP3 functionality as part of a larger project, couldn't find it, quickly wrote it, and thought it might be more generally useful.

Similar programs

There are (of course) many other MP3 and ID3 programs available, some of them very reliable, others less so. Surprisingly, however, it's hard to find any which can report an MP3 file's duration, on the command-line, in a script-friendly way.

The program overlaps in functionality with mp3info. Differences: mp3info can report a broader range of information, in arbitrary formats, but is restricted to ID3v1; mp3x aims to produce easily parseable output, and supports ID3v2. It would be reasonably straightforward to adapt mp3x to extract and report further technical information, if there were any call for it.


See download page.


$ ./configure
$ make
$ make check
$ make install

Use 'man mp3x' or 'man ./mp3x.1' to look at the documentation.

To build from a checkout, ensure that autoconf is installed, and prefix the above with ./bootstrap.

PORTABILITY: The program is intended, and expected, to be portable to any C compiler or POSIX system. I don't routinely test on a variety of systems, but any failures of portability are bugs, and I would be most obliged if you could report them as such.

The program is expected to be robust and correct, and to cope with any valid MPEG2 file. It is distributed with almost 2MB of test files, including a suite of ISO/MPEG layer 2 test files. Any failures to parse MPEG2 files are bugs: do let me know about these.

NOTE: the build appears to crash at least one version of gcc (4.4.3, on Debian squeeze). I'm not sure what's causing that, but I don't think it's my fault. If you have insights or workarounds, please do let me know.


The program is distributed under the terms of the 2-clause BSD licence. See the file LICENCE for details.

Norman Gray

2020 June 27