Annotation of src/usr.bin/audioctl/audioctl.8, Revision 1.1
1.1 ! deraadt 1: .\" $OpenBSD: audioctl.1,v 1.30 2016/06/21 07:55:21 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: June 21 2016 $
! 30: .Dt AUDIOCTL 1
! 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
! 47: The
! 48: .Nm
! 49: utility retrieves or sets
! 50: .Xr audio 4
! 51: driver variables.
! 52: The options are as follows:
! 53: .Bl -tag -width Ds
! 54: .It Fl f Ar file
! 55: Specifies the audio control device or the audio device.
! 56: The default is
! 57: .Pa /dev/audioctl0 .
! 58: .It Fl n
! 59: Suppress printing of the variable name.
! 60: .It Fl q
! 61: Suppress all output when setting a variable.
! 62: .It Ar name Ns = Ns Ar value
! 63: Attempt to set the specified variable
! 64: .Ar name
! 65: to
! 66: .Ar value .
! 67: .El
! 68: .Pp
! 69: If the audio control device is used, then values are only stored in the
! 70: .Xr audio 4
! 71: driver; they will be submitted to the hardware the next time the
! 72: device is opened for playback or recording.
! 73: If the audio device is used instead of the control device,
! 74: then values are negotiated with the hardware immediately; this requires
! 75: exclusive access to the device.
! 76: Variables may only be changed if the device is not opened for
! 77: playback or recording by another process.
! 78: .Pp
! 79: The 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 ,
! 87: or 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
! 102: Encoding names use the following scheme: signedness
! 103: .Po
! 104: .Va s
! 105: or
! 106: .Va u
! 107: .Pc
! 108: followed
! 109: by the precision in bits, the byte-order
! 110: .Po
! 111: .Va le
! 112: or
! 113: .Va be
! 114: .Pc ,
! 115: the number of
! 116: bytes per sample, and the alignment
! 117: .Po
! 118: .Va msb
! 119: or
! 120: .Va lsb
! 121: .Pc .
! 122: Only the signedness and the precision are mandatory.
! 123: Examples:
! 124: .Va u8 , s16le , s24le3 , s24le4lsb .
! 125: .Sh FILES
! 126: .Bl -tag -width /dev/audioctl0 -compact
! 127: .It Pa /dev/audioctlN
! 128: audio control devices
! 129: .It Pa /dev/audioN
! 130: audio devices
! 131: .El
! 132: .Sh EXAMPLES
! 133: Display the number of bytes of silence inserted during play buffer
! 134: underruns since device started:
! 135: .Bd -literal -offset indent
! 136: $ audioctl play.errors
! 137: .Ed
! 138: .Pp
! 139: Use 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
! 144: Note the use of
! 145: .Pa /dev/audio0
! 146: to force negotiation with the hardware.
! 147: If the above parameters are not supported by the
! 148: hardware, then supported ones will be selected instead.
! 149: .Sh SEE ALSO
! 150: .Xr aucat 1 ,
! 151: .Xr cdio 1 ,
! 152: .Xr mixerctl 8 ,
! 153: .Xr audio 4 ,
! 154: .Xr sysctl 8
! 155: .Sh HISTORY
! 156: The
! 157: .Nm
! 158: command first appeared in
! 159: .Nx 1.3 .