1.\" $OpenBSD: sndio.7,v 1.5 2011/06/03 18:57:51 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: June 3 2011 $ 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 aucat 1 29and 30.Xr midicat 1 , 31summarized below. 32.Pp 33Hardware 34.Xr audio 4 35devices correspond to peripherals. 36Only one application may use any device at a given time. 37Generally a limited number of encodings, sample rates and channel numbers are 38supported by the hardware, which may not meet the requirements of 39audio programs. 40.Pp 41To overcome hardware limitations and to allow multiple applications 42to share the hardware, 43.Xr aucat 1 44can be used. 45It exposes one or more software subdevices backed by the underlying hardware, 46while doing all necessary conversions on the fly. 47It can mix multiple streams or split the hardware into 48multiple subdevices, to allow programs to use the hardware 49concurently. 50.Pp 51Hardware MIDI ports correspond to serial connectors provided by the 52.Xr midi 4 53driver. 54They are typically used to access MIDI hardware (synthesizers, keyboards, 55control surfaces, etc.), but they do not allow applications to exchange 56information using the MIDI protocol. 57.Pp 58Software MIDI thru boxes allow one application to send MIDI data to other 59applications connected to the thru box (for instance a software sequencer 60can send events to multiple software synthesizers). 61There's no hardware involved: thru boxes are created by 62.Xr midicat 1 . 63.Pp 64Additionally, 65.Xr aucat 1 66exposes a MIDI device used to control and monitor audio streams 67in real time using MIDI. 68.Sh DEVICE NAMES 69From the user's perspective every audio interface, MIDI port, 70.Xr aucat 1 71or 72.Xr midicat 1 73service has a name of the form: 74.Bd -literal -offset center 75type:[hostname/]unit[.option] 76.Ed 77.Pp 78This information is used by audio and MIDI applications to determine 79how to access the audio or MIDI device or service. 80.Bl -tag -width "option" 81.It Pa type 82The type of the audio or MIDI device. 83Possible values for audio devices are 84.Pa aucat 85and 86.Pa sun , 87corresponding to 88.Xr aucat 1 89sockets and hardware 90.Xr audio 4 91devices. 92Possible values for MIDI devices are 93.Pa midithru , 94.Pa rmidi , 95and 96.Pa aucat 97corresponding to 98.Xr midicat 1 99software MIDI thru boxes, hardware 100.Xr midi 4 101ports and 102.Xr aucat 1 103control through MIDI respectively. 104.It Pa hostname 105The hostname where the remote 106.Xr aucat 1 107or 108.Xr midicat 1 109server to connect to is running. 110.It Pa unit 111For hardware audio or MIDI devices, this corresponds to 112the character device minor number. 113For audio or MIDI devices created with 114.Xr aucat 1 115or 116.Xr midicat 1 117it corresponds to the server 118.Em unit 119number, typically 0. 120.It Pa option 121Corresponds to the profile string registered using the 122.Fl s 123option of 124.Xr aucat 1 125or 126.Xr midicat 1 . 127Only meaningful for 128.Pa aucat 129and 130.Pa midithru 131device types. 132.El 133.Pp 134For example: 135.Pp 136.Bl -tag -width "aucat:0.rear" -offset 3n -compact 137.It Pa sun:0 138First hardware audio device. 139.It Pa aucat:0 140Default audio device of the first 141.Xr aucat 1 142audio server. 143.It Pa aucat:0.rear 144First 145.Xr aucat 1 146server; 147device registered with 148.Fl s Fa rear . 149.It Pa rmidi:5 150Hardware MIDI port number 5. 151.It Pa midithru:0 152First software MIDI thru box created with 153.Xr midicat 1 . 154.It Pa aucat:0 155MIDI port controlling the first 156.Xr aucat 1 157audio server. 158.El 159.Sh AUTHENTICATION 160If a shared 161.Xr aucat 1 162or 163.Xr midicat 1 164server is running, for privacy reasons only one user may have 165connections to it at a given time 166(though the same user could have multiple connections to it). 167Users are identified by their 168.Em session cookie , 169which is automatically generated by audio or MIDI applications 170upon the first connection to the server. 171The cookie is stored in 172.Pa "$HOME/.aucat_cookie" 173and contains 128 bits of raw random data. 174.Pp 175If a session needs to be shared between multiple users, they 176can connect to the server using the same cookie. 177.Sh ENVIRONMENT 178.Bl -tag -width "AUDIODEVICEXXX" -compact 179.It AUCAT_COOKIE 180Path to file containing the session cookie to be used 181when connecting to 182.Xr aucat 183or 184.Xr midicat . 185.It Ev AUDIODEVICE 186Audio device to use if the application provides 187no device chooser. 188.It Ev MIDIDEVICE 189MIDI port to use if the application provides 190no MIDI port chooser. 191.El 192.Pp 193Environment variables are ignored by programs 194with the set-user-ID or set-group-ID bits set. 195.Sh FILES 196.Bl -tag -width "/dev/audioNXXX" -compact 197.It Pa /dev/audioN 198Audio devices. 199.It Pa /dev/rmidiN 200MIDI ports. 201.El 202.Sh SEE ALSO 203.Xr aucat 1 , 204.Xr midicat 1 , 205.Xr mio_open 3 , 206.Xr sio_open 3 , 207.Xr audio 4 , 208.Xr midi 4 209