ref: 6e9b8e645c80f5ebad268920d980d04fa482bf53
parent: d97addd9e939eeef156551e1fd36649192b7bca4
author: robs <robs>
date: Sat May 5 10:21:13 EDT 2007
Updates mainly for compander
--- a/soxeffect.7
+++ b/soxeffect.7
@@ -33,8 +33,9 @@
.SH NAME
SoX \- Sound eXchange, the Swiss Army knife of audio manipulation
.SH DESCRIPTION
+.SS SOX EFFECTS
Multiple effects may be applied to the audio by specifying them
-one after another at the end of the command line.
+one after another at the end of the SoX command line.
.SP
.I Note:
Brackets [ ] are used to denote parameters that are optional, braces
@@ -164,37 +165,64 @@
.br
[\fIgain\fR [\fIinitial-volume-dB\fR [\fIdelay\fR]]]
.SP
-Compand (compress or expand) the dynamic range of the audio. The
-attack and decay time specify the integration time over which the
-absolute value of the input signal is integrated to determine its
+Compand (compress or expand) the dynamic range of the audio.
+.SP
+The
+.I attack
+and
+.I decay
+parameters (in seconds) determine the time over which the
+instantaneous level of the input signal is averaged to determine its
volume; attacks refer to increases in volume and decays refer to
decreases. Where more than one pair of attack/decay parameters are
-specified, each channel is treated separately and the number of pairs
-must agree with the number of input channels. The second parameter is
-a list of points on the compander's transfer function specified in dB
-relative to the maximum possible signal amplitude. The input values
-must be in a strictly increasing order but the transfer function does
-not have to be monotonically rising. The special value \fB\-inf\fR may
-be used to indicate that the input volume should be associated output
-volume. The points \fB\-inf,\-inf\fR and \fB0,0\fR are assumed; the
-latter may be overridden, but the former may not.
+specified, each input channel is companded separately and the number of
+pairs must agree with the number of input channels.
+Typical values are
+.B 0\*d3,0\*d8
+seconds.
.SP
-The third
-(optional) parameter is a post-processing gain in dB which is applied
-after the compression has taken place; the fourth (optional) parameter
-is an initial volume to be assumed for each channel when the effect
-starts. This permits the user to supply a nominal level initially, so
-that, for example, a very large gain is not applied to initial signal
-levels before the companding action has begun to operate: it is quite
-probable that in such an event, the output would be severely clipped
-while the compander gain properly adjusts itself.
+The second parameter is a list of points on the compander's transfer
+function specified in dB relative to the maximum possible signal
+amplitude. The input values must be in a strictly increasing order but
+the transfer function does not have to be monotonically rising. If
+omitted, the value of
+.I out-dB1
+defaults to the same value as
+.IR in-dB1 ;
+levels below
+.I in-dB1
+are not companded (but may have gain applied to them).
+The point \fB0,0\fR is assumed but may be overridden (by
+\fB0,\fIout-dBn\fR).
+If the list is preceded by a
+.I soft-knee-dB
+value, then the points at where adjacent line segments on the
+transfer function meet will be rounded by the amout given.
+Typical values for the transfer function are
+.BR 6:\-70,\-60,\-20 .
.SP
-The fifth (optional) parameter is a delay in seconds.
-The input signal is analysed immediately to control the compander, but
-it is delayed before being fed to the volume adjuster.
-Specifying a delay approximately equal to the attack/decay times
-allows the compander to effectively operate in a `predictive' rather than a
-reactive mode.
+The third (optional) parameter is an additional gain in dB to be applied
+at all points on the transfer function and allows easy adjustment
+of the overall gain.
+.SP
+The fourth (optional) parameter is an initial level to be assumed for
+each channel when companding starts. This permits the user to supply a
+nominal level initially, so that, for example, a very large gain is not
+applied to initial signal levels before the companding action has begun
+to operate: it is quite probable that in such an event, the output would
+be severely clipped while the compander gain properly adjusts itself.
+A typical value (for audio which is initially quiet) is
+.B \-90
+dB.
+.SP
+The fifth (optional) parameter is a delay in seconds. The input signal
+is analysed immediately to control the compander, but it is delayed
+before being fed to the volume adjuster. Specifying a delay
+approximately equal to the attack/decay times allows the compander to
+effectively operate in a `predictive' rather than a reactive mode.
+A typical value is
+.B 0\*d2
+seconds.
.SP
This effect supports the \fB\-\-plot\fR global option (for the transfer function).
.SP
--- a/soxexam.7
+++ b/soxexam.7
@@ -15,11 +15,23 @@
.ds RA \(->
'\"
'\" Decimal point set slightly raised
-.ds d \v'-.15m'.\v'+.15m'
+.if t .ds d \v'-.15m'.\v'+.15m'
+.if n .ds d .
'\"
+'\" Enclosure macro for examples
+.de EX
+.SP
+.nf
+.ft CW
+..
+.de EE
+.ft R
+.SP
+.fi
+..
.TH SoX 7 "January 31, 2007" "soxexam" "Sound eXchange"
.SH NAME
-soxexam\*mSoX Examples
+SoX \- Sound eXchange, the Swiss Army knife of audio manipulation
.SH EXAMPLES
.SS Introduction
The core problem is that you need some experience in using effects
@@ -250,59 +262,58 @@
play file.xxx phaser 0\*d6 0\*d66 3 0\*d6 2 \-t
.SS Compander
The compander effect allows the dynamic range of a signal to be
-compressed or expanded.
+compressed or expanded. It works by calculating the input signal level
+averaged over time according to the given attack and decay parameters,
+and setting the output signal level according to the given
+transfer-function parameters.
+.SP
For most situations, the attack time (response to the music getting
louder) should be shorter than the decay time because our ears are more
sensitive to suddenly loud music than to suddenly soft music.
.SP
For example, suppose you are listening to Strauss's `Also Sprach
-Zarathustra' in a noisy environment such as a car.
+Zarathustra' in a noisy environment such as a moving vehicle.
If you turn up the volume enough to hear the soft passages over the
road noise, the loud sections will be too loud.
-You could try this:
-.SP
- play file.xxx compand 0\*d3,1 \-90,\-90,\-70,\-70,\-60,\-20,0,0 \-5 0 0\*d2
-.SP
-The transfer function (`\-90,...') says that
-.I very
-soft sounds between \-90 and \-70 decibels (\-90 is about the limit of
-16-bit encoding) will remain unchanged.
-That keeps the compander from boosting the volume on `silent' passages
-such as between movements.
-However, sounds in the range \-60 decibels to 0 decibels (maximum
+So you could try this:
+.EX
+ sox asz.flac asz-car.flac compand 0.3,1 6:-70,-60,-20 -5 -90 0.2
+.EE
+The transfer function (`6:\-70,...') says that very soft sounds (below
+\-70dB) will remain unchanged. This will stop the compander from
+boosting the volume on `silent' passages such as between movements.
+However, sounds in the range \-60dB to 0dB (maximum
volume) will be boosted so that the 60dB dynamic range of the
original music will be compressed 3-to-1 into a 20dB range, which is
wide enough to enjoy the music but narrow enough to get around the
-road noise.
-The \-5 dB output gain is needed to avoid clipping (the number is
+road noise. The `6:' selects 6dB soft-knee companding.
+The \-5 (dB) output gain is needed to avoid clipping (the number is
inexact, and was derived by experimentation).
-The 0 for the initial volume will work fine for a clip that starts
-with a bit of silence, and the delay of 0\*d2 has the effect of causing
+The \-90 (dB) for the initial volume will work fine for a clip that starts
+with near silence, and the delay of 0\*d2 (seconds) has the effect of causing
the compander to react a bit more quickly to sudden volume changes.
.SP
+In order to visualise the transfer function, SoX can be invoked with the
+.B \-\-plot
+option, e.g.
+.EX
+ sox -n -n --plot gnuplot compand 0,0 6:-70,-60,-20 -5 > my.plt
+ gnuplot my.plt
+.EE
The following (one long) command shows how multi-band companding is
typically used in FM radio:
-.SP
- play file.xxx
-.br
- vol \-3 db filter 8000\- 32 100 mcompand \(dq0\*d005,0\*d1
-.br
- \-47,\-40,\-34,\-34,\-17,\-33 0 0 0\(dq 100 \(dq0\*d003,0\*d05
-.br
- \-47,\-40,\-34,\-34,\-17,\-33 0 0 0\(dq 400 \(dq0\*d000625,0\*d0125
-.br
- \-47,\-40,\-34,\-34,\-15,\-33 0 0 0\(dq 1600 \(dq0\*d0001,0\*d025
-.br
- \-47,\-40,\-34,\-34,\-31,\-31,\-0,\-30 0 0 0\(dq 6400
-.br
- \(dq0,0\*d025 \-38,\-31,\-28,\-28,\-0,\-25 0 0 0\(dq vol 27 db vol \-12
-.br
- db highpass 22 highpass 22 filter \-17500 256 vol +12 db
-.br
- vol \-3 db lowp 17801
-.SP
+.EX
+ play file.xxx vol -3dB filter 8000- 32 100 mcompand \\
+ \(dq0.005,0.1 -47,-40,-34,-34,-17,-33\(dq 100 \\
+ \(dq0.003,0.05 -47,-40,-34,-34,-17,-33\(dq 400 \\
+ \(dq0.000625,0.0125 -47,-40,-34,-34,-15,-33\(dq 1600 \\
+ \(dq0.0001,0.025 -47,-40,-34,-34,-31,-31,-0,-30\(dq 6400 \\
+ \(dq0,0.025 -38,-31,-28,-28,-0,-25\(dq \\
+ vol 15dB highpass 22 highpass 22 filter -17500 256 \\
+ vol 9dB lowpass -1 17801
+.EE
The audio file is played with a simulated FM radio sound (or broadcast
-signal condition if the lowp at the end is skipped).
+signal condition if the lowpass filter at the end is skipped).
Note that the pipeline is set up with US-style 75us preemphasis.
.SS Changing the Rate of Playback
You can use stretch to change the rate of playback of an audio sample
@@ -357,8 +368,7 @@
The scripting language shown is `Bourne shell' (sh) but it should be
simple to translate this to another scripting language if you do not
have access to sh.
-.nf
-
+.EX
# Make sure we append to a file that's initially empty:
rm \-f 2tones.raw
@@ -378,11 +388,10 @@
done
# Add a file header and save some disc space:
-sox \-sw \-c1 \-r8000 alert.raw alert.ogg
+sox \-s2 \-c1 \-r8000 alert.raw alert.ogg
play alert.ogg
-
-.fi
+.EE
If you try out the above script, you may want to hit Ctrl-C fairly soon
after the alert tone starts playing\*mit's not a pleasant sound! The
.B synth