Penguin
Recent Changes
Annotated edit history of mpg123(1) version 3, including all changes. View license author blame.
Rev Author # Line
1 perry 1 mpg123
2 !!!mpg123
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 OPERANDS
8 HTTP SUPPORT
9 INTERRUPT
10 SEE ALSO
11 NOTES
12 BUGS
13 AUTHORS
14 ----
15 !!NAME
16
17
18 mpg123 - play audio MPEG 1.0/2.0 file (layers 1, 2 and 3)
19 !!SYNOPSIS
20
21
22 __mpg123__ [[ __-tscvqy01m24wEC__ ] [[ __-b__
23 ''size'' ] [[ __-k__ ''num'' ] [[ __-n__
24 ''num'' ] [[ __-f__ ''factor'' ] [[ __-r__
25 ''rate'' ] [[ __-g__ ''gain'' ] [[ __-a__
26 ''dev'' ] [[ __-o s__ | __-o h__ | __-o l__ ] [[
27 __-d__ ''n'' ] [[ __-h__ ''n'' ] [[ __-w__
28 ''file'' ] [[ __-p__ ''proxy'' ] [[ __-@__
29 ''file'' ] ''file'' ... | ''URL'' ... |
30 __-__
31 !!DESCRIPTION
32
33
34 __mpg123__ reads one or more ''file''s (or standard
35 input if ``-'' is specified) or ''URL''s and plays them
36 on the audio device (default) or outputs them to stdout.
37 ''file''/''URL'' is assumed to be an MPEG-1/2 audio
38 bit stream.
39 !!OPTIONS
40
41
42 __mpg123__ options may be either the traditional POSIX
43 one letter options, or the GNU style long options. POSIX
44 style options start with a single ``-'', while GNU long
45 options start with ``--''.
46
47
48 __-t__, __--test__
49
50
51 Test mode. The audio stream is decoded, but no output
52 occurs.
53
54
55 __-s__, __--stdout__
56
57
58 The decoded audio samples are written to standard output,
59 instead of playing them through the audio device. This
60 option must be used if your audio hardware is not supported
61 by __mpg123__. The output format is raw (headerless)
62 linear PCM audio data, 16 bit, stereo, host byte
63 order.
64
65
66 __-c__, __--check__
67
68
69 Check for filter range violations, and report them for each
70 frame if any occur. __-C__, __--control__ Enable
71 control keys. By default use 's' to stop, 'p' to pause, 'f'
72 to jump forward to the next song, 'b' to jump back to the
73 beginning of the song, ',' to rewind, '.' to fast forward,
74 and 'q' to quit.
75
76
77 __-v__, __--verbose__
78
79
80 Increase the verbosity level. For example, displays the
81 frame numbers during decoding.
82
83
84 __-q__, __--quiet__
85
86
87 Quiet. Suppress diagnostic messages.
88
89
90 __-y__, __--resync__
91
92
93 Try to resync and continue decoding if an error occurs in
94 the input file. Also try to recover from certain broken
95 headers. Useful if you have a broken MPEG file, on which
96 __mpg123__ normally gives up saying `Illegal header'. Be
97 careful: Broken locations in MPEG files might cause sharp,
98 loud pops or clicks, which might damage your speakers if
99 played too loud.
100
101
102 __-0__, __--single0__; __-1__,
103 __--single1__
104
105
106 Decode only channel 0 (left) or channel 1 (right),
107 respectively. These options are available for stereo MPEG
108 streams only.
109
110
111 __-m__, __--singlemix__
112
113
114 Mix both channels. This option is available for stereo MPEG
115 layer-3 streams only. It takes less CPU time than full
116 stereo decoding.
117
118
119 __-2__, __--2to1__; __-4__,
120 __--4to1__
121
122
123 Performs a downsampling of ratio 2:1 (22 kHz) or 4:1 (11
124 kHz) on the output stream, respectively. Saves some CPU
125 cycles, but at least the 4:1 ratio sounds ugly.
126
127
128 __-b__ ''size'', __--buffer__
129 ''size''
130
131
132 Use an audio output buffer of ''size'' Kbytes. This is
133 useful to bypass short periods of heavy system activity,
134 which would normally cause the audio output to be
135 interrupted. You should specify a buffer size of at least
136 1024 (i.e. 1 Mb, which equals about 6 seconds of audio data)
137 or more; less than about 300 does not make much sense. The
138 default is 0, which turns buffering off.
139
140
141 __-k__ ''num'', __--skip__ ''num''
142
143
144 Skip first ''num'' frames. By default the decoding starts
145 at the first frame.
146
147
148 __-n__ ''num'', __--frames__
149 ''num''
150
151
152 Decode only ''num'' frames. By default the complete
153 stream is decoded.
154
155
156 __-f__ ''factor'', __--scale__
157 ''factor''
158
159
160 Change scale factor (default: 32768).
161
162
163 __-r__ ''rate'', __--rate__
164 ''rate''
165
166
167 Set sample rate (default: automatic). You may want to change
168 this if you need a constant bitrate independed of the mpeg
169 stream rate. mpg123 automagically converts the rate. You
170 should then combine this with --stereo or
171 --mono.
172
173
174 __-g__ ''gain'', __--gain__
175 ''gain''
176
177
178 Set audio hardware output gain (default: don't
179 change).
180
181
182 __-a__ ''dev'', __--audiodevice__
183 ''dev''
184
185
186 Specify the audio device to use. The default is
187 system-dependent (usually /dev/audio or /dev/dsp). Use this
188 option if you have multiple audio devices and the default is
189 not what you want.
190
191
192 __-o s__, __--speaker__
193
194
195 Direct audio output to the speaker.
196
197
198 __-o h__, __--headphones__
199
200
201 Direct audio output to the headphone connector.
202
203
204 __-o l__, __--lineout__
205
206
207 Direct audio output to the line-out connector.
208
209
210 __-d__ ''n'', __--doublespeed__
211 ''n''
212
213
214 Only play every ''n'''th frame. This will cause the MPEG
215 stream to be played ''n'' times faster, which can be used
216 for special effects. Can also be combined with the
217 __--halfspeed__ option to play 3 out of 4 frames etc.
218 Don't expect great sound quality when using this
219 option.
220
221
222 __-h__ ''n'', __--halfspeed__ ''n''
223
224
225 Play each frame ''n'' times. This will cause the MPEG
226 stream to be played at ''1''/''n'''th speed (n times
227 slower), which can be used for special effects. Can also be
228 combined with the __--doublespeed__ option to double
229 every third frame or things like that. Don't expect great
230 sound quality when using this option.
231
232
233 __-w__ ''file'', __--wav__
234
235
236 Write output as WAV file. This will cause the MPEG stream to
237 be decoded and saved as file ''file'' , or standard
238 output if ''-'' is used as file name. You can also use
239 ''--au'' and ''--cdr'' for AU and CDR format,
240 respectively.
241
242
243 __-p__ ''URL'' | __none__, __--proxy__
244 ''URL'' | __none__
245
246
247 The specified ''proxy'' will be used for HTTP requests.
248 It should be specified as full URL
249 (``http://host.domain:port/''), but the ``http://'' prefix,
250 the port number and the trailing slash are optional (the
251 default port is 80). Specifying __none__ means not to use
252 any proxy, and to retrieve files directly from the
253 respective servers. See also the ``HTTP SUPPORT''
254 section.
255
256
257 __-u__ ''auth'', __--auth__
258 ''auth''
259
260
261 HTTP authentication to use when recieving files via HTTP.
262 The format used is user:password.
263
264
265 __-@__ ''file'', __--list__
266 ''file''
267
268
269 Read filenames and/or URLs of MPEG audio streams from the
270 specified ''file'' in addition to the ones specified on
271 the command line (if any). Note that ''file'' can be
272 either an ordinary file, a dash ``-'' to indicate that a
273 list of filenames/URLs is to be read from the standard
274 input, or an URL pointing to a an appropriate list file.
275 Note: only one __-@__ option can be used (if more than
276 one is specified, only the last one will be
277 recognized).
278
279
280 __--au__ ''file''
281
282
283 Does not play the MPEG file but writes it to ''file'' in
284 SUN audio format. If - is used as the filename, the AU file
285 is written to stdout.
286
287
288 __--cdr__ ''file''
289
290
291 Does not play the MPEG file but writes it to ''file'' as
292 a CDR file. If - is used as the filename, the CDR file is
293 written to stdout.
294
295
296 __-z__, __--shuffle__
297
298
299 Shuffle play. Randomly shuffles the order of files specified
300 on the command line, or in the list file.
301
302
303 __-Z__, __--random__
304
305
306 Continuous random play. Keeps picking a random file from the
307 command line or the play list. Unlike shuffle play above,
308 random play never ends, and plays individual songs more than
309 once.
310
311
312 __--stereo__
313
314
315 Force stereo output
316
317
318 __--reopen__
319
320
321 Forces reopen of the audiodevice after ever
322 song
323
324
325 __--8bit__
326
327
328 Forces 8bit output
329
330
331 __-E__ ''file'', __--equalizer__
332
333
3 AlexKruppa 334 Enables equalization, taken from ''file''. File format is
335 32 lines with two floating point values on each, first
336 value for left channel, second for right. First line
337 corresponds to lowest frequency band, 32nd to highest.
1 perry 338
339
340 __-T__, __--realtime__
341
342
343 Tries to gain realtime priority. This option usually
344 requires root privileges to have any effect.
345
346
347 __--aggressive__
348
349
350 Tries to get higher priority
351
352
353 __--title__
354
355
356 In an xterm, or rxvt, change the window's title to the name
357 of song currently playing.
358
359
360 __--help, --longhelp__
361
362
363 Shows usage instructions
364 !!OPERANDS
365 The following operands are supported:
366
367
368 ''file''(s)
369
370
371 The path name(s) of one or more input files. They must be
372 valid MPEG-1/2 audio layer-1, -2 or -3 bit streams. If a
373 dash ``-'' is specified, MPEG data will be read from the
374 standard input. Furthermore, any name starting with
375 ``http://'' is recognized as ''URL'' (see next
376 section).
377 !!HTTP SUPPORT
378
379
380 In addition to reading MPEG audio streams from ordinary
381 files and from the standard input, __mpg123__ supports
382 retrieval of MPEG audio files via the HTTP protocol, which
383 is used in the World Wide Web (WWW). Such files are
384 specified using a so-called URL (universal resource
385 location), which starts with ``http://''. When a file with
386 that prefix is encountered, __mpg123__ attempts to open
387 an HTTP connection to the server in order to retrieve that
388 file to decode and play it.
389
390
391 It is often useful to retrieve files through a WWW cache or
392 so-called proxy. To accomplish this, __mpg123__ examines
393 the environment for variables named __MP3_HTTP_PROXY__,
394 __http_proxy__ and __HTTP_PROXY__, in this order. The
395 value of the first one that is set will be used as proxy
396 specification. To override this, you can use the __-p__
397 command line option (see the ``OPTIONS'' section).
398 Specifying __-p none__ will enforce contacting the server
399 directly without using any proxy, even if one of the above
400 environment variables is set.
401
402
403 Note that, in order to play MPEG audio files from a WWW
404 server, it is necessary that the connection to that server
405 is fast enough. For example, a 128 kbit/s MPEG file requires
406 the network connection to be at least 128 kbit/s (16
407 kbyte/s) plus protocol overhead. If you suffer from short
408 network outages, you should try the __-b__ option
409 (buffer) to bypass such outages. If your network connection
410 is generally not fast enough to retrieve MPEG audio files in
411 realtime, you can first download the files to your local
412 harddisk (e.g. using lynx(1)) and then play them from
413 there.
414
415
416 If authentication is needed to access the file it can be
417 specified with the __-u user:pass__.
418 !!INTERRUPT
419
420
421 You can abort __mpg123__ at any time by pressing Ctrl-C.
422 If you are playing multiple files, this will stop the
423 current file and begin playing the next one. If you want to
424 abort playing immediately instead of skipping to the next
425 file, press Ctrl-C twice in short succession (within about
426 one second).
427
428
429 Note that the result of pressing Ctrl-C might not be audible
430 immediately, due to audio data buffering in the audio
431 device. This delay is system dependent, but it is usually
432 not more than one or two seconds.
433 !!SEE ALSO
434
435
436 lynx(1), sox(1), intro(1)
437 !!NOTES
438
439
440 MPEG audio decoding requires a good deal of CPU performance,
441 especially layer-3. To decode it in realtime, you should
2 perry 442 have at least a Pentium, Alpha, !SuperSparc or equivalent
1 perry 443 processor. You can also use the __-singlemix__ option to
444 decode mono only, which reduces the CPU load somewhat for
445 layer-3 streams. See also the __-2__ and __-4__
446 options.
447
448
449 If everything else fails, use the __-s__ option to decode
450 to standard output, direct it into a file and then use an
451 appropriate utility to play that file. You might have to use
452 a tool such as sox(1) to convert the output to an
453 audio format suitable for your audio player.
454
455
456 Also note that __mpg123__ always generates 16 bit stereo
457 data (if one of the __-single__* options is used, two
458 identical stereo channels are generated). If your hardware
459 requires some other format, for example 8 bit mono, you also
460 have to use a converter such as sox(1).
461
462
463 If your system is generally fast enough to decode in
464 realtime, but there are sometimes periods of heavy system
465 load (such as cronjobs, users logging in remotely, starting
466 of ``big'' programs etc.) causing the audio output to be
467 interrupted, then you should use the __-b__ option to use
468 a buffer of at least 1000 Kbytes.
469 !!BUGS
470
471
472 Known bugs and limitations:
473
474
475 MPEG-2, Layer 1 and 2 not tested. May not work. (Layer 3
476 should work.)
477 Free format streams are not supported.
478 Layer-1 support is not heavily tested.
479 No CRC error checking is performed.
480 There is currently no support for audio hardware on DEC
481 Digital Unix, Ultrix and IBM AIX, therefore the __-s__
482 option has to be used on those platforms.
483 !!AUTHORS
484
485
486 Main author:
487
488
489 Michael Hipp
490
491
492 Uses code (or at least ideas) from:
493
494
495 MPEG Software Simulation Group (Base package)
496 Philipp Knirsch
497 Tobias Bading
498 Jeff Tsay
499 Thomas Woerner (SGI Audio)
500 Damien Clermonte
501 Oliver Fromme
502
503
504 Internet references:
505
506
507 http://www.mpg123.org
508 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.