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