vorbis-tools/ogg123/ogg123.1

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