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)

Debian                                             $Mdocdate$                                           SNDIO(7)