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