1.\" $OpenBSD: sndio.7,v 1.27 2021/11/01 14:43:24 ratchov Exp $ 2.\" 3.\" Copyright (c) 2007 Alexandre Ratchov <alex@caoua.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: November 1 2021 $ 18.Dt SNDIO 7 19.Os 20.Sh NAME 21.Nm sndio 22.Nd audio and MIDI device descriptors 23.Sh DESCRIPTION 24Programs access audio and MIDI hardware using the 25.Nm sndio 26library. 27It allows both access through the 28.Xr sndiod 8 29server and raw access to the hardware. 30The audio device or MIDI port, as well as the access method, 31are designated by the sndio descriptor. 32It is provided by the user with the program device selection method, 33or with the 34.Ev AUDIODEVICE 35and 36.Ev MIDIDEVICE 37environment variables if there's no device selection method. 38.Pp 39Usually, programs access the hardware via the 40.Xr sndiod 8 41server, because raw access to the hardware is exclusive and 42requires additional privileges. 43The 44.Xr sndiod 8 45server supports multiple connections at a time, allowing multiple programs to 46use the hardware concurrently. 47It performs the necessary audio processing on the fly to 48overcome any incompatibility between software and hardware. 49Connections to 50.Xr sndiod 8 51may also be established through the network, including from virtual machines. 52.Pp 53The 54.Xr sndiod 8 55server exposes 56.Em MIDI thru 57ports, allowing one program to send MIDI data to other programs, 58for instance to allow a sequencer to send events to a synthesizer. 59.Pp 60Additionally, 61.Xr sndiod 8 62exposes a MIDI port used to control audio programs using 63standard MIDI Machine Control (MMC), MIDI Time Code (MTC), 64and master volume messages. 65.Ss Server device descriptors 66From the user's perspective, every audio device or MIDI port exposed by 67.Xr sndiod 8 68has a descriptor of the form: 69.Bd -literal -offset center 70type[@hostname][,servnum]/[devnum|option] 71.Ed 72.Pp 73This information is used by programs to determine 74how to access the audio device or MIDI port. 75.Bl -tag -width "hostname" 76.It Ar type 77The type of the audio device or MIDI port. 78Possible values are: 79.Pp 80.Bl -tag -width "midithru" -offset 3n -compact 81.It Cm snd 82Audio device exposed by 83.Xr sndiod 8 . 84.It Cm midithru 85MIDI thru port created with 86.Xr sndiod 8 . 87.It Cm midi 88MIDI port exposed by 89.Xr sndiod 8 . 90.El 91.It Ar hostname 92The hostname or address where the remote 93.Xr sndiod 8 94server to connect to is running. 95.It Ar servnum 96The number of the 97.Xr sndiod 8 98server to connect to, corresponding to the integer specified using the 99.Fl U 100option of 101.Xr sndiod 8 . 102Useful only if multiple 103.Xr sndiod 8 104servers are running on the same system. 105.It Ar devnum 106Device number. 107It corresponds to the number of the corresponding 108.Fl f 109or 110.Fl q 111option on the 112.Xr sndiod 8 113command line. 114.It Ar option 115Corresponds to the sub-device string registered using the 116.Fl s 117option of 118.Xr sndiod 8 . 119.El 120.Ss Raw device descriptors 121Every raw audio device or MIDI port has a descriptor of the form: 122.Pp 123.D1 Ar type Ns / Ns Ar devnum 124.Pp 125The 126.Ar type 127can be either 128.Cm rsnd 129or 130.Cm rmidi . 131The rsnd/0 device descriptor accesses the 132.Pa /dev/audio0 133device, rsnd/1 accesses 134.Pa /dev/audio1 , 135and so on. 136Similarly, rmidi/0 accesses 137.Pa /dev/rmidi0 138and so on. 139.Ss Default Audio and MIDI devices 140When no audio device descriptor is provided to a program 141or when the reserved word 142.Cm default 143is used as the audio device, the program will use the 144one specified in the 145.Ev AUDIODEVICE , AUDIOPLAYDEVICE 146and/or 147.Ev AUDIORECDEVICE 148environment variables. 149If they are not set, the program first tries to connect to 150.Li snd/default . 151If that fails, it then tries to use 152.Li rsnd/0 . 153.Pp 154Similarly, if no MIDI descriptor is provided to a program 155or when the reserved word 156.Cm default 157is passed as the device descriptor, 158the program uses the one specified in the 159.Ev MIDIDEVICE 160environment variable. 161If it is not set, the program first tries to connect to 162.Li midithru/0 . 163If that fails, it then tries to use 164.Li rmidi/0 . 165As long as 166.Xr sndiod 8 167is running, this allows programs to exchange MIDI data on 168machines with no MIDI hardware by default, e.g. a MIDI player 169could use a software synthesizer with no manual configuration 170required. 171.Ss Authentication 172For privacy reasons only one user may have connections to 173.Xr sndiod 8 174at a given time. 175Users are identified by their 176.Em session cookie , 177which is automatically generated by audio or MIDI programs 178upon the first connection to the server. 179The cookie is stored in 180.Pa "$HOME/.sndio/cookie" 181and contains 128 bits of raw random data. 182.Pp 183If a session needs to be shared between multiple users, they 184can connect to the server using the same cookie. 185.Sh ENVIRONMENT 186.Bl -tag -width "AUDIOPLAYDEVICE" -compact 187.It Ev AUDIODEVICE 188Audio device descriptor to use 189when no descriptor is explicitly specified to a program. 190.It Ev AUDIOPLAYDEVICE 191Audio device descriptor to use for play-only mode 192when no descriptor is explicitly specified to a program. 193Overrides 194.Ev AUDIODEVICE . 195.It Ev AUDIORECDEVICE 196Audio device descriptor to use for record-only mode 197when no descriptor is explicitly specified to a program. 198Overrides 199.Ev AUDIODEVICE . 200.It Ev MIDIDEVICE 201MIDI port descriptor to use 202when no descriptor is explicitly specified to a program. 203.El 204.Pp 205These environment variables are ignored by 206.Nm 207if the program has the set-user-ID or set-group-ID bits set. 208.Sh FILES 209.Bl -tag -width "~/.sndio/cookie" -compact 210.It Pa ~/.sndio/cookie 211User's session authentication cookie. 212.It Pa /dev/audioN 213Raw audio devices. 214.It Pa /dev/rmidiN 215Raw MIDI ports. 216.El 217.Sh EXAMPLES 218.Bl -tag -width "midithru/0" -compact 219.It Li snd/0 220Audio device referred to by the first 221.Fl f 222option of 223.Xr sndiod 8 . 224.It Li snd/rear 225Sub-device registered with 226.Dq -s rear . 227.It Li midithru/0 228First MIDI thru port created with 229.Xr sndiod 8 . 230.It Li default 231Default audio or MIDI device. 232.It Li rsnd/0 233Direct hardware access to 234.Pa /dev/audio0 . 235.It Li rmidi/5 236Direct hardware access to 237.Pa /dev/rmidi5 . 238.El 239.Sh SEE ALSO 240.Xr aucat 1 , 241.Xr midicat 1 , 242.Xr sndioctl 1 , 243.Xr mio_open 3 , 244.Xr sio_open 3 , 245.Xr sioctl_open 3 , 246.Xr audio 4 , 247.Xr midi 4 , 248.Xr sndiod 8 249