| 1 |
.\" Process this file with |
| 2 |
.\" groff -man -Tascii ogg123.1 |
| 3 |
.\" |
| 4 |
.TH ogg123 1 "2010 March 24" "Xiph.Org Foundation" "Vorbis Tools" |
| 5 |
|
| 6 |
.SH NAME |
| 7 |
ogg123 \- plays Ogg, and FLAC files |
| 8 |
|
| 9 |
.SH SYNOPSIS |
| 10 |
.B ogg123 |
| 11 |
[ |
| 12 |
.B -vqrzZVh |
| 13 |
] [ |
| 14 |
.B -k |
| 15 |
.I seconds |
| 16 |
] [ |
| 17 |
.B -x |
| 18 |
.I nth |
| 19 |
] [ |
| 20 |
.B -y |
| 21 |
.I ntimes |
| 22 |
] [ |
| 23 |
.B -b |
| 24 |
.I buffer_size |
| 25 |
] [ |
| 26 |
.B -d |
| 27 |
.I driver |
| 28 |
[ |
| 29 |
.B -o |
| 30 |
.I option:value |
| 31 |
] |
| 32 |
[ |
| 33 |
.B -f |
| 34 |
.I filename |
| 35 |
] ] |
| 36 |
.I file |
| 37 |
.B ... |
| 38 |
| |
| 39 |
.I directory |
| 40 |
.B ... |
| 41 |
| |
| 42 |
.I URL |
| 43 |
.B ... |
| 44 |
|
| 45 |
.SH DESCRIPTION |
| 46 |
.B ogg123 |
| 47 |
reads Ogg/Vorbis, Ogg/Speex, Ogg/Opus, Ogg/FLAC, and native FLAC audio files |
| 48 |
and decodes them to the devices specified on the command line. By default, |
| 49 |
.B ogg123 |
| 50 |
writes to the standard sound device, but output can be sent to any |
| 51 |
number of devices. Files can be read from the file system, or URLs |
| 52 |
can be streamed via HTTP. If a directory is given, all of the files in |
| 53 |
it or its subdirectories will be played. |
| 54 |
|
| 55 |
.SH OPTIONS |
| 56 |
.IP "--audio-buffer n" |
| 57 |
Use an output audio buffer of approximately 'n' kilobytes. |
| 58 |
.IP "-@ playlist, --list playlist" |
| 59 |
Play all of the files named in the file 'playlist'. The playlist should have |
| 60 |
one filename, directory name, or URL per line. Blank lines are permitted. |
| 61 |
Directories will be treated in the same way as on the command line. |
| 62 |
.IP "-b n, --buffer n" |
| 63 |
Use an input buffer of approximately 'n' kilobytes. HTTP-only option. |
| 64 |
.IP "-p n, --prebuffer n" |
| 65 |
Prebuffer 'n' percent of the input buffer. Playback won't begin until |
| 66 |
this prebuffer is complete. HTTP-only option. |
| 67 |
.IP "-d device, --device device" |
| 68 |
Specify output device. See |
| 69 |
.B DEVICES |
| 70 |
section for a list of devices. Any number of devices may be specified. |
| 71 |
.IP "-f filename, --file filename" |
| 72 |
Specify output file for a file device previously specified with |
| 73 |
--device. The filename "-" writes to standard |
| 74 |
out. If the file already exists, |
| 75 |
.B ogg123 |
| 76 |
will overwrite it. |
| 77 |
.IP "-h, --help" |
| 78 |
Show command help. |
| 79 |
.IP "-k n, --skip n" |
| 80 |
Skip the first 'n' seconds. 'n' may also be in minutes:seconds or |
| 81 |
hours:minutes:seconds form. |
| 82 |
.IP "-K n, --end n" |
| 83 |
Stops playing 'n' seconds from the start of the stream. 'n' may also have the |
| 84 |
same format as used in the |
| 85 |
.I --skip |
| 86 |
option. |
| 87 |
.IP "-o option[:value], --device-option option[:value]" |
| 88 |
Sets the option |
| 89 |
.I option |
| 90 |
to |
| 91 |
.I value |
| 92 |
for the preceding device. See |
| 93 |
.B DEVICES |
| 94 |
for a list of valid options for each device. |
| 95 |
.IP "-q, --quiet" |
| 96 |
Quiet mode. No messages are displayed. |
| 97 |
.IP "-V, --version" |
| 98 |
Display version information. |
| 99 |
.IP "-v, --verbose" |
| 100 |
Increase verbosity. |
| 101 |
.IP "-x n, --nth" |
| 102 |
Play every 'n'th decoded block. Has the effect of playing audio at 'n' times |
| 103 |
faster than normal speed. |
| 104 |
.IP "-y n, --ntimes" |
| 105 |
Repeat every played block 'n' times. Has the effect of playing audio 'n' |
| 106 |
times slower than normal speed. May be with -x for interesting fractional |
| 107 |
speeds. |
| 108 |
.IP "-r, --repeat" |
| 109 |
Repeat playlist indefinitely. |
| 110 |
.IP "-z, --shuffle" |
| 111 |
Play files in pseudo-random order. |
| 112 |
.IP "-Z, --random" |
| 113 |
Play files in pseudo-random order forever. |
| 114 |
|
| 115 |
.SH DEVICES |
| 116 |
|
| 117 |
.B ogg123 |
| 118 |
supports a variety of audio output devices through libao. Only those |
| 119 |
devices supported by the target platform will be available. The |
| 120 |
.B -f |
| 121 |
option may only be used with devices that write to files. |
| 122 |
|
| 123 |
Options supported by all devices: |
| 124 |
.RS |
| 125 |
.IP debug |
| 126 |
Turn on debugging output [if any] for a chosen driver. |
| 127 |
.IP matrix:value |
| 128 |
Force a specific output channel ordering for a given device. |
| 129 |
.I value |
| 130 |
is a comma |
| 131 |
separated list of AO style channel names, eg, L,R,C,LFE,BL,BR,SL,SR. |
| 132 |
.IP verbose |
| 133 |
Turn on verbose output for a chosen driver. the -v option will also set the |
| 134 |
driver verbose option. |
| 135 |
.IP quiet |
| 136 |
Force chosen driver to be completely silent. Even errors will not produce any |
| 137 |
output. -q will also set the driver quiet option. |
| 138 |
.RE |
| 139 |
|
| 140 |
.B |
| 141 |
.IP aixs |
| 142 |
AIX live output driver. Options: |
| 143 |
.RS |
| 144 |
.IP dev:value |
| 145 |
Set AIX output device to |
| 146 |
.I value |
| 147 |
.RE |
| 148 |
|
| 149 |
.B |
| 150 |
.IP alsa |
| 151 |
Advanced Linux Sound Architecture live output driver. Options: |
| 152 |
.RS |
| 153 |
.IP buffer_time:value |
| 154 |
Override the default hardware buffer size (in milliseconds). |
| 155 |
.IP dev:value |
| 156 |
ALSA device label to use. Examples include "hw:0" for the first soundcard |
| 157 |
and "hw:1" for the second. The alsa driver normally chooses one of |
| 158 |
"surround71", |
| 159 |
"surround51", |
| 160 |
"surround40" or |
| 161 |
"default" |
| 162 |
automatically depending on number of output channels. For more information, |
| 163 |
see http://alsa.opensrc.org/ALSA+device+labels |
| 164 |
.IP period_time:value |
| 165 |
Override the default hardware period size (in microseconds). |
| 166 |
.IP period_time:value |
| 167 |
Override the default hardware period size (in microseconds). |
| 168 |
.IP use_mmap:value |
| 169 |
.I value |
| 170 |
is set to "yes" or "no" to override the compiled-in default to use or not use |
| 171 |
mmap device access. In the past, some buggy alsa drivers have behaved better when |
| 172 |
not using mmap access at the penalty of slightly higher CPU usage. |
| 173 |
.RE |
| 174 |
|
| 175 |
.B |
| 176 |
.IP arts |
| 177 |
aRts Sound Daemon live output driver. Options: |
| 178 |
.RS |
| 179 |
.IP multi:value |
| 180 |
.I value |
| 181 |
is set to "yes" or "no" to allow opening the aRts playback device for multiply |
| 182 |
concurrent playback. Although the driver works properly in multi mode, it is |
| 183 |
known to occasionally crash the aRts server itself. Default behavior is "no". |
| 184 |
.RE |
| 185 |
|
| 186 |
.B |
| 187 |
.IP au |
| 188 |
Sun audio file output. Writes the audio samples in AU format. The AU |
| 189 |
format supports writing to unseekable files like standard out. In |
| 190 |
such circumstances, the AU header will specify the sample format, but |
| 191 |
not the length of the recording. |
| 192 |
|
| 193 |
.B |
| 194 |
.IP esd |
| 195 |
Enlightened Sound Daemon live output. Options: |
| 196 |
.RS |
| 197 |
.IP host:value |
| 198 |
.I value |
| 199 |
specifies the hostname where esd is running. This can include a port number |
| 200 |
after a colon, as in "whizbang.com:555". (Default = localhost) |
| 201 |
.IP client_name:value |
| 202 |
Sets the client name for the new audio stream. Defaults to "libao client". |
| 203 |
.RE |
| 204 |
|
| 205 |
.B |
| 206 |
.IP irix |
| 207 |
IRIX live output audio driver. |
| 208 |
|
| 209 |
.B |
| 210 |
.IP macosx |
| 211 |
MacOS X 'AUHAL' live output driver. This driver supports MacOS X |
| 212 |
10.5 and later (10.4 and earlier uses an earlier, incompatible |
| 213 |
interface). Options: |
| 214 |
.RS |
| 215 |
.IP buffer_time:value |
| 216 |
Set the hardware buffer size to the equivalent of |
| 217 |
.I value |
| 218 |
milliseconds. |
| 219 |
.RE |
| 220 |
|
| 221 |
.B |
| 222 |
.IP nas |
| 223 |
Network Audio Server live output driver. Options: |
| 224 |
.RS |
| 225 |
.IP buf_size:value |
| 226 |
Set size of audio buffer on server in bytes. |
| 227 |
.IP host:value |
| 228 |
Set location of NAS server; See nas(1) for format. |
| 229 |
.RE |
| 230 |
|
| 231 |
.B |
| 232 |
.IP null |
| 233 |
Null driver. All audio data is discarded. (Note: Audio data is not |
| 234 |
written to |
| 235 |
.B /dev/null |
| 236 |
!) You could use this driver to test raw decoding speed without |
| 237 |
output overhead. |
| 238 |
|
| 239 |
.B |
| 240 |
.IP oss |
| 241 |
Open Sound System driver for Linux and FreeBSD, versions 2, 3 and 4. Options: |
| 242 |
.RS |
| 243 |
.IP dsp:value |
| 244 |
DSP device for soundcard. Defaults to |
| 245 |
.B /dev/dsp. |
| 246 |
.RE |
| 247 |
|
| 248 |
.B |
| 249 |
.IP pulse |
| 250 |
Pulseaudio live audio sound driver. Options: |
| 251 |
.RS |
| 252 |
.IP server:value |
| 253 |
Specifies location of remote or alternate Pulseaudio server. |
| 254 |
.IP sink:value |
| 255 |
Specifies a non-default Pulseaudio sink for audio stream. |
| 256 |
.RE |
| 257 |
|
| 258 |
.B |
| 259 |
.IP raw |
| 260 |
Raw file output. Writes raw audio samples to a file. Options: |
| 261 |
.RS |
| 262 |
.IP byteorder:value |
| 263 |
Chooses big endian ("big"), little endian ("little"), or native ("native") byte order. |
| 264 |
Default is native order. |
| 265 |
.RE |
| 266 |
|
| 267 |
.B |
| 268 |
.IP roar |
| 269 |
RoarAudio Daemon live output driver. Options: |
| 270 |
.RS |
| 271 |
.IP "server:value, host:value" |
| 272 |
Specifies location of remote RoarAudio server to use. |
| 273 |
.IP "id:value, dev:value" |
| 274 |
Specifies a non-default mixer within a RoarAudio server for audio stream. |
| 275 |
.IP role:value |
| 276 |
Sets the role setting for the audio stream. |
| 277 |
.IP client_name:value |
| 278 |
Sets the client name for the new audio stream. Defaults to "libao client". |
| 279 |
.RE |
| 280 |
|
| 281 |
.B |
| 282 |
.IP sndio |
| 283 |
OpenBSD SNDIO live output driver. Options: |
| 284 |
.RS |
| 285 |
.IP dev:value |
| 286 |
Specifies audio device to use for playback. |
| 287 |
.RE |
| 288 |
|
| 289 |
.B |
| 290 |
.IP sun |
| 291 |
Sun Audio live output driver for NetBSD, OpenBSD, and Solaris. Options: |
| 292 |
.RS |
| 293 |
.IP dev:value |
| 294 |
Audio device for soundcard. Defaults to |
| 295 |
.B /dev/audio. |
| 296 |
.RE |
| 297 |
|
| 298 |
|
| 299 |
.B |
| 300 |
.IP wav |
| 301 |
WAV file output. Writes the sound data to disk in uncompressed form. |
| 302 |
If multiple files are played, all of them will be concatenated into |
| 303 |
the same WAV file. WAV files cannot be written to unseekable files, |
| 304 |
such as standard out. Use the AU format instead. |
| 305 |
|
| 306 |
.B |
| 307 |
.IP wmm |
| 308 |
Windows MultiMedia live output driver for Win98 and later. Options: |
| 309 |
.RS |
| 310 |
.IP dev:value |
| 311 |
Selects audio device to use for playback by device name. |
| 312 |
.IP id:value |
| 313 |
Selects audio device to use for playback by device id (card number). |
| 314 |
.RE |
| 315 |
|
| 316 |
.SH EXAMPLES |
| 317 |
|
| 318 |
The |
| 319 |
.B ogg123 |
| 320 |
command line is fairly flexible, perhaps confusingly so. Here are |
| 321 |
some sample command lines and an explanation of what they do. |
| 322 |
.PP |
| 323 |
|
| 324 |
Play on the default soundcard: |
| 325 |
.RS |
| 326 |
.B ogg123 test.ogg |
| 327 |
.RE |
| 328 |
.PP |
| 329 |
|
| 330 |
Play all of the files in the directory ~/music and its subdirectories. |
| 331 |
.RS |
| 332 |
.B ogg123 ~/music |
| 333 |
.RE |
| 334 |
.PP |
| 335 |
|
| 336 |
Play a file using the OSS driver: |
| 337 |
.RS |
| 338 |
.B ogg123 -d oss test.ogg |
| 339 |
.RE |
| 340 |
.PP |
| 341 |
|
| 342 |
Pass the "dsp" option to the OSS driver: |
| 343 |
.RS |
| 344 |
.B ogg123 -d oss -o dsp:/dev/mydsp |
| 345 |
.RE |
| 346 |
.PP |
| 347 |
|
| 348 |
Use the ESD driver |
| 349 |
.RS |
| 350 |
.B ogg123 -d esd test.ogg |
| 351 |
.RE |
| 352 |
.PP |
| 353 |
|
| 354 |
Use the WAV driver with the output file, "test.wav": |
| 355 |
.RS |
| 356 |
.B ogg123 -d wav -f test.wav test.ogg |
| 357 |
.RE |
| 358 |
.PP |
| 359 |
|
| 360 |
Listen to a file while you write it to a WAV file: |
| 361 |
.RS |
| 362 |
.B ogg123 -d oss -d wav -f test.wav test.ogg |
| 363 |
.RE |
| 364 |
.PP |
| 365 |
|
| 366 |
Note that options apply to the device declared to the left: |
| 367 |
.RS |
| 368 |
.B ogg123 -d oss -o dsp:/dev/mydsp -d raw -f test2.raw -o byteorder:big test.ogg |
| 369 |
.RE |
| 370 |
.PP |
| 371 |
|
| 372 |
Stress test your harddrive: |
| 373 |
.RS |
| 374 |
.B ogg123 -d oss -d wav -f 1.wav -d wav -f 2.wav -d wav -f 3.wav -d wav -f 4.wav -d wav -f 5.wav test.ogg |
| 375 |
.RE |
| 376 |
.PP |
| 377 |
|
| 378 |
Create an echo effect with esd and a slow computer: |
| 379 |
.RS |
| 380 |
.B ogg123 -d esd -d esd test.ogg |
| 381 |
.RE |
| 382 |
.PP |
| 383 |
|
| 384 |
.SH INTERRUPT |
| 385 |
You can abort |
| 386 |
.B ogg123 |
| 387 |
at any time by pressing Ctrl-C. If you are playing multiple |
| 388 |
files, this will stop the current file and begin playing the |
| 389 |
next one. If you want to abort playing immediately instead |
| 390 |
of skipping to the next file, press Ctrl-C within the first |
| 391 |
second of the playback of a new file. |
| 392 |
.P |
| 393 |
Note that the result of pressing Ctrl-C might not be audible |
| 394 |
immediately, due to audio data buffering in the audio device. |
| 395 |
This delay is system dependent, but it is usually not more |
| 396 |
than one or two seconds. |
| 397 |
|
| 398 |
.SH FILES |
| 399 |
|
| 400 |
.TP |
| 401 |
/etc/libao.conf |
| 402 |
Can be used to set the default output device for all libao programs. |
| 403 |
|
| 404 |
.TP |
| 405 |
~/.libao |
| 406 |
Per-user config file to override the system wide output device settings. |
| 407 |
.PP |
| 408 |
|
| 409 |
.SH BUGS |
| 410 |
|
| 411 |
Piped WAV files may cause strange behavior in other programs. This is |
| 412 |
because WAV files store the data length in the header. However, the |
| 413 |
output driver does not know the length when it writes the header, and |
| 414 |
there is no value that means "length unknown". Use the raw or au |
| 415 |
output driver if you need to use ogg123 in a pipe. |
| 416 |
|
| 417 |
.SH AUTHORS |
| 418 |
|
| 419 |
.TP |
| 420 |
Program Authors: |
| 421 |
.br |
| 422 |
Kenneth Arnold <[email protected]> |
| 423 |
.br |
| 424 |
Stan Seibert <[email protected]> |
| 425 |
.br |
| 426 |
|
| 427 |
.TP |
| 428 |
Manpage Author: |
| 429 |
.br |
| 430 |
Stan Seibert <[email protected]> |
| 431 |
|
| 432 |
.SH "SEE ALSO" |
| 433 |
|
| 434 |
.PP |
| 435 |
\fBlibao.conf\fR(5), \fBoggenc\fR(1), \fBvorbiscomment\fR(1), \fBogginfo\fR(1) |
| 436 |
|