Module Name: src
Committed By: nia
Date: Sun Mar 21 10:50:08 UTC 2021
Modified Files:
src/usr.bin/audio/ctl: audioctl.1
Log Message:
audioctl.1: describe foibles
To generate a diff of this commit:
cvs rdiff -u -r1.23 -r1.24 src/usr.bin/audio/ctl/audioctl.1
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/usr.bin/audio/ctl/audioctl.1
diff -u src/usr.bin/audio/ctl/audioctl.1:1.23 src/usr.bin/audio/ctl/audioctl.1:1.24
--- src/usr.bin/audio/ctl/audioctl.1:1.23 Thu May 9 09:37:11 2019
+++ src/usr.bin/audio/ctl/audioctl.1 Sun Mar 21 10:50:08 2021
@@ -1,4 +1,4 @@
-.\" $NetBSD: audioctl.1,v 1.23 2019/05/09 09:37:11 wiz Exp $
+.\" $NetBSD: audioctl.1,v 1.24 2021/03/21 10:50:08 nia Exp $
.\"
.\" Copyright (c) 1997, 1999 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -26,12 +26,12 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd May 8, 2019
+.Dd March 21, 2021
.Dt AUDIOCTL 1
.Os
.Sh NAME
.Nm audioctl
-.Nd control audio device
+.Nd control software audio format
.Sh SYNOPSIS
.Nm
.Op Fl n
@@ -49,7 +49,26 @@
.Sh DESCRIPTION
The
.Nm
-command displays or sets various audio system driver variables.
+command displays or sets the paramaters that determine the playback and
+recording format for software using a audio device.
+It is most useful when the full
+.Xr audio 4
+API is not available, e.g. when playing or recording raw audio data from a
+.Xr sh 1
+script, or from the command line.
+It does not control the underlying hardware format, which can be
+changed with
+.Xr audiocfg 1 .
+.Pp
+The variables that can be inspected and changed with
+.Nm
+are normally per-application and are reset when a
+.Pa /dev/audioX
+device is opened.
+This can be circumvented by using
+.Pa /dev/soundX
+instead, which retains global state.
+.Pp
If a list of variables is present on the command line, then
.Nm
prints the current value of those variables for the specified device.
@@ -77,32 +96,23 @@ the audio control device to use.
.El
.Sh FILES
.Bl -tag -width /dev/audioctl0 -compact
-.It Pa /dev/audio0
-audio I/O device (resets on open)
+.It Pa /dev/sound0
+audio I/O device
.It Pa /dev/audioctl0
audio control device
-.It Pa /dev/sound0
-audio I/O device (does not reset on open)
.El
.Sh EXAMPLES
To set the playing sampling rate to 11025, you can use
.Dl audioctl -w play.sample_rate=11025
To set all of the play parameters for CD-quality audio, you can use
.Dl audioctl -w play=44100,2,16,slinear_le
-Note that many of the variables that can be inspected and changed with
-.Nm
-are reset when
-.Pa /dev/audio0
-is opened.
-This can be circumvented by using
-.Pa /dev/sound0
-instead.
.Sh COMPATIBILITY
The old
.Fl f
flag is still supported.
This support will be removed eventually.
.Sh SEE ALSO
+.Xr audiocfg 1 ,
.Xr audioplay 1 ,
.Xr audiorecord 1 ,
.Xr mixerctl 1 ,
@@ -113,3 +123,21 @@ The
.Nm
command first appeared in
.Nx 1.3 .
+.Sh CAVEATS
+Since the parameters controlled by
+.Nm
+are global, they can be changed unexpectedly if another application
+uses the same audio device.
+.Pp
+It is always preferable to use
+.Dv AUDIO_SETINFO
+on a per-process
+.Pa /dev/audioX
+device, if the
+.Xr audio 4
+ioctls are available in the programming environment.
+Similarly,
+.Xr audioplay 1
+and
+.Xr audiorecord 1
+are more safe for use in scripting.
