1mpg123(1) General Commands Manual mpg123(1)
2
6 mpg123 - play audio MPEG 1.0/2.0/2.5 stream (layers 1, 2 and 3)
7
9 mpg123 [ options ] file-or-URL...
10
12 mpg123 reads one or more files (or standard input if ``-'' is speci‐
13 fied) or URLs and plays them on the audio device (default) or outputs
14 them to stdout. file/URL is assumed to be an MPEG audio bit stream.
15
17 The following operands are supported:
18 file(s) The path name(s) of one or more input files. They must be
20 valid MPEG-1.0/2.0/2.5 audio layer 1, 2 or 3 bit streams. If a
21 dash ``-'' is specified, MPEG data will be read from the stan‐
22 dard input. Furthermore, any name starting with ``http://'' or
23 ``https://'' is recognized as URL (see next section), while a
24 leading ``file://'' is being stripped for normal local file ac‐
25 cess, for consistency (since mpg123 1.30.1).
26
28 mpg123 options may be either the traditional POSIX one letter options,
29 or the GNU style long options. POSIX style options start with a single
30 ``-'', while GNU long options start with ``--''. Option arguments (if
31 needed) follow separated by whitespace (not ``=''). Note that some op‐
32 tions can be absent from your installation when disabled in the build
33 process.
34
36 -k num, --skip num
37 Skip first num frames. By default the decoding starts at the
38 first frame.
39 -n num, --frames num
41 Decode only num frames. By default the complete stream is de‐
42 coded.
43 --fuzzy
45 Enable fuzzy seeks (guessing byte offsets or using approximate
46 seek points from Xing TOC). Without that, seeks need a first
47 scan through the file before they can jump at positions. You
48 can decide here: sample-accurate operation with gapless features
49 or faster (fuzzy) seeking.
50 -y, --no-resync
52 Do NOT try to resync and continue decoding if an error occurs in
53 the input file. Normally, mpg123 tries to keep the playback
54 alive at all costs, including skipping invalid material and
55 searching new header when something goes wrong. With this
56 switch you can make it bail out on data errors (and perhaps
57 spare your ears a bad time). Note that this switch has been re‐
58 named from --resync. The old name still works, but is not ad‐
59 vertised or recommended to use (subject to removal in future).
60 -F, --no-frankenstein
62 Disable support for Frankenstein streams. Normally, mpg123 stays
63 true to the concept of MPEG audio being just a concatenation of
64 MPEG frames. It will continue decoding even if the type of MPEG
65 frames varies wildly. With this switch, it will only decode the
66 input as long as it does not change its character (from layer I
67 to layer III, changing sampling rate, from mono to stereo),
68 silently assuming end of stream on such occasion. The switch
69 also stops decoding of compatible MPEG frames if there was an
70 Info frame (Xing header, Lame tag) that contained a length of
71 the track in MPEG frames. This comes a bit closer to the notion
72 of a MP3 file as a defined collection of MPEG frames that belong
73 together, but gets rid of the flexibility that can be fun at
74 times but mostly is hell for the programmer of the parser and
75 decoder ...
76 --network backend
78 Select network backend (helper program), choices are usually
79 auto, wget, and curl. Auto means to try the first available
80 backend.
81 --resync-limit bytes
83 Set number of bytes to search for valid MPEG data once lost in
84 stream; <0 means search whole stream. If you know there are
85 huge chunks of invalid data in your files... here is your ham‐
86 mer. Note: Only since version 1.14 this also increases the
87 amount of junk skipped on beginning.
88 -u auth, --auth auth
90 HTTP authentication to use when receiving files via HTTP. The
91 format used is user:password. Mpg123 will clear this quickly,
92 but it may still appear in sight of other users or even just in
93 your shell history. You may seek alternative ways to specify
94 that to your network backend.
95 --auth-file authfile
97 Provide the authentication info via given file instead of com‐
98 mand line directly.
99 --ignore-mime
101 Ignore MIME types given by HTTP server. If you know better and
102 want mpg123 to decode something the server thinks is image/png,
103 then just do it.
104 --no-icy-meta
106 Do not accept ICY meta data.
107 --streamdump filename
109 Dump a copy of the input data (as read by libmpg123) to the
110 given file. This enables you to store a web stream to disk
111 while playing, or just create a concatenation of the local files
112 you play for ... why not?
113 --icy-interval bytes
115 This setting enables you to play a stream dump containing ICY
116 metadata at the given interval in bytes (the value of the icy-
117 metaint HTTP response header). Without it, such a stream will
118 play, but will cause regular decoding glitches with resync.
119 --no-seekbuffer
121 Disable the default micro-buffering of non-seekable streams that
122 gives the parser a safer footing.
123 -@ file, --list file
125 Read filenames and/or URLs of MPEG audio streams from the speci‐
126 fied file in addition to the ones specified on the command line
127 (if any). Note that file can be either an ordinary file, a dash
128 ``-'' to indicate that a list of filenames/URLs is to be read
129 from the standard input, or an URL pointing to a an appropriate
130 list file. Note: only one -@ option can be used (if more than
131 one is specified, only the last one will be recognized). Fur‐
132 thermore, for HTTP resources, the MIME type information will be
133 used to re-open an actual MPEG stream as such instead of treat‐
134 ing it as playlist file. So you could just always use -@ for web
135 resources without bothering if it is a playlist or already the
136 resolved stream address.
137 -l n, --listentry n
139 Of the playlist, play specified entry only. n is the number of
140 entry starting at 1. A value of 0 is the default and means play‐
141 ing the whole list, a negative value means showing of the list
142 of titles with their numbers...
143 --continue
145 Enable playlist continuation mode. This changes frame skipping
146 to apply only to the first track and also continues to play fol‐
147 lowing tracks in playlist after the selected one. Also, the op‐
148 tion to play a number of frames only applies to the whole
149 playlist. Basically, this tries to treat the playlist more like
150 one big stream (like, an audio book). The current track number
151 in list (1-based) and frame number (0-based) are printed at exit
152 (useful if you interrupted playback and want to continue later).
153 Note that the continuation info is printed to standard output
154 unless the switch for piping audio data to standard out is used.
155 Also, it really makes sense to work with actual playlist files
156 instead of lists of file names as arguments, to keep track posi‐
157 tions consistent.
158 --loop times
160 for looping track(s) a certain number of times, < 0 means infi‐
161 nite loop (not with --random!).
162 --keep-open
164 For remote control mode: Keep loaded file open after reaching
165 end.
166 --timeout seconds
168 Timeout in (integer) seconds before declaring a stream dead (if
169 <= 0, wait forever).
170 -z, --shuffle
172 Shuffle play. Randomly shuffles the order of files specified on
173 the command line, or in the list file.
174 -Z, --random
176 Continuous random play. Keeps picking a random file from the
177 command line or the play list. Unlike shuffle play above, ran‐
178 dom play never ends, and plays individual songs more than once.
179 -i, --index
181 Index / scan through the track before playback. This fills the
182 index table for seeking (if enabled in libmpg123) and may make
183 the operating system cache the file contents for smoother oper‐
184 ating on playback.
185 --index-size size
187 Set the number of entries in the seek frame index table.
188 --preframes num
190 Set the number of frames to be read as lead-in before a seeked-
191 to position. This serves to fill the layer 3 bit reservoir,
192 which is needed to faithfully reproduce a certain sample at a
193 certain position. Note that for layer 3, a minimum of 1 is en‐
194 forced (because of frame overlap), and for layer 1 and 2, this
195 is limited to 2 (no bit reservoir in that case, but engine spin-
196 up anyway).
197
200 -o module, --output module
201 Select audio output module. You can provide a comma-separated
202 list to use the first one that works. Also see -a.
203 --list-modules
205 List the available modules.
206 --list-devices
208 List the available output devices for given output module. If
209 there is no functionality to list devices in the chosen module,
210 an error will be printed and mpg123 will exit with a non-zero
211 code.
212 -a dev, --audiodevice dev
214 Specify the audio device to use. The default as well as the
215 possible values depend on the active output. For the JACK out‐
216 put, a comma-separated list of ports to connect to (for each
217 channel) can be specified.
218 -s, --stdout
220 The decoded audio samples are written to standard output, in‐
221 stead of playing them through the audio device. This option
222 must be used if your audio hardware is not supported by mpg123.
223 The output format per default is raw (headerless) linear PCM au‐
224 dio data, 16 bit, stereo, host byte order (you can force mono or
225 8bit).
226 -O file, --outfile
228 Write raw output into a file (instead of simply redirecting
229 standard output to a file with the shell).
230 -w file, --wav
232 Write output as WAV file. This will cause the MPEG stream to be
233 decoded and saved as file file , or standard output if - is used
234 as file name. You can also use --au and --cdr for AU and CDR
235 format, respectively. Note that WAV/AU writing to non-seekable
236 files, or redirected stdout, needs some thought. Since 1.16.0,
237 the logic changed to writing the header with the first actual
238 data. This avoids spurious WAV headers in a pipe, for example.
239 The result of decoding nothing to WAV/AU is a file consisting
240 just of the header when it is seekable and really nothing when
241 not (not even a header). Correctly writing data with prophetic
242 headers to stdout is no easy business.
243 --au file
245 Does not play the MPEG file but writes it to file in SUN audio
246 format. If - is used as the filename, the AU file is written to
247 stdout. See paragraph about WAV writing for header fun with non-
248 seekable streams.
249 --cdr file
251 Does not play the MPEG file but writes it to file as a CDR file.
252 If - is used as the filename, the CDR file is written to stdout.
253 --reopen
255 Forces reopen of the audiodevice after ever song
256 --cpu decoder-type
258 Selects a certain decoder (optimized for specific CPU), for ex‐
259 ample i586 or MMX. The list of available decoders can vary; de‐
260 pending on the build and what your CPU supports. This option is
261 only available when the build actually includes several opti‐
262 mized decoders.
263 --test-cpu
265 Tests your CPU and prints a list of possible choices for --cpu.
266 --list-cpu
268 Lists all available decoder choices, regardless of support by
269 your CPU.
270 -g gain, --gain gain
272 [DEPRECATED] Set audio hardware output gain (default: don't
273 change). The unit of the gain value is hardware and output mod‐
274 ule dependent. (This parameter is only provided for backwards
275 compatibility and may be removed in the future without prior no‐
276 tice. Use the audio player for playing and a mixer app for mix‐
277 ing, UNIX style!)
278 -f factor, --scale factor
280 Change scale factor (default: 32768).
281 --rva-mix, --rva-radio
283 Enable RVA (relative volume adjustment) using the values stored
284 for ReplayGain radio mode / mix mode with all tracks roughly
285 equal loudness. The first valid information found in ID3V2 Tags
286 (Comment named RVA or the RVA2 frame) or ReplayGain header in
287 Lame/Info Tag is used.
288 --rva-album, --rva-audiophile
290 Enable RVA (relative volume adjustment) using the values stored
291 for ReplayGain audiophile mode / album mode with usually the ef‐
292 fect of adjusting album loudness but keeping relative loudness
293 inside album. The first valid information found in ID3V2 Tags
294 (Comment named RVA_ALBUM or the RVA2 frame) or ReplayGain header
295 in Lame/Info Tag is used.
296 -0, --single0; -1, --single1
298 Decode only channel 0 (left) or channel 1 (right), respectively.
299 These options are available for stereo MPEG streams only.
300 -m, --mono, --mix, --singlemix
302 Mix both channels / decode mono. It takes less CPU time than
303 full stereo decoding.
304 --stereo
306 Force stereo output
307 -r rate, --rate rate
309 Set sample rate (default: automatic). You may want to change
310 this if you need a constant bitrate independent of the mpeg
311 stream rate. mpg123 automagically converts the rate. You should
312 then combine this with --stereo or --mono.
313 --resample method
315 Set resampling method to employ if forcing an output rate.
316 Choices (case-insensitive) are NtoM, dirty, and fine. The fine
317 resampler is the default. It employs libsyn123's low-latency
318 fairly efficient resampler to postprocess the output from
319 libmpg123 instead of the fast but very crude NtoM decoder (drop
320 sample method) that mpg123 offers since decades. If you are re‐
321 ally low on CPU time, choose NtoM, as the resampler usually
322 needs more time than the MPEG decoder itself. The mpg123 pro‐
323 gram is smart enough to combine the 2to1 or 4to1 downsampling
324 modes with the postprocessing for extreme downsampling.
325 -2, --2to1; -4, --4to1
327 Performs a downsampling of ratio 2:1 (22 kHz from 44.1 kHz) or
328 4:1 (11 kHz) on the output stream, respectively. Saves some CPU
329 cycles, but of course throws away the high frequencies, as the
330 decoder does not bother producing them.
331 --pitch value
333 Set a pitch change (speedup/down, 0 is neutral; 0.05 is 5%
334 speedup). When not enforcing an output rate, this changes the
335 output sampling rate, so it only works in the range your audio
336 system/hardware supports. When you combine this with a fixed
337 output rate, it modifies a software resampling ratio instead.
338 --8bit Forces 8bit output
340 --float
342 Forces f32 encoding
343 -e enc, --encoding enc
345 Choose output sample encoding. Possible values look like f32
346 (32-bit floating point), s32 (32-bit signed integer), u32
347 (32-bit unsigned integer) and the variants with different num‐
348 bers of bits (s24, u24, s16, u16, s8, u8) and also special vari‐
349 ants like ulaw and alaw 8-bit. See the output of mpg123's
350 longhelp for actually available encodings.
351 -d n, --doublespeed n
353 Only play every n'th frame. This will cause the MPEG stream to
354 be played n times faster, which can be used for special effects.
355 Can also be combined with the --halfspeed option to play 3 out
356 of 4 frames etc. Don't expect great sound quality when using
357 this option.
358 -h n, --halfspeed n
360 Play each frame n times. This will cause the MPEG stream to be
361 played at 1/n'th speed (n times slower), which can be used for
362 special effects. Can also be combined with the --doublespeed op‐
363 tion to double every third frame or things like that. Don't ex‐
364 pect great sound quality when using this option.
365 -E file, --equalizer
367 Enables equalization, taken from file. The file needs to con‐
368 tain 32 lines of data, additional comment lines may be prefixed
369 with #. Each data line consists of two floating-point entries,
370 separated by whitespace. They specify the multipliers for left
371 and right channel of a certain frequency band, respectively.
372 The first line corresponds to the lowest, the 32nd to the high‐
373 est frequency band. Note that you can control the equalizer in‐
374 teractively with the generic control interface. Also note that
375 these are the 32 bands of the MPEG codec, not spaced like you
376 would see for a usual graphic equalizer. The upside is that
377 there is zero computational cost in addition to decoding. The
378 downside is that you roughly have bass in band 0, (upper) mids
379 in band 1, treble in all others.
380 --gapless
382 Enable code that cuts (junk) samples at beginning and end of
383 tracks, enabling gapless transitions between MPEG files when en‐
384 coder padding and codec delays would prevent it. This is en‐
385 abled per default beginning with mpg123 version 1.0.0 .
386 --no-gapless
388 Disable the gapless code. That gives you MP3 decodings that in‐
389 clude encoder delay and padding plus mpg123's decoder delay.
390 --no-infoframe
392 Do not parse the Xing/Lame/VBR/Info frame, decode it instead
393 just like a stupid old MP3 hardware player. This implies dis‐
394 abling of gapless playback as the necessary information is in
395 said metadata frame.
396 -D n, --delay n
398 Insert a delay of n seconds before each track.
399 -o h, --headphones
401 Direct audio output to the headphone connector (some hardware
402 only; AIX, HP, SUN).
403 -o s, --speaker
405 Direct audio output to the speaker (some hardware only; AIX,
406 HP, SUN).
407 -o l, --lineout
409 Direct audio output to the line-out connector (some hardware
410 only; AIX, HP, SUN).
411 -b size, --buffer size
413 Use an audio output buffer of size Kbytes. This is useful to
414 bypass short periods of heavy system activity, which would nor‐
415 mally cause the audio output to be interrupted. You should
416 specify a buffer size of at least 1024 (i.e. 1 Mb, which equals
417 about 6 seconds of audio data) or more; less than about 300 does
418 not make much sense. The default is 0, which turns buffering
419 off.
420 --preload fraction
422 Wait for the buffer to be filled to fraction before starting
423 playback (fraction between 0 and 1). You can tune this pre‐
424 buffering to either get faster sound to your ears or safer unin‐
425 terrupted web radio. Default is 0.2 (wait for 20 % of buffer to
426 be full, changed from 1 in version 1.23).
427 --devbuffer seconds
429 Set device buffer in seconds; <= 0 means default value. This is
430 the small buffer between the application and the audio backend,
431 possibly directly related to hardware buffers.
432 --smooth
434 Keep buffer over track boundaries -- meaning, do not empty the
435 buffer between tracks for possibly some added smoothness.
436
439 -t, --test
440 Test mode. The audio stream is decoded, but no output occurs.
441 -c, --check
443 Check for filter range violations (clipping), and report them
444 for each frame if any occur.
445 -v, --verbose
447 Increase the verbosity level. For example, displays the frame
448 numbers during decoding.
449 -q, --quiet
451 Quiet. Suppress diagnostic messages.
452 -C, --control
454 Enable terminal control keys. This is enabled automatically if a
455 terminal is detected. By default use 's' or the space bar to
456 stop/restart (pause, unpause) playback, 'f' to jump forward to
457 the next song, 'b' to jump back to the beginning of the song,
458 ',' to rewind, '.' to fast forward, and 'q' to quit. Type 'h'
459 for a full list of available controls.
460 --no-control
462 Disable terminal control even if terminal is detected.
463 --title
465 In an xterm, rxvt, screen, iris-ansi (compatible, TERM environ‐
466 ment variable is examined), change the window's title to the
467 name of song currently playing.
468 --name name
470 Set the name of this instance, possibly used in various places.
471 This sets the client name for JACK output.
472 --long-tag
474 Display ID3 tag info always in long format with one line per
475 item (artist, title, ...)
476 --utf8 Regardless of environment, print metadata in UTF-8 (otherwise,
478 when not using UTF-8 locale, you'll get ASCII stripdown).
479 -R, --remote
481 Activate generic control interface. mpg123 will then read and
482 execute commands from stdin. Basic usage is ``load <filename> ''
483 to play some file and the obvious ``pause'', ``command. ``jump
484 <frame>'' will jump/seek to a given point (MPEG frame number).
485 Issue ``help'' to get a full list of commands and syntax.
486 --remote-err
488 Print responses for generic control mode to standard error, not
489 standard out. This is automatically triggered when using -s.
490 --fifo path
492 Create a fifo / named pipe on the given path and use that for
493 reading commands instead of standard input.
494 --aggressive
496 Tries to get higher priority
497 -T, --realtime
499 Tries to gain realtime priority. This option usually requires
500 root privileges to have any effect.
501 -?, --help
503 Shows short usage instructions.
504 --longhelp
506 Shows long usage instructions.
507 --version
509 Print the version string.
510
512 In addition to reading MPEG audio streams from ordinary files and from
513 the standard input, mpg123 supports retrieval of MPEG audio streams or
514 playlists via the HTTP protocol, which is used in the World Wide Web
515 (WWW). Such files are specified using a so-called URL, which starts
516 with http:// or https://. When a file with that prefix is encountered,
517 mpg123 since 1.30.0 will by default call an external helper program
518 (either wget(1) or curl(1), see the --network option) to retrieve the
519 resource. You can configure access via a proxy server using the stan‐
520 dard environment variables those programs support. The --proxy option
521 that mpg123 before 1.30.0 used for its internal network code is gone in
522 the default build now and will probably disappear for good with 1.31.1.
523 Note that, in order to play MPEG audio files from a WWW server, it is
525 necessary that the connection to that server is fast enough. For exam‐
526 ple, a 128 kbit/s MPEG file requires the network connection to be at
527 least 128 kbit/s (16 kbyte/s) plus protocol overhead. If you suffer
528 from short network outages, you should try the -b option (buffer) to
529 bypass such outages. If your network connection is generally not fast
530 enough to retrieve MPEG audio files in realtime, you can first download
531 the files to your local harddisk (e.g. using wget(1)) and then play
532 them from there.
533 Streams with embedded ICY metadata are supported, the interval being
535 communicated via HTTP headers or --icy-interval.
536
538 When in terminal control mode, you can quit via pressing the q key,
539 while any time you can abort mpg123 by pressing Ctrl-C. If not in ter‐
540 minal control mode, this will skip to the next file (if any). If you
541 want to abort playing immediately in that case, press Ctrl-C twice in
542 short succession (within about one second).
543 Note that the result of quitting mpg123 pressing Ctrl-C might not be
545 audible immediately, due to audio data buffering in the audio device.
546 This delay is system dependent, but it is usually not more than one or
547 two seconds.
548
551 In verbose mode, mpg123 updates a line with various information center‐
552 ing around the current playback position. On any decent terminal, the
553 line also works as a progress bar in the current file by reversing
554 video for a fraction of the line according to the current position. An
555 example for a full line is this:
556 > 0291+0955 00:01.68+00:28.22 [00:05.30] mix 100=085 192 kb/s
558 576 B acc 18 clip p+0.014
559 The information consists of, in order:
561 > single-character playback state (``>'' for playing, ``='' for
563 pausing/looping, ``_'' for stopped)
564 0291+0955
566 current frame offset and number of remaining frames after the
567 plus sign
568 00:01.68+00:28.22
570 current position from and remaining time in human terms (hours,
571 minutes, seconds)
572 [00:05.30]
574 fill of the output buffer in terms of playback time, if the buf‐
575 fer is enabled
576 mix selected RVA mode (possible values: mix, alb (album), and ---
578 (neutral, off))
579 100=085
581 set volume and the RVA-modified effective volume after the equal
582 sign
583 192 kb/s
585 current bitrate
586 576 B size of current frame in bytes
588 acc if positions are accurate, possible values are ``acc'' for accu‐
590 rate positions or ``fuz'' for fuzzy (with guessed byte offsets
591 using mean frame size)
592 18 clip
594 amount of clipped samples, non-zero only if decoder reports that
595 (generic does, some optimized ones not)
596 p+0.014
598 pitch change (increased/decreased playback sampling rate on user
599 request)
600
603 MPEG audio decoding requires a good deal of CPU performance, especially
604 layer-3. To decode it in realtime, you should have at least an
605 i486DX4, Pentium, Alpha, SuperSparc or equivalent processor. You can
606 also use the -m option to decode mono only, which reduces the CPU load
607 somewhat for layer-3 streams. See also the -2 and -4 options.
608 If everything else fails, have mpg123 decode to a file and then use an
610 appropriate utility to play that file with less CPU load. Most proba‐
611 bly you can configure mpg123 to produce a format suitable for your au‐
612 dio device (see above about encodings and sampling rates).
613 If your system is generally fast enough to decode in realtime, but
615 there are sometimes periods of heavy system load (such as cronjobs,
616 users logging in remotely, starting of ``big'' programs etc.) causing
617 the audio output to be interrupted, then you should use the -b option
618 to use a buffer of reasonable size (at least 1000 Kbytes).
619
621 Up to version 1.25.x, mpg123 always returned exit code 0 also for com‐
622 plete junk on the input side. Fatal errors were only considered for
623 output. With version 1.26.0, this changed to the behaviour described
624 below.
625 When not using the remote control interface (which returns input errors
627 as text messages), the process exit code is zero (success) only if all
628 tracks in a playlist had at least one frame parsed, even if it did not
629 decode cleanly, or are empty, MPEG-wise (perhaps only metadata, or re‐
630 ally an empty file). When you decode nothing, nothing is the result
631 and that is fine. When a track later aborts because of parser errors or
632 breakdown of the network communication, this is treated as end of a
633 track, but does not make the process as such fail. One really bad (or
634 non-existing) stream in the playlist results in a non-zero error code,
635 consistent with other UNIX tools.
636 An error in audio output results in the process ending with a non-zero
638 exit code immediately, regardless of how much data has been success‐
639 fully played before. The forgiveness is only on the input side.
640
642 Mostly MPEG-1 layer 2 and 3 are tested in real life. Please report any
643 issues and provide test files to help fixing them.
644 No CRC error checking is performed. But the decoder is built and tested
646 to behave nicely with damaged streams. Mostly, damaged frames will just
647 be silent.
648 Some platforms lack audio hardware support; you may be able to use the
650 -s switch to feed the decoded data to a program that can play it on
651 your audio device.
652
654 Maintainer:
655 Thomas Orgis <maintainer@mpg123.org>, <thomas@orgis.org>
656 Original Creator:
658 Michael Hipp
659 Uses code or ideas from various people, see the AUTHORS file accompany‐
661 ing the source code.
662
664 mpg123 is licensed under the GNU Lesser/Library General Public License,
665 LGPL, version 2.1 .
666
668 http://www.mpg123.org
669 http://sourceforge.net/projects/mpg123
670 11 Jul 2022 mpg123(1)