Annotation of src/usr.bin/sndiod/sndiod.8, Revision 1.1
1.1 ! ratchov 1: .\" $OpenBSD: sndiod.1,v 1.9 2015/11/22 16:52:06 ratchov Exp $
! 2: .\"
! 3: .\" Copyright (c) 2006-2012 Alexandre Ratchov <alex@caoua.org>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the above
! 7: .\" copyright notice and this permission notice appear in all copies.
! 8: .\"
! 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 16: .\"
! 17: .Dd $Mdocdate: November 22 2015 $
! 18: .Dt SNDIOD 8
! 19: .Os
! 20: .Sh NAME
! 21: .Nm sndiod
! 22: .Nd audio/MIDI server
! 23: .Sh SYNOPSIS
! 24: .Nm sndiod
! 25: .Bk -words
! 26: .Op Fl d
! 27: .Op Fl a Ar flag
! 28: .Op Fl b Ar nframes
! 29: .Op Fl C Ar min : Ns Ar max
! 30: .Op Fl c Ar min : Ns Ar max
! 31: .Op Fl e Ar enc
! 32: .Op Fl f Ar device
! 33: .Op Fl j Ar flag
! 34: .Op Fl L Ar addr
! 35: .Op Fl m Ar mode
! 36: .Op Fl q Ar port
! 37: .Op Fl r Ar rate
! 38: .Op Fl s Ar name
! 39: .Op Fl t Ar mode
! 40: .Op Fl U Ar unit
! 41: .Op Fl v Ar volume
! 42: .Op Fl w Ar flag
! 43: .Op Fl z Ar nframes
! 44: .Ek
! 45: .Sh DESCRIPTION
! 46: The
! 47: .Nm
! 48: daemon is an intermediate layer between
! 49: audio or MIDI programs and the hardware.
! 50: It performs the necessary audio processing to
! 51: allow any program to work on any supported hardware.
! 52: By default,
! 53: .Nm
! 54: accepts connections from programs
! 55: running on the same system only;
! 56: it initializes only when programs are using its services,
! 57: allowing
! 58: .Nm
! 59: to consume a negligible amount of system resources the rest of the time.
! 60: Systems with no audio hardware can use
! 61: .Nm
! 62: to keep hot-pluggable devices usable by default at
! 63: virtually no cost.
! 64: .Pp
! 65: .Nm
! 66: operates as follows: it exposes at least one
! 67: .Em sub-device
! 68: that any number of audio programs can connect to and use as if it was
! 69: audio hardware.
! 70: During playback,
! 71: .Nm
! 72: receives audio data concurrently from all programs, mixes it and sends
! 73: the result to the hardware device.
! 74: Similarly, during recording it duplicates audio data recorded
! 75: from the device and sends it to all programs.
! 76: Since audio data flows through the
! 77: .Nm
! 78: process, it has the opportunity to process audio data on the fly:
! 79: .Pp
! 80: .Bl -bullet -offset indent -compact
! 81: .It
! 82: Change the sound encoding to overcome incompatibilities between
! 83: software and hardware.
! 84: .It
! 85: Route the sound from one channel to another,
! 86: join stereo or split mono.
! 87: .It
! 88: Control the per-application playback volume as well as the
! 89: master volume.
! 90: .It
! 91: Monitor the sound being played, allowing one program to record
! 92: what other programs play.
! 93: .El
! 94: .Pp
! 95: Processing is configured on a per sub-device basis, meaning that
! 96: the sound of all programs connected to the same sub-device will be
! 97: processed according to the same configuration.
! 98: Multiple sub-devices can be defined, allowing multiple configurations
! 99: to coexist.
! 100: The user selects the configuration a given program will use
! 101: by selecting the sub-device the program uses.
! 102: .Pp
! 103: .Nm
! 104: exposes MIDI thru boxes (hubs),
! 105: allowing programs to send MIDI messages to each other
! 106: or to hardware MIDI ports in a uniform way.
! 107: .Pp
! 108: Finally,
! 109: .Nm
! 110: exposes a control MIDI port usable for:
! 111: .Pp
! 112: .Bl -bullet -offset indent -compact
! 113: .It
! 114: Volume control.
! 115: .It
! 116: Common clock source for audio and MIDI programs.
! 117: .It
! 118: Start, stop and relocate groups of audio programs.
! 119: .El
! 120: .Pp
! 121: The options are as follows:
! 122: .Bl -tag -width Ds
! 123: .It Fl a Ar flag
! 124: Control whether
! 125: .Nm
! 126: opens the audio device or the MIDI port only when needed or keeps
! 127: it open all the time.
! 128: If the flag is
! 129: .Va on
! 130: then the audio device or MIDI port is kept open all the time, ensuring
! 131: no other program can steal it.
! 132: If the flag is
! 133: .Va off ,
! 134: then it's automatically closed, allowing other programs to have direct
! 135: access to the audio device, or the device to be disconnected.
! 136: The default is
! 137: .Va off .
! 138: .It Fl b Ar nframes
! 139: The buffer size of the audio device in frames.
! 140: A frame consists of one sample for each channel in the stream.
! 141: This is the number of frames that will be buffered before being played
! 142: and thus controls the playback latency.
! 143: The default is 7680 or twice the block size
! 144: .Pq Fl z ,
! 145: if the block size is set.
! 146: .It Xo
! 147: .Fl C Ar min : Ns Ar max ,
! 148: .Fl c Ar min : Ns Ar max
! 149: .Xc
! 150: The range of channel numbers for recording and playback directions,
! 151: respectively any client is allowed to use.
! 152: This is a subset of the audio device channels.
! 153: The default is 0:1, i.e. stereo.
! 154: .It Fl d
! 155: Increase log verbosity.
! 156: .Nm
! 157: logs on
! 158: .Em stderr .
! 159: .It Fl e Ar enc
! 160: Attempt to configure the device to use this encoding.
! 161: The default is
! 162: .Va s16 .
! 163: Encoding names use the following scheme: signedness
! 164: .Po
! 165: .Va s
! 166: or
! 167: .Va u
! 168: .Pc
! 169: followed
! 170: by the precision in bits, the byte-order
! 171: .Po
! 172: .Va le
! 173: or
! 174: .Va be
! 175: .Pc ,
! 176: the number of
! 177: bytes per sample, and the alignment
! 178: .Po
! 179: .Va msb
! 180: or
! 181: .Va lsb
! 182: .Pc .
! 183: Only the signedness and the precision are mandatory.
! 184: Examples:
! 185: .Va u8 , s16le , s24le3 , s24le4lsb .
! 186: .It Fl f Ar device
! 187: Add this
! 188: .Xr sndio 7
! 189: audio device to devices used for playing and/or recording.
! 190: Preceding per-device options
! 191: .Pq Fl aberwz
! 192: apply to this device.
! 193: Sub-devices
! 194: .Pq Fl s
! 195: that are applied after will be attached to this device.
! 196: Device mode and parameters are determined from sub-devices
! 197: attached to it.
! 198: .It Fl j Ar flag
! 199: Control whether program channels are joined or expanded if
! 200: the number of channels requested by a program is not equal
! 201: to the device number of channels.
! 202: If the flag is
! 203: .Va off
! 204: then client channels are routed to the corresponding
! 205: device channel, possibly discarding channels not present in the device.
! 206: If the flag is
! 207: .Va on ,
! 208: then a single client channel may be sent on multiple device channels,
! 209: or multiple client channels may be sent to a single device channel.
! 210: For instance, this feature could be used for mono to stereo conversions.
! 211: The default is
! 212: .Ar on .
! 213: .It Fl L Ar addr
! 214: Specify a local network address
! 215: .Nm
! 216: should listen on;
! 217: .Nm
! 218: will listen on TCP port 11025+n, where n is the unit number
! 219: specified with
! 220: .Fl U .
! 221: Without this option,
! 222: .Nm
! 223: listens on the
! 224: .Ux Ns -domain
! 225: socket only, and is not reachable from any network.
! 226: If the option argument is
! 227: .Sq -
! 228: then
! 229: .Nm
! 230: will accept connections from any address.
! 231: As the communication is not secure, this
! 232: option is only suitable for local networks where all hosts
! 233: and users are trusted.
! 234: .It Fl m Ar mode
! 235: Set the sub-device mode.
! 236: Valid modes are
! 237: .Ar play ,
! 238: .Ar rec ,
! 239: and
! 240: .Ar mon ,
! 241: corresponding to playback, recording and monitoring.
! 242: A monitoring stream is a fake recording stream corresponding to
! 243: the mix of all playback streams.
! 244: Multiple modes can be specified, separated by commas,
! 245: but the same sub-device cannot be used for both recording and monitoring.
! 246: The default is
! 247: .Ar play , Ns Ar rec
! 248: (i.e. full-duplex).
! 249: .It Fl q Ar port
! 250: Expose the given MIDI port.
! 251: This allows multiple programs to share the port.
! 252: .It Fl r Ar rate
! 253: Attempt to force the device to use this sample rate in Hertz.
! 254: The default is 48000.
! 255: .It Fl s Ar name
! 256: Add
! 257: .Ar name
! 258: to the list of sub-devices to expose.
! 259: This allows clients to use
! 260: .Nm
! 261: instead of the physical audio device for audio input and output
! 262: in order to share the physical device with other clients.
! 263: Defining multiple sub-devices allows splitting a physical audio device
! 264: into sub-devices having different properties (e.g. channel ranges).
! 265: The given
! 266: .Ar name
! 267: corresponds to the
! 268: .Dq option
! 269: part of the
! 270: .Xr sndio 7
! 271: device name string.
! 272: .It Fl t Ar mode
! 273: Select the way clients are controlled by MIDI Machine Control (MMC)
! 274: messages received by
! 275: .Nm .
! 276: If the mode is
! 277: .Va off
! 278: (the default), then programs are not affected by MMC messages.
! 279: If the mode is
! 280: .Va slave ,
! 281: then programs are started synchronously by MMC start messages;
! 282: additionally, the server clock is exposed as MIDI Time Code (MTC)
! 283: messages allowing MTC-capable software or hardware to be synchronized
! 284: to audio programs.
! 285: .It Fl U Ar unit
! 286: Unit number.
! 287: Each
! 288: .Nm
! 289: server instance has an unique unit number,
! 290: used in
! 291: .Xr sndio 7
! 292: device names.
! 293: The default is 0.
! 294: .It Fl v Ar volume
! 295: Software volume attenuation of playback.
! 296: The value must be between 1 and 127,
! 297: corresponding to \-42dB and \-0dB attenuation in 1/3dB steps.
! 298: Clients inherit this parameter.
! 299: Reducing the volume in advance allows a client's volume to stay independent
! 300: from the number of clients as long as their number is small enough.
! 301: 18 volume units (i.e. \-6dB attenuation) allows the number
! 302: of playback programs to be doubled.
! 303: The default is 118 i.e. \-3dB.
! 304: .It Fl w Ar flag
! 305: Control
! 306: .Nm
! 307: behaviour when the maximum volume of the hardware is reached
! 308: and a new program starts playing.
! 309: This happens only when volumes are not properly set using the
! 310: .Fl v
! 311: option.
! 312: If the flag is
! 313: .Va on ,
! 314: then the master volume is automatically adjusted to avoid clipping.
! 315: Using
! 316: .Va off
! 317: makes sense in the rare situation where all programs lower their volumes.
! 318: The default is
! 319: .Va on .
! 320: .It Fl z Ar nframes
! 321: The audio device block size in frames.
! 322: This is the number of frames between audio clock ticks,
! 323: i.e. the clock resolution.
! 324: If a sub-device is created with the
! 325: .Fl t
! 326: option, and MTC is used for synchronization, the clock
! 327: resolution must be 96, 100 or 120 ticks per second for maximum
! 328: accuracy.
! 329: For instance, 100 ticks per second at 48000Hz corresponds
! 330: to a 480 frame block size.
! 331: The default is 960 or half of the buffer size
! 332: .Pq Fl b ,
! 333: if the buffer size is set.
! 334: .El
! 335: .Pp
! 336: On the command line,
! 337: per-device parameters
! 338: .Pq Fl aberwz
! 339: must precede the device definition
! 340: .Pq Fl f ,
! 341: and per-sub-device parameters
! 342: .Pq Fl Ccjmtvx
! 343: must precede the sub-device definition
! 344: .Pq Fl s .
! 345: Sub-device definitions
! 346: .Pq Fl s
! 347: must follow the definition of the device
! 348: .Pq Fl f
! 349: to which they are attached.
! 350: .Pp
! 351: If no audio devices
! 352: .Pq Fl f
! 353: are specified,
! 354: settings are applied as if
! 355: the default device is specified.
! 356: If no sub-devices
! 357: .Pq Fl s
! 358: are specified for a device, a default sub-device is
! 359: created attached to it.
! 360: If a device
! 361: .Pq Fl f
! 362: is defined twice, both definitions are merged:
! 363: parameters of the first one are used but sub-devices
! 364: .Pq Fl s
! 365: of both definitions are created.
! 366: The default
! 367: .Xr sndio 7
! 368: device used by
! 369: .Nm
! 370: is
! 371: .Pa rsnd/0 ,
! 372: and the default sub-device exposed by
! 373: .Nm
! 374: is
! 375: .Pa snd/0 .
! 376: .Pp
! 377: If
! 378: .Nm
! 379: is sent
! 380: .Dv SIGHUP ,
! 381: .Dv SIGINT
! 382: or
! 383: .Dv SIGTERM ,
! 384: it terminates.
! 385: .Pp
! 386: By default, when the program cannot accept
! 387: recorded data fast enough or cannot provide data to play fast enough,
! 388: the program is paused, i.e. samples that cannot be written are discarded
! 389: and samples that cannot be read are replaced by silence.
! 390: If a sub-device is created with the
! 391: .Fl t
! 392: option, then recorded samples are discarded,
! 393: but the same amount of silence will be written
! 394: once the program is unblocked, in order to reach the right position in time.
! 395: Similarly silence is played, but the same amount of samples will be discarded
! 396: once the program is unblocked.
! 397: This ensures proper synchronization between programs.
! 398: .Sh MIDI CONTROL
! 399: .Nm
! 400: creates a MIDI port with the same name as the exposed audio
! 401: sub-device to which MIDI programs can connect.
! 402: .Nm
! 403: exposes the audio device clock
! 404: and allows audio device properties to be controlled
! 405: through MIDI.
! 406: .Pp
! 407: A MIDI channel is assigned to each stream, and the volume
! 408: is changed using the standard volume controller (number 7).
! 409: Similarly, when the audio client changes its volume,
! 410: the same MIDI controller message is sent out; it can be used
! 411: for instance for monitoring or as feedback for motorized
! 412: faders.
! 413: .Pp
! 414: The master volume can be changed using the standard master volume
! 415: system exclusive message.
! 416: .Pp
! 417: Streams created with the
! 418: .Fl t
! 419: option are controlled by the following MMC messages:
! 420: .Bl -tag -width relocateXXX -offset indent
! 421: .It relocate
! 422: This message is ignored by audio
! 423: .Nm
! 424: clients, but the given time position is sent to MIDI ports as an MTC
! 425: .Dq "full frame"
! 426: message forcing all MTC-slaves to relocate to the given
! 427: position (see below).
! 428: .It start
! 429: Put all streams in starting mode.
! 430: In this mode,
! 431: .Nm
! 432: waits for all streams to become ready
! 433: to start, and then starts them synchronously.
! 434: Once started, new streams can be created
! 435: .Pq Nm sndiod
! 436: but they will be blocked
! 437: until the next stop-to-start transition.
! 438: .It stop
! 439: Put all streams in stopped mode (the default).
! 440: In this mode, any stream attempting to start playback or recording
! 441: is paused.
! 442: Client streams that are already
! 443: started are not affected until they stop and try to start again.
! 444: .El
! 445: .Pp
! 446: Streams created with the
! 447: .Fl t
! 448: option export the
! 449: .Nm
! 450: device clock using MTC, allowing non-audio
! 451: software or hardware to be synchronized to the audio stream.
! 452: Maximum accuracy is achieved when the number of blocks per
! 453: second is equal to one of the standard MTC clock rates (96, 100 and 120Hz).
! 454: The following sample rates
! 455: .Pq Fl r
! 456: and block sizes
! 457: .Pq Fl z
! 458: are recommended:
! 459: .Pp
! 460: .Bl -bullet -offset indent -compact
! 461: .It
! 462: 44100Hz, 441 frames (MTC rate is 100Hz)
! 463: .It
! 464: 48000Hz, 400 frames (MTC rate is 120Hz)
! 465: .It
! 466: 48000Hz, 480 frames (MTC rate is 100Hz)
! 467: .It
! 468: 48000Hz, 500 frames (MTC rate is 96Hz)
! 469: .El
! 470: .Pp
! 471: For instance, the following command will create two devices:
! 472: the default
! 473: .Va snd/0
! 474: and a MIDI-controlled
! 475: .Va snd/0.mmc :
! 476: .Bd -literal -offset indent
! 477: $ sndiod -r 48000 -z 400 -s default -t slave -s mmc
! 478: .Ed
! 479: .Pp
! 480: Streams connected to
! 481: .Va snd/0
! 482: behave normally, while streams connected to
! 483: .Va snd/0.mmc
! 484: wait for the MMC start signal and start synchronously.
! 485: Regardless of which device a stream is connected to,
! 486: its playback volume knob is exposed.
! 487: .Sh EXAMPLES
! 488: Start server using default parameters, creating an
! 489: additional sub-device for output to channels 2:3 only (rear speakers
! 490: on most cards), exposing the
! 491: .Pa snd/0
! 492: and
! 493: .Pa snd/0.rear
! 494: devices:
! 495: .Bd -literal -offset indent
! 496: $ sndiod -s default -c 2:3 -s rear
! 497: .Ed
! 498: .Pp
! 499: Start server creating the default sub-device with low volume and
! 500: an additional sub-device for high volume output, exposing the
! 501: .Pa snd/0
! 502: and
! 503: .Pa snd/0.max
! 504: devices:
! 505: .Bd -literal -offset indent
! 506: $ sndiod -v 65 -s default -v 127 -s max
! 507: .Ed
! 508: .Pp
! 509: Start server configuring the audio device to use
! 510: a 48kHz sample frequency, 240-frame block size,
! 511: and 2-block buffers.
! 512: The corresponding latency is 10ms, which is
! 513: the time it takes the sound to propagate 3.5 meters.
! 514: .Bd -literal -offset indent
! 515: $ sndiod -r 48000 -b 480 -z 240
! 516: .Ed
! 517: .Sh SEE ALSO
! 518: .Xr sndio 7
! 519: .Sh BUGS
! 520: Resampling is low quality; down-sampling especially should be avoided
! 521: when recording.
! 522: .Pp
! 523: Processing is done using 16-bit arithmetic,
! 524: thus samples with more than 16 bits are rounded.
! 525: 16 bits (i.e. 97dB dynamic) are largely enough for most applications though.
! 526: Processing precision can be increased to 24-bit at compilation time though.
! 527: .Pp
! 528: If
! 529: .Fl a Ar off
! 530: is used,
! 531: .Nm
! 532: creates sub-devices to expose first
! 533: and then opens the audio hardware on demand.
! 534: Technically, this allows
! 535: .Nm
! 536: to attempt to use one of the sub-devices it exposes as an audio device,
! 537: creating a deadlock.
! 538: There's nothing to prevent the user
! 539: from shooting himself in the foot by creating such a deadlock.
![[BACK]](/icons/back.gif){kind=icon}
Return to sndiod.8 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / sndiod