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