[src/netbsd-9]: src/share/man/man4 Pull up following revision(s) (requested b...

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

details:   https://anonhg.NetBSD.org/src/rev/0d2f0e2fa477
branches:  netbsd-9
changeset: 953268:0d2f0e2fa477
user:      martin <martin%NetBSD.org@localhost>
date:      Tue Mar 02 15:57:06 2021 +0000

description:
Pull up following revision(s) (requested by nia in ticket #1220):

        share/man/man4/pad.4: revision 1.7
        share/man/man4/pad.4: revision 1.8
        share/man/man4/pad.4: revision 1.9
        share/man/man4/pad.4: revision 1.10

Use /dev/audioX rather than /dev/soundX in examples.

Avoids accidentally running into confusing behavior.
Add another example of recording the output of an application.

Explain something that confused me.

Slightly adjust wording.

It does seem to work with multiple applications concurrently writing to
the device in a quick test I did.

Explain the format of the raw PCM data users can read from a pad(4).

Since it's headerless this is important so the data can be interpreted
properly. Also, ordinary audio ioctls cannot be used on a pad and the
format can't be changed, so applications that attempt to automatically
determine the format of a device like audiorecord don't work.

diffstat:

 share/man/man4/pad.4 |  28 +++++++++++++++++++++-------
 1 files changed, 21 insertions(+), 7 deletions(-)

diffs (65 lines):

diff -r 6c8bbb94a472 -r 0d2f0e2fa477 share/man/man4/pad.4
--- a/share/man/man4/pad.4      Mon Mar 01 16:01:06 2021 +0000
+++ b/share/man/man4/pad.4      Tue Mar 02 15:57:06 2021 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: pad.4,v 1.6 2017/07/03 21:30:58 wiz Exp $
+.\" $NetBSD: pad.4,v 1.6.8.1 2021/03/02 15:57:06 martin Exp $
 .\"
 .\" Copyright (c) 2007 Jared D. McNeill <jmcneill%invisible.ca@localhost>
 .\" All rights reserved.
@@ -24,7 +24,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 11, 2007
+.Dd February 6, 2021
 .Dt PAD 4
 .Os
 .Sh NAME
@@ -36,19 +36,27 @@
 .Sh DESCRIPTION
 .Nm
 is a pseudo-device driver which provides support for feeding back PCM data
-from a consumer of the
+from consumers of an
 .Xr audio 4
-API to userland.
+device to userland.
+.Pp
+The raw PCM data readable from
+.Pa /dev/padN
+is encoded in stereo little-endian 16-bit linear PCM at 44100 Hz.
 .Sh FILES
 The
 .Nm
 pseudo-device driver receives data from
-.Pa /dev/soundN
+.Pa /dev/audioN
 and feeds the raw PCM output to
 .Pa /dev/padN .
+.Pa /dev/audioN
+is created once
+.Pa /dev/padN
+is opened.
 .Bl -item
 .It
-.Pa /dev/soundN
+.Pa /dev/audioN
 .It
 .Pa /dev/padN
 .El
@@ -56,7 +64,13 @@
 The following example streams an MP3 to an Apple AirTunes compatible device:
 .Bd -literal -offset indent
 $ rtunes - < /dev/pad0 &
-$ mpg123 -a /dev/sound1 mozart.mp3
+$ mpg123 -a /dev/audio1 mozart.mp3
+.Ed
+.Pp
+Record the output of an application (in this case, audioplay):
+.Bd -literal -offset indent
+$ ffmpeg -f s16le -ar 44100 -ac 2 -i /dev/pad0 output.wav
+$ audioplay -d /dev/audio1 input.wav
 .Ed
 .Sh SEE ALSO
 .Xr audio 4