1ogg123(1)                        Vorbis Tools                        ogg123(1)
2
3
4

NAME

6       ogg123 - plays Ogg, and FLAC files
7
8

SYNOPSIS

10       ogg123  [  -vqrzZVh ] [ -k seconds ] [ -x nth ] [ -y ntimes ] [ -b buf‐
11       fer_size ] [ -d driver [ -o option:value ] [ -f filename ] ]  file  ...
12       | directory ...  | URL ...
13
14

DESCRIPTION

16       ogg123 reads Ogg/Vorbis, Ogg/Speex, Ogg/Opus, Ogg/FLAC, and native FLAC
17       audio files and decodes them to the devices specified  on  the  command
18       line.  By default, ogg123 writes to the standard sound device, but out‐
19       put can be sent to any number of devices.  Files can be read  from  the
20       file  system,  or  URLs  can  be  streamed via HTTP.  If a directory is
21       given, all of the files in it or its subdirectories will be played.
22
23

OPTIONS

25       --audio-buffer n
26              Use an output audio buffer of approximately 'n' kilobytes.
27
28       -@ playlist, --list playlist
29              Play all of  the  files  named  in  the  file  'playlist'.   The
30              playlist  should  have  one filename, directory name, or URL per
31              line.  Blank lines are permitted.  Directories will  be  treated
32              in the same way as on the command line.
33
34       -b n, --buffer n
35              Use  an  input buffer of approximately 'n' kilobytes.  HTTP-only
36              option.
37
38       -p n, --prebuffer n
39              Prebuffer 'n' percent of the input buffer.  Playback won't begin
40              until this prebuffer is complete.  HTTP-only option.
41
42       -d device, --device device
43              Specify  output  device.   See  DEVICES  section  for  a list of
44              devices.  Any number of devices may be specified.
45
46       -f filename, --file filename
47              Specify output file for a file device previously specified  with
48              --device.  The filename "-" writes to standard out.  If the file
49              already exists, ogg123 will overwrite it.
50
51       -h, --help
52              Show command help.
53
54       -k n, --skip n
55              Skip the first 'n' seconds.  'n' may also be in  minutes:seconds
56              or hours:minutes:seconds form.
57
58       -K n, --end n
59              Stops playing 'n' seconds from the start of the stream.  'n' may
60              also have the same format as used in the --skip option.
61
62       -o option[:value], --device-option option[:value]
63              Sets the option option to value for the preceding  device.   See
64              DEVICES for a list of valid options for each device.
65
66       -q, --quiet
67              Quiet mode.  No messages are displayed.
68
69       -V, --version
70              Display version information.
71
72       -v, --verbose
73              Increase verbosity.
74
75       -x n, --nth
76              Play every 'n'th decoded block.  Has the effect of playing audio
77              at 'n' times faster than normal speed.
78
79       -y n, --ntimes
80              Repeat every played block 'n' times.  Has the effect of  playing
81              audio  'n'  times  slower than normal speed.  May be with -x for
82              interesting fractional speeds.
83
84       -r, --repeat
85              Repeat playlist indefinitely.
86
87       -z, --shuffle
88              Play files in pseudo-random order.
89
90       -Z, --random
91              Play files in pseudo-random order forever.
92
93

DEVICES

95       ogg123 supports a variety of audio output devices through libao.   Only
96       those  devices supported by the target platform will be available.  The
97       -f option may only be used with devices that write to files.
98
99       Options supported by all devices:
100
101              debug  Turn on debugging output [if any] for a chosen driver.
102
103              matrix:value
104                     Force a specific output  channel  ordering  for  a  given
105                     device.   value  is  a  comma  separated list of AO style
106                     channel names, eg, L,R,C,LFE,BL,BR,SL,SR.
107
108              verbose
109                     Turn on verbose output for a chosen driver. the -v option
110                     will also set the driver verbose option.
111
112              quiet  Force chosen driver to be completely silent.  Even errors
113                     will not produce any output. -q will also set the  driver
114                     quiet option.
115
116
117       aixs   AIX live output driver. Options:
118
119              dev:value
120                     Set AIX output device to value
121
122
123       alsa   Advanced Linux Sound Architecture live output driver. Options:
124
125              buffer_time:value
126                     Override  the  default hardware buffer size (in millisec‐
127                     onds).
128
129              dev:value
130                     ALSA device label to use. Examples include "hw:0" for the
131                     first  soundcard  and  "hw:1"  for  the second.  The alsa
132                     driver  normally  chooses  one  of  "surround71",   "sur‐
133                     round51", "surround40" or "default" automatically depend‐
134                     ing on number of output channels.  For more  information,
135                     see http://alsa.opensrc.org/ALSA+device+labels
136
137              period_time:value
138                     Override  the  default hardware period size (in microsec‐
139                     onds).
140
141              period_time:value
142                     Override the default hardware period size  (in  microsec‐
143                     onds).
144
145              use_mmap:value
146                     value is set to "yes" or "no" to override the compiled-in
147                     default to use or not use mmap  device  access.   In  the
148                     past,  some  buggy  alsa drivers have behaved better when
149                     not using mmap access at the penalty of  slightly  higher
150                     CPU usage.
151
152
153       arts   aRts Sound Daemon live output driver. Options:
154
155              multi:value
156                     value  is  set to "yes" or "no" to allow opening the aRts
157                     playback  device  for   multiply   concurrent   playback.
158                     Although  the  driver works properly in multi mode, it is
159                     known to  occasionally  crash  the  aRts  server  itself.
160                     Default behavior is "no".
161
162
163       au     Sun  audio  file output.  Writes the audio samples in AU format.
164              The AU format supports writing to unseekable files like standard
165              out.  In such circumstances, the AU header will specify the sam‐
166              ple format, but not the length of the recording.
167
168
169       esd    Enlightened Sound Daemon live output. Options:
170
171              host:value
172                     value specifies the hostname where esd is running.   This
173                     can   include   a  port  number  after  a  colon,  as  in
174                     "whizbang.com:555".  (Default = localhost)
175
176              client_name:value
177                     Sets the client name for the new audio  stream.  Defaults
178                     to "libao client".
179
180
181       irix   IRIX live output audio driver.
182
183
184       macosx MacOS  X 'AUHAL' live output driver.  This driver supports MacOS
185              X 10.5 and later (10.4 and earlier uses an earlier, incompatible
186              interface). Options:
187
188              buffer_time:value
189                     Set  the  hardware buffer size to the equivalent of value
190                     milliseconds.
191
192
193       nas    Network Audio Server live output driver. Options:
194
195              buf_size:value
196                     Set size of audio buffer on server in bytes.
197
198              host:value
199                     Set location of NAS server; See nas(1) for format.
200
201
202       null   Null driver.  All audio data is discarded.  (Note: Audio data is
203              not  written  to /dev/null !)  You could use this driver to test
204              raw decoding speed without output overhead.
205
206
207       oss    Open Sound System driver for Linux and FreeBSD,  versions  2,  3
208              and 4. Options:
209
210              dsp:value
211                     DSP device for soundcard.  Defaults to /dev/dsp.
212
213
214       pulse  Pulseaudio live audio sound driver. Options:
215
216              server:value
217                     Specifies  location  of  remote  or  alternate Pulseaudio
218                     server.
219
220              sink:value
221                     Specifies a non-default Pulseaudio sink for audio stream.
222
223
224       raw    Raw file output.  Writes raw audio samples to a file. Options:
225
226              byteorder:value
227                     Chooses big endian ("big"), little endian ("little"),  or
228                     native ("native") byte order.  Default is native order.
229
230
231       roar   RoarAudio Daemon live output driver. Options:
232
233              server:value, host:value
234                     Specifies location of remote RoarAudio server to use.
235
236              id:value, dev:value
237                     Specifies  a  non-default mixer within a RoarAudio server
238                     for audio stream.
239
240              role:value
241                     Sets the role setting for the audio stream.
242
243              client_name:value
244                     Sets the client name for the new audio  stream.  Defaults
245                     to "libao client".
246
247
248       sndio  OpenBSD SNDIO live output driver. Options:
249
250              dev:value
251                     Specifies audio device to use for playback.
252
253
254       sun    Sun  Audio  live output driver for NetBSD, OpenBSD, and Solaris.
255              Options:
256
257              dev:value
258                     Audio device for soundcard.  Defaults to /dev/audio.
259
260
261
262       wav    WAV file output.  Writes the sound data to disk in  uncompressed
263              form.   If  multiple  files are played, all of them will be con‐
264              catenated into the same WAV file.  WAV files cannot  be  written
265              to  unseekable  files,  such as standard out.  Use the AU format
266              instead.
267
268
269       wmm    Windows MultiMedia live  output  driver  for  Win98  and  later.
270              Options:
271
272              dev:value
273                     Selects audio device to use for playback by device name.
274
275              id:value
276                     Selects  audio  device  to  use for playback by device id
277                     (card number).
278
279

EXAMPLES

281       The ogg123 command line is fairly  flexible,  perhaps  confusingly  so.
282       Here are some sample command lines and an explanation of what they do.
283
284       Play on the default soundcard:
285              ogg123 test.ogg
286
287       Play all of the files in the directory ~/music and its subdirectories.
288              ogg123 ~/music
289
290       Play a file using the OSS driver:
291              ogg123 -d oss test.ogg
292
293       Pass the "dsp" option to the OSS driver:
294              ogg123 -d oss -o dsp:/dev/mydsp
295
296       Use the ESD driver
297              ogg123 -d esd test.ogg
298
299       Use the WAV driver with the output file, "test.wav":
300              ogg123 -d wav -f test.wav test.ogg
301
302       Listen to a file while you write it to a WAV file:
303              ogg123 -d oss -d wav -f test.wav test.ogg
304
305       Note that options apply to the device declared to the left:
306              ogg123  -d  oss  -o  dsp:/dev/mydsp -d raw -f test2.raw -o byte‐
307              order:big test.ogg
308
309       Stress test your harddrive:
310              ogg123 -d oss -d wav -f 1.wav -d wav -f 2.wav -d wav -f 3.wav -d
311              wav -f 4.wav -d wav -f 5.wav test.ogg
312
313       Create an echo effect with esd and a slow computer:
314              ogg123 -d esd -d esd test.ogg
315

INTERRUPT

317       You  can abort ogg123 at any time by pressing Ctrl-C.  If you are play‐
318       ing multiple files, this will stop the current file and  begin  playing
319       the  next  one.   If  you  want to abort playing immediately instead of
320       skipping to the next file, press Ctrl-C within the first second of  the
321       playback of a new file.
322
323       Note  that  the  result of pressing Ctrl-C might not be audible immedi‐
324       ately, due to audio data buffering in the audio device.  This delay  is
325       system dependent, but it is usually not more than one or two seconds.
326
327

FILES

329       /etc/libao.conf
330              Can  be used to set the default output device for all libao pro‐
331              grams.
332
333
334       ~/.libao
335              Per-user config file to override the system wide  output  device
336              settings.
337

BUGS

339       Piped  WAV files may cause strange behavior in other programs.  This is
340       because WAV files store the data length in the  header.   However,  the
341       output  driver  does not know the length when it writes the header, and
342       there is no value that means "length unknown".  Use the raw or au  out‐
343       put driver if you need to use ogg123 in a pipe.
344
345

AUTHORS

347       Program Authors:
348              Kenneth Arnold <kcarnold-xiph@arnoldnet.net>
349              Stan Seibert <volsung@xiph.org>
350
351
352       Manpage Author:
353              Stan Seibert <volsung@xiph.org>
354
355

SEE ALSO

357       libao.conf(5), oggenc(1), vorbiscomment(1), ogginfo(1)
358
359
360
361
362Xiph.Org Foundation              2010 March 24                       ogg123(1)
Impressum