Annotation of src/usr.bin/sndiod/sndiod.8, Revision 1.2
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
1.2 ! ratchov 155: Enable debugging to standard error, and do not disassociate from the
! 156: controlling terminal.
! 157: Can be specified multiple times to further increase log verbosity.
1.1 ratchov 158: .It Fl e Ar enc
159: Attempt to configure the device to use this encoding.
160: The default is
161: .Va s16 .
162: Encoding names use the following scheme: signedness
163: .Po
164: .Va s
165: or
166: .Va u
167: .Pc
168: followed
169: by the precision in bits, the byte-order
170: .Po
171: .Va le
172: or
173: .Va be
174: .Pc ,
175: the number of
176: bytes per sample, and the alignment
177: .Po
178: .Va msb
179: or
180: .Va lsb
181: .Pc .
182: Only the signedness and the precision are mandatory.
183: Examples:
184: .Va u8 , s16le , s24le3 , s24le4lsb .
185: .It Fl f Ar device
186: Add this
187: .Xr sndio 7
188: audio device to devices used for playing and/or recording.
189: Preceding per-device options
190: .Pq Fl aberwz
191: apply to this device.
192: Sub-devices
193: .Pq Fl s
194: that are applied after will be attached to this device.
195: Device mode and parameters are determined from sub-devices
196: attached to it.
197: .It Fl j Ar flag
198: Control whether program channels are joined or expanded if
199: the number of channels requested by a program is not equal
200: to the device number of channels.
201: If the flag is
202: .Va off
203: then client channels are routed to the corresponding
204: device channel, possibly discarding channels not present in the device.
205: If the flag is
206: .Va on ,
207: then a single client channel may be sent on multiple device channels,
208: or multiple client channels may be sent to a single device channel.
209: For instance, this feature could be used for mono to stereo conversions.
210: The default is
211: .Ar on .
212: .It Fl L Ar addr
213: Specify a local network address
214: .Nm
215: should listen on;
216: .Nm
217: will listen on TCP port 11025+n, where n is the unit number
218: specified with
219: .Fl U .
220: Without this option,
221: .Nm
222: listens on the
223: .Ux Ns -domain
224: socket only, and is not reachable from any network.
225: If the option argument is
226: .Sq -
227: then
228: .Nm
229: will accept connections from any address.
230: As the communication is not secure, this
231: option is only suitable for local networks where all hosts
232: and users are trusted.
233: .It Fl m Ar mode
234: Set the sub-device mode.
235: Valid modes are
236: .Ar play ,
237: .Ar rec ,
238: and
239: .Ar mon ,
240: corresponding to playback, recording and monitoring.
241: A monitoring stream is a fake recording stream corresponding to
242: the mix of all playback streams.
243: Multiple modes can be specified, separated by commas,
244: but the same sub-device cannot be used for both recording and monitoring.
245: The default is
246: .Ar play , Ns Ar rec
247: (i.e. full-duplex).
248: .It Fl q Ar port
249: Expose the given MIDI port.
250: This allows multiple programs to share the port.
251: .It Fl r Ar rate
252: Attempt to force the device to use this sample rate in Hertz.
253: The default is 48000.
254: .It Fl s Ar name
255: Add
256: .Ar name
257: to the list of sub-devices to expose.
258: This allows clients to use
259: .Nm
260: instead of the physical audio device for audio input and output
261: in order to share the physical device with other clients.
262: Defining multiple sub-devices allows splitting a physical audio device
263: into sub-devices having different properties (e.g. channel ranges).
264: The given
265: .Ar name
266: corresponds to the
267: .Dq option
268: part of the
269: .Xr sndio 7
270: device name string.
271: .It Fl t Ar mode
272: Select the way clients are controlled by MIDI Machine Control (MMC)
273: messages received by
274: .Nm .
275: If the mode is
276: .Va off
277: (the default), then programs are not affected by MMC messages.
278: If the mode is
279: .Va slave ,
280: then programs are started synchronously by MMC start messages;
281: additionally, the server clock is exposed as MIDI Time Code (MTC)
282: messages allowing MTC-capable software or hardware to be synchronized
283: to audio programs.
284: .It Fl U Ar unit
285: Unit number.
286: Each
287: .Nm
288: server instance has an unique unit number,
289: used in
290: .Xr sndio 7
291: device names.
292: The default is 0.
293: .It Fl v Ar volume
294: Software volume attenuation of playback.
295: The value must be between 1 and 127,
296: corresponding to \-42dB and \-0dB attenuation in 1/3dB steps.
297: Clients inherit this parameter.
298: Reducing the volume in advance allows a client's volume to stay independent
299: from the number of clients as long as their number is small enough.
300: 18 volume units (i.e. \-6dB attenuation) allows the number
301: of playback programs to be doubled.
302: The default is 118 i.e. \-3dB.
303: .It Fl w Ar flag
304: Control
305: .Nm
306: behaviour when the maximum volume of the hardware is reached
307: and a new program starts playing.
308: This happens only when volumes are not properly set using the
309: .Fl v
310: option.
311: If the flag is
312: .Va on ,
313: then the master volume is automatically adjusted to avoid clipping.
314: Using
315: .Va off
316: makes sense in the rare situation where all programs lower their volumes.
317: The default is
318: .Va on .
319: .It Fl z Ar nframes
320: The audio device block size in frames.
321: This is the number of frames between audio clock ticks,
322: i.e. the clock resolution.
323: If a sub-device is created with the
324: .Fl t
325: option, and MTC is used for synchronization, the clock
326: resolution must be 96, 100 or 120 ticks per second for maximum
327: accuracy.
328: For instance, 100 ticks per second at 48000Hz corresponds
329: to a 480 frame block size.
330: The default is 960 or half of the buffer size
331: .Pq Fl b ,
332: if the buffer size is set.
333: .El
334: .Pp
335: On the command line,
336: per-device parameters
337: .Pq Fl aberwz
338: must precede the device definition
339: .Pq Fl f ,
340: and per-sub-device parameters
341: .Pq Fl Ccjmtvx
342: must precede the sub-device definition
343: .Pq Fl s .
344: Sub-device definitions
345: .Pq Fl s
346: must follow the definition of the device
347: .Pq Fl f
348: to which they are attached.
349: .Pp
350: If no audio devices
351: .Pq Fl f
352: are specified,
353: settings are applied as if
354: the default device is specified.
355: If no sub-devices
356: .Pq Fl s
357: are specified for a device, a default sub-device is
358: created attached to it.
359: If a device
360: .Pq Fl f
361: is defined twice, both definitions are merged:
362: parameters of the first one are used but sub-devices
363: .Pq Fl s
364: of both definitions are created.
365: The default
366: .Xr sndio 7
367: device used by
368: .Nm
369: is
370: .Pa rsnd/0 ,
371: and the default sub-device exposed by
372: .Nm
373: is
374: .Pa snd/0 .
375: .Pp
376: If
377: .Nm
378: is sent
379: .Dv SIGHUP ,
380: .Dv SIGINT
381: or
382: .Dv SIGTERM ,
383: it terminates.
384: .Pp
385: By default, when the program cannot accept
386: recorded data fast enough or cannot provide data to play fast enough,
387: the program is paused, i.e. samples that cannot be written are discarded
388: and samples that cannot be read are replaced by silence.
389: If a sub-device is created with the
390: .Fl t
391: option, then recorded samples are discarded,
392: but the same amount of silence will be written
393: once the program is unblocked, in order to reach the right position in time.
394: Similarly silence is played, but the same amount of samples will be discarded
395: once the program is unblocked.
396: This ensures proper synchronization between programs.
397: .Sh MIDI CONTROL
398: .Nm
399: creates a MIDI port with the same name as the exposed audio
400: sub-device to which MIDI programs can connect.
401: .Nm
402: exposes the audio device clock
403: and allows audio device properties to be controlled
404: through MIDI.
405: .Pp
406: A MIDI channel is assigned to each stream, and the volume
407: is changed using the standard volume controller (number 7).
408: Similarly, when the audio client changes its volume,
409: the same MIDI controller message is sent out; it can be used
410: for instance for monitoring or as feedback for motorized
411: faders.
412: .Pp
413: The master volume can be changed using the standard master volume
414: system exclusive message.
415: .Pp
416: Streams created with the
417: .Fl t
418: option are controlled by the following MMC messages:
419: .Bl -tag -width relocateXXX -offset indent
420: .It relocate
421: This message is ignored by audio
422: .Nm
423: clients, but the given time position is sent to MIDI ports as an MTC
424: .Dq "full frame"
425: message forcing all MTC-slaves to relocate to the given
426: position (see below).
427: .It start
428: Put all streams in starting mode.
429: In this mode,
430: .Nm
431: waits for all streams to become ready
432: to start, and then starts them synchronously.
433: Once started, new streams can be created
434: .Pq Nm sndiod
435: but they will be blocked
436: until the next stop-to-start transition.
437: .It stop
438: Put all streams in stopped mode (the default).
439: In this mode, any stream attempting to start playback or recording
440: is paused.
441: Client streams that are already
442: started are not affected until they stop and try to start again.
443: .El
444: .Pp
445: Streams created with the
446: .Fl t
447: option export the
448: .Nm
449: device clock using MTC, allowing non-audio
450: software or hardware to be synchronized to the audio stream.
451: Maximum accuracy is achieved when the number of blocks per
452: second is equal to one of the standard MTC clock rates (96, 100 and 120Hz).
453: The following sample rates
454: .Pq Fl r
455: and block sizes
456: .Pq Fl z
457: are recommended:
458: .Pp
459: .Bl -bullet -offset indent -compact
460: .It
461: 44100Hz, 441 frames (MTC rate is 100Hz)
462: .It
463: 48000Hz, 400 frames (MTC rate is 120Hz)
464: .It
465: 48000Hz, 480 frames (MTC rate is 100Hz)
466: .It
467: 48000Hz, 500 frames (MTC rate is 96Hz)
468: .El
469: .Pp
470: For instance, the following command will create two devices:
471: the default
472: .Va snd/0
473: and a MIDI-controlled
474: .Va snd/0.mmc :
475: .Bd -literal -offset indent
476: $ sndiod -r 48000 -z 400 -s default -t slave -s mmc
477: .Ed
478: .Pp
479: Streams connected to
480: .Va snd/0
481: behave normally, while streams connected to
482: .Va snd/0.mmc
483: wait for the MMC start signal and start synchronously.
484: Regardless of which device a stream is connected to,
485: its playback volume knob is exposed.
486: .Sh EXAMPLES
487: Start server using default parameters, creating an
488: additional sub-device for output to channels 2:3 only (rear speakers
489: on most cards), exposing the
490: .Pa snd/0
491: and
492: .Pa snd/0.rear
493: devices:
494: .Bd -literal -offset indent
495: $ sndiod -s default -c 2:3 -s rear
496: .Ed
497: .Pp
498: Start server creating the default sub-device with low volume and
499: an additional sub-device for high volume output, exposing the
500: .Pa snd/0
501: and
502: .Pa snd/0.max
503: devices:
504: .Bd -literal -offset indent
505: $ sndiod -v 65 -s default -v 127 -s max
506: .Ed
507: .Pp
508: Start server configuring the audio device to use
509: a 48kHz sample frequency, 240-frame block size,
510: and 2-block buffers.
511: The corresponding latency is 10ms, which is
512: the time it takes the sound to propagate 3.5 meters.
513: .Bd -literal -offset indent
514: $ sndiod -r 48000 -b 480 -z 240
515: .Ed
516: .Sh SEE ALSO
517: .Xr sndio 7
518: .Sh BUGS
519: Resampling is low quality; down-sampling especially should be avoided
520: when recording.
521: .Pp
522: Processing is done using 16-bit arithmetic,
523: thus samples with more than 16 bits are rounded.
524: 16 bits (i.e. 97dB dynamic) are largely enough for most applications though.
525: Processing precision can be increased to 24-bit at compilation time though.
526: .Pp
527: If
528: .Fl a Ar off
529: is used,
530: .Nm
531: creates sub-devices to expose first
532: and then opens the audio hardware on demand.
533: Technically, this allows
534: .Nm
535: to attempt to use one of the sub-devices it exposes as an audio device,
536: creating a deadlock.
537: There's nothing to prevent the user
538: 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