Penguin
Recent Changes
Blame: mpg123-oss(1)
EditPageHistoryDiffInfoLikePages
Annotated edit history of mpg123-oss(1) version 2, 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
334 Enables equalization, taken from ''file''
335
336
337 __-T__, __--realtime__
338
339
340 Tries to gain realtime priority. This option usually
341 requires root privileges to have any effect.
342
343
344 __--aggressive__
345
346
347 Tries to get higher priority
348
349
350 __--title__
351
352
353 In an xterm, or rxvt, change the window's title to the name
354 of song currently playing.
355
356
357 __--help, --longhelp__
358
359
360 Shows usage instructions
361 !!OPERANDS
362 The following operands are supported:
363
364
365 ''file''(s)
366
367
368 The path name(s) of one or more input files. They must be
369 valid MPEG-1/2 audio layer-1, -2 or -3 bit streams. If a
370 dash ``-'' is specified, MPEG data will be read from the
371 standard input. Furthermore, any name starting with
372 ``http://'' is recognized as ''URL'' (see next
373 section).
374 !!HTTP SUPPORT
375
376
377 In addition to reading MPEG audio streams from ordinary
378 files and from the standard input, __mpg123__ supports
379 retrieval of MPEG audio files via the HTTP protocol, which
380 is used in the World Wide Web (WWW). Such files are
381 specified using a so-called URL (universal resource
382 location), which starts with ``http://''. When a file with
383 that prefix is encountered, __mpg123__ attempts to open
384 an HTTP connection to the server in order to retrieve that
385 file to decode and play it.
386
387
388 It is often useful to retrieve files through a WWW cache or
389 so-called proxy. To accomplish this, __mpg123__ examines
390 the environment for variables named __MP3_HTTP_PROXY__,
391 __http_proxy__ and __HTTP_PROXY__, in this order. The
392 value of the first one that is set will be used as proxy
393 specification. To override this, you can use the __-p__
394 command line option (see the ``OPTIONS'' section).
395 Specifying __-p none__ will enforce contacting the server
396 directly without using any proxy, even if one of the above
397 environment variables is set.
398
399
400 Note that, in order to play MPEG audio files from a WWW
401 server, it is necessary that the connection to that server
402 is fast enough. For example, a 128 kbit/s MPEG file requires
403 the network connection to be at least 128 kbit/s (16
404 kbyte/s) plus protocol overhead. If you suffer from short
405 network outages, you should try the __-b__ option
406 (buffer) to bypass such outages. If your network connection
407 is generally not fast enough to retrieve MPEG audio files in
408 realtime, you can first download the files to your local
409 harddisk (e.g. using lynx(1)) and then play them from
410 there.
411
412
413 If authentication is needed to access the file it can be
414 specified with the __-u user:pass__.
415 !!INTERRUPT
416
417
418 You can abort __mpg123__ at any time by pressing Ctrl-C.
419 If you are playing multiple files, this will stop the
420 current file and begin playing the next one. If you want to
421 abort playing immediately instead of skipping to the next
422 file, press Ctrl-C twice in short succession (within about
423 one second).
424
425
426 Note that the result of pressing Ctrl-C might not be audible
427 immediately, due to audio data buffering in the audio
428 device. This delay is system dependent, but it is usually
429 not more than one or two seconds.
430 !!SEE ALSO
431
432
433 lynx(1), sox(1), intro(1)
434 !!NOTES
435
436
437 MPEG audio decoding requires a good deal of CPU performance,
438 especially layer-3. To decode it in realtime, you should
2 perry 439 have at least a Pentium, Alpha, !SuperSparc or equivalent
1 perry 440 processor. You can also use the __-singlemix__ option to
441 decode mono only, which reduces the CPU load somewhat for
442 layer-3 streams. See also the __-2__ and __-4__
443 options.
444
445
446 If everything else fails, use the __-s__ option to decode
447 to standard output, direct it into a file and then use an
448 appropriate utility to play that file. You might have to use
449 a tool such as sox(1) to convert the output to an
450 audio format suitable for your audio player.
451
452
453 Also note that __mpg123__ always generates 16 bit stereo
454 data (if one of the __-single__* options is used, two
455 identical stereo channels are generated). If your hardware
456 requires some other format, for example 8 bit mono, you also
457 have to use a converter such as sox(1).
458
459
460 If your system is generally fast enough to decode in
461 realtime, but there are sometimes periods of heavy system
462 load (such as cronjobs, users logging in remotely, starting
463 of ``big'' programs etc.) causing the audio output to be
464 interrupted, then you should use the __-b__ option to use
465 a buffer of at least 1000 Kbytes.
466 !!BUGS
467
468
469 Known bugs and limitations:
470
471
472 MPEG-2, Layer 1 and 2 not tested. May not work. (Layer 3
473 should work.)
474 Free format streams are not supported.
475 Layer-1 support is not heavily tested.
476 No CRC error checking is performed.
477 There is currently no support for audio hardware on DEC
478 Digital Unix, Ultrix and IBM AIX, therefore the __-s__
479 option has to be used on those platforms.
480 !!AUTHORS
481
482
483 Main author:
484
485
486 Michael Hipp
487
488
489 Uses code (or at least ideas) from:
490
491
492 MPEG Software Simulation Group (Base package)
493 Philipp Knirsch
494 Tobias Bading
495 Jeff Tsay
496 Thomas Woerner (SGI Audio)
497 Damien Clermonte
498 Oliver Fromme
499
500
501 Internet references:
502
503
504 http://www.mpg123.org
505 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.