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