sndio/libsndio/sndio.7

.\" $OpenBSD$
.\"
.\" Copyright (c) 2007 Alexandre Ratchov <alex@caoua.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt SNDIO 7
.Os
.Sh NAME
.Nm sndio
.Nd interface to audio and MIDI
.Sh DESCRIPTION
The
.Nm sndio
audio and MIDI system provides access to audio and MIDI hardware and
to services provided by
.Xr sndiod 8 ,
summarized below.
.Pp
Hardware
.Xr audio 4
devices correspond to peripherals.
Only one application may use any device at a given time.
Generally a limited number of encodings, sample rates and channel numbers are
supported by the hardware, which may not meet the requirements of
audio programs.
.Pp
To overcome hardware limitations and to allow multiple applications
to share the hardware,
.Xr sndiod 8
can be used.
It exposes one or more software sub-devices backed by the underlying hardware,
while doing all necessary conversions on the fly.
It can mix multiple streams or split the hardware into
multiple sub-devices, to allow programs to use the hardware
concurrently.
.Pp
Hardware MIDI ports correspond to serial connectors provided by the
.Xr midi 4
driver.
They are typically used to access MIDI hardware (synthesizers, keyboards,
control surfaces, etc.), but they do not allow applications to exchange
information using the MIDI protocol.
.Pp
Software MIDI thru boxes allow one application to send MIDI data to other
applications connected to the thru box (for instance a software sequencer
can send events to multiple software synthesizers).
There's no hardware involved: thru boxes are created by
.Xr sndiod 8 .
.Pp
Additionally,
.Xr sndiod 8
exposes a MIDI port used to control and monitor audio streams
in real time using MIDI.
.Sh DEVICE NAMES
From the user's perspective every audio interface, MIDI port, and
.Xr sndiod 8
service has a name of the form:
.Bd -literal -offset center
type[@hostname][,unit]/devnum[.option]
.Ed
.Pp
This information is used by audio and MIDI applications to determine
how to access the audio device or MIDI port.
.Bl -tag -width "hostname"
.It Ar type
The type of the audio device or MIDI port.
Possible values are:
.Pp
.Bl -tag -width "midithru" -offset 3n -compact
.It Cm rsnd
Raw
.Xr audio 4
device.
.It Cm rmidi
Raw
.Xr midi 4
port.
.It Cm snd
Audio device exposed by
.Xr sndiod 8 .
.It Cm midithru
MIDI thru box created with
.Xr sndiod 8 .
.It Cm midi
MIDI port exposed by
.Xr sndiod 8 .
.It Cm default
Default audio device or MIDI port (see below).
.El
.It Ar hostname
The hostname or address where the remote
.Xr sndiod 8
server to connect to is running.
.It Ar unit
The number of the
.Xr sndiod 8
server to connect to, corresponding to the integer specified using the
.Fl U
option of
.Xr sndiod 8 .
Useful only if multiple
.Xr sndiod 8
servers are running on the same system.
.It Ar devnum
Device number.
For hardware audio or MIDI ports, this corresponds to
the character device minor number.
For audio devices or MIDI ports created with
.Xr sndiod 8
it corresponds to the number of the corresponding
.Fl fq
option on the command line.
.It Ar option
Corresponds to the sub-device string registered using the
.Fl s
option of
.Xr sndiod 8 .
.El
.Pp
For example:
.Pp
.Bl -tag -width "snd/0.rear" -offset 3n -compact
.It Li rsnd/0
First hardware audio device.
.It Li rmidi/5
Hardware MIDI port number 5.
.It Li snd/0
First audio device exposed by
.Xr sndiod 8 .
.It Li snd/0.rear
Sub-device registered with
.Fl s Fa rear .
.It Li midithru/0
First MIDI thru box created with
.Xr sndiod 8 .
.El
.Sh DEFAULTS
If
.Cm default
is used as the audio device, the program will use the
one specified in the
.Ev AUDIODEVICE
environment variable.
If it is not set, the program first tries to connect to
.Li snd/0 .
If that fails, it then tries to use
.Li rsnd/0 .
This allows the
.Xr sndiod 8
audio server to be used by default and the bare hardware as fallback;
programs don't have to be reconfigured when
.Xr sndiod 8
is started or stopped.
.Pp
If
.Cm default
is used as the MIDI port, the program will use the
one specified in the
.Ev MIDIDEVICE
environment variable.
If it is not set, the program first tries to connect to
.Li midithru/0 .
If that fails, it then tries to use
.Li rmidi/0 .
As long as
.Xr 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.
.Sh AUTHENTICATION
If a shared
.Xr sndiod 8
server is running, for privacy reasons only one user may have
connections to it at a given time
(though the same user could have multiple connections to it).
Users are identified by their
.Em session cookie ,
which is automatically generated by audio or MIDI applications
upon the first connection to the server.
The cookie is stored in
.Pa "$HOME/.sndio/cookie"
and contains 128 bits of raw random data.
.Pp
If a session needs to be shared between multiple users, they
can connect to the server using the same cookie.
.Sh ENVIRONMENT
.Bl -tag -width "AUDIODEVICEXXX" -compact
.It Ev AUDIODEVICE
Audio device that
.Xr sio_open 3
uses if the application provides no device chooser.
.It Ev MIDIDEVICE
MIDI port that
.Xr mio_open 3
uses if the application provides no MIDI port chooser.
.El
.Pp
These environment variables are ignored by
.Nm
if the program has the set-user-ID or set-group-ID bits set.
.Sh FILES
.Bl -tag -width "/dev/audioNXXX" -compact
.It Pa /dev/audioN
Audio devices.
.It Pa /dev/rmidiN
MIDI ports.
.El
.Sh SEE ALSO
.Xr mio_open 3 ,
.Xr sio_open 3 ,
.Xr audio 4 ,
.Xr midi 4 ,
.Xr sndiod 8