Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
out123(1)		    General Commands Manual		     out123(1)

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

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

       out123 [	options	] filename [ filename ... ]

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

       out123 --source geiger [	options	]

       out123  reads raw PCM data (in host byte	order) from standard input and
       plays it	on the audio device  specified	by  given  options.   Alterna-
       tively, it can generate periodic	or random signals for playback itself.

       out123  options may be either the traditional POSIX one letter options,
       or the GNU style	long options.  POSIX style options start with a	single
       '-',  while  GNU	 long  options	start with '--'.  Option arguments (if
       needed) follow separated	by whitespace (not '=').  Note that  some  op-
       tions  can  be absent from your installation when disabled in the build

       --name name
	      Set the name of this instance, possibly used in various  places.
	      This sets	the client name	for JACK output.

       -o module, --output module
	      Select  audio  output  module. You can provide a comma-separated
	      list to use the first one	that works.  Also see -a.

	      List the available modules.

	      List the available output	devices	for given  output  module.  If
	      there  is	no functionality to list devices in the	chosen module,
	      an error will be printed and out123 will exit  with  a  non-zero

       -a dev, --audiodevice dev
	      Specify  the  audio  device  to use.  The	default	as well	as the
	      possible values depend on	the active output. For the  JACK  out-
	      put,  a  comma-separated	list  of ports to connect to (for each
	      channel) can be specified.

       -s, --stdout
	      The audio	samples	are written to	standard  output,  instead  of
	      playing them through the audio device.  The output format	is the
	      same as the input	... so in this mode, out123 acts  similar  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 is	more like some flavour
	      of tee than a cat.

       -O file,	--outfile
	      Write raw	output into a  file  (instead  of  simply  redirecting
	      standard	output	to  a  file with the shell).  This shortcut is
	      equivalent to '-o	raw -a file'.

       -w file,	--wav
	      Write output as WAV file file , or standard output if  -	is  or
	      the  empty  string  used as 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  not
	      (not even	a header). Correctly writing data with prophetic head-
	      ers 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
	      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 - is or the empty string used
	      as the filename, the CDR file is written to stdout.  This	short-
	      cut 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

       -R rate,	--inputrate rate
	      Set input	sample rate to a different value. This triggers	resam-
	      pling if the output rate is indeed different. See	--resample.

       --speed factor
	      Speed up/down playback by	 that  factor  using  resampling.  See

       --resample method
	      This  chooses  the  method for resampling	between	differing sam-
	      pling rates or to	apply a	change in tempo. You  can  choose  be-
	      tween  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 co-
	      efficients involved.

       -c count, --channels count
	      Set channel count	to 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  num-
	      bers of bits (s24, u24, s16, u16,	s8, u8)	and also special vari-
	      ants 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

       -E enc, --inputenc enc
	      Specify input encoding different from output encoding  for  con-

       --inputend choice
	      Select  input  endianess (byte order). By	default	it is the same
	      as output	byte order.  See --endian.

	      A	switch to trigger swapping of byte order just  before  output,
	      after any	other transformations.	This works on top of any endi-
	      aness you	specify	with

       -m, --mono
	      Set for single-channel audio (default is two channels, stereo).

	      Select stereo output (2 channels,	default).

	      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 fac-
	      tors 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
	      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.

	      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.

	      Check if given format is supported by given  driver  and	device
	      (in command line before encountering this), silently returning 0
	      as exit value if it is the case.

	      Print out	the short names	of encodings supported with  the  cur-
	      rent setup.

	      If  the  selected	driver and device communicate some default ac-
	      cepted format, print out a command line fragment for out123 set-
	      ting  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  nor-
	      mally  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  pre-
	      buffering	to either get sound faster to your ears	or safer unin-
	      terrupted	web radio.  Default is 0.2 (changed from 1 since  ver-
	      sion 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.

       --wave-freq frequencies
	      Set wave generator frequency or list of those with comma separa-
	      tion  for	 enabling  a generated test signal instead of standard
	      input. Empty values repeat the previous one.

       --wave-pat patterns
	      Set the waveform patterns	of the generated waves as  comma-sepa-
	      rated  list.   Choices include sine, square, triangle, sawtooth,
	      gauss, pulse, and	shot.  Empty values repeat the previous	one.

       --wave-phase phases
	      Set waveform phase shift(s) as  comma-separated  list,  negative
	      values  inverting	 the pattern in	time and empty value repeating
	      the previous. There is also --wave-direction overriding the neg-
	      ative bit.

	      Set wave direction explicitly (the sign counts).

       --wave-sweep frequency
	      Sweep  a	generated  wave	to the given frequency,	from first one
	      specified	for --wave-freq, using the first wave pattern and  di-
	      rection, too.

       --sweep-time seconds
	      Set frequency sweep duration in seconds if > 0. This defaults to
	      the configured time limit	if set,	otherwise one second, as  end-
	      less sweeps are not sensible.

       --sweep-count count
	      Set timelimit to exactly produce that many (smooth) sweeps

       --sweep-type type
	      Set  sweep  type:	lin(ear) for linear, qua(d) (default) for qua-
	      dratic, or exp(onential) for an exponential change of  frequency
	      with time.

	      Disable post-sweep smoothing for periodicity.

       --genbuffer bytes
	      Set  the	buffer size (limit) for	signal generators, if >	0 (de-
	      fault), this enforces a periodic buffer  also  for  non-periodic
	      signals,	benefit:  less	runtime	CPU overhead, as everything is
	      precomputed as enforced periodic signal.

       --wave-limit samples
	      This is an alias for --genbuffer.

       --pink-rows number
	      Activate pink noise source and choose rows for the algorithm (<1
	      chooses  default).   The generator follows code provided by Phil
	      Burk ( and uses the Gardner method.

       --geiger-activity number
	      This configures the simulation of	a  Geiger-Mueller  counter  as
	      source,  with the	given numer as average events per second. Play
	      with it. It's fun!

       -t, --test
	      Test mode.  The audio stream is read, but	no output occurs.

       -v, --verbose
	      Increase the verbosity level.

       -q, --quiet
	      Quiet.  Suppress diagnostic messages.

	      Tries to get higher priority

       -T, --realtime
	      Tries to gain realtime priority.	This option  usually  requires
	      root privileges to have any effect.

       -?, --help
	      Shows short usage	instructions.

	      Shows long usage instructions.

	      Print the	version	string.

	      Thomas Orgis <>, <>

       Creator (ancestry of code inside	mpg123):
	      Michael Hipp

       Uses code or ideas from various people, see the AUTHORS file accompany-
       ing the source code.

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


				  26 Apr 2020			     out123(1)


Want to link to this manual page? Use this URL:

home | help