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

FreeBSD Manual Pages


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

     sndiod -- audio/MIDI server

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

     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.

     -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
	     Same as -f	except that if the device is disconnected, the one
	     given with	the previous -f	or -F option will be used.

     -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.  If no	-f option is used, sndiod will
	     use rsnd/0, rsnd/1, ..., rsnd/3.

     -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-

     -Q	port
	     Specify an	alternate MIDI port to use.  If	it doesn't work, the
	     one given with the	last -Q	or -q options will be used.  For in-
	     stance, this allows a USB MIDI controller to be replaced without
	     the need to restart programs using	it.

     -q	port
	     Expose the	given MIDI port.  This allows multiple programs	to
	     share the port.  If no -q option is used, sndiod will use
	     rmidi/0, rmidi/1, ..., rmidi/7.

     -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 a 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 127.

     -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.  The default is off.

     -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	480 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 SIGINT or SIGTERM, it terminates.  If sndiod is sent
     SIGHUP, it	reopens	all audio devices and MIDI ports.

     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.

     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

     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

     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

	   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-

	   +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.

     If	devices	specified with -F are unavailable when needed or unplugged at
     runtime, sndiod will attempt to seamlessly	fall back to the last device

     sndiod will not automatically switch to specified device that is plugged
     at	runtime.  Instead, sndioctl(1) must be used to change the
     server.device control.

     For instance, specifying a	USB device with	-F following a PCI device with
     -f	allows sndiod to use the USB one preferably when it's connected	and to
     fall back to the PCI one when it's	disconnected.

     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-

	   $ sndiod -r 48000 -b	480 -z 240


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

     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
     themselves	in the foot by creating	such a deadlock.

FreeBSD	13.0			October	5, 2022			  FreeBSD 13.0


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

home | help