NAME

     sndio — audio and MIDI device descriptors

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.

   Server device descriptors
     From the user's perspective, every audio device or MIDI port exposed by sndiod(8) 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:

                  snd       Audio device exposed by sndiod(8).
                  midithru  MIDI thru port created with sndiod(8).
                  midi      MIDI port exposed by sndiod(8).

     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.  It corresponds to the number of the corresponding -f or -q option
               on the sndiod(8) command line.

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

   Raw device descriptors
     Every raw audio device or MIDI port has a descriptor of the form:

           type/devnum

     The type can be either rsnd or rmidi.  The rsnd/0 device descriptor accesses the /dev/audio0
     device, rsnd/1 accesses /dev/audio1, and so on.  Similarly, rmidi/0 accesses /dev/rmidi0 and
     so on.

   Default Audio and MIDI devices
     When no audio device descriptor is provided to a program or when the reserved word default
     is used as the audio device, the program will use the one specified in the AUDIODEVICE,
     AUDIOPLAYDEVICE and/or AUDIORECDEVICE environment variables.  If they are not set, the
     program first tries to connect to snd/default.  If that fails, it then tries to use rsnd/0.

     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.
     AUDIOPLAYDEVICE  Audio device descriptor to use for play-only mode when no descriptor is
                      explicitly specified to a program.  Overrides AUDIODEVICE.
     AUDIORECDEVICE   Audio device descriptor to use for record-only mode when no descriptor is
                      explicitly specified to a program.  Overrides AUDIODEVICE.
     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      Raw audio devices.
     /dev/rmidiN      Raw MIDI ports.

EXAMPLES

     snd/0       Audio device referred to by the first -f option of sndiod(8).
     snd/rear    Sub-device registered with “-s rear”.
     midithru/0  First MIDI thru port created with sndiod(8).
     default     Default audio or MIDI device.
     rsnd/0      Direct hardware access to /dev/audio0.
     rmidi/5     Direct hardware access to /dev/rmidi5.

SEE ALSO

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