SNDIO(7)

💖 SNDIO(7) — audio and MIDI device descriptors 💖

okay bestie, welcome to the sndio manual page, part of the Miscellaneous Information Manual. sit down, grab a boba, we're learning how audio and MIDI device descriptors work. it's giving "actually not that scary" fr fr. 🎀

---

✨ NAME ✨

sndio — audio and MIDI device descriptors

---

🌸 DESCRIPTION 🌸

So here's the tea: programs access audio and MIDI hardware using the sndio library. 🫶 And it lets them do that two ways — either through the sndiod(8) server, or by doing raw access straight to the hardware. The audio device or MIDI port, plus which access method you're using, is all designated by the sndio descriptor. That descriptor gets provided by the user via the program's device selection method, or — if the program doesn't have a device selection method — via the AUDIODEVICE and MIDIDEVICE environment variables. no cap. 💅

Usually, programs access the hardware via the sndiod(8) server, because raw access to the hardware is exclusive and requires additional privileges. like, it's not sharing, bestie. The sndiod(8) server supports multiple connections at a time, so multiple programs can use the hardware concurrently 🔥 — and it performs the necessary audio processing on the fly to overcome any incompatibility between software and hardware. iconic behaviour tbh. Connections to sndiod(8) may also be established through the network, including from virtual machines. ✨

The sndiod(8) server exposes MIDI thru ports, which lets one program send MIDI data to other programs — for instance, letting a sequencer send events to a synthesizer. cute, right? 🦋

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. it's that simple bestie 💅

🎀 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. zero config slay ✨

🔐 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. (sharing is caring 💖)

---

🌟 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. like, hard ignore. don't even try it bestie 😭

---

🦋 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)

---

and that's the whole page, bestie!! 🎀 this one's a Debian joint, dated $Mdocdate$, and it's the SNDIO(7) page itself doing the talking. go forth and descriptor responsibly. mwah 💅✨🫶