mirror of
https://github.com/ericonr/sndio.git
synced 2024-02-18 04:45:21 -06:00
c531dda0ad
From schwarze@
230 lines
6.1 KiB
Groff
230 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
|
|
Programs access audio and MIDI hardware using the
|
|
.Nm sndio
|
|
library.
|
|
It allows both access through the
|
|
.Xr sndiod 8
|
|
server and raw access to the hardware.
|
|
The audio device or MIDI port, as well as the access method,
|
|
are designated by the sndio descriptor.
|
|
It is provided by the user with the program device selection method,
|
|
or with the
|
|
.Ev AUDIODEVICE
|
|
and
|
|
.Ev MIDIDEVICE
|
|
environment variables if there's no device selection method.
|
|
.Pp
|
|
Usually, programs access the hardware via the
|
|
.Xr sndiod 8
|
|
server, because raw access to the hardware is exclusive and
|
|
requires additional privileges.
|
|
The
|
|
.Xr sndiod 8
|
|
server supports multiple connections at a time, allowing multiple programs to
|
|
use the hardware concurrently.
|
|
It performs the necessary audio processing on the fly to
|
|
overcome any incompatibility between software and hardware.
|
|
Connections to
|
|
.Xr sndiod 8
|
|
may also be established through the network, including from virtual machines.
|
|
.Pp
|
|
The
|
|
.Xr sndiod 8
|
|
server exposes
|
|
.Em MIDI thru
|
|
ports, allowing one program to send MIDI data to other programs,
|
|
for instance to allow a sequencer to send events to a synthesizer.
|
|
.Pp
|
|
Additionally,
|
|
.Xr sndiod 8
|
|
exposes a MIDI port used to control audio programs using
|
|
standard MIDI Machine Control (MMC), MIDI Time Code (MTC),
|
|
and master volume messages.
|
|
.Sh AUDIO AND MIDI DESCRIPTORS
|
|
From the user's perspective every audio device or MIDI port
|
|
has a descriptor of the form:
|
|
.Bd -literal -offset center
|
|
type[@hostname][,servnum]/devnum[.option]
|
|
.Ed
|
|
.Pp
|
|
This information is used by programs 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 port 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 servnum
|
|
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
|
|
Raw access to first audio device.
|
|
.It Li rmidi/5
|
|
Raw access to MIDI port number 5.
|
|
.It Li snd/0
|
|
Audio device referred by first
|
|
.Fl f
|
|
option of
|
|
.Xr sndiod 8 .
|
|
.It Li snd/0.rear
|
|
Sub-device registered with
|
|
.Fl s Fa rear .
|
|
.It Li midithru/0
|
|
First MIDI thru port 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 raw hardware as fallback;
|
|
programs don't have to be reconfigured when
|
|
.Xr sndiod 8
|
|
is started or stopped.
|
|
.Pp
|
|
Similarly, if no MIDI descriptor is provided to a program
|
|
or when the reserved word
|
|
.Cm default
|
|
is passed as the device descriptor,
|
|
the program uses 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
|
|
For privacy reasons only one user may have connections to
|
|
.Xr sndiod 8
|
|
at a given time.
|
|
Users are identified by their
|
|
.Em session cookie ,
|
|
which is automatically generated by audio or MIDI programs
|
|
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 descriptor to use
|
|
when no descriptor is explicitly specified to a program.
|
|
.It Ev MIDIDEVICE
|
|
MIDI port descriptor to use
|
|
when no descriptor is explicitly specified to a program.
|
|
.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 "~/.sndio/cookie" -compact
|
|
.It Pa ~/.sndio/cookie
|
|
User's session authentication cookie.
|
|
.It Pa /dev/audioN
|
|
Audio devices.
|
|
.It Pa /dev/rmidiN
|
|
MIDI ports.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr aucat 1 ,
|
|
.Xr midicat 1 ,
|
|
.Xr sndioctl 1 ,
|
|
.Xr mio_open 3 ,
|
|
.Xr sio_open 3 ,
|
|
.Xr sioctl_open 3 ,
|
|
.Xr audio 4 ,
|
|
.Xr midi 4 ,
|
|
.Xr sndiod 8
|