1.\" $OpenBSD: audioctl.8,v 1.7 2023/01/09 17:13:46 jmc Exp $ 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.\" 29.Dd $Mdocdate: January 9 2023 $ 30.Dt AUDIOCTL 8 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 nq 38.Op Fl f Ar file 39.Op Fl w Ar wait 40.Op Ar name Ns Oo = Ns Ar value Oc Ar ... 41.Sh DESCRIPTION 42The 43.Nm 44utility retrieves or sets 45.Xr audio 4 46driver variables. 47The options are as follows: 48.Bl -tag -width Ds 49.It Fl f Ar file 50Specifies the audio control device or the audio device. 51The default is 52.Pa /dev/audioctl0 . 53.It Fl n 54Suppress printing of the variable name. 55.It Fl q 56Suppress all output when setting a variable. 57.It Fl w Ar wait 58Display variables every 59.Ar wait 60seconds. 61.Nm 62will continue to display variables until interrupted. 63.It Ar name Ns Op = Ns Ar value 64Retrieve the specified variable 65.Ar name , 66or attempt to set it to value. 67Multiple 68.Ar name Ns Op = Ns Ar value 69arguments may be given. 70.El 71.Pp 72If the audio control device is used, then values are only stored in the 73.Xr audio 4 74driver; they will be submitted to the hardware the next time the 75device is opened for playback or recording. 76If the audio device is used instead of the control device, 77then values are negotiated with the hardware immediately; this requires 78exclusive access to the device. 79Variables may only be changed if the device is not opened for 80playback or recording by another process. 81.Pp 82The following variable names are available: 83.Bl -column "record.channels" -offset indent 84.It Sy Name Ta Sy Meaning 85.It name Ta device name, as shown by 86.Xr dmesg 8 87.It mode Ta current device mode ( 88.Va play , 89.Va record , 90or both) 91.It pause Ta set if not attempting to start 92.It active Ta set if playing or recording 93.It nblks Ta number of blocks (in frames) in the play buffer 94.It blksz Ta number of frames per block 95.It rate Ta sample rate in Hz 96.It encoding Ta current sample format 97.It play.channels Ta number of play channels 98.It play.bytes Ta bytes played since playback started 99.It play.errors Ta bytes inserted during underruns 100.It record.channels Ta number of recording channels 101.It record.bytes Ta bytes recorded since device started 102.It record.errors Ta bytes dropped during overruns 103.El 104.Pp 105Encoding names use the following scheme: signedness 106.Po 107.Va s 108or 109.Va u 110.Pc 111followed 112by the precision in bits, the byte-order 113.Po 114.Va le 115or 116.Va be 117.Pc , 118the number of 119bytes per sample, and the alignment 120.Po 121.Va msb 122or 123.Va lsb 124.Pc . 125Only the signedness and the precision are mandatory. 126Examples: 127.Va u8 , s16le , s24le3 , s24le4lsb . 128.Sh FILES 129.Bl -tag -width /dev/audioctl0 -compact 130.It Pa /dev/audioctlN 131audio control devices 132.It Pa /dev/audioN 133audio devices 134.El 135.Sh EXAMPLES 136Once per second, display the number of bytes of silence inserted due to buffer 137underruns (since the device started playback): 138.Bd -literal -offset indent 139# audioctl -w 1 play.errors 140.Ed 141.Pp 142Use signed 24-bit samples and 44100Hz sample rate: 143.Bd -literal -offset indent 144# audioctl -f /dev/audio0 encoding=s24 rate=44100 145.Ed 146.Pp 147Note the use of 148.Pa /dev/audio0 149to force negotiation with the hardware. 150If the above parameters are not supported by the 151hardware, then supported ones will be selected instead. 152.Sh SEE ALSO 153.Xr aucat 1 , 154.Xr cdio 1 , 155.Xr audio 4 , 156.Xr mixerctl 8 , 157.Xr sysctl 8 158.Sh HISTORY 159The 160.Nm 161command first appeared in 162.Nx 1.3 . 163