Debian Codegraph @

README

raw
1 * * * * * * * * * * * * * * * * * * * * * * * * * * * *
2 * mpg123 - MPEG 1.0/2.0/2.5 audio player *
3 * README for version 1.x.y, dated at 29.06.2025 *
4 * *
5 * ...still the fastest MPEG audio player for UNIX ;) *
6 * * * * * * * * * * * * * * * * * * * * * * * * * * * *
7
8 0. Stuff
9
10 For building/installation info see INSTALL.
11
12 The mpg123 project was started by Michel Hipp and is now being maintained
13 by Thomas Orgis. The source code contains contributions from quite a few
14 people - see AUTHORS for more info.
15
16 It is Open Source software licensed mostly under the LGPL v2.1, COPYING
17 for details. Patents on MPEG audio used to be an issue, but around 2017
18 the last patents should have expired. I'm no lawyer, that is just my
19 opinion, of course. Get your own to make sure (opinion or lawyer, whatever
20 you prefer).
21
22 Project's official website URL is
23
24 https://mpg123.org
25
26 (or https://mpg123.orgis.org as fallback address if there is a problem
27 with the DNS forwarding)
28
29 for the traditional home page and
30
31 https://sourceforge.net/projects/mpg123
32
33 for sourceforge.net based services like download mirrors, mailing lists
34 and bug/feature trackers.
35
36
37 1. Introduction
38
39 This is a console based decoder/player for mono/stereo mpeg audio files,
40 probably more familiar as MP3 or MP2 files.
41 It's focus is speed. We still need some low-end benchmarks for the
42 current version, but playback should be possible even on i486 CPUs. There
43 is hand-optimized assembly code for i586, MMX, 3DNow, SEE and 3DNowExt
44 instructions, while generic code runs on a variety of different platforms
45 and CPUs.
46 It can play MPEG1.0/2.0/2.5 layer I, II, II (1, 2, 3;-) files (VBR files
47 are fine, too) and produce output on a number of different ways: raw
48 data to stdout and different sound systems depending on your platform
49 (see INSTALL).
50 Most tested are Linux on x86 and Alpha/AXP and MacOSX on ppc as the
51 environments the current developers work in.
52 We are always thankful for user reports on success (and failure) on
53 any platform!
54
55
56 2. Contact
57
58 short:
59
60 [email protected]
61 [email protected]
62 or
63 [email protected]
64
65 long: see doc/CONTACT
66
67
68 3. Interface/Usage
69
70 Please consult the manpage mpg123(1). Some starter info follows.
71
72 3.1 Simple Console Usage
73
74 Mpg123 is a console program - normally it just plays a list of files
75 you specify on command line and that's it. See the included manpage or
76
77 mpg123 --help
78
79 or, for the full story,
80
81 mpg123 --longhelp
82
83 on command line syntax/options. I encourage you to check out the --gapless
84 and --rva-album/--rva-mix options:-)
85
86 In the simple "mpg123 file1.mp3 file2.mp3" mode, the only thing you can
87 do to interact is to press Ctrl+C to skip to next track or end the whole
88 playback if pressing it twice.
89
90 Note that this Ctrl+C behaviour is special to this mode; when any of
91 the following is activated, Ctrl+C will just kill the program like you
92 would expect normally (this changed from earlier versions).
93
94 3.2 Advanced Console Usage
95
96 You can specify the option -C to enable a terminal control interface
97 enabling to influence playback on current title/playlist by pressing
98 some key:
99 -= terminal control keys =-
100 [s] or [ ] interrupt/restart playback (i.e. '(un)pause')
101 [f] next track
102 [d] previous track
103 []] next directory (next track until directory part changes)
104 [[] previous directory (previous track until directory part changes)
105 [b] back to beginning of track
106 [p] loop around current position (don't combine with output buffer)
107 [.] forward
108 [,] rewind
109 [:] fast forward
110 [;] fast rewind
111 [>] fine forward
112 [<] fine rewind
113 [+] volume up
114 [-] volume down
115 [u] (un)mute volume
116 [r] RVA switch
117 [v] verbose switch
118 [l] list current playlist, indicating current track there
119 [t] display tag info (again)
120 [m] print MPEG header info (again)
121 [c] or [C] pitch up (small step, big step)
122 [x] or [X] pitch down (small step, big step)
123 [w] reset pitch to zero
124 [k] print out current position in playlist and track, for the benefit
125 of some external tool to store bookmarks
126 [h] this help
127 [q] quit
128
129 You can change these bindings to key to your liking by modifying term.h .
130
131 Note: This interface needs not to be available on _every_ platform/build.
132
133 Another note: The volume up and down is performed by changing the scale
134 factor (like the -f parameter) ... so the audio is scaled digitally in
135 the given range of the output format (usually 16bits). That means the
136 lowering the volume will decrease the dynamic range and possibly lessen
137 the quality while increasing volume can in fact increase the dynamic
138 range and thus make it better, if you deal with a silent source and no
139 clipping is necessary.
140 It is a good idea to use RVA values stored in the file for adjusting
141 low volume files, though - mpg123 handles that in addition to your
142 volume setting.
143
144 3.3 Control Interface for Frontends
145
146 There used to be several interfaces for frontends left over from that
147 past, but only one of them remains for the present and future:
148
149 The Generic Control Interface
150
151 It contains of communication of textual messages via standard input to
152 mpg123 and responses to standard output unless the -s switch for output
153 of audio data on stdout is used - then the responses come via stderr.
154
155 See doc/README.remote for usage.
156
157
158 4. Speed
159
160 mpg123 is fast. Any faster software player is probably based on some
161 hacked mpg123;-)
162 MPlayer included mpg123 source code in it's mp3lib and we have to
163 be thankful for the MPlayer folks adding SSE, 3DNowExt and AltiVec
164 optimizations over the years, which we were able to backport.
165
166 mpg123 includes the AltiVec optimization since version 0.61 and the SSE
167 and 3DNowExt optimizations since 0.66 .
168 Also, version 0.66 adds the merged x86 optimization build, which includes
169 every applicable optimization for x86 cpus except the one for i486,
170 wich is a bit special.
171
172 Now mpg123 catched up with MPlayer's mp3lib concerning decoding speed
173 on my Pentium M (which supports SSE):
174 Decoding a certain album (Queensryche's Rage for Order) to /dev/null took
175 22.4s user time with mpg123-0.66 compared to 24.7s with MPlayer-1.0rc1 .
176
177 Also, beginning with mpg123 1.8.0, there are fresh x86-64 SSE
178 optimizations (provided by Taihei Monma) which make mpg123 the fastest
179 MPEG audio decoder in my knowledge also on current 64bit x86 systems.
180 Manual optimizations continued with AVX probably being the last vector
181 instruction set that makes sense to implement the decoder for.
182
183 In 2025, a Core i7-10710U CPU needs 5.97 s for Queensryche's Rage for
184 Order with the AVX decoder, 6.01 s with x86-64 (SSE) and 9.05 s with
185 generic C code from the Ubuntu 22.04 build of mpg123 1.29.3.
186
187
188 5. Accuracy
189
190 The mpg123 engine is able to decode in full compliance to ISO/IEC 11172-3,
191 for all three layers, using floating point or integer math (the latter
192 since 1.8.1).
193 Accuracy of 16bit output depends on specific optimization in use and
194 compile-time choice about the rounding mode (which is performance
195 relevant).
196
197 The ISO test suite is incorporated in the mpg123 subversion repository
198 under svn://orgis.org/mpg123/test, nightly tests of a build (with
199 high-quality 16bit rounding) are published on the mpg123 website.
200
201 Dithered 16bit output is available as an option (the --cpu choices ending
202 with _dither). See
203
204 http://dither123.dyndns.org
205
206 on the whereabouts.
207
208 6. History
209
210 A looooong time ago (mid-90s), Michael Hipp wrote some initial mpg123
211 and made it _the_ Unix console mp3 player in the following years.
212 The exact date of birth is fuzzy in human memory, but according to the
213 master himself (Michael) mpg123 started in 1994 as an MP2 player which
214 a year later, 1995, gained MP3 ability.
215 The core decoder files have mostly 1995 as their birth year listed,
216 so one can say that mpg123 as the layer1,2,3 player was born in 1995.
217 In any case, that is a looooong time ago for a media player - especially
218 for one that is still alive!
219
220 This is the historic description:
221
222 This isn't a new player. It's a fully rewritten version originally
223 based
224 on the mpegaudio (FHG-version) package. The DCT algorithm in the
225 synthesis filter is a rewritten version of the DCT first seen
226 in the maplay
227 package, which was written by Tobias Bading
228 ([email protected]). The
229 rewrite was necessary, because the GPL may not allow this
230 copyright mix.
231 The mpegaudio package was written by various people from the
232 MPEG/audio
233 software simulation group. The maplay is under GPL .. You can
234 find the
235 original source code and the mpegaudio package on:
236 ftp.tnt.uni-hannover.de.
237
238 Especially layer3.c common.c and mpg123.h is based on the
239 dist10 package.
240 The code is fully rewritten but I'm using sometimes the
241 same variable names or similar function names as in the
242 original package.
243
244 In the current layer3.c I'm using a DCT36 first seen in Jeff
245 Tsay's
246 ([email protected]) maplay 1.2+ package. His code is
247 under GPL .. I also tried the enhancement from Mikko Tommila. His
248 code is also in layer3.c (but it's disabled at the moment, because
249 it was slightly slower than the unrolled 9 point DCT (at least on
250 _my_ system)). Theoretically it should be faster. You may try
251 it on
252 your system.
253
254 Well, that's how it started...
255 Official development ceased due to the typical lack-of-time syndrome
256 around 2002 and the free-floating patches began to seize the day.
257
258 But before that, Michael wrote or rewrote the essential code; others
259 contributed their bits.
260 The main message is:
261
262 Code is copyrighted by Michael Hipp, who made it free software under
263 the terms of the LGPL 2.1.
264
265 Please see doc/ROAD_TO_LGPL, COPYING and AUTHORS for details on that. Note
266 that the only notable legacy non-LGPL file was the old alsa output that
267 didn't work with alsa 0.9/1.0 anymore.
268 Also, there has been a libao output in the betas 0.60 for a short
269 period. Libao being generally problematic for us because of its
270 GPL license, this output is not distributed anymore in the release
271 packages. There is now a new, LGPLed alsa output that made both the old
272 alsa and libao obsolete for our purposes.
273 So, the distributed mpg123 releases actually only contain LGPL code, but
274 you get the other files from our subversion repository if you checkout
275 the trunk / version tags.
276
277 There has been quite some confusion about the licensing and "freeness"
278 of mpg123 in the past.
279 The initial "free for private use, ask me when you want to do something
280 commercial" license caused some people to avoid mpg123 and even to write
281 a replacement mimicking the interface but using a different decoding
282 engine - what was not actively developed for too long but entered the
283 "free" software sections.
284
285 The Debian (non-free section) and Gentoo distributions cared about the
286 last stable and the last development release of mpg123 over the years
287 with mainly applying security fixes. Thanks go to the distribution
288 maintainers for not letting it alone to bitrot over the years.
289
290 Thomas Orgis started to hack on mpg123 in 2004 while working on his
291 personal audio experience with mixplayd and later DerMixD, utilizing
292 the generic control interface. In Feb 2005, he crammed control interface
293 improvements together with Debian's r19 fixes and released the personal
294 fork/patch named mpg123-thor.
295 Little later that year, Nicholas J. Humphrey independently created the
296 sourceforge project and released an autotooled 0.59r under official GPL
297 flag with Debian and MacOSX fixes.
298 In the beginning of 2006, Thomas finally decided that he could work
299 "officially" on mpg123 and contacted Michael Hipp for taking over
300 maintainership.
301 Michael was all-positive about letting mpg123 really live again (and
302 perhaps see version 1.0 some time;-) and also pointed at the sourceforge
303 project that didn't see much activity since the initial release.
304 A lot of emails and some weeks later there was the two-developer team
305 of Nicholas and Thomas working on merging their mpg123 variants as well
306 as adding some features and fixes to let it shine again.
307
308 And there we are now...
309
310 7. End
311
312 Have fun!
313 ____________
314 Thomas Orgis