ref: 3ede00030f8d5d8dbfbdb52ddab02ef0de0ed7c2
parent: 556f4b5081288f19f89873b5a8353151b1ab4498
author: cbagwell <cbagwell>
date: Mon Jul 24 18:01:16 EDT 2000
Updated descriptions of resample effects.
--- a/sox.1
+++ b/sox.1
@@ -9,7 +9,7 @@
.if t .sp .5v
.if n .sp
..
-.TH SoX 1 "December 10, 1999"
+.TH SoX 1 "July 24, 2000"
.SH NAME
sox \- Sound eXchange : universal sound sample translator
.SH SYNOPSIS
@@ -103,7 +103,7 @@
.br
\fBrate
.br
- resample
+ resample [ \fI-qs\fB | \fI-q\fB | \fI-ql\fB ] [ \fIrolloff\fB [ \fIbeta\fB ] ]\fR
.br
reverb \fIgain-out reverb-time delay\fB [ \fIdelay ... \fB]
.br
@@ -180,11 +180,11 @@
.PP
Format options:
.PP
-Format options effect the audio samples that they immediately percede. If
+Format options effect the audio samples that they immediately precede. If
they are placed before the input file name then they effect the input
data. If they are placed before the output file name then they will
effect the output data. By taking advantage of this, you can override
-a input file's currupted header or produce an output file that is totally
+a input file's corrupted header or produce an output file that is totally
different style then the input file.
.TP 10
\fB-t\fI filetype
@@ -233,7 +233,7 @@
The number of sound channels in the data file.
This may be 1, 2, or 4; for mono, stereo, or quad sound data. To cause
the output file to have a different number of channels than the input
-file, include this option with the approraite value with the output
+file, include this option with the appropriate value with the output
file options.
If the input and output file have a different number of channels then the
avg effect must be used. If the avg effect is not specified on the
@@ -274,11 +274,11 @@
.SH FILE TYPES
.I SoX
uses the file extension of the input and output file to determine what
-type of file format to use. This can be overriden by specifying the
+type of file format to use. This can be overridden by specifying the
"-t" option on the command line.
.P
The input and output files may be read from standard in and out. This
-is done by specifing '-' as the filename.
+is done by specifying '-' as the filename.
.P
File formats which have headers are checked,
if that header doesn't seem right,
@@ -398,7 +398,7 @@
.B .sf
IRCAM Sound Files.
.br
-SoundFiles are used by academic music software
+Sound Files are used by academic music software
such as the CSound package, and the MixView sound sample editor.
.TP 10
.B .smp
@@ -686,10 +686,10 @@
.TP 10
pan \fIdirection\fB
Pan the sound of an audio file from one channel to another. This is done by
-changing the volume of the input channels so that it fade's out on one
+changing the volume of the input channels so that it fades out on one
channel and fades-in on another. If the number of input channels is
different then the number of output channels then this effect tries to
-intellegently handle this. For instance, if the input contains 1 channel
+intelligently handle this. For instance, if the input contains 1 channel
and the output contains 2 channels, then it will create the missing channel
itself. The
.I direction
@@ -734,10 +734,12 @@
interpolation, a DSP algorithm. This method is slow and uses lots
of RAM, but gives much better results than
.B rate.
+
.br
-w < nut / ham > : select either a Nuttal (~90 dB stopband) or Hamming
(~43 dB stopband) window. Default is
.I nut.
+
.br
-width long / short / # : specify the (approximate) width of the filter.
.I long
@@ -750,9 +752,13 @@
option is
.B not
recommended, as it produces poor quality results.
+
.br
-cutoff # : specify the filter cutoff frequency in terms of fraction of
-bandwidth. If upsampling, then this is the fraction of the original signal
+bandwidth, also know as the Nyquist frequency. Please see
+the \fIresample\fR effect for
+further information on Nyquist frequency. If upsampling, then this is the
+fraction of the original signal
that should go through. If downsampling, this is the fraction of the
signal left after downsampling. Default is 0.95. Remember that
this is a float.
@@ -768,17 +774,14 @@
This is fast but noisy:
the spectrum of the original sound will be shifted upwards
and duplicated faintly when up-translating by a multiple.
+
Lerp-ing is acceptable for cheap 8-bit sound hardware,
but for CD-quality sound you should instead use either
.B resample
or
.B polyphase.
-If you are wondering which of
-.B SoX's
-rate changing effects to use, you will want to read a
+If you are wondering which rate changing effects to use, you will want to read a
detailed analysis of all of them at http://eakaw2.et.tu-dresden.de/~wilde/resample/resample.html
-[Nov,1999: These tests need to be updated for sox-12.17, which has bugfixes to the
-resample and polyphase code.]
.TP 10
resample [ \fI-qs\fB | \fI-q\fB | \fI-ql\fB ] [ \fIrolloff\fB [ \fIbeta\fB ] ]\fR
Translate input sampling rate to output sampling rate
@@ -787,19 +790,24 @@
.B rate,
but gives much better results.
-The \fI-qs\fR, \fI-q\fR, or \fI-ql\fR options specify increased accuracy
-at the cost of lower execution speed. By default, linear interpolation
-is used, with a window width about 45 samples at the lower rate.
+By default, linear interpolation is used,
+with a window width about 45 samples at the lower of the two rate.
This gives an accuracy of about 16 bits, but insufficient stopband rejection
in the case that you want to have rolloff greater than about 0.80 of
the Nyquist frequency.
-The \fI-q*\fR options use quadratic interpolation of filter
+
+The \fI-q*\fR options will change the default values for rolloff and beta
+as well as use quadratic interpolation of filter
coefficients, resulting in about 24 bits precision.
-.br
+The \fI-qs\fR, \fI-q\fR, or \fI-ql\fR options specify increased accuracy
+at the cost of lower execution speed. It is optional to specify
+rolloff and beta parameters when using the \fI-q*\fR options.
+
Following is a table of the reasonable defaults which are built-in to sox:
+
.br
\fBOption Window rolloff beta interpolation\fR
-.br
+.br
\fB------ ------ ------- ---- -------------\fR
.br
(none) 45 0.80 16 linear
@@ -811,8 +819,7 @@
-ql 149 0.94 16 quadratic
.br
\fB------ ------ ------- ---- -------------\fR
-.br
-.br
+
\fI-qs\fR, \fI-q\fR, or \fI-ql\fR use window lengths of 45, 75, or 149
samples, respectively, at the lower sample-rate of the two files.
This means progressively sharper stop-band rejection, at proportionally
@@ -821,9 +828,22 @@
\fIrolloff\fR refers to the cut-off frequency of the
low pass filter and is given in terms of the
Nyquist frequency for the lower sample rate. rolloff therefore should
-be something between 0. and 1., in practice 0.8-0.95. The defaults are
+be something between 0.0 and 1.0, in practice 0.8-0.95. The defaults are
indicated above.
+The \fINyquist frequency\fR is 1/2 of the sample rate. This refers to the
+fact that an audio file can only represent frequencies up to 1/2 of the
+sample rate. Therefore, when reducing the sample rate of an audio file a
+filter will remove all frequency information above the new Nyquist frequency.
+The \fIrolloff\fR refers to how close to the Nyquist frequency this cutoff
+is, with closer being better. When increasing the sample rate of an
+audio file you would not expect to have any frequencies exist that are
+past the original Nyquist frequency. Because of filter properties, it
+is common to have false frequency data created that is above the old
+Nyquist frequency. In that case the \fIrolloff\fR refers to how close
+to the original Nyquist frequency to use a highpass filter to remove
+this false data, with closer also being better.
+
The \fIbeta\fR parameter
determines the type of filter window used. Any value greater than 2.0 is
the beta for a Kaiser window. Beta <= 2.0 selects a Nuttall window.
@@ -842,7 +862,7 @@
Default parameters are, as indicated above, Kaiser window of length 45,
rolloff 0.80, beta 16, linear interpolation.
-\fBNOTE: \fI-qs\fR is only slightly slower, but more accurate for
+\fBNOTE:\fR \fI-qs\fR is only slightly slower, but more accurate for
16-bit or higher precision.
\fBNOTE:\fR In many cases of up-sampling, no interpolation is needed,