mirror of https://github.com/ericonr/sndio.git
227 lines
6.1 KiB
Groff
227 lines
6.1 KiB
Groff
.\" $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
|