Annotation of src/usr.bin/audioctl/audioctl.8, Revision 1.5
1.5 ! ratchov 1: .\" $OpenBSD: audioctl.8,v 1.4 2020/04/23 00:16:59 schwarze Exp $
1.1 deraadt 2: .\" $NetBSD: audioctl.1,v 1.7 1998/04/27 16:55:23 augustss Exp $
3: .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
4: .\" All rights reserved.
5: .\"
6: .\" Author: Lennart Augustsson
7: .\"
8: .\" Redistribution and use in source and binary forms, with or without
9: .\" modification, are permitted provided that the following conditions
10: .\" are met:
11: .\" 1. Redistributions of source code must retain the above copyright
12: .\" notice, this list of conditions and the following disclaimer.
13: .\" 2. Redistributions in binary form must reproduce the above copyright
14: .\" notice, this list of conditions and the following disclaimer in the
15: .\" documentation and/or other materials provided with the distribution.
16: .\"
17: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
18: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
21: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27: .\" POSSIBILITY OF SUCH DAMAGE.
28: .\"
1.5 ! ratchov 29: .Dd $Mdocdate: April 23 2020 $
1.4 schwarze 30: .Dt AUDIOCTL 8
1.1 deraadt 31: .Os
32: .Sh NAME
33: .Nm audioctl
34: .Nd get or set audio driver variables
35: .Sh SYNOPSIS
36: .Nm audioctl
37: .Op Fl f Ar file
1.5 ! ratchov 38: .Op Fl w Ar wait
1.1 deraadt 39: .Nm audioctl
40: .Op Fl n
41: .Op Fl f Ar file
1.5 ! ratchov 42: .Op Fl w Ar wait
1.1 deraadt 43: .Ar name ...
44: .Nm audioctl
45: .Op Fl nq
46: .Op Fl f Ar file
47: .Ar name Ns = Ns Ar value ...
48: .Sh DESCRIPTION
49: The
50: .Nm
51: utility retrieves or sets
52: .Xr audio 4
53: driver variables.
54: The options are as follows:
55: .Bl -tag -width Ds
56: .It Fl f Ar file
57: Specifies the audio control device or the audio device.
58: The default is
59: .Pa /dev/audioctl0 .
60: .It Fl n
61: Suppress printing of the variable name.
62: .It Fl q
63: Suppress all output when setting a variable.
1.5 ! ratchov 64: .It Fl w Ar wait
! 65: Pause
! 66: .Ar wait
! 67: seconds between each display.
! 68: .Nm
! 69: will display variables forever.
1.1 deraadt 70: .It Ar name Ns = Ns Ar value
71: Attempt to set the specified variable
72: .Ar name
73: to
74: .Ar value .
75: .El
76: .Pp
77: If the audio control device is used, then values are only stored in the
78: .Xr audio 4
79: driver; they will be submitted to the hardware the next time the
80: device is opened for playback or recording.
81: If the audio device is used instead of the control device,
82: then values are negotiated with the hardware immediately; this requires
83: exclusive access to the device.
84: Variables may only be changed if the device is not opened for
85: playback or recording by another process.
86: .Pp
87: The following variable names are available:
88: .Bl -column "record.channels" -offset indent
89: .It Sy Name Ta Sy Meaning
90: .It name Ta device name, as shown by
91: .Xr dmesg 8
92: .It mode Ta current device mode (
93: .Va play ,
94: .Va record ,
95: or both)
96: .It pause Ta set if not attempting to start
97: .It active Ta set if playing or recording
98: .It nblks Ta number of blocks (in frames) in the play buffer
99: .It blksz Ta number of frames per block
100: .It rate Ta sample rate in Hz
101: .It encoding Ta current sample format
102: .It play.channels Ta number of play channels
103: .It play.bytes Ta bytes played since playback started
104: .It play.errors Ta bytes inserted during underruns
105: .It record.channels Ta number of recording channels
106: .It record.bytes Ta bytes recorded since device started
107: .It record.errors Ta bytes dropped during overruns
108: .El
109: .Pp
110: Encoding names use the following scheme: signedness
111: .Po
112: .Va s
113: or
114: .Va u
115: .Pc
116: followed
117: by the precision in bits, the byte-order
118: .Po
119: .Va le
120: or
121: .Va be
122: .Pc ,
123: the number of
124: bytes per sample, and the alignment
125: .Po
126: .Va msb
127: or
128: .Va lsb
129: .Pc .
130: Only the signedness and the precision are mandatory.
131: Examples:
132: .Va u8 , s16le , s24le3 , s24le4lsb .
133: .Sh FILES
134: .Bl -tag -width /dev/audioctl0 -compact
135: .It Pa /dev/audioctlN
136: audio control devices
137: .It Pa /dev/audioN
138: audio devices
139: .El
140: .Sh EXAMPLES
1.5 ! ratchov 141: Once per-second, display the number of bytes of silence inserted due to buffer
! 142: underruns (since the device started playback):
1.1 deraadt 143: .Bd -literal -offset indent
1.5 ! ratchov 144: # audioctl -w 1 play.errors
1.1 deraadt 145: .Ed
146: .Pp
147: Use signed 24-bit samples and 44100Hz sample rate:
148: .Bd -literal -offset indent
1.3 jmc 149: # audioctl -f /dev/audio0 encoding=s24 rate=44100
1.1 deraadt 150: .Ed
151: .Pp
152: Note the use of
153: .Pa /dev/audio0
154: to force negotiation with the hardware.
155: If the above parameters are not supported by the
156: hardware, then supported ones will be selected instead.
157: .Sh SEE ALSO
158: .Xr aucat 1 ,
159: .Xr cdio 1 ,
1.2 jmc 160: .Xr audio 4 ,
1.1 deraadt 161: .Xr mixerctl 8 ,
162: .Xr sysctl 8
163: .Sh HISTORY
164: The
165: .Nm
166: command first appeared in
167: .Nx 1.3 .