1.\" $OpenBSD: sndio.7,v 1.10 2012/05/23 19:25:11 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: May 23 2012 $ 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 1 , 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 1 42can be used. 43It exposes one or more software subdevices backed by the underlying hardware, 44while doing all necessary conversions on the fly. 45It can mix multiple streams or split the hardware into 46multiple subdevices, to allow programs to use the hardware 47concurently. 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 1 . 61.Pp 62Additionally, 63.Xr sndiod 1 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 1 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 1 . 93.It Pa midithru 94MIDI thru box created with 95.Xr sndiod 1 . 96.It Pa default 97Any audio device or MIDI port. 98.El 99.It Pa hostname 100The hostname or address where the remote 101.Xr sndiod 1 102server to connect to is running. 103.It Pa unit 104The number of the 105.Xr sndiod 1 106server to connect to, corresponding to the integer specified using the 107.Fl U 108option of 109.Xr sndiod 1 . 110Useful only if multiple 111.Xr sndiod 1 112servers are running on the same system. 113.It Pa devnum 114Device number. 115For hardware audio or MIDI ports, this corresponds to 116the character device minor number. 117For audio devices or MIDI ports created with 118.Xr sndiod 1 119it corresponds to the number of the corresponding 120.Fl fM 121option on the command line. 122.It Pa option 123Corresponds to the sub-device string registered using the 124.Fl s 125option of 126.Xr sndiod 1 . 127.El 128.Pp 129For example: 130.Pp 131.Bl -tag -width "snd/0.rear" -offset 3n -compact 132.It Pa rsnd/0 133First hardware audio device. 134.It Pa rmidi/5 135Hardware MIDI port number 5. 136.It Pa snd/0 137First audio device exposed by 138.Xr sndiod 1 . 139.It Pa snd/0.rear 140Sub-device registered with 141.Fl s Fa rear . 142.It Pa midithru/0 143First MIDI thru box created with 144.Xr sndiod 1 . 145.El 146.Sh AUTHENTICATION 147If a shared 148.Xr sndiod 1 149server is running, for privacy reasons only one user may have 150connections to it at a given time 151(though the same user could have multiple connections to it). 152Users are identified by their 153.Em session cookie , 154which is automatically generated by audio or MIDI applications 155upon the first connection to the server. 156The cookie is stored in 157.Pa "$HOME/.aucat_cookie" 158and contains 128 bits of raw random data. 159.Pp 160If a session needs to be shared between multiple users, they 161can connect to the server using the same cookie. 162.Sh ENVIRONMENT 163.Bl -tag -width "AUDIODEVICEXXX" -compact 164.It AUCAT_COOKIE 165Path to file containing the session cookie to be used 166when connecting to 167.Xr sndiod 1 . 168.It Ev AUDIODEVICE 169Audio device to use if the application provides 170no device chooser. 171.It Ev MIDIDEVICE 172MIDI port to use if the application provides 173no MIDI port chooser. 174.El 175.Pp 176Environment variables are ignored by programs 177with the set-user-ID or set-group-ID bits set. 178.Sh FILES 179.Bl -tag -width "/dev/audioNXXX" -compact 180.It Pa /dev/audioN 181Audio devices. 182.It Pa /dev/rmidiN 183MIDI ports. 184.El 185.Sh SEE ALSO 186.Xr sndiod 1 , 187.Xr mio_open 3 , 188.Xr sio_open 3 , 189.Xr audio 4 , 190.Xr midi 4 191