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

FreeBSD Manual Pages

  
 
  

home | help
SNDIOD(8)		  BSD System Manager's Manual		     SNDIOD(8)

NAME
     sndiod -- audio/MIDI server

SYNOPSIS
     sndiod [-d] [-a flag] [-b nframes]	[-C min:max] [-c min:max] [-e enc]
	    [-f	device]	[-j flag] [-L addr] [-m	mode] [-q port]	[-r rate]
	    [-s	name] [-t mode]	[-U unit] [-v volume] [-w flag]	[-z nframes]

DESCRIPTION
     The sndiod	daemon is an intermediate layer	between	audio or MIDI programs
     and the hardware.	It performs the	necessary audio	processing to allow
     any program to work on any	supported hardware.  By	default, sndiod	ac-
     cepts connections from programs running on	the same system	only; it ini-
     tializes only when	programs are using its services, allowing sndiod to
     consume a negligible amount of system resources the rest of the time.
     Systems with no audio hardware can	use sndiod to keep hot-pluggable de-
     vices usable by default at	virtually no cost.

     sndiod operates as	follows: it exposes at least one sub-device that any
     number of audio programs can connect to and use as	if it was audio	hard-
     ware.  During playback, sndiod receives audio data	concurrently from all
     programs, mixes it	and sends the result to	the hardware device.  Simi-
     larly, during recording it	duplicates audio data recorded from the	device
     and sends it to all programs.  Since audio	data flows through the sndiod
     process, it has the opportunity to	process	audio data on the fly:

	   +o   Change the sound	encoding to overcome incompatibilities between
	       software	and hardware.
	   +o   Route the sound from one	channel	to another, join stereo	or
	       split mono.
	   +o   Control the per-application playback volume as well as the mas-
	       ter volume.
	   +o   Monitor the sound being played, allowing	one program to record
	       what other programs play.

     Processing	is configured on a per sub-device basis, meaning that the
     sound of all programs connected to	the same sub-device will be processed
     according to the same configuration.  Multiple sub-devices	can be de-
     fined, allowing multiple configurations to	coexist.  The user selects the
     configuration a given program will	use by selecting the sub-device	the
     program uses.

     sndiod exposes MIDI thru boxes (hubs), allowing programs to send MIDI
     messages to each other or to hardware MIDI	ports in a uniform way.

     Finally, sndiod exposes a control MIDI port usable	for:

	   +o   Volume control.
	   +o   Common clock source for audio and MIDI programs.
	   +o   Start, stop and relocate	groups of audio	programs.

     The options are as	follows:

     -a	flag
	     Control whether sndiod opens the audio device or the MIDI port
	     only when needed or keeps it open all the time.  If the flag is
	     on	then the audio device or MIDI port is kept open	all the	time,
	     ensuring no other program can steal it.  If the flag is off, then
	     it's automatically	closed,	allowing other programs	to have	direct
	     access to the audio device, or the	device to be disconnected.
	     The default is off.

     -b	nframes
	     The buffer	size of	the audio device in frames.  A frame consists
	     of	one sample for each channel in the stream.  This is the	number
	     of	frames that will be buffered before being played and thus con-
	     trols the playback	latency.  The default is 7680 or twice the
	     block size	(-z), if the block size	is set.

     -C	min:max, -c min:max
	     The range of channel numbers for recording	and playback direc-
	     tions, respectively any client is allowed to use.	This is	a sub-
	     set of the	audio device channels.	The default is 0:1, i.e.
	     stereo.

     -d	     Enable debugging to standard error, and do	not disassociate from
	     the controlling terminal.	Can be specified multiple times	to
	     further increase log verbosity.

     -e	enc  Attempt to	configure the device to	use this encoding.  The	de-
	     fault is s16.  Encoding names use the following scheme: signed-
	     ness (s or	u) followed by the precision in	bits, the byte-order
	     (le or be), the number of bytes per sample, and the alignment
	     (msb or lsb).  Only the signedness	and the	precision are manda-
	     tory.  Examples: u8, s16le, s24le3, s24le4lsb.

     -f	device
	     Add this sndio(7) audio device to devices used for	playing	and/or
	     recording.	 Preceding per-device options (-aberwz)	apply to this
	     device.  Sub-devices (-s) that are	applied	after will be attached
	     to	this device.  Device mode and parameters are determined	from
	     sub-devices attached to it.

     -j	flag
	     Control whether program channels are joined or expanded if	the
	     number of channels	requested by a program is not equal to the de-
	     vice number of channels.  If the flag is off then client channels
	     are routed	to the corresponding device channel, possibly discard-
	     ing channels not present in the device.  If the flag is on, then
	     a single client channel may be sent on multiple device channels,
	     or	multiple client	channels may be	sent to	a single device	chan-
	     nel.  For instance, this feature could be used for	mono to	stereo
	     conversions.  The default is on.

     -L	addr
	     Specify a local network address sndiod should listen on; sndiod
	     will listen on TCP	port 11025+n, where n is the unit number spec-
	     ified with	-U.  Without this option, sndiod listens on the
	     UNIX-domain socket	only, and is not reachable from	any network.
	     If	the option argument is `-' then	sndiod will accept connections
	     from any address.	As the communication is	not secure, this op-
	     tion is only suitable for local networks where all	hosts and
	     users are trusted.

     -m	mode
	     Set the sub-device	mode.  Valid modes are play, rec, and mon,
	     corresponding to playback,	recording and monitoring.  A monitor-
	     ing stream	is a fake recording stream corresponding to the	mix of
	     all playback streams.  Multiple modes can be specified, separated
	     by	commas,	but the	same sub-device	cannot be used for both
	     recording and monitoring.	The default is play,rec	(i.e. full-du-
	     plex).

     -q	port
	     Expose the	given MIDI port.  This allows multiple programs	to
	     share the port.

     -r	rate
	     Attempt to	force the device to use	this sample rate in Hertz.
	     The default is 48000.

     -s	name
	     Add name to the list of sub-devices to expose.  This allows
	     clients to	use sndiod instead of the physical audio device	for
	     audio input and output in order to	share the physical device with
	     other clients.  Defining multiple sub-devices allows splitting a
	     physical audio device into	sub-devices having different proper-
	     ties (e.g.	channel	ranges).  The given name corresponds to	the
	     "option" part of the sndio(7) device name string.

     -t	mode
	     Select the	way clients are	controlled by MIDI Machine Control
	     (MMC) messages received by	sndiod.	 If the	mode is	off (the de-
	     fault), then programs are not affected by MMC messages.  If the
	     mode is slave, then programs are started synchronously by MMC
	     start messages; additionally, the server clock is exposed as MIDI
	     Time Code (MTC) messages allowing MTC-capable software or hard-
	     ware to be	synchronized to	audio programs.

     -U	unit
	     Unit number.  Each	sndiod server instance has an unique unit num-
	     ber, used in sndio(7) device names.  The default is 0.

     -v	volume
	     Software volume attenuation of playback.  The value must be be-
	     tween 1 and 127, corresponding to -42dB and -0dB attenuation in
	     1/3dB steps.  Clients inherit this	parameter.  Reducing the vol-
	     ume in advance allows a client's volume to	stay independent from
	     the number	of clients as long as their number is small enough.
	     18	volume units (i.e. -6dB	attenuation) allows the	number of
	     playback programs to be doubled.  The default is 118 i.e. -3dB.

     -w	flag
	     Control sndiod behaviour when the maximum volume of the hardware
	     is	reached	and a new program starts playing.  This	happens	only
	     when volumes are not properly set using the -v option.  If	the
	     flag is on, then the master volume	is automatically adjusted to
	     avoid clipping.  Using off	makes sense in the rare	situation
	     where all programs	lower their volumes.  The default is on.

     -z	nframes
	     The audio device block size in frames.  This is the number	of
	     frames between audio clock	ticks, i.e. the	clock resolution.  If
	     a sub-device is created with the -t option, and MTC is used for
	     synchronization, the clock	resolution must	be 96, 100 or 120
	     ticks per second for maximum accuracy.  For instance, 100 ticks
	     per second	at 48000Hz corresponds to a 480	frame block size.  The
	     default is	960 or half of the buffer size (-b), if	the buffer
	     size is set.

     On	the command line, per-device parameters	(-aberwz) must precede the de-
     vice definition (-f), and per-sub-device parameters (-Ccjmtvx) must pre-
     cede the sub-device definition (-s).  Sub-device definitions (-s) must
     follow the	definition of the device (-f) to which they are	attached.

     If	no audio devices (-f) are specified, settings are applied as if	the
     default device is specified.  If no sub-devices (-s) are specified	for a
     device, a default sub-device is created attached to it.  If a device (-f)
     is	defined	twice, both definitions	are merged: parameters of the first
     one are used but sub-devices (-s) of both definitions are created.	 The
     default sndio(7) device used by sndiod is rsnd/0, and the default sub-de-
     vice exposed by sndiod is snd/0.

     If	sndiod is sent SIGHUP, SIGINT or SIGTERM, it terminates.

     By	default, when the program cannot accept	recorded data fast enough or
     cannot provide data to play fast enough, the program is paused, i.e. sam-
     ples that cannot be written are discarded and samples that	cannot be read
     are replaced by silence.  If a sub-device is created with the -t option,
     then recorded samples are discarded, but the same amount of silence will
     be	written	once the program is unblocked, in order	to reach the right po-
     sition in time.  Similarly	silence	is played, but the same	amount of sam-
     ples will be discarded once the program is	unblocked.  This ensures
     proper synchronization between programs.

MIDI CONTROL
     sndiod creates a MIDI port	with the same name as the exposed audio	sub-
     device to which MIDI programs can connect.	 sndiod	exposes	the audio de-
     vice clock	and allows audio device	properties to be controlled through
     MIDI.

     A MIDI channel is assigned	to each	stream,	and the	volume is changed us-
     ing the standard volume controller	(number	7).  Similarly,	when the audio
     client changes its	volume,	the same MIDI controller message is sent out;
     it	can be used for	instance for monitoring	or as feedback for motorized
     faders.

     The master	volume can be changed using the	standard master	volume system
     exclusive message.

     Streams created with the -t option	are controlled by the following	MMC
     messages:

	   relocate	This message is	ignored	by audio sndiod	clients, but
			the given time position	is sent	to MIDI	ports as an
			MTC "full frame" message forcing all MTC-slaves	to re-
			locate to the given position (see below).

	   start	Put all	streams	in starting mode.  In this mode,
			sndiod waits for all streams to	become ready to	start,
			and then starts	them synchronously.  Once started, new
			streams	can be created (sndiod)	but they will be
			blocked	until the next stop-to-start transition.

	   stop		Put all	streams	in stopped mode	(the default).	In
			this mode, any stream attempting to start playback or
			recording is paused.  Client streams that are already
			started	are not	affected until they stop and try to
			start again.

     Streams created with the -t option	export the sndiod device clock using
     MTC, allowing non-audio software or hardware to be	synchronized to	the
     audio stream.  Maximum accuracy is	achieved when the number of blocks per
     second is equal to	one of the standard MTC	clock rates (96, 100 and
     120Hz).  The following sample rates (-r) and block	sizes (-z) are recom-
     mended:

	   +o   44100Hz,	441 frames (MTC	rate is	100Hz)
	   +o   48000Hz,	400 frames (MTC	rate is	120Hz)
	   +o   48000Hz,	480 frames (MTC	rate is	100Hz)
	   +o   48000Hz,	500 frames (MTC	rate is	96Hz)

     For instance, the following command will create two devices: the default
     snd/0 and a MIDI-controlled snd/0.mmc:

	   $ sndiod -r 48000 -z	400 -s default -t slave	-s mmc

     Streams connected to snd/0	behave normally, while streams connected to
     snd/0.mmc wait for	the MMC	start signal and start synchronously.  Regard-
     less of which device a stream is connected	to, its	playback volume	knob
     is	exposed.

EXAMPLES
     Start server using	default	parameters, creating an	additional sub-device
     for output	to channels 2:3	only (rear speakers on most cards), exposing
     the snd/0 and snd/0.rear devices:

	   $ sndiod -s default -c 2:3 -s rear

     Start server creating the default sub-device with low volume and an addi-
     tional sub-device for high	volume output, exposing	the snd/0 and
     snd/0.max devices:

	   $ sndiod -v 65 -s default -v	127 -s max

     Start server configuring the audio	device to use a	48kHz sample fre-
     quency, 240-frame block size, and 2-block buffers.	 The corresponding la-
     tency is 10ms, which is the time it takes the sound to propagate 3.5 me-
     ters.

	   $ sndiod -r 48000 -b	480 -z 240

SEE ALSO
     sndio(7)

BUGS
     Resampling	is low quality;	down-sampling especially should	be avoided
     when recording.

     Processing	is done	using 16-bit arithmetic, thus samples with more	than
     16	bits are rounded.  16 bits (i.e. 97dB dynamic) are largely enough for
     most applications though.	Processing precision can be increased to
     24-bit at compilation time	though.

     If	-a off is used,	sndiod creates sub-devices to expose first and then
     opens the audio hardware on demand.  Technically, this allows sndiod to
     attempt to	use one	of the sub-devices it exposes as an audio device, cre-
     ating a deadlock.	There's	nothing	to prevent the user from shooting him-
     self in the foot by creating such a deadlock.

BSD				August 7, 2020				   BSD

NAME | SYNOPSIS | DESCRIPTION | MIDI CONTROL | EXAMPLES | SEE ALSO | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sndiod&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help