aplay -- update the man file

Bring the man file up to date, documenting the signals and all the
options, including those added for audio surveilance.

Signed-off-by: John Sauter <John_Sauter@systemeyescomputerstore.com>
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

aplay/aplay.1

@@ -1,4 +1,4 @@
-.TH APLAY 1 "2 August 2001"
+.TH APLAY 1 "1 January 2010"
 .SH NAME
 arecord, aplay \- command-line sound recorder and player for ALSA 
 soundcard driver
@@ -46,6 +46,7 @@ If this parameter is omitted the WAVE format is used.
 \fI\-c, \-\-channels=#\fP
 The number of channels.
 The default is one channel.
+Valid values are 1 through 32.
 .TP
 \fI\-f \-\-format=FORMAT\fP
 Sample format
@@ -53,19 +54,23 @@ Sample format
 Recognized sample formats are: S8 U8 S16_LE S16_BE U16_LE U16_BE S24_LE
 S24_BE U24_LE U24_BE S32_LE S32_BE U32_LE U32_BE FLOAT_LE FLOAT_BE
 FLOAT64_LE FLOAT64_BE IEC958_SUBFRAME_LE IEC958_SUBFRAME_BE MU_LAW
-A_LAW IMA_ADPCM MPEG GSM
+A_LAW IMA_ADPCM MPEG GSM SPECIAL S24_3LE S24_3BE U24_3LE U24_3BE S20_3LE
+S20_3BE U20_3LE U20_3BE S18_3LE S18_3BE U18_3LE
 .br
 Some of these may not be available on selected hardware
 .br
-There are also two format shortcuts available:
+The available format shortcuts are:
 .nf
-\-f cd (16 bit little endian, 44100, stereo [\-f S16_LE \-c2 \-r44100]
+\-f cd (16 bit little endian, 44100, stereo) [\-f S16_LE \-c2 \-r44100]
+\-f cdr (16 bit big endian, 44100, stereo) [\-f S16_BE \-c2 \-f44100]
 \-f dat (16 bit little endian, 48000, stereo) [\-f S16_LE \-c2 \-r48000]
 .fi
 If no format is given U8 is used.
 .TP
 \fI\-r, \-\-rate=#<Hz>\fP
 Sampling rate in Hertz. The default rate is 8000 Hertz.
+If the value specified is less than 300, it is taken as the rate in kilohertz.
+Valid values are 2000 through 192000 Hertz.
 .TP
 \fI\-d, \-\-duration=#\fP
 Interrupt after # seconds.
@@ -120,10 +125,69 @@ The stereo VU-meter is available only for 2-channel stereo samples
 with interleaved format.
 .TP
 \fI\-I, \-\-separate\-channels\fP 
-One file for each channel
+One file for each channel.  This option disables max\-file\-time
+and use\-strftime, and ignores SIGUSR1.  The stereo VU meter is
+not available with separate channels.
+.TP
+\fI\-P\fP
+Playback.  This is the default if the program is invoked
+by typing aplay.
+.TP
+\fI\-C\fP
+Record.  This is the default if the program is invoked
+by typing arecord.
+.TP
+\fI\-\-disable\-resample\fP
+Disable automatic rate resample.
+.TP
+\fI\-\-disable\-channels\fP
+Disable automatic channel conversions.
+.TP
+\fI\-\-disable\-format\fP
+Disable automatic format conversions.
+.TP
+\fI\-\-disable\-softvol\fP
+Disable software volume control (softvol).
+.TP
+\fI\-\-test\-position\fP
+Test ring buffer position.
+.TP
+\fI\-\-test\-coef=<coef>\fP
+Test coefficient for ring buffer position; default is 8.
+Expression for validation is: coef * (buffer_size / 2).
+Minimum value is 1.
+.TP
+\fI\-\-test\-nowait\fP
+Do not wait for the ring buffer--eats the whole CPU.
+.TP
+\fI\-\-max\-file\-time\fP
+While recording, when the output file has been accumulating
+sound for this long,
+close it and open a new output file.  Default is the maximum
+size supported by the file format: 2 GiB for WAV files.
+This option has no effect if  \-\-separate\-channels is
+specified.
+.TP
+\fI\-\-process\-id\-file <file name>\fP
+aplay writes its process ID here, so other programs can
+send signals to it.
+.TP
+\fI\-\-use\-strftime\fP
+When recording, interpret %-codes in the file name parameter using
+the strftime facility whenever the output file is opened.  The
+important strftime codes are: %Y is the year, %m month, %d day of
+the month, %H hour, %M minute and %S second.  In addition, %v is
+the file number, starting at 1.  When this option is specified,
+intermediate directories for the output file are created automatically.
+This option has no effect if \-\-separate\-channels is specified.
 
-.SS
+.SH SIGNALS
-Example:
+When recording, SIGINT, SIGTERM and SIGABRT will close the output 
+file and exit.  SIGUSR1 will close the output file, open a new one,
+and continue recording.  However, SIGUSR1 does not work with
+\-\-separate\-channels.
+
+.SH EXAMPLES
 
 .TP
 \fBaplay \-c 1 \-t raw \-r 22050 \-f mu_law foobar\fR
@@ -144,6 +208,19 @@ pcm.copy {
 }
 .fi
 
+.TP
+\fBarecord \-t wav \-max-file_time 30 mon.wav\fP
+Record from the default audio source in monaural, 8,000 samples
+per second, 8 bits per sample.  Start a new file every
+30 seconds.  File names are mon-nn.wav, where nn increases
+from 01.  The file after mon-99.wav is mon-100.wav.
+
+.TP
+\fBarecord \-f cd \-t wav \-max-file-time 3600 --use-strftime %Y/%m/%d/listen-%H-%M-%v.wav\fP
+Record in stereo from the default audio source.  Create a new file
+every hour.  The files are placed in directories based on their start dates
+and have names which include their start times and file numbers.
+
 .SH SEE ALSO
 \fB
 alsamixer(1),