1mpg123(1)                   General Commands Manual                  mpg123(1)
2
3
4

NAME

6       mpg123 - play audio MPEG 1.0/2.0/2.5 stream (layers 1, 2 and 3)
7

SYNOPSIS

9       mpg123 [ options ] file-or-URL...
10

DESCRIPTION

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

OPERANDS

17       The following operands are supported:
18
19       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://'' is
23               recognized as URL (see next section).
24

OPTIONS

26       mpg123  options may be either the traditional POSIX one letter options,
27       or the GNU style long options.  POSIX style options start with a single
28       ``-'',  while GNU long options start with ``--''.  Option arguments (if
29       needed) follow separated by whitespace (not  ``='').   Note  that  some
30       options can be absent from your installation when disabled in the build
31       process.
32

INPUT OPTIONS

34       -k num, --skip num
35              Skip first num frames.  By default the decoding  starts  at  the
36              first frame.
37
38       -n num, --frames num
39              Decode  only  num  frames.   By  default  the complete stream is
40              decoded.
41
42       --fuzzy
43              Enable fuzzy seeks (guessing byte offsets or  using  approximate
44              seek  points  from  Xing TOC).  Without that, seeks need a first
45              scan through the file before they can jump  at  positions.   You
46              can decide here: sample-accurate operation with gapless features
47              or faster (fuzzy) seeking.
48
49       -y, --no-resync
50              Do NOT try to resync and continue decoding if an error occurs in
51              the  input  file.  Normally,  mpg123  tries to keep the playback
52              alive at all costs,  including  skipping  invalid  material  and
53              searching  new  header  when  something  goes  wrong.  With this
54              switch you can make it bail out  on  data  errors  (and  perhaps
55              spare  your  ears  a  bad  time). Note that this switch has been
56              renamed from --resync.  The old name still  works,  but  is  not
57              advertised or recommened to use (subject to removal in future).
58
59       --resync-limit bytes
60              Set  number  of bytes to search for valid MPEG data once lost in
61              stream; <0 means search whole stream.  If  you  know  there  are
62              huge  chunks  of invalid data in your files... here is your ham‐
63              mer.  Note: Only since version  1.14  this  also  increases  the
64              amount of junk skipped on beginning.
65
66       -p URL | none, --proxy URL | none
67              The  specified  proxy will be used for HTTP requests.  It should
68              be specified as full URL (``http://host.domain:port/''), but the
69              ``http://''  prefix,  the port number and the trailing slash are
70              optional (the default port is 80).  Specifying none means not to
71              use  any  proxy, and to retrieve files directly from the respec‐
72              tive servers.  See also the ``HTTP SUPPORT'' section.
73
74       -u auth, --auth auth
75              HTTP authentication to use when recieving files via  HTTP.   The
76              format used is user:password.
77
78       --ignore-mime
79              Ignore  MIME  types given by HTTP server. If you know better and
80              want mpg123 to decode something the server thinks is  image/png,
81              then just do it.
82
83       --no-seekbuffer
84              Disable the default micro-buffering of non-seekable streams that
85              gives the parser a safer footing.
86
87       -@ file, --list file
88              Read filenames and/or URLs of MPEG audio streams from the speci‐
89              fied  file in addition to the ones specified on the command line
90              (if any).  Note that file can be either an ordinary file, a dash
91              ``-''  to  indicate  that a list of filenames/URLs is to be read
92              from the standard input, or an URL pointing to a an  appropriate
93              list  file.   Note: only one -@ option can be used (if more than
94              one is specified, only the last one will be recognized).
95
96       -l n, --listentry n
97              Of the playlist, play specified entry only.  n is the number  of
98              entry  starting  at  1.  A  value  of 0 is the default and means
99              playling the whole list,  a negative value means showing of  the
100              list of titles with their numbers...
101
102       --continue
103              Enable  playlist  continuation mode. This changes frame skipping
104              to apply only to the first track and also continues to play fol‐
105              lowing  tracks  in  playlist  after  the selected one. Also, the
106              option to play a number of frames  only  applies  to  the  whole
107              playlist.  Basically, this tries to treat the playlist more like
108              one big stream (like, an audio book).  The current track  number
109              in list (1-based) and frame number (0-based) are printed at exit
110              (useful if you interrupted playback and want to continue later).
111              Note  that  the  continuation info is printed to standard output
112              unless the switch for piping audio data to standard out is used.
113              Also,  it  really makes sense to work with actual playlist files
114              instead of lists of file names as arguments, to keep track posi‐
115              tions consistent.
116
117       --loop times
118              for  looping track(s) a certain number of times, < 0 means infi‐
119              nite loop (not with --random!).
120
121       --keep-open
122              For remote control mode: Keep loaded file  open  after  reaching
123              end.
124
125       --timeout seconds
126              Timeout  in (integer) seconds before declaring a stream dead (if
127              <= 0, wait forever).
128
129       -z, --shuffle
130              Shuffle play.  Randomly shuffles the order of files specified on
131              the command line, or in the list file.
132
133       -Z, --random
134              Continuous  random  play.   Keeps picking a random file from the
135              command line or the play list.  Unlike shuffle play above,  ran‐
136              dom play never ends, and plays individual songs more than once.
137
138       --no-icy-meta
139              Do not accept ICY meta data.
140
141       -i, --index
142              Index  / scan through the track before playback.  This fills the
143              index table for seeking (if enabled in libmpg123) and  may  make
144              the  operating system cache the file contents for smoother oper‐
145              ating on playback.
146
147       --index-size size
148              Set the number of entries in the seek frame index table.
149
150       --preframes num
151              Set the number of frames to be read as lead-in before a  seeked-
152              to  position.   This  serves  to fill the layer 3 bit reservoir,
153              which is needed to faithfully reproduce a certain  sample  at  a
154              certain  position.   Note  that  for  layer 3, a minimum of 1 is
155              enforced (because of frame overlap), and for layer 1 and 2, this
156              is limited to 2 (no bit reservoir in that case, but engine spin-
157              up anyway).
158
159

OUTPUT and PROCESSING OPTIONS

161       -o module, --output module
162              Select audio output module. You can  provide  a  comma-separated
163              list to use the first one that works.
164
165       --list-modules
166              List the available modules.
167
168       -a dev, --audiodevice dev
169              Specify  the  audio device to use.  The default is system-depen‐
170              dent (usually /dev/audio or /dev/dsp).  Use this option  if  you
171              have  multiple  audio  devices  and  the default is not what you
172              want.
173
174       -s, --stdout
175              The decoded  audio  samples  are  written  to  standard  output,
176              instead  of  playing them through the audio device.  This option
177              must be used if your audio hardware is not supported by  mpg123.
178              The  output  format  per  default is raw (headerless) linear PCM
179              audio data, 16 bit, stereo, host byte order (you can force  mono
180              or 8bit).
181
182       -O file, --outfile
183              Write  raw  output  into  a  file (instead of simply redirecting
184              standard output to a file with the shell).
185
186       -w file, --wav
187              Write output as WAV file. This will cause the MPEG stream to  be
188              decoded and saved as file file , or standard output if - is used
189              as file name. You can also use --au and --cdr  for  AU  and  CDR
190              format,  respectively.  Note that WAV/AU writing to non-seekable
191              files, or redirected stdout, needs some thought.  Since  1.16.0,
192              the  logic  changed  to writing the header with the first actual
193              data. This avoids spurious WAV headers in a pipe,  for  example.
194              The  result  of  decoding nothing to WAV/AU is a file consisting
195              just of the header when it is seekable and really  nothing  when
196              not  (not  even a header). Correctly writing data with prophetic
197              headers to stdout is no easy business.
198
199       --au file
200              Does not play the MPEG file but writes it to file in  SUN  audio
201              format.  If - is used as the filename, the AU file is written to
202              stdout. See paragraph about WAV writing for header fun with non-
203              seekable streams.
204
205       --cdr file
206              Does not play the MPEG file but writes it to file as a CDR file.
207              If - is used as the filename, the CDR file is written to stdout.
208
209       --reopen
210              Forces reopen of the audiodevice after ever song
211
212       --cpu decoder-type
213              Selects a certain decoder  (optimized  for  specific  CPU),  for
214              example  i586  or MMX.  The list of available decoders can vary;
215              depending on the build and what your CPU supports.  This options
216              is  only availabe when the build actually includes several opti‐
217              mized decoders.
218
219       --test-cpu
220              Tests your CPU and prints a list of possible choices for --cpu.
221
222       --list-cpu
223              Lists all available decoder choices, regardless  of  support  by
224              your CPU.
225
226       -g gain, --gain gain
227              [DEPRECATED]  Set  audio  hardware  output  gain (default: don't
228              change). The unit of the gain value is hardware and output  mod‐
229              ule  dependent.   (This parameter is only provided for backwards
230              compatibility and may be removed in  the  future  without  prior
231              notice.  Use  the  audio  player for playing and a mixer app for
232              mixing, UNIX style!)
233
234       -f factor, --scale factor
235              Change scale factor (default: 32768).
236
237       --rva-mix, --rva-radio
238              Enable RVA (relative volume adjustment) using the values  stored
239              for  ReplayGain  radio  mode  / mix mode with all tracks roughly
240              equal loudness.  The first valid information found in ID3V2 Tags
241              (Comment  named  RVA  or the RVA2 frame) or ReplayGain header in
242              Lame/Info Tag is used.
243
244       --rva-album, --rva-audiophile
245              Enable RVA (relative volume adjustment) using the values  stored
246              for  ReplayGain  audiophile  mode  / album mode with usually the
247              effect of adjusting album loudness but keeping relative loudness
248              inside  album.   The first valid information found in ID3V2 Tags
249              (Comment named RVA_ALBUM or the RVA2 frame) or ReplayGain header
250              in Lame/Info Tag is used.
251
252       -0, --single0; -1, --single1
253              Decode only channel 0 (left) or channel 1 (right), respectively.
254              These options are available for stereo MPEG streams only.
255
256       -m, --mono, --mix, --singlemix
257              Mix both channels / decode mono. It takes  less  CPU  time  than
258              full stereo decoding.
259
260       --stereo
261              Force stereo output
262
263       -r rate, --rate rate
264              Set  sample  rate  (default: automatic).  You may want to change
265              this if you need a constant  bitrate  independent  of  the  mpeg
266              stream  rate. mpg123 automagically converts the rate. You should
267              then combine this with --stereo or --mono.
268
269       -2, --2to1; -4, --4to1
270              Performs a downsampling of ratio 2:1 (22 kHz) or 4:1 (11 kHz) on
271              the  output  stream, respectively. Saves some CPU cycles, but at
272              least the 4:1 ratio sounds ugly.
273
274       --pitch value
275              Set hardware pitch (speedup/down, 0 is  neutral;  0.05  is  5%).
276              This  changes  the output sampling rate, so it only works in the
277              range your audio system/hardware supports.
278
279       --8bit Forces 8bit output
280
281       --float
282              Forces f32 encoding
283
284       -e enc, --encoding enc
285              Choose output sample encoding. Possible  values  look  like  f32
286              (32-bit  floating  point),  s32  (32-bit  signed  integer),  u32
287              (32-bit unsigned integer) and the variants with  different  num‐
288              bers of bits (s24, u24, s16, u16, s8, u8) and also special vari‐
289              ants like ulaw and alaw  8-bit.   See  the  output  of  mpg123's
290              longhelp for actually available encodings.
291
292       -d n, --doublespeed n
293              Only  play every n'th frame.  This will cause the MPEG stream to
294              be played n times faster, which can be used for special effects.
295              Can  also  be combined with the --halfspeed option to play 3 out
296              of 4 frames etc.  Don't expect great sound  quality  when  using
297              this option.
298
299       -h n, --halfspeed n
300              Play  each frame n times.  This will cause the MPEG stream to be
301              played at 1/n'th speed (n times slower), which can be  used  for
302              special  effects.  Can  also  be combined with the --doublespeed
303              option to double every third frame or things like  that.   Don't
304              expect great sound quality when using this option.
305
306       -E file, --equalizer
307              Enables  equalization,  taken from file.  The file needs to con‐
308              tain 32 lines of data, additional comment lines may be  prefixed
309              with  #.  Each data line consists of two floating-point entries,
310              separated by whitespace.  They specify the multipliers for  left
311              and  right  channel  of  a certain frequency band, respectively.
312              The first line corresponds to the lowest, the 32nd to the  high‐
313              est  frequency  band.   Note  that you can control the equalizer
314              interactively with the generic control interface.
315
316       --gapless
317              Enable code that cuts (junk) samples at  beginning  and  end  of
318              tracks,  enabling  gapless  transitions  between MPEG files when
319              encoder padding and codec delays  would  prevent  it.   This  is
320              enabled per default beginning with mpg123 version 1.0.0 .
321
322       --no-gapless
323              Disable  the  gapless  code.  That  gives you MP3 decodings that
324              include encoder delay and padding plus mpg123's decoder delay.
325
326       --no-infoframe
327              Do not parse the Xing/Lame/VBR/Info  frame,  decode  it  instead
328              just  like  a stupid old MP3 hardware player.  This implies dis‐
329              abling of gapless playback as the necessary  information  is  in
330              said metadata frame.
331
332       -D n, --delay n
333              Insert a delay of n seconds before each track.
334
335       -o h, --headphones
336              Direct  audio  output  to the headphone connector (some hardware
337              only; AIX, HP, SUN).
338
339       -o s, --speaker
340              Direct audio output to the speaker  (some  hardware  only;  AIX,
341              HP, SUN).
342
343       -o l, --lineout
344              Direct  audio  output  to  the line-out connector (some hardware
345              only; AIX, HP, SUN).
346
347       -b size, --buffer size
348              Use an audio output buffer of size Kbytes.  This  is  useful  to
349              bypass  short periods of heavy system activity, which would nor‐
350              mally cause the audio output  to  be  interrupted.   You  should
351              specify  a buffer size of at least 1024 (i.e. 1 Mb, which equals
352              about 6 seconds of audio data) or more; less than about 300 does
353              not  make  much  sense.  The default is 0, which turns buffering
354              off.
355
356       --preload fraction
357              Wait for the buffer to be filled  to  fraction  before  starting
358              playback  (fraction  between  0  and  1). You can tune this pre‐
359              buffering to either get faster sound to your ears or safer unin‐
360              terrupted web radio.  Default is 0.2 (wait for 20 % of buffer to
361              be full, changed from 1 in version 1.23).
362
363       --devbuffer seconds
364              Set device buffer in seconds; <= 0 means default value. This  is
365              the  small buffer between the application and the audio backend,
366              possibly directly related to hardware buffers.
367
368       --smooth
369              Keep buffer over track boundaries -- meaning, do not  empty  the
370              buffer between tracks for possibly some added smoothness.
371
372

MISC OPTIONS

374       -t, --test
375              Test mode.  The audio stream is decoded, but no output occurs.
376
377       -c, --check
378              Check  for  filter  range violations (clipping), and report them
379              for each frame if any occur.
380
381       -v, --verbose
382              Increase the verbosity level.  For example, displays  the  frame
383              numbers during decoding.
384
385       -q, --quiet
386              Quiet.  Suppress diagnostic messages.
387
388       -C, --control
389              Enable terminal control keys. This is enabled automatically if a
390              terminal is detected.  By default use 's' or the  space  bar  to
391              stop/restart  (pause,  unpause) playback, 'f' to jump forward to
392              the next song, 'b' to jump back to the beginning  of  the  song,
393              ','  to  rewind, '.' to fast forward, and 'q' to quit.  Type 'h'
394              for a full list of available controls.
395
396       --no-control
397              Disable terminal control even if terminal is detected.
398
399       --title
400              In an xterm, rxvt, screen, iris-ansi (compatible, TERM  environ‐
401              ment  variable  is  examined),  change the window's title to the
402              name of song currently playing.
403
404       --name name
405              Set the name of this instance, possibly used in various  places.
406              This sets the client name for JACK output.
407
408       --long-tag
409              Display  ID3  tag  info  always in long format with one line per
410              item (artist, title, ...)
411
412       --utf8 Regardless of environment, print metadata in  UTF-8  (otherwise,
413              when not using UTF-8 locale, you'll get ASCII stripdown).
414
415       -R, --remote
416              Activate  generic  control interface.  mpg123 will then read and
417              execute commands from stdin. Basic usage is ``load <filename> ''
418              to  play some file and the obvious ``pause'', ``command.  ``jump
419              <frame>'' will jump/seek to a given point (MPEG  frame  number).
420              Issue ``help'' to get a full list of commands and syntax.
421
422       --remote-err
423              Print  responses for generic control mode to standard error, not
424              standard out.  This is automatically triggered when using -s N.
425
426       --fifo path
427              Create a fifo / named pipe on the given path and  use  that  for
428              reading commands instead of standard input.
429
430       --aggressive
431              Tries to get higher priority
432
433       -T, --realtime
434              Tries  to  gain realtime priority.  This option usually requires
435              root privileges to have any effect.
436
437       -?, --help
438              Shows short usage instructions.
439
440       --longhelp
441              Shows long usage instructions.
442
443       --version
444              Print the version string.
445

HTTP SUPPORT

447       In addition to reading MPEG audio streams from ordinary files and  from
448       the  standard  input,  mpg123 supports retrieval of MPEG audio files or
449       playlists via the HTTP protocol, which is used in the  World  Wide  Web
450       (WWW).   Such  files  are specified using a so-called URL, which starts
451       with ``http://''.  When a file with that prefix is encountered,  mpg123
452       attempts  to open an HTTP connection to the server in order to retrieve
453       that file to decode and play it.
454
455       It is often useful to retrieve files through a WWW cache  or  so-called
456       proxy.   To  accomplish this, mpg123 examines the environment for vari‐
457       ables named MP3_HTTP_PROXY, http_proxy and HTTP_PROXY, in  this  order.
458       The value of the first one that is set will be used as proxy specifica‐
459       tion.  To override this, you can use the -p command  line  option  (see
460       the  ``OPTIONS''  section).  Specifying -p none will enforce contacting
461       the server directly without using any proxy, even if one of  the  above
462       environment variables is set.
463
464       Note  that,  in order to play MPEG audio files from a WWW server, it is
465       necessary that the connection to that server is fast enough.  For exam‐
466       ple,  a  128  kbit/s MPEG file requires the network connection to be at
467       least 128 kbit/s (16 kbyte/s) plus protocol overhead.   If  you  suffer
468       from  short  network  outages, you should try the -b option (buffer) to
469       bypass such outages.  If your network connection is generally not  fast
470       enough to retrieve MPEG audio files in realtime, you can first download
471       the files to your local harddisk (e.g. using  wget(1))  and  then  play
472       them from there.
473
474       If authentication is needed to access the file it can be specified with
475       the -u user:pass.
476

INTERRUPT

478       When in terminal control mode, you can quit via  pressing  the  q  key,
479       while  any time you can abort mpg123 by pressing Ctrl-C. If not in ter‐
480       minal control mode, this will skip to the next file (if  any).  If  you
481       want  to  abort playing immediately in that case, press Ctrl-C twice in
482       short succession (within about one second).
483
484       Note that the result of quitting mpg123 pressing Ctrl-C  might  not  be
485       audible  immediately,  due to audio data buffering in the audio device.
486       This delay is system dependent, but it is usually not more than one  or
487       two seconds.
488
489

PLAYBACK STATUS LINE

491       In verbose mode, mpg123 updates a line with various information center‐
492       ing around the current playback position. On any decent  terminal,  the
493       line  also  works  as  a  progress bar in the current file by reversing
494       video for a fraction of the line according to the current position.  An
495       example for a full line is this:
496
497            >  0291+0955   00:01.68+00:28.22  [00:05.30]  mix 100=085 192 kb/s
498       576 B acc   18 clip p+0.014
499
500       The information consists of, in order:
501
502       >      single-character playback state (``>'' for  playing,  ``=''  for
503              pausing/looping, ``_'' for stopped)
504
505       0291+0955
506              current  frame  offset  and number of remaining frames after the
507              plus sign
508
509       00:01.68+00:28.22
510              current position from and remaining time in human terms  (hours,
511              minutes, seconds)
512
513       [00:05.30]
514              fill of the output buffer in terms of playback time, if the buf‐
515              fer is enabled
516
517       mix    selected RVA mode (possible values: mix, alb  (album),  and  ---
518              (neutral, off))
519
520       100=085
521              set volume and the RVA-modified effective volume after the equal
522              sign
523
524       192 kb/s
525              current bitrate
526
527       576 B  size of current frame in bytes
528
529       acc    if positions are accurate, possible values are ``acc'' for accu‐
530              rate  positions  or ``fuz'' for fuzzy (with guessed byte offsets
531              using mean frame size)
532
533       18 clip
534              amount of clipped samples, non-zero only if decoder reports that
535              (generic does, some optimized ones not)
536
537       p+0.014
538              pitch change (increased/decreased playback sampling rate on user
539              request)
540
541

NOTES

543       MPEG audio decoding requires a good deal of CPU performance, especially
544       layer-3.   To  decode  it  in  realtime,  you  should  have at least an
545       i486DX4, Pentium, Alpha, SuperSparc or equivalent processor.   You  can
546       also  use the -m option to decode mono only, which reduces the CPU load
547       somewhat for layer-3 streams.  See also the -2 and -4 options.
548
549       If everything else fails, have mpg123 decode to a file and then use  an
550       appropriate  utility to play that file with less CPU load.  Most proba‐
551       bly you can configure mpg123 to produce  a  format  suitable  for  your
552       audio device (see above about encodings and sampling rates).
553
554       If  your  system  is  generally  fast enough to decode in realtime, but
555       there are sometimes periods of heavy system  load  (such  as  cronjobs,
556       users  logging  in remotely, starting of ``big'' programs etc.) causing
557       the audio output to be interrupted, then you should use the  -b  option
558       to use a buffer of reasonable size (at least 1000 Kbytes).
559

BUGS

561       Mostly MPEG-1 layer 2 and 3 are tested in real life.  Please report any
562       issues and provide test files to help fixing them.
563
564       No CRC error checking is performed.
565
566       Some platforms lack audio hardware support; you may be able to use  the
567       -s  switch  to  feed  the decoded data to a program that can play it on
568       your audio device.
569

AUTHORS

571       Maintainer:
572              Thomas Orgis <maintainer@mpg123.org>, <thomas@orgis.org>
573
574       Original Creator:
575              Michael Hipp
576
577       Uses code or ideas from various people, see the AUTHORS file accompany‐
578       ing the source code.
579

LICENSE

581       mpg123 is licensed under the GNU Lesser/Library General Public License,
582       LGPL, version 2.1 .
583

WEBSITE

585       http://www.mpg123.org
586       http://sourceforge.net/projects/mpg123
587
588
589
590                                  29 Feb 2016                        mpg123(1)
Impressum