.\" $OpenBSD: audioctl.8,v 1.7 2023/01/09 17:13:46 jmc Exp $
.\" $NetBSD: audioctl.1,v 1.7 1998/04/27 16:55:23 augustss Exp $
.\" Copyright (c) 1997 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Author: Lennart Augustsson
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: January 9 2023 $
.Dt AUDIOCTL 8
.Os
.Sh NAME
.Nm audioctl
.Nd get or set audio driver variables
.Sh SYNOPSIS
.Nm audioctl
.Op Fl nq
.Op Fl f Ar file
.Op Fl w Ar wait
.Op Ar name Ns Oo = Ns Ar value Oc Ar ...
.Sh DESCRIPTION
The
.Nm
utility retrieves or sets
.Xr audio 4
driver variables.
The options are as follows:
.Bl -tag -width Ds
.It Fl f Ar file
Specifies the audio control device or the audio device.
The default is
.Pa /dev/audioctl0 .
.It Fl n
Suppress printing of the variable name.
.It Fl q
Suppress all output when setting a variable.
.It Fl w Ar wait
Display variables every
.Ar wait
seconds.
.Nm
will continue to display variables until interrupted.
.It Ar name Ns Op = Ns Ar value
Retrieve the specified variable
.Ar name ,
or attempt to set it to value.
Multiple
.Ar name Ns Op = Ns Ar value
arguments may be given.
.El
.Pp
If the audio control device is used, then values are only stored in the
.Xr audio 4
driver; they will be submitted to the hardware the next time the
device is opened for playback or recording.
If the audio device is used instead of the control device,
then values are negotiated with the hardware immediately; this requires
exclusive access to the device.
Variables may only be changed if the device is not opened for
playback or recording by another process.
.Pp
The following variable names are available:
.Bl -column "record.channels" -offset indent
.It Sy Name Ta Sy Meaning
.It name Ta device name, as shown by
.Xr dmesg 8
.It mode Ta current device mode (
.Va play ,
.Va record ,
or both)
.It pause Ta set if not attempting to start
.It active Ta set if playing or recording
.It nblks Ta number of blocks (in frames) in the play buffer
.It blksz Ta number of frames per block
.It rate Ta sample rate in Hz
.It encoding Ta current sample format
.It play.channels Ta number of play channels
.It play.bytes Ta bytes played since playback started
.It play.errors Ta bytes inserted during underruns
.It record.channels Ta number of recording channels
.It record.bytes Ta bytes recorded since device started
.It record.errors Ta bytes dropped during overruns
.El
.Pp
Encoding names use the following scheme: signedness
.Po
.Va s
or
.Va u
.Pc
followed
by the precision in bits, the byte-order
.Po
.Va le
or
.Va be
.Pc ,
the number of
bytes per sample, and the alignment
.Po
.Va msb
or
.Va lsb
.Pc .
Only the signedness and the precision are mandatory.
Examples:
.Va u8 , s16le , s24le3 , s24le4lsb .
.Sh FILES
.Bl -tag -width /dev/audioctl0 -compact
.It Pa /dev/audioctlN
audio control devices
.It Pa /dev/audioN
audio devices
.El
.Sh EXAMPLES
Once per second, display the number of bytes of silence inserted due to buffer
underruns (since the device started playback):
.Bd -literal -offset indent
# audioctl -w 1 play.errors
.Ed
.Pp
Use signed 24-bit samples and 44100Hz sample rate:
.Bd -literal -offset indent
# audioctl -f /dev/audio0 encoding=s24 rate=44100
.Ed
.Pp
Note the use of
.Pa /dev/audio0
to force negotiation with the hardware.
If the above parameters are not supported by the
hardware, then supported ones will be selected instead.
.Sh SEE ALSO
.Xr aucat 1 ,
.Xr cdio 1 ,
.Xr audio 4 ,
.Xr mixerctl 8 ,
.Xr sysctl 8
.Sh HISTORY
The
.Nm
command first appeared in
.Nx 1.3 .