Module Name: src
Committed By: nat
Date: Mon Dec 12 11:49:27 UTC 2016
Modified Files:
src/share/man/man4: audio.4
Log Message:
Update audio man page with regard to audio changes.
OK wiz@
To generate a diff of this commit:
cvs rdiff -u -r1.72 -r1.73 src/share/man/man4/audio.4
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man4/audio.4
diff -u src/share/man/man4/audio.4:1.72 src/share/man/man4/audio.4:1.73
--- src/share/man/man4/audio.4:1.72 Tue Sep 6 01:17:48 2011
+++ src/share/man/man4/audio.4 Mon Dec 12 11:49:27 2016
@@ -1,4 +1,4 @@
-.\" $NetBSD: audio.4,v 1.72 2011/09/06 01:17:48 jmcneill Exp $
+.\" $NetBSD: audio.4,v 1.73 2016/12/12 11:49:27 nat Exp $
.\"
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,7 +27,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd September 5, 2011
+.Dd December 11, 2016
.Dt AUDIO 4
.Os
.Sh NAME
@@ -67,11 +67,16 @@ operations as
.Pa /dev/sound ,
but no other operations.
.Pp
-In contrast to
.Pa /dev/sound
-which has the exclusive open property
+and
+.Pa /dev/audio
+can be opened at
+.Em any
+time and audio sources of different precision and playback
+parameters i.e frequency will be mixed and played back simultaneously.
+.Pp
.Pa /dev/audioctl
-can be opened at any time and can be used to manipulate the audio device
+can be used to manipulate the audio device
while it is in use.
.Sh SAMPLING DEVICES
When
@@ -84,16 +89,67 @@ recording (playing) unpaused and playing
When
.Pa /dev/sound
is opened, it maintains the previous audio sample mode and
-record/playback mode.
+record/playback mode most recently set on
+.Pa /dev/sound
+by any open channel.
In all other respects
.Pa /dev/audio
and
.Pa /dev/sound
are identical.
+.Sh VIRTUAL CHANNELS
+Any process may open a sampling device at a given time.
+There is a constraint of
+.Em one
+device per process and file descriptors may
+.Em not
+be shared between processes.
+.Pp
+Virtual channels are converted to a common format, signed linear encoding,
+frequency channels and precision.
+These can be modified to taste by the following
+.Xr sysctl 8
+variables.
+.Pp
+.Bl -tag -width -compact
+.It hw.driverN.precision
+.It hw.driverN.frequency
+.It hw.driverN.channels
+.It hw.driverN.saturate
+.El
.Pp
-Only one process may hold open a sampling device at a given time
-(although file descriptors may be shared between processes once the
-first open completes).
+Where
+.Em driverN
+corresponds to the underlying audio device driver and device number.
+e.g In the case of an hdafg supported device the variables would be:
+hw.hdafg0.channels, hw.hdafg0.precision, hw.hdafg0.frequency.
+.Pp
+For best results, values close to the underlying hardware should be chosen.
+These variables may only be changed when the sampling device is not in use.
+.Pp
+An additional
+.Xr sysctl 8
+variable controls how the samples are combined, hw.driverN.saturate.
+.Pp
+By default it is set to true.
+This means that volumes are not adjusted for each channel to be mixed.
+All virtual channels will use the
+.Em maximum
+set master volume unless the virtual channel volume is lowered by the user.
+.Pp
+If set to false the channels are
+.Em divided
+evenly in volume with respect to the master volume.
+.Pp
+Each virtual channel has a corresponding mixer:
+.Bl -tag -width -compact
+.It outputs.dacN Output volume
+.It inputs.micN Recording volume
+.El
+.Pp
+Where N is the virtual channel number.
+e.g ouputs.dac0 controlling playback volume and outputs.mic0 controlling
+recording volume for the first virtual channel.
.Pp
On a half-duplex device, writes while recording is in progress will be
immediately discarded.
@@ -177,6 +233,17 @@ The following
commands are supported on the sample devices:
.Pp
.Bl -tag -width indent
+.It Dv AUDIO_SETPROC (struct audio_pid)
+This command will select the audio device opened by pid.
+.Bd -literal
+struct audio_pid {
+ pid_t pid;
+ lwpid_t lwpid;
+};
+.Ed
+.Pp
+Currently the lpwid value is
+.Em ignored .
.It Dv AUDIO_FLUSH
This command stops all playback and recording, clears all queued
buffers, resets error counters, and restarts recording and playback as
@@ -682,7 +749,8 @@ string values.
.Xr ioctl 2 ,
.Xr ossaudio 3 ,
.Xr midi 4 ,
-.Xr radio 4
+.Xr radio 4 ,
+.Xr sysctl 8
.Ss ISA bus
.Xr aria 4 ,
.Xr ess 4 ,
@@ -716,7 +784,8 @@ string values.
.Ss USB
.Xr uaudio 4
.Sh BUGS
-If the device is used in
.Xr mmap 2
-it is currently always mapped for writing (playing) due to
-VM system weirdness.
+currently does not work and should be avoided.
+.Sh HISTORY
+Support for virtual channels and mixing first appeared in
+.Nx 8.0 .
