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