SNDIO(7) Miscellaneous Information Manual SNDIO(7)

# [NAME](#NAME)

`sndio` — audio and MIDI device descriptors

# [DESCRIPTION](#DESCRIPTION)

Programs access audio and MIDI hardware using the `sndio` library. It allows both access through the [sndiod(8)](/man/os/sndio/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)](/man/os/sndio/sndiod.8) server, because raw access to the hardware is exclusive and requires additional privileges. The [sndiod(8)](/man/os/sndio/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)](/man/os/sndio/sndiod.8) may also be established through the network, including from virtual machines.

The [sndiod(8)](/man/os/sndio/sndiod.8) server exposes [*MIDI thru*](#MIDI) 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)](/man/os/sndio/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](#Server_device_descriptors)

From the user's perspective, every audio device or MIDI port exposed by [sndiod(8)](/man/os/sndio/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`](#snd)

Audio device exposed by [sndiod(8)](/man/os/sndio/sndiod.8).

[`midithru`](#midithru)

MIDI thru port created with [sndiod(8)](/man/os/sndio/sndiod.8).

[`midi`](#midi)

MIDI port exposed by [sndiod(8)](/man/os/sndio/sndiod.8).

`hostname`

The hostname or address where the remote [sndiod(8)](/man/os/sndio/sndiod.8) server to connect to is running.

`servnum`

The number of the [sndiod(8)](/man/os/sndio/sndiod.8) server to connect to, corresponding to the integer specified using the `-U` option of [sndiod(8)](/man/os/sndio/sndiod.8). Useful only if multiple [sndiod(8)](/man/os/sndio/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)](/man/os/sndio/sndiod.8) command line.

`option`

Corresponds to the sub-device string registered using the `-s` option of [sndiod(8)](/man/os/sndio/sndiod.8).

## [Raw device descriptors](#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](#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)](/man/os/sndio/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](#Authentication)

For privacy reasons only one user may have connections to [sndiod(8)](/man/os/sndio/sndiod.8) at a given time. Users are identified by their [*session cookie*](#session), 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](#ENVIRONMENT)

[`AUDIODEVICE`](#AUDIODEVICE)

Audio device descriptor to use when no descriptor is explicitly specified to a program.

[`AUDIOPLAYDEVICE`](#AUDIOPLAYDEVICE)

Audio device descriptor to use for play-only mode when no descriptor is explicitly specified to a program. Overrides `AUDIODEVICE`.

[`AUDIORECDEVICE`](#AUDIORECDEVICE)

Audio device descriptor to use for record-only mode when no descriptor is explicitly specified to a program. Overrides `AUDIODEVICE`.

[`MIDIDEVICE`](#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](#FILES)

~/.sndio/cookie

User's session authentication cookie.

/dev/audioN

Raw audio devices.

/dev/rmidiN

Raw MIDI ports.

# [EXAMPLES](#EXAMPLES)

[`snd/0`](#snd/0)

Audio device referred to by the first `-f` option of [sndiod(8)](/man/os/sndio/sndiod.8).

[`snd/rear`](#snd/rear)

Sub-device registered with “-s rear”.

[`midithru/0`](#midithru/0)

First MIDI thru port created with [sndiod(8)](/man/os/sndio/sndiod.8).

[`default`](#default)

Default audio or MIDI device.

[`rsnd/0`](#rsnd/0)

Direct hardware access to /dev/audio0.

[`rmidi/5`](#rmidi/5)

Direct hardware access to /dev/rmidi5.

# [SEE ALSO](#SEE_ALSO)

[aucat(1)](/man/os/sndio/aucat.1), [midicat(1)](/man/os/sndio/midicat.1), [sndioctl(1)](/man/os/sndio/sndioctl.1), [mio\_open(3)](/man/os/sndio/mio_open.3), [sio\_open(3)](/man/os/sndio/sio_open.3), [sioctl\_open(3)](/man/os/sndio/sioctl_open.3), [audio(4)](/man/os/sndio/audio.4), [midi(4)](/man/os/sndio/midi.4), [sndiod(8)](/man/os/sndio/sndiod.8)

Linux 4.19.0-gvisor

---

Document: sndio(7) from sndio 1.10.0-r10 (Chainguard OS)
Source: https://github.com/ratchov/sndio