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:

  • that it display basic MP3 information in an easily parsed way;
  • that it be robust; and
  • that it be small and self-contained, and therefore easy to
    incorporate into a larger software set or distribution.

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

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.


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

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

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 which I would be obliged if you would
report them as such on the program's issue list.

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