Annotation of src/usr.bin/sndioctl/sndioctl.1, Revision 1.3
1.3 ! ratchov 1: .\" $OpenBSD: sndioctl.1,v 1.2 2020/02/26 14:47:48 ratchov Exp $
1.1 ratchov 2: .\"
3: .\" Copyright (c) 2014-2020 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 ratchov 17: .Dd $Mdocdate: February 26 2020 $
1.1 ratchov 18: .Dt SNDIOCTL 1
19: .Os
20: .Sh NAME
21: .Nm sndioctl
22: .Nd control audio parameters
23: .Sh SYNOPSIS
24: .Nm
25: .Bk -words
1.2 ratchov 26: .Op Fl dimv
1.1 ratchov 27: .Op Fl f Ar device
28: .Op Ar command ...
29: .Ek
30: .Sh DESCRIPTION
31: The
32: .Nm
33: utility can display or change parameters of
34: .Xr sndio 7
35: audio devices.
36: The options are as follows:
37: .Bl -tag -width Ds
38: .It Fl d
39: Dump the raw list of available parameters and exit.
40: Useful as a debugging tool.
41: .It Fl f Ar device
42: Use this
43: .Xr sndio 7
44: audio device.
45: .It Fl i
46: Display characteristics of requested parameters
47: instead of their values.
48: .It Fl m
49: Monitor and display audio parameter changes.
50: .It Fl v
51: Enable verbose mode, a.k.a. multi-channel mode.
52: By default parameters affecting different channels
53: of the same stream are disguised as a single mono
54: parameter to hide details that are not essential.
55: .El
56: .Pp
57: If no commands are specified all valid parameters are displayed on
58: .Em stdout .
59: Unless
60: .Fl d ,
61: .Fl m ,
62: or
63: .Fl i
64: are used, displayed parameters are valid commands.
65: The set of available controls depends on the control device.
66: .Pp
67: Commands use the following two formats to display and set
68: parameters respectively:
69: .Pp
70: .Dl group/stream[channel].function
71: .Dl group/stream[channel].function=value
72: .Pp
73: On the left-hand side are specified the optional parameter group,
74: the affected stream name, and the optional channel number.
75: Examples of left-hand side terms:
76: .Pp
77: .Dl output.level
78: .Dl hw/spkr[6].mute
79: .Pp
80: There are 4 parameter types: switches, numbers, selectors, and vectors.
81: .Pp
82: Numbers are specified in decimal and follow the same semantics
83: as MIDI controllers.
84: Values are in the 0..127 range and 64 is the neutral state (if applicable).
85: Two-state controls (switches) take either 0 or 1 as value,
86: typically corresponding to the
87: .Em off
88: and
89: .Em on
90: states respectively.
91: .Pp
92: If a decimal is prefixed by the plus (minus) sign then
93: the given value is added to (subtracted from) the
94: current value of the control.
95: If
96: .Qq \&!
97: is used instead of a number, then the switch is toggled.
98: Examples:
99: .Pp
100: .Dl hw/spkr.level=85
101: .Dl hw/spkr.level=+10
102: .Dl hw/spkr.mute=0
103: .Dl hw/spkr.mute=!
104: .Pp
105: Selector values are substreams; they are specified
106: as the stream name followed by an optional channel
107: number.
108: If no channel number is specified, the same
109: number as the stream specified on the left-hand side is used.
110: For instance the following are equivalent:
111: .Pp
112: .Dl hw/record[1].source=mic
113: .Dl hw/record[1].source=mic1
114: .Pp
115: Vectors are arrays of numbers.
116: Values are specified as comma-separated components.
117: Each component is a substream, followed by
118: a colon, followed by a number.
119: If the colon and the number are omitted, then 127 is
120: assumed.
121: If a component is missing, then 0 is assumed.
122: Example:
123: .Pp
124: .Dl hw/monitor.mix=play:120,linein:85
125: .Dl hw/record.source=mic,linein
126: .Pp
127: Numbers are specified as discussed above.
128: Note that a vector of switches is equivalent to
129: a list.
130: .Sh EXAMPLES
131: The following will set all
132: .Ar level
133: parameters that control the
134: .Ar spkr
1.3 ! ratchov 135: stream to zero:
1.1 ratchov 136: .Pp
137: .Dl $ sndioctl hw/spkr.level=0
138: .Pp
139: The following commands are equivalent:
140: .Pp
141: .Dl $ sndioctl hw/record[0].source=mic0 hw/record[1].source=mic1
142: .Dl $ sndioctl hw/record.source=mic
143: .Sh SEE ALSO
144: .Xr sioctl_open 3