out123(1)

out123(1) — straight from the General Commands Manual, and yes bestie we're doing this 💖

🎀 NAME 🎀

out123 — send raw PCM audio or a waveform pattern to an output device

🦋 SYNOPSIS 🦋

cat audio.raw | out123 [ - ] [ options  ]

out123 [ options ] filename [ filename ... ]

out123 --wave-freq freq1[,freq2,...] [ options ]

out123 --source geiger [ options ]

💅 DESCRIPTION 💅

okay so here's the vibe: out123 reads raw PCM data — in host byte order, don't forget that part — from standard input, and plays it on the audio device you picked with your options. 🎧

OR. plot twist. it can generate periodic or random signals for playback all by itself, no input file needed. main character energy, fr fr. ✨

🔥 OPTIONS 🔥

so out123 options can be either the traditional POSIX one-letter options, or the GNU style long options. POSIX style ones start with a single -, GNU long ones start with --. Option arguments (if they even need one) follow separated by whitespace — not =, bestie, we don't do that here. And heads up: some options can be absent from your installation when they were disabled in the build process. not ghosting you, they just weren't compiled in. 😭

• --name name — sets the name of this instance, possibly used in various places. this sets the client name for JACK output.
• -o module, --output module — pick your audio output module. you can hand it a comma-separated list and it'll use the first one that works. also peep -a.
• --list-modules — lists the available modules. that's it, that's the whole option 💅
• --list-devices — lists the available output devices for the given output module. if the chosen module has literally no device-listing functionality, it prints an error and out123 exits with a non-zero code. rude but fair.
• -a dev, --audiodevice dev — specify the audio device to use. the default and the possible values depend on the active output. for the JACK output, you can give a comma-separated list of ports to connect to (one for each channel).
• -s, --stdout — the audio samples get written to standard output instead of being played through the audio device. the output format is the same as the input ... so in this mode out123 acts similar to the standard tool cat, possibly with some conversions involved. this shortcut is equivalent to -o raw -a -.
• -S, --STDOUT — this variant additionally writes the data to stdout while still playing it on the output device. so it's more like some flavour of tee than a cat. 👑
• -O file, --outfile — write raw output into a file (instead of just redirecting standard output to a file with the shell). this shortcut is equivalent to -o raw -a file.
• -w file, --wav — write output as a WAV file file, or to standard output if - or the empty string is used as the file name. you can also use --au and --cdr for AU and CDR format, respectively. note that WAV/AU writing to non-seekable files or redirected stdout needs some thought. the header is written with the first actual data. the result of decoding nothing to WAV/AU is a file consisting just of the header when it is seekable, and really nothing when it's not (not even a header). correctly writing data with prophetic headers to stdout is no easy business. this shortcut is equivalent to -o wav -a file.
• --au file — write to file in SUN audio format. if - or the empty string is used as the filename, the AU file is written to stdout. see the paragraph about WAV writing for header fun with non-seekable streams. this shortcut is equivalent to -o au -a file.
• --cdr file — write to file as a CDR (CD-ROM audio, more correctly CDDA for Compact Disc Digital Audio). if - or the empty string is used as the filename, the CDR file is written to stdout. this shortcut is equivalent to -o cdr -a file.
• -r rate, --rate rate — set sample rate in Hz (default: 44100). if this does not match the actual input sampling rate, you get changed pitch. might be intentional ;-)
• -R rate, --inputrate rate — set input sample rate to a different value. this triggers resampling if the output rate is indeed different. see --resample.
• --speed factor — speed up/down playback by that factor using resampling. see --resample.
• --resample method — this chooses the method for resampling between differing sampling rates, or to apply a change in tempo. you can choose between two variants of the syn123 resampler: fine (the default) and dirty. the fine one features 108 dB dynamic range and at worst-case 84% bandwidth. the dirty one uses a bit less CPU time (not that much, though) by reducing the dynamic range to 72 dB with worst-case bandwidth of 85%. the exact properties vary with the sampling rate ratio, as there is interpolation of filter coefficients involved.
• -c count, --channels count — set channel count to the given value.
• -C count, --inputch count — set input channel count to a differnt value than for output. this probably means you want some remixing. also see --mix.
• -e enc, --encoding enc — choose output sample encoding. possible values look like f32 (32-bit floating point), s32 (32-bit signed integer), u32 (32-bit unsigned integer) and the variants with different numbers of bits (s24, u24, s16, u16, s8, u8) and also special variants like ulaw and alaw 8-bit. see the output of out123's longhelp for actually available encodings. default is s16.
• --endian choice — select output endianess (byte order). choice is big, little, or native, which is the default. the processing can only work in native mode, so you need to specify input or output byte order if that does not match your machine. this also sets the input endianess if that is not set separately. see also --inputend and --byteswap.
• -E enc, --inputenc enc — specify input encoding different from output encoding, for conversion.
• --inputend choice — select input endianess (byte order). by default it is the same as output byte order. see --endian.
• --byteswap — a switch to trigger swapping of byte order just before output, after any other transformations. this works on top of any endianess you specify with … (and yeah, the original page literally trails off right there, bestie, I'm not making that up 💀)
• -m, --mono — set for single-channel audio (default is two channels, stereo).
• --stereo — select stereo output (2 channels, default).
• --list-encodings — list known encoding short and long names to standard output.
• --mix matrix — specify a mixing matrix between input and output channels as linear factors, comma separated list for the input channel factors for output channel 1, then output channel 2, and so forth. the default is a unit matrix if channel counts match, so for 3 channels the equivalent of both channels with halved amplitude, so --mix 0.5,0.5. for splitting mono to stereo, it is --mix 1,1 top keep the symmetry.
• --filter coeff — apply digital filter(s) before pre-amplification (see --preamp) with the coefficient list coeff as

b_0,...,b_N,a_0,...,a_N

where a_0=1 is mandatory and perhaps helps orientation a bit. multiple filters are separated by :.

• -P dbvalue, --preamp dbvalue — enable a pre-amplification stage that amplifies the signal with the given value in dB before output.
• --offset value — apply a PCM offset (floating point value scaled in [-1:1]) in the pre-amplification stage. normally, you would do that to correct a known DC offset in a recording.
• --clip mode — select clipping mode: soft or hard for forced clipping also for floating point output, implicit (default) for implied hard clipping during conversion where necessary.
• --dither — enable dithering for conversions to integer. if you insist. this is just some un-spectacular TPDF dither. for some people, that is not fancy enough. most people cannot be bothered that way or the other. 🫠
• --test-format — check if the given format is supported by the given driver and device (in the command line before encountering this), silently returning 0 as exit value if it is the case.
• --test-encodings — print out the short names of encodings supported with the current setup.
• --query-format — if the selected driver and device communicate some default accepted format, print out a command line fragment for out123 setting that format, always in that order: --rate <r> --channels <c> --encoding <e>
• -o h, --headphones — direct audio output to the headphone connector (some hardware only; AIX, HP, SUN).
• -o s, --speaker — direct audio output to the speaker (some hardware only; AIX, HP, SUN).
• -o l, --lineout — direct audio output to the line-out connector (some hardware only; AIX, HP, SUN).
• -b size, --buffer size — use an audio output buffer of size Kbytes. this is useful to bypass short periods of heavy system activity, which would normally cause the audio output to be interrupted. you should specify a buffer size of at least 1024 (i.e. 1 Mb, which equals about 6 seconds of usual audio data) or more; less than about 300 does not make much sense. the default is 0, which turns buffering off.
• --preload fraction — wait for the buffer to be filled to fraction before starting playback (fraction between 0 and 1). you can tune this prebuffering to either get sound faster to your ears or safer uninterrupted web radio. default is 0.2 (changed from 1 since version 1.23).
• --devbuffer seconds — set device buffer in seconds; <= 0 means default value. this is the small buffer between the application and the audio backend, possibly directly related to hardware buffers.
• --timelimit samples — set playback time limit in PCM samples if set to a value greater than zero. out123 will stop reading from stdin or playing from the generated wave table after reaching that number of samples.
• --seconds seconds — set time limit in seconds instead.
• --source name — choose the signal source: file (default) for playback of the given file(s) on the command line or standard input if there are none, or one of the generators wave (see --wave-freq), geiger (see --geiger-activity), or just white for some white noise.

and we are literally not even done yet, bestie — there's more of this page coming in part 2, don't go anywhere 🌈

• --wave-freq frequencies — sets the wave generator frequency, or a whole comma-separated list of them, so you can turn on a generated test signal instead of feeding from standard input. Empty values just repeat the previous one, periodt. ✨
• --wave-pat patterns — picks the waveform patterns for those generated waves, as a comma-separated list. The choices are sine, square, triangle, sawtooth, gauss, pulse, and shot. Empty values repeat the previous one, no cap. 🎀
• --wave-phase phases — sets waveform phase shift(s) as a comma-separated list. Negative values invert the pattern in time, and an empty value repeats the previous one. There’s also --wave-direction overriding that negative bit, iykyk. 💅
• --wave-direction — sets the wave direction explicitly. And bestie, the sign counts. 🔥
• --wave-sweep frequency — sweeps a generated wave to the given frequency, starting from the first one you specified for --wave-freq, and it uses the first wave pattern and direction too. 🦋
• --sweep-time seconds — sets the frequency sweep duration in seconds if it’s > 0. This defaults to the configured time limit if one is set, otherwise one second, because endless sweeps are just not sensible, okay? 😭
• --sweep-count count — sets the timelimit to exactly produce that many (smooth) sweeps. Slay. ✨
• --sweep-type type — sets the sweep type: lin(ear) for linear, qua(d) (default) for quadratic, or exp(onential) for an exponential change of frequency with time. 👑
• --sweep-hard — disables post-sweep smoothing for periodicity. Hard mode. 💀
• --genbuffer bytes — sets the buffer size (limit) for signal generators, if it’s > 0 (which is the default). This enforces a periodic buffer also for non-periodic signals, and the benefit is less runtime CPU overhead, as everything is precomputed as an enforced periodic signal. Efficiency queen. 💅
• --wave-limit samples — this is just an alias for --genbuffer. Twin vibes. 🫶
• --pink-rows number — activates the pink noise source and chooses rows for the algorithm (anything < 1 chooses the default). The generator follows code provided by Phil Burk (http://softsynth.com) and uses the Gardner method. 🎀
• --geiger-activity number — configures the simulation of a Geiger-Mueller counter as source, with the given number as average events per second. Play with it. It’s fun! ⚡
• -t, --test — test mode, bestie. The audio stream is read, but no output occurs. Silent but present. 🙈
• -v, --verbose — increases the verbosity level. Spill the tea. ☕
• -q, --quiet — quiet mode. Suppresses diagnostic messages. Shhh. 🤫
• --aggressive — tries to get higher priority. Go-getter energy. 💪
• -T, --realtime — tries to gain realtime priority. This option usually requires root privileges to have any effect, so don’t be surprised. 👑
• -?, --help — shows short usage instructions. The quick lil map. 🗺️
• --longhelp — shows long usage instructions. The full novel. 📚
• --version — prints the version string. Know your roots. ⭐

🫶 AUTHORS 🫶

• Maintainer: Thomas Orgis <maintainer@mpg123.org>, <thomas@orgis.org>
• Creator (ancestry of code inside mpg123): Michael Hipp
• Uses code or ideas from various people, see the AUTHORS file accompanying the source code.

💖 LICENSE 💖

out123 is licensed under the GNU Lesser/Library General Public License, LGPL, version 2.1 .

🌐 WEBSITE 🌐

• http://www.mpg123.org
• http://sourceforge.net/projects/mpg123

kisses, your out123(1) bestie 💖 this lil page is from 26 Apr 2020, out123(1), mwah 💋