1out123(1) General Commands Manual out123(1)
2
6 out123 - send raw PCM audio or a waveform pattern to an output device
7
9 cat audio.raw | out123 [ - ] [ options ]
10 out123 [ options ] filename [ filename ... ]
12 out123 --wave-freq freq1[,freq2,...] [ options ]
14 out123 --source geiger [ options ]
16
19 out123 reads raw PCM data (in host byte order) from standard input and
20 plays it on the audio device specified by given options. Alterna‐
21 tively, it can generate periodic or random signals for playback itself.
22
24 out123 options may be either the traditional POSIX one letter options,
25 or the GNU style long options. POSIX style options start with a single
26 '-', while GNU long options start with '--'. Option arguments (if
27 needed) follow separated by whitespace (not '='). Note that some op‐
28 tions can be absent from your installation when disabled in the build
29 process.
30 --name name
32 Set the name of this instance, possibly used in various places.
33 This sets the client name for JACK output.
34 -o module, --output module
36 Select audio output module. You can provide a comma-separated
37 list to use the first one that works. Also see -a.
38 --list-modules
40 List the available modules.
41 -a dev, --audiodevice dev
43 Specify the audio device to use. The default as well as the
44 possible values depend on the active output. For the JACK out‐
45 put, a comma-separated list of ports to connect to (for each
46 channel) can be specified.
47 -s, --stdout
49 The audio samples are written to standard output, instead of
50 playing them through the audio device. The output format is the
51 same as the input ... so in this mode, out123 acts similar the
52 standard tool cat, possibly with some conversions involved.
53 This shortcut is equivalent to '-o raw -a -'.
54 -S, --STDOUT
56 This variant additionally writes the data to stdout, while still
57 playing it on the output device. So it is more like some flavour
58 of tee than a cat.
59 -O file, --outfile
61 Write raw output into a file (instead of simply redirecting
62 standard output to a file with the shell). This shortcut is
63 equivalent to '-o raw -a file'.
64 -w file, --wav
66 Write output as WAV file file , or standard output if - is or
67 the empty string used as file name. You can also use --au and
68 --cdr for AU and CDR format, respectively. Note that WAV/AU
69 writing to non-seekable files or redirected stdout needs some
70 thought. The header is written with the first actual data. The
71 result of decoding nothing to WAV/AU is a file consisting just
72 of the header when it is seekable and really nothing when not
73 (not even a header). Correctly writing data with prophetic head‐
74 ers to stdout is no easy business. This shortcut is equivalent
75 to '-o wav -a file'.
76 --au file
78 Write to file in SUN audio format. If - or the empty string is
79 used as the filename, the AU file is written to stdout. See
80 paragraph about WAV writing for header fun with non-seekable
81 streams. This shortcut is equivalent to '-o au -a file'.
82 --cdr file
84 Write to file as a CDR (CD-ROM audio, more correctly CDDA for
85 Compact Disc Digital Audio). If - is or the empty string used
86 as the filename, the CDR file is written to stdout. This short‐
87 cut is equivalent to '-o cdr -a file'.
88 -r rate, --rate rate
90 Set sample rate in Hz (default: 44100). If this does not match
91 the actual input sampling rate, you get changed pitch. Might be
92 intentional;-)
93 -R rate, --inputrate rate
95 Set input sample rate to a different value. This triggers resam‐
96 pling if the output rate is indeed different. See --resample.
97 --speed factor
99 Speed up/down playback by that factor using resampling. See
100 --resample.
101 --resample method
103 This chooses the method for resampling between differing sam‐
104 pling rates or to apply a change in tempo. You can choose be‐
105 tween two variants of the syn123 resampler: fine (the default)
106 and dirty. The fine one features 108 dB dynamic range and at
107 worst-case 84% bandwidth. The dirty one uses a bit less CPU time
108 (not that much, though) by reducing the dynamic range to 72 dB
109 with worst-case bandwidth of 85%. The exact properties vary with
110 the sampling rate ratio, as there is interpolation of filter co‐
111 efficients involved.
112 -c count, --channels count
114 Set channel count to given value.
115 -C count, --inputch count
117 Set input channel count to a differnt value than for output.
118 This probably means you want some remixing. Also see --mix.
119 -e enc, --encoding enc
121 Choose output sample encoding. Possible values look like f32
122 (32-bit floating point), s32 (32-bit signed integer), u32
123 (32-bit unsigned integer) and the variants with different num‐
124 bers of bits (s24, u24, s16, u16, s8, u8) and also special vari‐
125 ants like ulaw and alaw 8-bit. See the output of out123's
126 longhelp for actually available encodings. Default is s16.
127 --endian choice
129 Select output endianess (byte order). Choice is big, little, or
130 native, which is the default. The processing can only work in
131 native mode, so you need to specify input or output byte order
132 if that does not match your machine. This also sets the input
133 endianess if that is not set separately. See also --inputend and
134 --byteswap.
135 -E enc, --inputenc enc
137 Specify input encoding different from output encoding for con‐
138 version.
139 --inputend choice
141 Select input endianess (byte order). By default it is the same
142 as output byte order. See --endian.
143 --byteswap
145 A switch to trigger swapping of byte order just before output,
146 after any other transformations. This works on top of any endi‐
147 aness you specify with
148 -m, --mono
150 Set for single-channel audio (default is two channels, stereo).
151 --stereo
153 Select stereo output (2 channels, default).
154 --list-encodings
156 List known encoding short and long names to standard output.
157 --mix matrix
159 Specify a mixing matrix between input and output channels as
160 linear factors, comma separated list for the input channel fac‐
161 tors for output channel 1, then output channel 2, and so forth.
162 The default is a unit matrix if channel counts match, so for 3
163 channels the equivalent of both channels with halved amplitude,
164 so '--mix 0.5,0.5'. For splitting mono to stereo, it is '--mix
165 1,1' top keep the symmetry.
166 --filter coeff
168 Apply digital filter(s) before pre-amplification (see --preamp)
169 with the coefficient list coeff as
170 b_0,...,b_N,a_0,...,a_N
171 where a_0=1 is mandatory and perhaps helps orientation a bit.
172 Multiple filters are separated by ':'.
173 -P dbvalue --preamp dbvalue
175 Enable a pre-amplification stage that amplifies the signal with
176 the given value in dB before output.
177 --offset value
179 Apply a PCM offset (floating point value scaled in [-1:1] in the
180 pre-amplification stage. Normally, you would do that to correct
181 a known DC offset in a recording.
182 --clip mode
184 Select clipping mode: 'soft' or 'hard' for forced clipping also
185 for floating point output, 'implicit' (default) for implied hard
186 clipping during conversion where necessary.
187 --dither
189 Enable dithering for conversions to integer. If you insist.
190 This is just some un-spectacular TPDF dither. For some people,
191 that is not fancy enough. Most people cannot be bothered that
192 way or the other.
193 --test-format
195 Check if given format is supported by given driver and device
196 (in command line before encountering this), silently returning 0
197 as exit value if it is the case.
198 --test-encodings
200 Print out the short names of encodings supported with the cur‐
201 rent setup.
202 --query-format
204 If the selected driver and device communicate some default ac‐
205 cepted format, print out a command line fragment for out123 set‐
206 ting that format, always in that order: --rate <r> --channels
207 <c> --encoding <e>
208 -o h, --headphones
210 Direct audio output to the headphone connector (some hardware
211 only; AIX, HP, SUN).
212 -o s, --speaker
214 Direct audio output to the speaker (some hardware only; AIX,
215 HP, SUN).
216 -o l, --lineout
218 Direct audio output to the line-out connector (some hardware
219 only; AIX, HP, SUN).
220 -b size, --buffer size
222 Use an audio output buffer of size Kbytes. This is useful to
223 bypass short periods of heavy system activity, which would nor‐
224 mally cause the audio output to be interrupted. You should
225 specify a buffer size of at least 1024 (i.e. 1 Mb, which equals
226 about 6 seconds of usual audio data) or more; less than about
227 300 does not make much sense. The default is 0, which turns
228 buffering off.
229 --preload fraction
231 Wait for the buffer to be filled to fraction before starting
232 playback (fraction between 0 and 1). You can tune this pre‐
233 buffering to either get sound faster to your ears or safer unin‐
234 terrupted web radio. Default is 0.2 (changed from 1 since ver‐
235 sion 1.23).
236 --devbuffer seconds
238 Set device buffer in seconds; <= 0 means default value. This is
239 the small buffer between the application and the audio backend,
240 possibly directly related to hardware buffers.
241 --timelimit samples
243 Set playback time limit in PCM samples if set to a value greater
244 than zero. out123 will stop reading from stdin or playing from
245 the generated wave table after reaching that number of samples.
246 --seconds seconds
248 Set time limit in seconds instead.
249 --source name
251 Choose the signal source: 'file' (default) for playback of the
252 given file(s) on the command line or standard input if there are
253 none, or one of the generators 'wave' (see --wave-freq), geiger
254 (see --geiger-activity), or just 'white' for some white noise.
255 --wave-freq frequencies
257 Set wave generator frequency or list of those with comma separa‐
258 tion for enabling a generated test signal instead of standard
259 input. Empty values repeat the previous one.
260 --wave-pat patterns
262 Set the waveform patterns of the generated waves as comma-sepa‐
263 rated list. Choices include sine, square, triangle, sawtooth,
264 gauss, pulse, and shot. Empty values repeat the previous one.
265 --wave-phase phases
267 Set waveform phase shift(s) as comma-separated list, negative
268 values inverting the pattern in time and empty value repeating
269 the previous. There is also --wave-direction overriding the neg‐
270 ative bit.
271 --wave-direction
273 Set wave direction explicitly (the sign counts).
274 --wave-sweep frequency
276 Sweep a generated wave to the given frequency, from first one
277 specified for --wave-freq, using the first wave pattern and di‐
278 rection, too.
279 --sweep-time seconds
281 Set frequency sweep duration in seconds if > 0. This defaults to
282 the configured time limit if set, otherwise one second, as end‐
283 less sweeps are not sensible.
284 --sweep-count count
286 Set timelimit to exactly produce that many (smooth) sweeps
287 --sweep-type type
289 Set sweep type: lin(ear) for linear, qua(d) (default) for qua‐
290 dratic, or exp(onential) for an exponential change of frequency
291 with time.
292 --sweep-hard
294 Disable post-sweep smoothing for periodicity.
295 --genbuffer bytes
297 Set the buffer size (limit) for signal generators, if > 0 (de‐
298 fault), this enforces a periodic buffer also for non-periodic
299 signals, benefit: less runtime CPU overhead, as everything is
300 precomputed as enforced periodic signal.
301 --wave-limit samples
303 This is an alias for --genbuffer.
304 --pink-rows number
306 Activate pink noise source and choose rows for the algorithm (<1
307 chooses default). The generator follows code provided by Phil
308 Burk (http://softsynth.com) and uses the Gardner method.
309 --geiger-activity number
311 This configures the simulation of a Geiger-Mueller counter as
312 source, with the given numer as average events per second. Play
313 with it. It's fun!
314 -t, --test
316 Test mode. The audio stream is read, but no output occurs.
317 -v, --verbose
319 Increase the verbosity level.
320 -q, --quiet
322 Quiet. Suppress diagnostic messages.
323 --aggressive
325 Tries to get higher priority
326 -T, --realtime
328 Tries to gain realtime priority. This option usually requires
329 root privileges to have any effect.
330 -?, --help
332 Shows short usage instructions.
333 --longhelp
335 Shows long usage instructions.
336 --version
338 Print the version string.
339
341 Maintainer:
342 Thomas Orgis <maintainer@mpg123.org>, <thomas@orgis.org>
343 Creator (ancestry of code inside mpg123):
345 Michael Hipp
346 Uses code or ideas from various people, see the AUTHORS file accompany‐
348 ing the source code.
349
351 out123 is licensed under the GNU Lesser/Library General Public License,
352 LGPL, version 2.1 .
353
355 http://www.mpg123.org
356 http://sourceforge.net/projects/mpg123
357 26 Apr 2020 out123(1)