Annotation of src/usr.bin/sndioctl/sndioctl.1, Revision 1.4
1.4 ! ratchov 1: .\" $OpenBSD: sndioctl.1,v 1.3 2020/02/26 14:48:46 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
1.4 ! ratchov 82: Values are numbers between 0 and 1.
1.1 ratchov 83: Two-state controls (switches) take either 0 or 1 as value,
84: typically corresponding to the
85: .Em off
86: and
87: .Em on
88: states respectively.
89: .Pp
90: If a decimal is prefixed by the plus (minus) sign then
91: the given value is added to (subtracted from) the
92: current value of the control.
93: If
94: .Qq \&!
95: is used instead of a number, then the switch is toggled.
96: Examples:
97: .Pp
1.4 ! ratchov 98: .Dl hw/spkr.level=0.85
! 99: .Dl hw/spkr.level=+0.1
1.1 ratchov 100: .Dl hw/spkr.mute=0
101: .Dl hw/spkr.mute=!
102: .Pp
103: Selector values are substreams; they are specified
104: as the stream name followed by an optional channel
105: number.
106: If no channel number is specified, the same
107: number as the stream specified on the left-hand side is used.
108: For instance the following are equivalent:
109: .Pp
110: .Dl hw/record[1].source=mic
111: .Dl hw/record[1].source=mic1
112: .Pp
113: Vectors are arrays of numbers.
114: Values are specified as comma-separated components.
115: Each component is a substream, followed by
116: a colon, followed by a number.
1.4 ! ratchov 117: If the colon and the number are omitted, then 1 is assumed.
1.1 ratchov 118: If a component is missing, then 0 is assumed.
119: Example:
120: .Pp
1.4 ! ratchov 121: .Dl hw/monitor.mix=play:0.12,linein:0.85
1.1 ratchov 122: .Dl hw/record.source=mic,linein
123: .Pp
124: Numbers are specified as discussed above.
125: Note that a vector of switches is equivalent to
126: a list.
127: .Sh EXAMPLES
128: The following will set all
129: .Ar level
130: parameters that control the
131: .Ar spkr
1.3 ratchov 132: stream to zero:
1.1 ratchov 133: .Pp
134: .Dl $ sndioctl hw/spkr.level=0
135: .Pp
136: The following commands are equivalent:
137: .Pp
138: .Dl $ sndioctl hw/record[0].source=mic0 hw/record[1].source=mic1
139: .Dl $ sndioctl hw/record.source=mic
140: .Sh SEE ALSO
141: .Xr sioctl_open 3