[src/trunk]: src/usr.bin/audio/ctl audioctl.1: describe foibles

[nia <nia%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/0968c76f4922
branches:  trunk
changeset: 953809:0968c76f4922
user:      nia <nia%NetBSD.org@localhost>
date:      Sun Mar 21 10:50:08 2021 +0000

description:
audioctl.1: describe foibles

diffstat:

 usr.bin/audio/ctl/audioctl.1 |  60 ++++++++++++++++++++++++++++++++-----------
 1 files changed, 44 insertions(+), 16 deletions(-)

diffs (110 lines):

diff -r 346d3630cba5 -r 0968c76f4922 usr.bin/audio/ctl/audioctl.1
--- a/usr.bin/audio/ctl/audioctl.1      Sun Mar 21 10:43:08 2021 +0000
+++ b/usr.bin/audio/ctl/audioctl.1      Sun Mar 21 10:50:08 2021 +0000
@@ -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 @@
 .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 @@
 .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.