SIO_OPEN(3) | Library Functions Manual | SIO_OPEN(3) |
sio_open
, sio_close
,
sio_setpar
, sio_getpar
,
sio_getcap
, sio_start
,
sio_stop
, sio_read
,
sio_write
, sio_onmove
,
sio_nfds
, sio_pollfd
,
sio_revents
, sio_eof
,
sio_setvol
, sio_onvol
,
sio_initpar
—
#include <sndio.h>
struct sio_hdl *
sio_open
(const
char *name, unsigned int
mode, int
nbio_flag);
void
sio_close
(struct
sio_hdl *hdl);
int
sio_setpar
(struct
sio_hdl *hdl, struct
sio_par *par);
int
sio_getpar
(struct
sio_hdl *hdl, struct
sio_par *par);
int
sio_getcap
(struct
sio_hdl *hdl, struct
sio_cap *cap);
int
sio_start
(struct
sio_hdl *hdl);
int
sio_stop
(struct
sio_hdl *hdl);
size_t
sio_read
(struct
sio_hdl *hdl, void
*addr, size_t
nbytes);
size_t
sio_write
(struct
sio_hdl *hdl, const void
*addr, size_t
nbytes);
void
sio_onmove
(struct
sio_hdl *hdl, void
(*cb)(void *arg, int delta),
void *arg);
int
sio_nfds
(struct
sio_hdl *hdl);
int
sio_pollfd
(struct
sio_hdl *hdl, struct
pollfd *pfd, int
events);
int
sio_revents
(struct
sio_hdl *hdl, struct
pollfd *pfd);
int
sio_eof
(struct
sio_hdl *hdl);
int
sio_setvol
(struct
sio_hdl *hdl, unsigned
int vol);
int
sio_onvol
(struct
sio_hdl *hdl, void
(*cb)(void *arg, unsigned int vol),
void *arg);
void
sio_initpar
(struct
sio_par *par);
sndio
library allows user processes to access
audio(4) hardware and the
sndiod(8) audio server in a uniform way.
sio_open
() function
to obtain a handle to the device; later it will be passed as the
hdl argument of most other functions. The
name parameter gives the device string discussed in
sndio(7). In most cases it should be set to
SIO_DEVANY
to allow the user to select it using the
AUDIODEVICE
environment variable.
The following values of the mode parameter are supported:
SIO_PLAY
SIO_REC
SIO_PLAY
|
SIO_REC
If the nbio_flag argument is true (i.e.
non-zero), then the sio_read
() and
sio_write
() functions (see below) will be
non-blocking.
The sio_close
() function stops the device
as if sio_stop
() is called and frees the handle.
Thus, no samples submitted with sio_write
() are
discarded.
The set of parameters of the device that can be controlled is given by the following structure:
struct sio_par { unsigned int bits; /* bits per sample */ unsigned int bps; /* bytes per sample */ unsigned int sig; /* 1 = signed, 0 = unsigned int */ unsigned int le; /* 1 = LE, 0 = BE byte order */ unsigned int msb; /* 1 = MSB, 0 = LSB aligned */ unsigned int rchan; /* number channels for recording */ unsigned int pchan; /* number channels for playback */ unsigned int rate; /* frames per second */ unsigned int appbufsz; /* minimum buffer size without xruns */ unsigned int bufsz; /* end-to-end buffer size (read-only) */ unsigned int round; /* optimal buffer size divisor */ #define SIO_IGNORE 0 /* pause during xrun */ #define SIO_SYNC 1 /* resync after xrun */ #define SIO_ERROR 2 /* terminate on xrun */ unsigned int xrun; /* what to do on overrun/underrun */ };
The parameters are as follows:
SIO_REC
mode was selected.SIO_PLAY
mode was selected.sio_write
() or sio_read
()
fast enough to avoid overrun or underrun conditions. The audio subsystem
may use additional buffering, thus this parameter cannot be used for
latency calculations.SIO_IGNORE
, SIO_SYNC
, or
SIO_ERROR
constants.The following approach is recommended to negotiate device parameters:
sio_initpar
() and fill it with the desired
parameters. Then call sio_setpar
() to request the
device to use them. Parameters left unset in the
sio_par structure will be set to device-specific
defaults.sio_getpar
() to retrieve the actual
parameters of the device and check that they are usable. If they are not,
then fail or set up a conversion layer. Sometimes the rate set can be
slightly different to what was requested. A difference of about 0.5% is
not audible and should be ignored.Parameters cannot be changed after
sio_start
() has been called,
sio_stop
() must be called before parameters can be
changed.
If the device is exposed by the sndiod(8) server, which is the default configuration, a transparent emulation layer will automatically be set up, and in this case any combination of rate, encoding and numbers of channels is supported.
To ease filling the sio_par structure, the following macros can be used:
SIO_BPS
(bits)SIO_LE_NATIVE
sio_getcap
()
function. However, for most new applications it's generally not recommended to
use sio_getcap
(). Instead, follow the recommendations
for negotiating device parameters (see above).
The sio_cap structure contains the list of parameter configurations. Each configuration contains multiple parameter sets. The application must examine all configurations, and choose its parameter set from one of the configurations. Parameters of different configurations are not usable together.
struct sio_cap { struct sio_enc { /* allowed encodings */ unsigned int bits; unsigned int bps; unsigned int sig; unsigned int le; unsigned int msb; } enc[SIO_NENC]; unsigned int rchan[SIO_NCHAN]; /* allowed rchans */ unsigned int pchan[SIO_NCHAN]; /* allowed pchans */ unsigned int rate[SIO_NRATE]; /* allowed rates */ unsigned int nconf; /* num. of confs[] */ struct sio_conf { unsigned int enc; /* bitmask of enc[] indexes */ unsigned int rchan; /* bitmask of rchan[] indexes */ unsigned int pchan; /* bitmask of pchan[] indexes */ unsigned int rate; /* bitmask of rate[] indexes */ } confs[SIO_NCONF]; };
The parameters are as follows:
SIO_NENC
]SIO_NCHAN
]SIO_NCHAN
]SIO_NRATE
]SIO_NCONF
]SIO_NRATE
] array of the
sio_cap structure is valid for this configuration.
As such, when reading the array elements in the
sio_cap structure, the corresponding
sio_conf bitmasks should always be used.sio_start
() function puts the device in a waiting
state: the device will wait for playback data to be provided (using the
sio_write
() function). Once enough data is queued to
ensure that play buffers will not underrun, actual playback is started
automatically. If record mode only is selected, then recording starts
immediately. In full-duplex mode, playback and recording will start
synchronously as soon as enough data to play is available.
The sio_stop
() function puts the audio
subsystem in the same state as before sio_start
() is
called. It stops recording, drains the play buffer and then stops playback.
If samples to play are queued but playback hasn't started yet then playback
is forced immediately; playback will actually stop once the buffer is
drained. In no case are samples in the play buffer discarded.
sio_read
() function
must be called to retrieve recorded data; it must be called often enough to
ensure that internal buffers will not overrun. It will store at most
nbytes bytes at the addr location
and return the number of bytes stored. Unless the
nbio_flag flag is set, it will block until data becomes
available and will return zero only on error.
Similarly, when play mode is selected, the
sio_write
() function must be called to provide data
to play. Unless the nbio_flag is set,
sio_write
() will block until the requested amount of
data is written.
sio_open
(), then the
sio_read
() and sio_write
()
functions will never block; if no data is available, they will return zero
immediately.
The poll(2) system call can be
used to check if data can be read from or written to the device. The
sio_pollfd
() function fills the array
pfd of pollfd structures, used
by poll(2), with
events; the latter is a bit-mask of
POLLIN
and POLLOUT
constants; refer to poll(2) for more
details. The sio_revents
() function returns the
bit-mask set by poll(2) in the
pfd array of pollfd structures.
If POLLIN
is set, recorded samples are available in
the device buffer and can be read with sio_read
().
If POLLOUT
is set, space is available in the device
buffer and new samples to play can be submitted with
sio_write
(). POLLHUP
may be
set if an error occurs, even if it is not selected with
sio_pollfd
().
The size of the pfd array, which the caller
must pre-allocate, is provided by the sio_nfds
()
function.
The sio_onmove
() function can be used to
register the cb
() callback function called at
regular time intervals. The delta argument contains
the number of frames the hardware played and/or recorded since the last call
of cb
(). It is called by
sio_read
(), sio_write
(), and
sio_revents
(). When the first sample is played
and/or recorded, right after the device starts, the callback is invoked with
a zero delta argument. The value of the
arg pointer is passed to the callback and can contain
anything.
If desired, the application can maintain the current position by
starting from zero (when sio_start
() is called) and
adding to the current position delta every time
cb
() is called.
sio_write
() only
queues data; once there's enough data, actual playback starts. During this
phase talking about latency is meaningless.
In any cases, at most bufsz frames are buffered. This value takes into account all buffers. The number of frames stored is equal to the number of frames written minus the current position.
The recording latency is obtained similarly, by subtracting the number of frames read from the current position.
Note that sio_write
() might block even if
there is buffer space left; using the buffer usage to guess if
sio_write
() would block is false and leads to
unreliable programs – consider using
poll(2) for this.
SIO_IGNORE
sio_onmove
()) stops
being incremented. Once the overrun and/or underrun condition is gone, the
device resumes; play and record are always kept in sync. With this mode,
the application cannot notice underruns and/or overruns and shouldn't care
about them.
This mode is the default. It's suitable for applications, like audio players and telephony, where time is not important and overruns or underruns are not short.
SIO_SYNC
sio_onmove
()) is still incremented. When the play
buffer underruns the play latency might become negative; when the record
buffer overruns, the record latency might become larger than
bufsz.
This mode is suitable for applications, like music production, where time is important and where underruns or overruns are short and rare.
SIO_ERROR
sio_close
() will succeed.
This mode is mostly useful for testing.
sio_setvol
() function can be used to set playback
attenuation. The vol parameter takes a value between 0
(maximum attenuation) and SIO_MAXVOL
(no attenuation).
It specifies the weight the audio subsystem will give to this stream. It is
not meant to control hardware parameters like speaker gain; the
mixerctl(1) interface should be used for
that purpose instead.
An application can use the sio_onvol
()
function to register a callback function that will be called each time the
volume is changed, including when sio_setvol
() is
used. The callback is always invoked when
sio_onvol
() is called in order to provide the
initial volume. An application can safely assume that once
sio_onvol
() has returned a non-zero value, the
callback has been invoked and thus the current volume is available. If
there's no volume setting available, sio_onvol
()
returns 0 and the callback is never invoked and calls to
sio_setvol
() are ignored.
The sio_onvol
() function can be called
with a NULL argument to check whether a volume knob is available.
sio_read
() on a play-only stream) are considered
fatal. Once an error occurs, all functions taking a
sio_hdl argument, except
sio_close
() and sio_eof
(),
stop working (i.e. always return 0). The sio_eof
()
function can be used at any stage.
sndio
library is used in combination with
pledge(2), then the
sio_open
() function needs the
stdio, rpath,
wpath, cpath,
inet, unix,
dns, and audio
pledge(2) promises.
Once no further calls to sio_open
() will
be made, all these pledge(2) promises may
be dropped, except for the audio promise.
sio_open
() function returns the newly created handle
on success or NULL on failure.
The sio_setpar
(),
sio_getpar
(), sio_getcap
(),
sio_start
(), sio_stop
(), and
sio_setvol
() functions return 1 on success and 0 on
failure.
The sio_pollfd
() function returns the
number of pollfd structures filled. The
sio_nfds
() function returns the number of
pollfd structures the caller must preallocate in order
to be sure that sio_pollfd
() will never overrun.
The sio_read
() and
sio_write
() functions return the number of bytes
transferred.
The sio_eof
() function returns 0 if
there's no pending error, and a non-zero value if there's an error.
AUDIODEVICE
sio_open
() is called with
SIO_DEVANY
as the name
argument.SNDIO_DEBUG
sio_stop
() function will stop playback immediately.
If the application doesn't consume recorded data fast enough then
“control messages” from the
sndiod(8) server are delayed and
consequently sio_onmove
() callback or volume changes
may be delayed.
The sio_open
(),
sio_setpar
(), sio_getpar
(),
sio_getcap
(), sio_start
(),
and sio_stop
() functions may block for a very short
period of time, thus they should be avoided in code sections where blocking
is not desirable.
January 18, 2019 | OpenBSD-current |