Annotation of src/usr.bin/audioctl/audioctl.1, Revision 1.29
1.27 ratchov 1: .\" $OpenBSD: audioctl.1,v 1.26 2008/06/26 05:42:20 ray Exp $
1.4 provos 2: .\" $NetBSD: audioctl.1,v 1.7 1998/04/27 16:55:23 augustss Exp $
1.1 provos 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
1.7 aaron 20: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
1.1 provos 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.27 ratchov 29: .Dd $Mdocdate: June 26 2008 $
1.1 provos 30: .Dt AUDIOCTL 1
31: .Os
32: .Sh NAME
33: .Nm audioctl
1.29 ! ratchov 34: .Nd get or set audio driver variables
1.1 provos 35: .Sh SYNOPSIS
1.6 aaron 36: .Nm audioctl
1.14 pvalchev 37: .Op Fl f Ar file
1.6 aaron 38: .Nm audioctl
1.22 sobrado 39: .Op Fl n
1.14 pvalchev 40: .Op Fl f Ar file
1.21 sobrado 41: .Ar name ...
1.6 aaron 42: .Nm audioctl
1.29 ! ratchov 43: .Op Fl nq
1.14 pvalchev 44: .Op Fl f Ar file
1.21 sobrado 45: .Ar name Ns = Ns Ar value ...
1.1 provos 46: .Sh DESCRIPTION
1.7 aaron 47: The
1.1 provos 48: .Nm
1.29 ! ratchov 49: utility retrieves or sets
! 50: .Xr audio 4
! 51: driver variables.
1.8 aaron 52: The options are as follows:
1.29 ! ratchov 53: .Bl -tag -width Ds
1.19 jmc 54: .It Fl f Ar file
1.29 ! ratchov 55: Specifies the audio control device or the audio device.
! 56: The default is
! 57: .Pa /dev/audioctl0 .
1.19 jmc 58: .It Fl n
59: Suppress printing of the variable name.
1.29 ! ratchov 60: .It Fl q
! 61: Suppress all output when setting a variable.
1.19 jmc 62: .It Ar name Ns = Ns Ar value
1.8 aaron 63: Attempt to set the specified variable
64: .Ar name
65: to
66: .Ar value .
67: .El
1.28 ratchov 68: .Pp
1.29 ! ratchov 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.
1.28 ratchov 76: Variables may only be changed if the device is not opened for
77: playback or recording by another process.
1.29 ! ratchov 78: .Pp
! 79: The following variable names are available:
! 80: .Bl -column "record.channels"
! 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
1.15 jmc 100: .El
1.29 ! ratchov 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 .
1.15 jmc 125: .Sh FILES
1.29 ! ratchov 126: .Bl -tag -width /dev/audioctl0
! 127: .It Pa /dev/audioctlN
! 128: audio control devices
! 129: .It Pa /dev/audioN
! 130: audio devices
1.15 jmc 131: .El
1.1 provos 132: .Sh EXAMPLES
1.29 ! ratchov 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
1.8 aaron 143: .Pp
1.29 ! ratchov 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.
1.1 provos 149: .Sh SEE ALSO
1.19 jmc 150: .Xr aucat 1 ,
151: .Xr cdio 1 ,
1.1 provos 152: .Xr mixerctl 1 ,
153: .Xr audio 4 ,
154: .Xr sysctl 8
155: .Sh HISTORY
156: The
157: .Nm
158: command first appeared in
159: .Nx 1.3 .