Annotation of src/usr.bin/sndiod/sndiod.1, Revision 1.4
1.4 ! nicm 1: .\" $OpenBSD: sndiod.1,v 1.3 2012/12/02 15:54:20 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.4 ! nicm 17: .Dd $Mdocdate: December 2 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
1.3 jmc 104: exposes MIDI thru boxes (hubs),
1.1 ratchov 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 follwing 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
1.4 ! nicm 177: bytes per sample, and the alignment
1.1 ratchov 178: .Po
179: .Va msb
180: or
181: .Va lsb
182: .Pc .
183: Only the signedness and the precision are mandatory.
184: Examples:
1.2 jmc 185: .Va u8 , s16le , s24le3 , s24le4lsb .
1.1 ratchov 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;
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: .It Fl m Ar mode
232: Set the sub-device mode.
233: Valid modes are
234: .Ar play ,
235: .Ar rec ,
236: and
237: .Ar mon ,
238: corresponding to playback, recording and monitoring.
239: A monitoring stream is a fake recording stream corresponding to
240: the mix of all playback streams.
241: Multiple modes can be specified, separated by commas,
242: but the same sub-device cannot be used for both recording and monitoring.
243: The default is
244: .Ar play , Ns Ar rec
245: (i.e. full-duplex).
246: .It Fl q Ar port
247: Expose the given MIDI port.
248: This allows multiple programs to share the port.
249: .It Fl r Ar rate
250: Attempt to force the device to use this sample rate in Hertz.
251: The default is 48000.
252: .It Fl s Ar name
253: Add
254: .Ar name
255: to the list of sub-devices to expose.
256: This allows clients to use
257: .Nm
258: instead of the physical audio device for audio input and output
259: in order to share the physical device with other clients.
260: Defining multiple sub-devices allows splitting a physical audio device
261: into sub-devices having different properties (e.g. channel ranges).
262: The given
263: .Ar name
264: corresponds to the
265: .Dq option
266: part of the
267: .Xr sndio 7
268: device name string.
269: .It Fl t Ar mode
270: Select the way clients are controlled by MIDI Machine Control (MMC)
271: messages received by
272: .Nm .
273: If the mode is
274: .Va off
275: (the default), then programs are not affected by MMC messages.
276: If the mode is
277: .Va slave ,
278: then programs are started synchronously by MMC start messages;
279: additionally, the server clock is exposed as MIDI Time Code (MTC)
280: messages allowing MTC-capable software or hardware to be synchronized
281: to audio programs.
282: .It Fl U Ar unit
283: Unit number.
284: Each
285: .Nm
286: server instance has an unique unit number,
287: used in
288: .Xr sndio 7
289: device names.
290: The default is 0.
291: The unit number must be set before any
292: .Fl L
293: is used.
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.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / sndiod