Provided by: sndiod_1.1.0-3_amd64 bug

NAME

     sndiod — audio/MIDI server

SYNOPSIS

     sndiod [-d] [-a flag] [-b nframes] [-C min:max] [-c min:max] [-e enc] [-f device] [-j flag]
            [-L addr] [-m mode] [-q port] [-r rate] [-s name] [-t mode] [-U unit] [-v volume]
            [-w flag] [-z nframes]

DESCRIPTION

     The sndiod daemon is an intermediate layer between audio or MIDI programs and the hardware.
     It performs the necessary audio processing to allow any program to work on any supported
     hardware.  By default, sndiod accepts connections from programs running on the same system
     only; it initializes only when programs are using its services, allowing sndiod to consume a
     negligible amount of system resources the rest of the time.  Systems with no audio hardware
     can use sndiod to keep hot-pluggable devices usable by default at virtually no cost.

     sndiod operates as follows: it exposes at least one sub-device that any number of audio
     programs can connect to and use as if it was audio hardware.  During playback, sndiod
     receives audio data concurrently from all programs, mixes it and sends the result to the
     hardware device.  Similarly, during recording it duplicates audio data recorded from the
     device and sends it to all programs.  Since audio data flows through the sndiod process, it
     has the opportunity to process audio data on the fly:

              Change the sound encoding to overcome incompatibilities between software and
               hardware.
              Route the sound from one channel to another, join stereo or split mono.
              Control the per-application playback volume as well as the master volume.
              Monitor the sound being played, allowing one program to record what other programs
               play.

     Processing is configured on a per sub-device basis, meaning that the sound of all programs
     connected to the same sub-device will be processed according to the same configuration.
     Multiple sub-devices can be defined, allowing multiple configurations to coexist.  The user
     selects the configuration a given program will use by selecting the sub-device the program
     uses.

     sndiod exposes MIDI thru boxes (hubs), allowing programs to send MIDI messages to each other
     or to hardware MIDI ports in a uniform way.

     Finally, sndiod exposes a control MIDI port usable for:

              Volume control.
              Common clock source for audio and MIDI programs.
              Start, stop and relocate groups of audio programs.

     The options are as follows:

     -a flag
             Control whether sndiod opens the audio device or the MIDI port only when needed or
             keeps it open all the time.  If the flag is on then the audio device or MIDI port is
             kept open all the time, ensuring no other program can steal it.  If the flag is off,
             then it's automatically closed, allowing other programs to have direct access to the
             audio device, or the device to be disconnected.  The default is off.

     -b nframes
             The buffer size of the audio device in frames.  A frame consists of one sample for
             each channel in the stream.  This is the number of frames that will be buffered
             before being played and thus controls the playback latency.  The default is 7680 or
             twice the block size (-z), if the block size is set.

     -C min:max, -c min:max
             The range of channel numbers for recording and playback directions, respectively any
             client is allowed to use.  This is a subset of the audio device channels.  The
             default is 0:1, i.e. stereo.

     -d      Enable debugging to standard error, and do not disassociate from the controlling
             terminal.  Can be specified multiple times to further increase log verbosity.

     -e enc  Attempt to configure the device to use this encoding.  The default is s16.  Encoding
             names use the following scheme: signedness (s or u) followed by the precision in
             bits, the byte-order (le or be), the number of bytes per sample, and the alignment
             (msb or lsb).  Only the signedness and the precision are mandatory.  Examples: u8,
             s16le, s24le3, s24le4lsb.

     -f device
             Add this sndio(7) audio device to devices used for playing and/or recording.
             Preceding per-device options (-aberwz) apply to this device.  Sub-devices (-s) that
             are applied after will be attached to this device.  Device mode and parameters are
             determined from sub-devices attached to it.

     -j flag
             Control whether program channels are joined or expanded if the number of channels
             requested by a program is not equal to the device number of channels.  If the flag
             is off then client channels are routed to the corresponding device channel, possibly
             discarding channels not present in the device.  If the flag is on, then a single
             client channel may be sent on multiple device channels, or multiple client channels
             may be sent to a single device channel.  For instance, this feature could be used
             for mono to stereo conversions.  The default is on.

     -L addr
             Specify a local network address sndiod should listen on; sndiod will listen on TCP
             port 11025+n, where n is the unit number specified with -U.  Without this option,
             sndiod listens on the UNIX-domain socket only, and is not reachable from any
             network.  If the option argument is ‘-’ then sndiod will accept connections from any
             address.  As the communication is not secure, this option is only suitable for local
             networks where all hosts and users are trusted.

     -m mode
             Set the sub-device mode.  Valid modes are play, rec, and mon, corresponding to
             playback, recording and monitoring.  A monitoring stream is a fake recording stream
             corresponding to the mix of all playback streams.  Multiple modes can be specified,
             separated by commas, but the same sub-device cannot be used for both recording and
             monitoring.  The default is play,rec (i.e. full-duplex).

     -q port
             Expose the given MIDI port.  This allows multiple programs to share the port.

     -r rate
             Attempt to force the device to use this sample rate in Hertz.  The default is 48000.

     -s name
             Add name to the list of sub-devices to expose.  This allows clients to use sndiod
             instead of the physical audio device for audio input and output in order to share
             the physical device with other clients.  Defining multiple sub-devices allows
             splitting a physical audio device into sub-devices having different properties (e.g.
             channel ranges).  The given name corresponds to the “option” part of the sndio(7)
             device name string.

     -t mode
             Select the way clients are controlled by MIDI Machine Control (MMC) messages
             received by sndiod.  If the mode is off (the default), then programs are not
             affected by MMC messages.  If the mode is slave, then programs are started
             synchronously by MMC start messages; additionally, the server clock is exposed as
             MIDI Time Code (MTC) messages allowing MTC-capable software or hardware to be
             synchronized to audio programs.

     -U unit
             Unit number.  Each sndiod server instance has an unique unit number, used in
             sndio(7) device names.  The default is 0.

     -v volume
             Software volume attenuation of playback.  The value must be between 1 and 127,
             corresponding to -42dB and -0dB attenuation in 1/3dB steps.  Clients inherit this
             parameter.  Reducing the volume in advance allows a client's volume to stay
             independent from the number of clients as long as their number is small enough.  18
             volume units (i.e. -6dB attenuation) allows the number of playback programs to be
             doubled.  The default is 118 i.e. -3dB.

     -w flag
             Control sndiod behaviour when the maximum volume of the hardware is reached and a
             new program starts playing.  This happens only when volumes are not properly set
             using the -v option.  If the flag is on, then the master volume is automatically
             adjusted to avoid clipping.  Using off makes sense in the rare situation where all
             programs lower their volumes.  The default is on.

     -z nframes
             The audio device block size in frames.  This is the number of frames between audio
             clock ticks, i.e. the clock resolution.  If a sub-device is created with the -t
             option, and MTC is used for synchronization, the clock resolution must be 96, 100 or
             120 ticks per second for maximum accuracy.  For instance, 100 ticks per second at
             48000Hz corresponds to a 480 frame block size.  The default is 960 or half of the
             buffer size (-b), if the buffer size is set.

     On the command line, per-device parameters (-aberwz) must precede the device definition
     (-f), and per-sub-device parameters (-Ccjmtvx) must precede the sub-device definition (-s).
     Sub-device definitions (-s) must follow the definition of the device (-f) to which they are
     attached.

     If no audio devices (-f) are specified, settings are applied as if the default device is
     specified.  If no sub-devices (-s) are specified for a device, a default sub-device is
     created attached to it.  If a device (-f) is defined twice, both definitions are merged:
     parameters of the first one are used but sub-devices (-s) of both definitions are created.
     The default sndio(7) device used by sndiod is rsnd/0, and the default sub-device exposed by
     sndiod is snd/0.

     If sndiod is sent SIGHUP, SIGINT or SIGTERM, it terminates.

     By default, when the program cannot accept recorded data fast enough or cannot provide data
     to play fast enough, the program is paused, i.e. samples that cannot be written are
     discarded and samples that cannot be read are replaced by silence.  If a sub-device is
     created with the -t option, then recorded samples are discarded, but the same amount of
     silence will be written once the program is unblocked, in order to reach the right position
     in time.  Similarly silence is played, but the same amount of samples will be discarded once
     the program is unblocked.  This ensures proper synchronization between programs.

MIDI CONTROL

     sndiod creates a MIDI port with the same name as the exposed audio sub-device to which MIDI
     programs can connect.  sndiod exposes the audio device clock and allows audio device
     properties to be controlled through MIDI.

     A MIDI channel is assigned to each stream, and the volume is changed using the standard
     volume controller (number 7).  Similarly, when the audio client changes its volume, the same
     MIDI controller message is sent out; it can be used for instance for monitoring or as
     feedback for motorized faders.

     The master volume can be changed using the standard master volume system exclusive message.

     Streams created with the -t option are controlled by the following MMC messages:

           relocate     This message is ignored by audio sndiod clients, but the given time
                        position is sent to MIDI ports as an MTC “full frame” message forcing all
                        MTC-slaves to relocate to the given position (see below).

           start        Put all streams in starting mode.  In this mode, sndiod waits for all
                        streams to become ready to start, and then starts them synchronously.
                        Once started, new streams can be created (sndiod) but they will be
                        blocked until the next stop-to-start transition.

           stop         Put all streams in stopped mode (the default).  In this mode, any stream
                        attempting to start playback or recording is paused.  Client streams that
                        are already started are not affected until they stop and try to start
                        again.

     Streams created with the -t option export the sndiod device clock using MTC, allowing non-
     audio software or hardware to be synchronized to the audio stream.  Maximum accuracy is
     achieved when the number of blocks per second is equal to one of the standard MTC clock
     rates (96, 100 and 120Hz).  The following sample rates (-r) and block sizes (-z) are
     recommended:

              44100Hz, 441 frames (MTC rate is 100Hz)
              48000Hz, 400 frames (MTC rate is 120Hz)
              48000Hz, 480 frames (MTC rate is 100Hz)
              48000Hz, 500 frames (MTC rate is 96Hz)

     For instance, the following command will create two devices: the default snd/0 and a MIDI-
     controlled snd/0.mmc:

           $ sndiod -r 48000 -z 400 -s default -t slave -s mmc

     Streams connected to snd/0 behave normally, while streams connected to snd/0.mmc wait for
     the MMC start signal and start synchronously.  Regardless of which device a stream is
     connected to, its playback volume knob is exposed.

EXAMPLES

     Start server using default parameters, creating an additional sub-device for output to
     channels 2:3 only (rear speakers on most cards), exposing the snd/0 and snd/0.rear devices:

           $ sndiod -s default -c 2:3 -s rear

     Start server creating the default sub-device with low volume and an additional sub-device
     for high volume output, exposing the snd/0 and snd/0.max devices:

           $ sndiod -v 65 -s default -v 127 -s max

     Start server configuring the audio device to use a 48kHz sample frequency, 240-frame block
     size, and 2-block buffers.  The corresponding latency is 10ms, which is the time it takes
     the sound to propagate 3.5 meters.

           $ sndiod -r 48000 -b 480 -z 240

SEE ALSO

     sndio(7)

BUGS

     Resampling is low quality; down-sampling especially should be avoided when recording.

     Processing is done using 16-bit arithmetic, thus samples with more than 16 bits are rounded.
     16 bits (i.e. 97dB dynamic) are largely enough for most applications though.  Processing
     precision can be increased to 24-bit at compilation time though.

     If -a off is used, sndiod creates sub-devices to expose first and then opens the audio
     hardware on demand.  Technically, this allows sndiod to attempt to use one of the sub-
     devices it exposes as an audio device, creating a deadlock.  There's nothing to prevent the
     user from shooting himself in the foot by creating such a deadlock.