goto page;
You could access this page securely.

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

2017-03-02 thomas: Releasing mpg123 version 1.24.0: Further we proceed.

This release is a mix of accumulated fixes and enhancements. Have a read of the list of changes:

  • Avoid repeating genre in metadata printout for specifications like (144)Thrash Metal.
  • In remote control mode, only enforce --quiet if no verbosity was required.
  • Prevent --loop and --shuffle or --random from messing with the remote control LOADLIST command (printout of the list would loop without reason).
  • Fix the mpg123 command (esp. our provided binaries on Windows) to now find modules again relative to the executable directory, not the current working directory. This was a regression in 1.23 and might be security-relevant if you called mpg123 in working directories with untrusted content. Note that mpg123 1.23 looked for modules relative to the current working directory only if the installation prefix for modules did not exist. So, usage on an intact installation (with /usr/lib/mpg123 or the like) was safe. Nevertheless this new version fixes the search to be relative to the binary path as it was with 1.22 and before.
  • At least consistent behaviour of playlist code in the face of looping. Looping is about individual tracks, always. They are looped also in random mode. Jumping (prev/next keys) is between tracks and resets the loop counter. The display of currently playing track in the playlist is fixed for random and looped play now (bug 198).
  • Looping is now mentioned for a to-be-repeated track with --verbose.
  • Move some compiler nagging from --enable-debug to --enable-nagging, fix up some new build failures by adding some pesky feature test macros.
  • Try not to pollute the terminal buffer with old progress bars in inverse video. Only the currently live one shall be seen. That one is pretty. The others are not.
  • Using plain dlopen()/LoadLibrary() for opening modules instead of libltdl. This also means that --with-module-suffix is gone in configure.
  • Windows builds only work when Unicode support is there (older than Windows 2000/XP will definitely not work anymore).
  • The out123 tool now features tone generation, with a mix of differing wave patterns. Makes sense to be able to test the audio output by itself, and it's fun. See --wave-freq and related parameters.
  • libmpg123 version 43:
    • Add flags MPG123_NO_PEEK_END and MPG123_FORCE_SEEKABLE, as suggested by Bent Bisballe Nyeng.
    • Build fix for MSVC (consistent definition of ssize_t, spotted by manx, bug 243).
    • Build fix for --with-cpu=ppc_nofpu (thanks to Michael Kostylev, bug 244).
    • Add asm optimized MSVC++ Win32|x64 and UWP|x64 builds
    • Remove old, broken MSVC++ builds
  • libout123 version 2:
    • Added OUT123_BINDIR.
    • New search order for output plugin directory: MPG123_MODDIR, or (relative to executable directory OUT123_BINDIR) ../lib/mpg123, plugins libout123/modules/.libs, libout123/modules, ../libout123/modules/.libs, ../libout123/modules, and at last the installation prefix $libdir/mpg213/. This shall ensure that a build inside a source tree does not try to use old modules from the system prefix. The normal libtool wrapper deals with the shared libout123 or libmpg123 only, not modules. Note that if you set MPG123_MODDIR to a non-existing directory, no modules will be found (earlier versions fell back to other choices).
    • The OUT123_NAME parameter is now copied by out123_param_from(), as is the newly added OUT123_BINDIR.
    • Coreaudio: Use AudioComponents API on OSX >= 10.6 (thanks to Michael Weiser).
    • Coreaudio: Fix behaviour of out123_drop(), not killing the output anymore without re-opening the device (bug 236, thanks to Taihei for the fix).

Note: There was an error in the build machinery in the first upload of the tarball. (uninstalling of modules was broken). I really hate to do that, but I am uploading a fixed version under the same name, since nobody downloaded the file from sf.net yet … it was just hours ago.

Update 2017-03-12: We uploaded new win32 binaries that now should not depend on the libgcc DLL, like the win64 ones. There is a hack in the configure script to achieve that (force -static-libgcc into CC), scheduled to appear in the next normal release.

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-20170322022201 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)

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.323452e-06 (PASS) maxdiff=7.688999e-06 (PASS)
fl6.bit:	RMS=4.389624e-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.972553e-08 (PASS) maxdiff=1.490116e-07 (PASS)
fl2.bit:	RMS=1.978601e-08 (PASS) maxdiff=1.117587e-07 (PASS)
fl3.bit:	RMS=2.010351e-08 (PASS) maxdiff=1.341105e-07 (PASS)
fl4.bit:	RMS=1.907782e-08 (PASS) maxdiff=1.303852e-07 (PASS)
fl5.bit:	RMS=3.889605e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl6.bit:	RMS=3.227466e-08 (PASS) maxdiff=1.788139e-07 (PASS)
fl7.bit:	RMS=1.772727e-08 (PASS) maxdiff=8.195639e-08 (PASS)
fl8.bit:	RMS=1.864087e-08 (PASS) maxdiff=8.381903e-08 (PASS)
--> 24 bit integer output
fl1.bit:	RMS=4.119399e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl2.bit:	RMS=4.170666e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl3.bit:	RMS=4.143659e-08 (PASS) maxdiff=1.788139e-07 (PASS)
fl4.bit:	RMS=4.125478e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl5.bit:	RMS=4.812134e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl6.bit:	RMS=4.046463e-08 (PASS) maxdiff=1.788139e-07 (PASS)
fl7.bit:	RMS=4.190445e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl8.bit:	RMS=4.112140e-08 (PASS) maxdiff=1.192093e-07 (PASS)
--> 32 bit floating point output
fl1.bit:	RMS=1.973294e-08 (PASS) maxdiff=1.490116e-07 (PASS)
fl2.bit:	RMS=1.978905e-08 (PASS) maxdiff=1.117587e-07 (PASS)
fl3.bit:	RMS=2.010275e-08 (PASS) maxdiff=1.359731e-07 (PASS)
fl4.bit:	RMS=1.909051e-08 (PASS) maxdiff=1.303852e-07 (PASS)
fl5.bit:	RMS=3.905891e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl6.bit:	RMS=3.231803e-08 (PASS) maxdiff=1.788139e-07 (PASS)
fl7.bit:	RMS=1.772906e-08 (PASS) maxdiff=8.195639e-08 (PASS)
fl8.bit:	RMS=1.865477e-08 (PASS) maxdiff=8.376082e-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.787393e-08 (PASS) maxdiff=8.288771e-08 (PASS)
fl11.bit:	RMS=1.796529e-08 (PASS) maxdiff=1.005828e-07 (PASS)
fl12.bit:	RMS=1.790962e-08 (PASS) maxdiff=8.195639e-08 (PASS)
fl13.bit:	RMS=1.769648e-08 (PASS) maxdiff=4.470348e-08 (PASS)
fl14.bit:	RMS=3.877762e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl15.bit:	RMS=2.477604e-08 (PASS) maxdiff=1.490116e-07 (PASS)
fl16.bit:	RMS=1.950440e-08 (PASS) maxdiff=1.490116e-07 (PASS)
--> 24 bit integer output
fl10.bit:	RMS=4.102627e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl11.bit:	RMS=4.111420e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl12.bit:	RMS=4.106085e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl13.bit:	RMS=4.126123e-08 (PASS) maxdiff=5.960464e-08 (PASS)
fl14.bit:	RMS=4.911543e-08 (PASS) maxdiff=1.192093e-07 (PASS)
fl15.bit:	RMS=4.139470e-08 (PASS) maxdiff=1.788139e-07 (PASS)
fl16.bit:	RMS=4.162519e-08 (PASS) maxdiff=1.788139e-07 (PASS)
--> 32 bit floating point output
fl10.bit:	RMS=1.787218e-08 (PASS) maxdiff=8.288771e-08 (PASS)
fl11.bit:	RMS=1.795900e-08 (PASS) maxdiff=1.005828e-07 (PASS)
fl12.bit:	RMS=1.791415e-08 (PASS) maxdiff=8.568168e-08 (PASS)
fl13.bit:	RMS=1.769960e-08 (PASS) maxdiff=4.470348e-08 (PASS)
fl14.bit:	RMS=3.849115e-08 (PASS) maxdiff=1.490116e-07 (PASS)
fl15.bit:	RMS=2.478901e-08 (PASS) maxdiff=1.490116e-07 (PASS)
fl16.bit:	RMS=1.951640e-08 (PASS) maxdiff=1.490116e-07 (PASS)

==== Layer 3 ====
--> 16 bit signed integer output
compl.bit:	RMS=4.300915e-06 (PASS) maxdiff=7.688999e-06 (PASS)
--> 32 bit integer output
compl.bit:	RMS=2.152388e-08 (PASS) maxdiff=1.769513e-07 (PASS)
--> 24 bit integer output
compl.bit:	RMS=4.206530e-08 (PASS) maxdiff=1.788139e-07 (PASS)
--> 32 bit floating point output
compl.bit:	RMS=2.152658e-08 (PASS) maxdiff=1.769513e-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.0xqQ5/prefix/include  -c -o helpers.o helpers.c
CC 2859531_id3_tag_not_skipped_when_NO_ID3V2_is_defined.bin
CC 2950218_extra_samples_seek_last_frame.bin
CC basic_resync.bin
CC bug201_another_one.bin
CC bug201_wrong_frame_buffer.bin
CC chomp_strings.bin
CC custom_io.bin
CC frame_seek_weirdness.bin
CC freeformat.bin
CC less_bytes_after_seek2.bin
CC less_bytes_after_seek.bin
CC more_bytes_on_second_decode.bin
CC out123_passthrough.bin
CC premature_decoder_change.bin
CC seek_accuracy.bin
Running tests.
Starting tests, look into test.log for messages.
PASS|SKIP is good, FAIL is bad.

2859531_id3_tag_not_skipped_when_NO_ID3V2_is_defined:     PASS
2950218_extra_samples_seek_last_frame:                    PASS
basic_resync:                                             PASS
bug201_another_one:                                       PASS
bug201_wrong_frame_buffer:                                PASS
chomp_strings:                                            PASS
custom_io:                                                PASS
frame_seek_weirdness:                                     PASS
freeformat:                                               PASS
less_bytes_after_seek2:                                   PASS
less_bytes_after_seek:                                    PASS
more_bytes_on_second_decode:                              PASS
out123_passthrough:                                       PASS
premature_decoder_change:                                 PASS
seek_accuracy:                                            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.

Hopefully valid HTML! Valid CSS!