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

FreeBSD Manual Pages


home | help
SNDIO(7)	   FreeBSD Miscellaneous Information Manual	      SNDIO(7)

     sndio -- interface	to audio and MIDI

     Programs access audio and MIDI hardware using the sndio library.  It al-
     lows both access through the sndiod(8) server and raw access to the hard-
     ware.  The	audio device or	MIDI port, as well as the access method, are
     designated	by the sndio descriptor.  It is	provided by the	user with the
     program device selection method, or with the AUDIODEVICE and MIDIDEVICE
     environment variables if there's no device	selection method.

     Usually, programs access the hardware via the sndiod(8) server, because
     raw access	to the hardware	is exclusive and requires additional privi-
     leges.  The sndiod(8) server supports multiple connections	at a time, al-
     lowing multiple programs to use the hardware concurrently.	 It performs
     the necessary audio processing on the fly to overcome any incompatibility
     between software and hardware.  Connections to sndiod(8) may also be es-
     tablished through the network, including from virtual machines.

     The sndiod(8) server exposes MIDI thru ports, allowing one	program	to
     send MIDI data to other programs, for instance to allow a sequencer to
     send events to a synthesizer.

     Additionally, sndiod(8) exposes a MIDI port used to control audio pro-
     grams using standard MIDI Machine Control (MMC), MIDI Time	Code (MTC),
     and master	volume messages.

     From the user's perspective every audio device or MIDI port has a de-
     scriptor of the form:


     This information is used by programs to determine how to access the audio
     device or MIDI port.

     type      The type	of the audio device or MIDI port.  Possible values

		  rsnd	    Raw	audio(4) device.
		  rmidi	    Raw	midi(4)	port.
		  snd	    Audio device exposed by sndiod(8).
		  midithru  MIDI thru port created with	sndiod(8).
		  midi	    MIDI port exposed by sndiod(8).
		  default   Default audio device or MIDI port (see below).

     hostname  The hostname or address where the remote	sndiod(8) server to
	       connect to is running.

     servnum   The number of the sndiod(8) server to connect to, corresponding
	       to the integer specified	using the -U option of sndiod(8).
	       Useful only if multiple sndiod(8) servers are running on	the
	       same system.

     devnum    Device number.  For hardware audio or MIDI ports, this corre-
	       sponds to the character device minor number.  For audio devices
	       or MIDI ports created with sndiod(8) it corresponds to the num-
	       ber of the corresponding	-fq option on the command line.

     option    Corresponds to the sub-device string registered using the -s
	       option of sndiod(8).

     For example:

	rsnd/0	    Raw	access to first	audio device.
	rmidi/5	    Raw	access to MIDI port number 5.
	snd/0	    Audio device referred by first -f option of	sndiod(8).
	snd/0.rear  Sub-device registered with -s rear.
	midithru/0  First MIDI thru port created with sndiod(8).

     If	default	is used	as the audio device, the program will use the one
     specified in the AUDIODEVICE environment variable.	 If it is not set, the
     program first tries to connect to snd/0.  If that fails, it then tries to
     use rsnd/0.  This allows the sndiod(8) audio server to be used by default
     and the raw hardware as fallback; programs	don't have to be reconfigured
     when sndiod(8) is started or stopped.

     Similarly,	if no MIDI descriptor is provided to a program or when the re-
     served word default is passed as the device descriptor, the program uses
     the one specified in the MIDIDEVICE environment variable.	If it is not
     set, the program first tries to connect to	midithru/0.  If	that fails, it
     then tries	to use rmidi/0.	 As long as sndiod(8) is running, this allows
     programs to exchange MIDI data on machines	with no	MIDI hardware by de-
     fault, e.g. a MIDI	player could use a software synthesizer	with no	manual
     configuration required.

     For privacy reasons only one user may have	connections to sndiod(8) at a
     given time.  Users	are identified by their	session	cookie,	which is auto-
     matically generated by audio or MIDI programs upon	the first connection
     to	the server.  The cookie	is stored in $HOME/.sndio/cookie and contains
     128 bits of raw random data.

     If	a session needs	to be shared between multiple users, they can connect
     to	the server using the same cookie.

     AUDIODEVICE     Audio device descriptor to	use when no descriptor is ex-
		     plicitly specified	to a program.
     MIDIDEVICE	     MIDI port descriptor to use when no descriptor is explic-
		     itly specified to a program.

     These environment variables are ignored by	sndio if the program has the
     set-user-ID or set-group-ID bits set.

     ~/.sndio/cookie  User's session authentication cookie.
     /dev/audioN      Audio devices.
     /dev/rmidiN      MIDI ports.

     aucat(1), midicat(1), sndioctl(1),	mio_open(3), sio_open(3),
     sioctl_open(3), audio(4), midi(4),	sndiod(8)

FreeBSD	13.0			 July 25, 2021			  FreeBSD 13.0


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

home | help