SNDIO(7)           FreeBSD Miscellaneous Information Manual           SNDIO(7)

NAME
     sndio â< interface to audio and MIDI

DESCRIPTION
     Programs access audio and MIDI hardware using the sndio library.  It
     allows both access through the sndiod(8) server and raw access to the
     hardware.  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
     privileges.  The sndiod(8) server supports multiple connections at a
     time, allowing 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 established 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
     programs using standard MIDI Machine Control (MMC), MIDI Time Code (MTC),
     and master volume messages.

AUDIO AND MIDI DESCRIPTORS
     From the user's perspective every audio device or MIDI port has a
     descriptor of the form:

           type[@hostname][,servnum]/devnum[.option]

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

                  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
               corresponds to the character device minor number.  For audio
               devices or MIDI ports created with sndiod(8) it corresponds to
               the number 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).

DEFAULTS
     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
     reserved 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 default, e.g. a MIDI player could use a software synthesizer
     with no manual configuration required.

AUTHENTICATION
     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
     automatically 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.

ENVIRONMENT
     AUDIODEVICE     Audio device descriptor to use when no descriptor is
                     explicitly specified to a program.
     MIDIDEVICE      MIDI port descriptor to use when no descriptor is
                     explicitly 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.

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

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

FreeBSD 13.0-RELEASE             June 15, 2021            FreeBSD 13.0-RELEASE
html   Home