1.\" $OpenBSD: sndio.7,v 1.18 2016/01/07 08:51:48 jmc 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: January 7 2016 $ 18.Dt SNDIO 7 19.Os 20.Sh NAME 21.Nm sndio 22.Nd interface to audio and MIDI 23.Sh DESCRIPTION 24The 25.Nm sndio 26audio and MIDI system provides access to audio and MIDI hardware and 27to services provided by 28.Xr sndiod 8 , 29summarized below. 30.Pp 31Hardware 32.Xr audio 4 33devices correspond to peripherals. 34Only one application may use any device at a given time. 35Generally a limited number of encodings, sample rates and channel numbers are 36supported by the hardware, which may not meet the requirements of 37audio programs. 38.Pp 39To overcome hardware limitations and to allow multiple applications 40to share the hardware, 41.Xr sndiod 8 42can be used. 43It exposes one or more software sub-devices backed by the underlying hardware, 44while doing all necessary conversions on the fly. 45It can mix multiple streams or split the hardware into 46multiple sub-devices, to allow programs to use the hardware 47concurrently. 48.Pp 49Hardware MIDI ports correspond to serial connectors provided by the 50.Xr midi 4 51driver. 52They are typically used to access MIDI hardware (synthesizers, keyboards, 53control surfaces, etc.), but they do not allow applications to exchange 54information using the MIDI protocol. 55.Pp 56Software MIDI thru boxes allow one application to send MIDI data to other 57applications connected to the thru box (for instance a software sequencer 58can send events to multiple software synthesizers). 59There's no hardware involved: thru boxes are created by 60.Xr sndiod 8 . 61.Pp 62Additionally, 63.Xr sndiod 8 64exposes a MIDI port used to control and monitor audio streams 65in real time using MIDI. 66.Sh DEVICE NAMES 67From the user's perspective every audio interface, MIDI port, and 68.Xr sndiod 8 69service has a name of the form: 70.Bd -literal -offset center 71type[@hostname][,unit]/devnum[.option] 72.Ed 73.Pp 74This information is used by audio and MIDI applications to determine 75how to access the audio device or MIDI port. 76.Bl -tag -width "hostname" 77.It Pa type 78The type of the audio device or MIDI port. 79Possible values are: 80.Pp 81.Bl -tag -width "midithru" -offset 3n -compact 82.It Pa rsnd 83Raw 84.Xr audio 4 85device. 86.It Pa rmidi 87Raw 88.Xr midi 4 89port. 90.It Pa snd 91Audio device exposed by 92.Xr sndiod 8 . 93.It Pa midithru 94MIDI thru box created with 95.Xr sndiod 8 . 96.It Pa midi 97MIDI port exposed by 98.Xr sndiod 8 . 99.It Pa default 100Default audio device or MIDI port (see below). 101.El 102.It Pa hostname 103The hostname or address where the remote 104.Xr sndiod 8 105server to connect to is running. 106.It Pa unit 107The number of the 108.Xr sndiod 8 109server to connect to, corresponding to the integer specified using the 110.Fl U 111option of 112.Xr sndiod 8 . 113Useful only if multiple 114.Xr sndiod 8 115servers are running on the same system. 116.It Pa devnum 117Device number. 118For hardware audio or MIDI ports, this corresponds to 119the character device minor number. 120For audio devices or MIDI ports created with 121.Xr sndiod 8 122it corresponds to the number of the corresponding 123.Fl fq 124option on the command line. 125.It Pa option 126Corresponds to the sub-device string registered using the 127.Fl s 128option of 129.Xr sndiod 8 . 130.El 131.Pp 132For example: 133.Pp 134.Bl -tag -width "snd/0.rear" -offset 3n -compact 135.It Pa rsnd/0 136First hardware audio device. 137.It Pa rmidi/5 138Hardware MIDI port number 5. 139.It Pa snd/0 140First audio device exposed by 141.Xr sndiod 8 . 142.It Pa snd/0.rear 143Sub-device registered with 144.Fl s Fa rear . 145.It Pa midithru/0 146First MIDI thru box created with 147.Xr sndiod 8 . 148.El 149.Sh DEFAULTS 150If 151.Pa default 152is used as the audio device, the program will use the 153one specified in the 154.Ev AUDIODEVICE 155environment variable. 156If it is not set, the program first tries to connect to 157.Pa snd/0 . 158If that fails, it then tries to use 159.Pa rsnd/0 . 160This allows the 161.Xr sndiod 8 162audio server to be used by default and the bare hardware as fallback; 163programs don't have to be reconfigured when 164.Xr sndiod 8 165is started or stopped. 166.Pp 167If 168.Pa default 169is used as the MIDI port, the program will use the 170one specified in the 171.Ev MIDIDEVICE 172environment variable. 173If it is not set, the program first tries to connect to 174.Pa midithru/0 . 175If that fails, it then tries to use 176.Pa rmidi/0 . 177As long as 178.Xr sndiod 8 179is running, this allows programs to exchange MIDI data on 180machines with no MIDI hardware by default, e.g. a MIDI player 181could use a software synthesizer with no manual configuration 182required. 183.Sh AUTHENTICATION 184If a shared 185.Xr sndiod 8 186server is running, for privacy reasons only one user may have 187connections to it at a given time 188(though the same user could have multiple connections to it). 189Users are identified by their 190.Em session cookie , 191which is automatically generated by audio or MIDI applications 192upon the first connection to the server. 193The cookie is stored in 194.Pa "$HOME/.aucat_cookie" 195and contains 128 bits of raw random data. 196.Pp 197If a session needs to be shared between multiple users, they 198can connect to the server using the same cookie. 199.Sh ENVIRONMENT 200.Bl -tag -width "AUDIODEVICEXXX" -compact 201.It Ev AUDIODEVICE 202Audio device to use if the application provides 203no device chooser. 204.It Ev MIDIDEVICE 205MIDI port to use if the application provides 206no MIDI port chooser. 207.El 208.Pp 209Environment variables are ignored by programs 210with the set-user-ID or set-group-ID bits set. 211.Sh FILES 212.Bl -tag -width "/dev/audioNXXX" -compact 213.It Pa /dev/audioN 214Audio devices. 215.It Pa /dev/rmidiN 216MIDI ports. 217.El 218.Sh SEE ALSO 219.Xr mio_open 3 , 220.Xr sio_open 3 , 221.Xr audio 4 , 222.Xr midi 4 , 223.Xr sndiod 8 224