mirror of https://github.com/ericonr/sndio.git
Replace off-topic parts of the desciption by an architecture overview
Remove useless (re)wording of what are audio(4) and midi(4), add a quick description of sndiod as intermediate layer. Try to focuse on what the sndio library and sndiod do instead of how they do it. As suggested by schwarze, use the word "device descriptor" instead of "device name" to avoid the common confusion with the device files. Remove information already given in same sentence; Tweaks from jmc@
This commit is contained in:
Alexandre Ratchov
parent
2c8bea3f08
commit
f8795c056d
116
libsndio/sndio.7
116
libsndio/sndio.7
|
|
@ -21,57 +21,54 @@
|
|||
.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,
|
||||
Programs access audio and MIDI hardware using the sndio library.
|
||||
It allows both access through the
|
||||
.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.
|
||||
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
|
||||
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.
|
||||
Most programs connect to the
|
||||
.Xr sndiod 8
|
||||
server, which does the hardware access for them because
|
||||
direct access to the raw 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 be established through the network, including from virtual machines.
|
||||
.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 .
|
||||
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 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:
|
||||
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][,unit]/devnum[.option]
|
||||
type[@hostname][,servnum]/devnum[.option]
|
||||
.Ed
|
||||
.Pp
|
||||
This information is used by audio and MIDI applications to determine
|
||||
This information is used by programs to determine
|
||||
how to access the audio device or MIDI port.
|
||||
.Bl -tag -width "hostname"
|
||||
.It Ar type
|
||||
|
|
@ -91,7 +88,7 @@ port.
|
|||
Audio device exposed by
|
||||
.Xr sndiod 8 .
|
||||
.It Cm midithru
|
||||
MIDI thru box created with
|
||||
MIDI thru port created with
|
||||
.Xr sndiod 8 .
|
||||
.It Cm midi
|
||||
MIDI port exposed by
|
||||
|
|
@ -103,7 +100,7 @@ Default audio device or MIDI port (see below).
|
|||
The hostname or address where the remote
|
||||
.Xr sndiod 8
|
||||
server to connect to is running.
|
||||
.It Ar unit
|
||||
.It Ar servnum
|
||||
The number of the
|
||||
.Xr sndiod 8
|
||||
server to connect to, corresponding to the integer specified using the
|
||||
|
|
@ -133,17 +130,19 @@ For example:
|
|||
.Pp
|
||||
.Bl -tag -width "snd/0.rear" -offset 3n -compact
|
||||
.It Li rsnd/0
|
||||
First hardware audio device.
|
||||
Raw access to first audio device.
|
||||
.It Li rmidi/5
|
||||
Hardware MIDI port number 5.
|
||||
Raw access to MIDI port number 5.
|
||||
.It Li snd/0
|
||||
First audio device exposed by
|
||||
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 box created with
|
||||
First MIDI thru port created with
|
||||
.Xr sndiod 8 .
|
||||
.El
|
||||
.Sh DEFAULTS
|
||||
|
|
@ -181,14 +180,12 @@ 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
|
||||
For privacy reasons only one user may have connections to
|
||||
.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).
|
||||
at a given time.
|
||||
Users are identified by their
|
||||
.Em session cookie ,
|
||||
which is automatically generated by audio or MIDI applications
|
||||
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"
|
||||
|
|
@ -199,20 +196,18 @@ 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.
|
||||
Audio device to use if the program offers no audio device selection method.
|
||||
.It Ev MIDIDEVICE
|
||||
MIDI port that
|
||||
.Xr mio_open 3
|
||||
uses if the application provides no MIDI port chooser.
|
||||
MIDI port to use if the program offers no MIDI port selection method.
|
||||
.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
|
||||
.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
|
||||
|
|
@ -221,6 +216,7 @@ MIDI ports.
|
|||
.Sh SEE ALSO
|
||||
.Xr mio_open 3 ,
|
||||
.Xr sio_open 3 ,
|
||||
.Xr sioctl_open 3 ,
|
||||
.Xr audio 4 ,
|
||||
.Xr midi 4 ,
|
||||
.Xr sndiod 8
|
||||
|
|
|
|||
Loading…
Reference in New Issue