mpg123 - Fast console MPEG Audio Player and decoder library
The mpg123 distribution contains a real time MPEG 1.0/2.0/2.5 audio player/decoder for layers 1,2 and 3 (most commonly MPEG 1.0 layer 3 aka MP3), as well as re-usable decoding and output libraries. Among others, it works on GNU/Linux, MacOSX, the BSDs, Solaris, AIX, HPUX, SGI Irix, OS/2 and Cygwin or plain MS Windows (not all more exotic platforms tested regularily, but patches welcome). You may jump to the non-exhaustive list of features.
It is free software licensed under LGPL 2.1 .
Note that nowadays, the mpg123 decoder core can work with floating point or integer math and with some tuning between accuracy and performance at build-time, using assembly optimizations for several platforms, depending on your build configuration. There is detection and selection of assembly optimisations on x86, x86-64, and ARM at program runtime. It's fast, it's high-quality. Just use it;-)
Top News
Here is a rather boring mpg123 release to celebrate the end of the weird year 2020.
- Clarify seeking documentation regarding samples and PCM frames.
- Fix build on MorphOS (patch by Ozkan Sezer, bug 295).
- Fix cmake build to install fmt123.h.
- Some cmake build fixes, tinyalsa addition by Maarten (bug 299).
- libmpg123: explicitly handle some irrelevant corner cases in tabinit (bug 279)
Head over to the download section for getting your hands on the release.
For older news see the news archive
ISO MPEG compliance
This is a rough log of an automated compliance test on the mpg123 webserver (Xeon E3, GNU/Linux), using the test bitstreams from the ISO MPEG reference set. At least the floating point output should really be close enough to the reference.
Regarding the method: This is comparing mpg123's output (with gapless code deactivated) from reference bitstreams to the reference output. A simple RMS error measure is employed, relative to full scale, just summing over mono or stereo data indiscriminently. This is my interpretation of the rules... maximum allowed RMS=8.80967e-06, maximum signal difference 6.10352e-05.
compliance test for mpg123-20210117022201 on Linux x86_64 First decoder in this list will be tested first, then generic: Supported decoders: AVX x86-64 generic generic_dither Testing default decoder... ==== Layer 1 ==== --> 16 bit signed integer output fl1.bit: RMS=4.364373e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl2.bit: RMS=4.353138e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl3.bit: RMS=4.348759e-06 (PASS) maxdiff=7.688999e-06 (PASS) fl4.bit: RMS=4.403421e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl5.bit: RMS=4.323446e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl6.bit: RMS=4.389607e-06 (PASS) maxdiff=7.688999e-06 (PASS) fl7.bit: RMS=3.826083e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl8.bit: RMS=4.362205e-06 (PASS) maxdiff=7.629395e-06 (PASS) --> 32 bit integer output fl1.bit: RMS=1.967634e-08 (PASS) maxdiff=1.490116e-07 (PASS) fl2.bit: RMS=1.969954e-08 (PASS) maxdiff=1.117587e-07 (PASS) fl3.bit: RMS=2.001651e-08 (PASS) maxdiff=1.341105e-07 (PASS) fl4.bit: RMS=1.903406e-08 (PASS) maxdiff=1.266599e-07 (PASS) fl5.bit: RMS=3.651337e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl6.bit: RMS=3.117874e-08 (PASS) maxdiff=2.086163e-07 (PASS) fl7.bit: RMS=1.768833e-08 (PASS) maxdiff=8.940697e-08 (PASS) fl8.bit: RMS=1.857696e-08 (PASS) maxdiff=8.428469e-08 (PASS) --> 24 bit integer output fl1.bit: RMS=4.096055e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl2.bit: RMS=4.154692e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl3.bit: RMS=4.127229e-08 (PASS) maxdiff=1.788139e-07 (PASS) fl4.bit: RMS=4.100170e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl5.bit: RMS=4.573922e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl6.bit: RMS=3.918939e-08 (PASS) maxdiff=1.788139e-07 (PASS) fl7.bit: RMS=4.186568e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl8.bit: RMS=4.105456e-08 (PASS) maxdiff=1.192093e-07 (PASS) --> 32 bit floating point output fl1.bit: RMS=1.967635e-08 (PASS) maxdiff=1.490116e-07 (PASS) fl2.bit: RMS=1.969944e-08 (PASS) maxdiff=1.117587e-07 (PASS) fl3.bit: RMS=2.001658e-08 (PASS) maxdiff=1.341105e-07 (PASS) fl4.bit: RMS=1.903395e-08 (PASS) maxdiff=1.266599e-07 (PASS) fl5.bit: RMS=3.651337e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl6.bit: RMS=3.117872e-08 (PASS) maxdiff=2.086163e-07 (PASS) fl7.bit: RMS=1.768828e-08 (PASS) maxdiff=8.940697e-08 (PASS) fl8.bit: RMS=1.857700e-08 (PASS) maxdiff=8.428469e-08 (PASS) ==== Layer 2 ==== --> 16 bit signed integer output fl10.bit: RMS=3.512100e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl11.bit: RMS=3.837267e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl12.bit: RMS=3.901071e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl13.bit: RMS=4.379583e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl14.bit: RMS=4.112578e-06 (PASS) maxdiff=7.688999e-06 (PASS) fl15.bit: RMS=4.388579e-06 (PASS) maxdiff=7.688999e-06 (PASS) fl16.bit: RMS=4.147495e-06 (PASS) maxdiff=7.688999e-06 (PASS) --> 32 bit integer output fl10.bit: RMS=1.777285e-08 (PASS) maxdiff=8.475035e-08 (PASS) fl11.bit: RMS=1.789150e-08 (PASS) maxdiff=9.685755e-08 (PASS) fl12.bit: RMS=1.780872e-08 (PASS) maxdiff=8.940697e-08 (PASS) fl13.bit: RMS=1.760690e-08 (PASS) maxdiff=4.470348e-08 (PASS) fl14.bit: RMS=3.361258e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl15.bit: RMS=2.418801e-08 (PASS) maxdiff=1.490116e-07 (PASS) fl16.bit: RMS=1.924891e-08 (PASS) maxdiff=1.192093e-07 (PASS) --> 24 bit integer output fl10.bit: RMS=4.085486e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl11.bit: RMS=4.098320e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl12.bit: RMS=4.095125e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl13.bit: RMS=4.108581e-08 (PASS) maxdiff=5.960464e-08 (PASS) fl14.bit: RMS=4.444728e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl15.bit: RMS=4.087458e-08 (PASS) maxdiff=1.788139e-07 (PASS) fl16.bit: RMS=4.146825e-08 (PASS) maxdiff=1.192093e-07 (PASS) --> 32 bit floating point output fl10.bit: RMS=1.777284e-08 (PASS) maxdiff=8.475035e-08 (PASS) fl11.bit: RMS=1.789151e-08 (PASS) maxdiff=9.685755e-08 (PASS) fl12.bit: RMS=1.780868e-08 (PASS) maxdiff=8.940697e-08 (PASS) fl13.bit: RMS=1.760693e-08 (PASS) maxdiff=4.470348e-08 (PASS) fl14.bit: RMS=3.361258e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl15.bit: RMS=2.418793e-08 (PASS) maxdiff=1.490116e-07 (PASS) fl16.bit: RMS=1.924847e-08 (PASS) maxdiff=1.192093e-07 (PASS) ==== Layer 3 ==== --> 16 bit signed integer output compl.bit: RMS=4.300912e-06 (PASS) maxdiff=7.688999e-06 (PASS) --> 32 bit integer output compl.bit: RMS=2.105351e-08 (PASS) maxdiff=1.881272e-07 (PASS) --> 24 bit integer output compl.bit: RMS=4.172895e-08 (PASS) maxdiff=2.384186e-07 (PASS) --> 32 bit floating point output compl.bit: RMS=2.105351e-08 (PASS) maxdiff=1.881272e-07 (PASS) ==== Layer 3 intensity stereo ==== (no official reference, comparing to mpg123 generic 24 bit) --> 16 bit signed integer output drumshort08kHz.bit: RMS=4.348691e-06 (PASS) maxdiff=7.629395e-06 (PASS) drumshort24kHz.bit: RMS=4.365980e-06 (PASS) maxdiff=7.629395e-06 (PASS) drumshort48kHz.bit: RMS=4.375106e-06 (PASS) maxdiff=8.106232e-06 (PASS) --> 32 bit integer output drumshort08kHz.bit: RMS=3.274575e-08 (PASS) maxdiff=5.937181e-08 (PASS) drumshort24kHz.bit: RMS=3.277976e-08 (PASS) maxdiff=5.937181e-08 (PASS) drumshort48kHz.bit: RMS=4.066349e-08 (PASS) maxdiff=6.854534e-07 (PASS) --> 24 bit integer output drumshort08kHz.bit: RMS=0.000000e+00 (PASS) maxdiff=0.000000e+00 (PASS) drumshort24kHz.bit: RMS=0.000000e+00 (PASS) maxdiff=0.000000e+00 (PASS) drumshort48kHz.bit: RMS=2.915400e-08 (PASS) maxdiff=7.152557e-07 (PASS) --> 32 bit floating point output drumshort08kHz.bit: RMS=3.274569e-08 (PASS) maxdiff=5.948616e-08 (PASS) drumshort24kHz.bit: RMS=3.277980e-08 (PASS) maxdiff=5.948719e-08 (PASS) drumshort48kHz.bit: RMS=4.066347e-08 (PASS) maxdiff=6.854534e-07 (PASS) Now the generic decoder: ==== Layer 1 ==== --> 16 bit signed integer output fl1.bit: RMS=4.364373e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl2.bit: RMS=4.353138e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl3.bit: RMS=4.348759e-06 (PASS) maxdiff=7.688999e-06 (PASS) fl4.bit: RMS=4.403421e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl5.bit: RMS=4.323446e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl6.bit: RMS=4.389618e-06 (PASS) maxdiff=7.688999e-06 (PASS) fl7.bit: RMS=3.826083e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl8.bit: RMS=4.362205e-06 (PASS) maxdiff=7.629395e-06 (PASS) --> 32 bit integer output fl1.bit: RMS=1.963732e-08 (PASS) maxdiff=1.499429e-07 (PASS) fl2.bit: RMS=1.969794e-08 (PASS) maxdiff=1.117587e-07 (PASS) fl3.bit: RMS=2.001570e-08 (PASS) maxdiff=1.359731e-07 (PASS) fl4.bit: RMS=1.904758e-08 (PASS) maxdiff=1.266599e-07 (PASS) fl5.bit: RMS=3.707870e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl6.bit: RMS=3.106253e-08 (PASS) maxdiff=1.788139e-07 (PASS) fl7.bit: RMS=1.767630e-08 (PASS) maxdiff=8.195639e-08 (PASS) fl8.bit: RMS=1.858603e-08 (PASS) maxdiff=8.568168e-08 (PASS) --> 24 bit integer output fl1.bit: RMS=4.105573e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl2.bit: RMS=4.167314e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl3.bit: RMS=4.137374e-08 (PASS) maxdiff=1.788139e-07 (PASS) fl4.bit: RMS=4.120803e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl5.bit: RMS=4.672934e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl6.bit: RMS=3.930971e-08 (PASS) maxdiff=1.788139e-07 (PASS) fl7.bit: RMS=4.189212e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl8.bit: RMS=4.100406e-08 (PASS) maxdiff=1.192093e-07 (PASS) --> 32 bit floating point output fl1.bit: RMS=1.963737e-08 (PASS) maxdiff=1.499429e-07 (PASS) fl2.bit: RMS=1.969777e-08 (PASS) maxdiff=1.117587e-07 (PASS) fl3.bit: RMS=2.001570e-08 (PASS) maxdiff=1.359731e-07 (PASS) fl4.bit: RMS=1.904733e-08 (PASS) maxdiff=1.266599e-07 (PASS) fl5.bit: RMS=3.707858e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl6.bit: RMS=3.106251e-08 (PASS) maxdiff=1.788139e-07 (PASS) fl7.bit: RMS=1.767655e-08 (PASS) maxdiff=8.195639e-08 (PASS) fl8.bit: RMS=1.858607e-08 (PASS) maxdiff=8.568168e-08 (PASS) ==== Layer 2 ==== --> 16 bit signed integer output fl10.bit: RMS=3.512100e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl11.bit: RMS=3.837267e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl12.bit: RMS=3.901071e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl13.bit: RMS=4.379583e-06 (PASS) maxdiff=7.629395e-06 (PASS) fl14.bit: RMS=4.112584e-06 (PASS) maxdiff=7.688999e-06 (PASS) fl15.bit: RMS=4.388591e-06 (PASS) maxdiff=7.688999e-06 (PASS) fl16.bit: RMS=4.147492e-06 (PASS) maxdiff=7.688999e-06 (PASS) --> 32 bit integer output fl10.bit: RMS=1.778199e-08 (PASS) maxdiff=8.381903e-08 (PASS) fl11.bit: RMS=1.788019e-08 (PASS) maxdiff=9.313226e-08 (PASS) fl12.bit: RMS=1.782325e-08 (PASS) maxdiff=8.940697e-08 (PASS) fl13.bit: RMS=1.760957e-08 (PASS) maxdiff=4.470348e-08 (PASS) fl14.bit: RMS=3.655757e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl15.bit: RMS=2.422136e-08 (PASS) maxdiff=1.490116e-07 (PASS) fl16.bit: RMS=1.923566e-08 (PASS) maxdiff=1.490116e-07 (PASS) --> 24 bit integer output fl10.bit: RMS=4.092544e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl11.bit: RMS=4.106930e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl12.bit: RMS=4.105086e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl13.bit: RMS=4.120309e-08 (PASS) maxdiff=5.960464e-08 (PASS) fl14.bit: RMS=4.677675e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl15.bit: RMS=4.099465e-08 (PASS) maxdiff=1.788139e-07 (PASS) fl16.bit: RMS=4.152576e-08 (PASS) maxdiff=1.788139e-07 (PASS) --> 32 bit floating point output fl10.bit: RMS=1.778199e-08 (PASS) maxdiff=8.381903e-08 (PASS) fl11.bit: RMS=1.788022e-08 (PASS) maxdiff=9.313226e-08 (PASS) fl12.bit: RMS=1.782324e-08 (PASS) maxdiff=8.940697e-08 (PASS) fl13.bit: RMS=1.760955e-08 (PASS) maxdiff=4.470348e-08 (PASS) fl14.bit: RMS=3.655758e-08 (PASS) maxdiff=1.192093e-07 (PASS) fl15.bit: RMS=2.422128e-08 (PASS) maxdiff=1.490116e-07 (PASS) fl16.bit: RMS=1.923544e-08 (PASS) maxdiff=1.490116e-07 (PASS) ==== Layer 3 ==== --> 16 bit signed integer output compl.bit: RMS=4.300914e-06 (PASS) maxdiff=7.688999e-06 (PASS) --> 32 bit integer output compl.bit: RMS=2.135350e-08 (PASS) maxdiff=1.783483e-07 (PASS) --> 24 bit integer output compl.bit: RMS=4.196590e-08 (PASS) maxdiff=1.788139e-07 (PASS) --> 32 bit floating point output compl.bit: RMS=2.135350e-08 (PASS) maxdiff=1.783483e-07 (PASS) ==== Layer 3 intensity stereo ==== (no official reference, comparing to mpg123 generic 24 bit) --> 16 bit signed integer output drumshort08kHz.bit: RMS=4.348726e-06 (PASS) maxdiff=7.748604e-06 (PASS) drumshort24kHz.bit: RMS=4.366060e-06 (PASS) maxdiff=7.867813e-06 (PASS) drumshort48kHz.bit: RMS=4.375037e-06 (PASS) maxdiff=7.748604e-06 (PASS) --> 32 bit integer output drumshort08kHz.bit: RMS=3.653002e-08 (PASS) maxdiff=4.172325e-07 (PASS) drumshort24kHz.bit: RMS=3.869177e-08 (PASS) maxdiff=7.450581e-07 (PASS) drumshort48kHz.bit: RMS=3.411450e-08 (PASS) maxdiff=2.682209e-07 (PASS) --> 24 bit integer output drumshort08kHz.bit: RMS=2.207543e-08 (PASS) maxdiff=4.172325e-07 (PASS) drumshort24kHz.bit: RMS=2.626600e-08 (PASS) maxdiff=7.748604e-07 (PASS) drumshort48kHz.bit: RMS=1.577338e-08 (PASS) maxdiff=2.384186e-07 (PASS) --> 32 bit floating point output drumshort08kHz.bit: RMS=3.653007e-08 (PASS) maxdiff=4.172325e-07 (PASS) drumshort24kHz.bit: RMS=3.869177e-08 (PASS) maxdiff=7.450581e-07 (PASS) drumshort48kHz.bit: RMS=3.411445e-08 (PASS) maxdiff=2.682209e-07 (PASS)
Depending on what integer quality mode you choose at compile time (and the decoder in use), the 16bit output can vary between PASS and LIMITED for fully or limited accuracy compliance. But keep in mind: For the integer output, you have to give +-1 for rounding... that's what I append to any integer number read from some measurement device anyway, by default. That minimum possible deviation already brings the output close (or over) the border of full compliance... that really does not mean that the output sounds bad! It shall be noted that a measure to improve subjective quality, namely the dithering before rounding to integers, can also increase the theoretical decoding error.
In the end, RMS values in the order of 10 to the power of -5 should sound just fine. To get 16bit output to PASS, you usually need to enable proper rounding using the --enable-int-quality configure flag. It is not on by default because it mostly (yeah, there are odd cases) needs somewhat more CPU time and the simple truncation is fine for most people. Note that mpg123 does have a rounding method using the specific IEEE754 floating point format, selected at build-time, which seems to be nearly as fast as simple truncation on x86-64 hardware. So, --enable-int-quality might be a no-brainer on those systems if using the generic C decoder. But then, there are the specific assembly routines (SSE, AVX), where the difference between accurate and non-accurate integer conversion can still amount to 20 % runtime increase (measured on a Core2Duo P8600 with GCC 5.3.0).
For comparisong with other decoders (as well as older incarnations of the mpg123 engine), have a read of the Underbit compliance tests. Actually, my testing method follows that example, including their quoting of ISO MPEG rules.
Regression tests
This is output from the rudimentary regression test suite (which should eventually merge several approaches we had on testing in the past), working on the periodic snapshot:
cc -I/tmp/mpg123-svn.fgcFI/prefix/include -c -o helpers.o helpers.c CC custom_io.bin CC chomp_strings.bin CC more_bytes_on_second_decode.bin CC 2859531_id3_tag_not_skipped_when_NO_ID3V2_is_defined.bin CC less_bytes_after_seek2.bin CC seek_accuracy.bin CC out123_passthrough.bin CC bug201_wrong_frame_buffer.bin CC bug201_another_one.bin CC basic_resync.bin CC freeformat.bin CC out123_errorlist.bin CC premature_decoder_change.bin CC less_bytes_after_seek.bin CC frame_seek_weirdness.bin CC string_alloc.bin CC 2950218_extra_samples_seek_last_frame.bin Running tests. Starting tests, look into test.log for messages. PASS|SKIP is good, FAIL is bad. custom_io: PASS chomp_strings: PASS more_bytes_on_second_decode: PASS 2859531_id3_tag_not_skipped_when_NO_ID3V2_is_defined: PASS less_bytes_after_seek2: PASS seek_accuracy: PASS out123_passthrough: PASS bug201_wrong_frame_buffer: PASS bug201_another_one: PASS basic_resync: PASS freeformat: PASS out123_errorlist: PASS premature_decoder_change: PASS less_bytes_after_seek: PASS frame_seek_weirdness: PASS string_alloc: PASS 2950218_extra_samples_seek_last_frame: PASS PASS
Needed computing power
A test (GNU/Linux OS) with 0.60-beta2 showed 3 % to 4 % CPU usage on decoding high quality VBR MP3 with a pentiumII laptop with 366MHz, while a pentium 100MHz can easily handle two mpg123 instances in realtime (plus the mixing daemon that works on decoded data). Well, and more recently, A Core2Duo P8600 core can do 500 times realtime decoding (a track nearly five minutes long decoded in half a second).
Also, we have reports from such devices as nintendo DS or Sony PSP, or various embedded systems...
Michael said once upon a time
Plays Layer 3 in stereo on an AMD-486-120Mhz or (of course) a faster machine.
Just for info: mpg123 plays an average 128bps stream, with about 66% in full quality on an AMD 486-133MHz machine.
