ref: f8cde2c8f5430871ab298912da46e5da14215f4c
parent: 4018ddfbd16b7c53a8fb5a6f4d65b6c2665d74de
author: robs <robs>
date: Sat Apr 11 09:53:40 EDT 2009
doc updates
--- a/libsox.3
+++ b/libsox.3
@@ -188,27 +188,29 @@
.SH ERRORS
TODO
.SH INTERNALS
-SoX's formats and effects operate on an internal buffer format of
-signed 32-bit longs. The data processing routines are called with
+SoX's formats and effects operate with an internal sample format of
+signed 32-bit integer. The data processing routines are called with
buffers of these samples, and buffer sizes which refer to the number
-of samples processed, not the number of bytes. File readers translate
+of samples processed, not the number of bytes. File readers translate
the input samples to signed 32-bit integers and return the number of
-samples read. For example, data in linear signed byte format is
+samples read. For example, data in linear signed byte format is
left-shifted 24 bits.
.P
-This does cause problems in processing the data.
-For example:
-.br
+Representing samples as integers can cause problems when processing the audio.
+For example, if an effect to
+mix down left and right channels into one monophonic channel
+were to use the line
+.EX
*obuf++ = (*ibuf++ + *ibuf++)/2;
-.br
-would
-.I not
-mix down left and right channels into one monophonic channel,
-because the resulting samples would overflow 32 bits.
-Instead, the ``avg'' effects must use:
-.br
+.EE
+distortion might occur since
+the intermediate addition can overflow 32 bits.
+The line
+.EX
*obuf++ = *ibuf++/2 + *ibuf++/2;
-.br
+.EE
+would get round the overflow problem (at the expense of the least significant
+bit).
.P
Stereo data is stored with the left and right speaker data in
successive samples.
--- a/sox.1
+++ b/sox.1
@@ -1049,16 +1049,25 @@
.TP
\fB\-r, \fB\-\-rate\fR \fIRATE\fR[\fBk\fR]
Gives the sample rate in Hz (or kHz if appended with `k') of the file.
-To cause the output file to have
-a different sample rate than the input file, include this option with
-the output file format options.
-.SP
-If the input and output files have
-different rates then a sample rate change effect must be run. Since
-SoX has
-multiple rate changing effects, the user can specify which to use as an effect.
-If no rate change effect is specified then the \fBrate\fR effect will
-be chosen by default.
+For an input file, the most likely need for this option is for a `raw'
+audio file; for audio file types that store the sample rate value in
+the file header, this option is only needed in order to override
+the (presumably incorrect) value in the file header.
+For an output file, this option provides a shorthand for specifying
+that the
+.B rate
+effect should be invoked in order to change the sample rate of the
+audio signal before it is stored in the output file.
+For example, the following two commands are
+equivalent:
+.EX
+.ne 2
+ sox input.au -r 48k output.au bass -3
+ sox input.au output.au bass -3 rate 48k
+.EE
+though the second command is more flexible as it allows
+.B rate
+options to be given, and allows the effects to be ordered arbitrarily.
.TP
\fB\-t\fR, \fB\-\-type\fR \fIfile-type\fR
Gives the type of the audio file. This is useful when the