ref: 4eddd5b3f9425988478f6b5856364c5f61615795
parent: 012443916146c670f7f9a521c89a45d8b7ab0c7a
author: cbagwell <cbagwell>
date: Sat Mar 18 23:12:21 EST 2006
Updating silence effect docs.
--- a/sox.1
+++ b/sox.1
@@ -1200,15 +1200,59 @@
[ \fIbelow_periods duration
.TP 10
threshold\fR[ \fId\fR | \fI%\fR ]]
-Removes silence from the beginning or end of a sound file. Silence is anything below a specified threshold.
-.br
-When trimming silence from the beginning of a sound file, you specify a duration of audio that is above a given silence threshold before audio data is processed. You can also specify the count of periods of none-silence you want to detect before processing audio data. Specify a period of 0 if you do not want to trim data from the front of the sound file.
-.br
-When optionally trimming silence from the end of a sound file, you specify the duration of audio that must be below a given threshold before stopping to process audio data. A count of periods that occur below the threshold may also be specified. If this options are not specified then data is not trimmed from the end of the audio file. If \fIbelow_periods\fR is negative, it is treated as a positive value and is also used to indicate the effect should restart processing as specified by the \fIabove_periods\fR, making it suitable for removing periods of silence in the middle of a sound file.
-.br
-Duration counts may be in the format of time, hh:mm:ss.frac, or in the exact count of samples.
-.br
-Threshold may be suffixed with d, or % to indicated the value is in decibels or a percentage of max value of the sample value. A value of '0%' will look for total silence.
+Removes silence from the beginning, middle, or end of a sound file. Silence is anything below a specified threshold.
+
+The \fIabove_periods\fR value is used to indicate if sound should be trimmed at
+the beginning of the audio file. A value of zero indicates no silence
+should be trimmed from the beginning. When specifing an non-zero
+\fIabove_periods\fR, it trims audio up until it finds non-silence.
+Normally, when trimming silence from
+beginning of audio the \fIabove_periods\fR will be 1 but it can be increased to
+higher values to trim all data up to a specific count of non-silence periods.
+For example, if you had an audio file with two songs that each contained
+2 seconds of silence before the song, you could specify an \fIabove_period\fR
+of 2 to strip out both silence periods and the first song.
+
+When \fIabove_periods\fR is non-zero, you must also specify a \fIduration\fR and
+\fIthreshold\fR. \fIDuration\fR indications the amount of time that non-silence must be
+detected before it stops trimming data. By increasing the duration, burst of noise can be treated as silence and trimmed off.
+
+\fIThreshold\fR is used to indicate what sample value you should treat as
+silence. For digital audio, a value of 0 may be fine but for audio
+recorded from analog, you may wish to increase ths value to account
+for background noise.
+
+When optionally trimming silence from the end of a sound file, you specify
+a \fIbelow_periods\fR count. In this case, \fIbelow_period\fR means
+to remove all audio data after silence is detected.
+Normally, this will be a value 1 of but it can
+be increased to skip over periods of silence that are wanted. For example,
+if you have a song with 2 seconds of silence in the middle and 2 second
+at the end, you could set below_period to a value of 2 to skip over the
+silence in the middle of the audio file.
+
+For \fIbelow_periods\fR, \fIduration\fR specifies a period of silence
+that must exist before data is not copied any more. By specifying
+a higher duration, silence that is wanted can be left in the audio.
+For example, if you have a song with an expected 1 second of silence
+in the middle and 2 seconds of silence at the end, a duration of 2
+seconds could be used to skip over the middle silence.
+
+Unfortunetly, you must know the length of the silence at the
+end of your audio file to trim off silence reliably. A work around is
+to use the \fIsilence\fR effect in combination with the \fIreverse\fR effect.
+By first reversing the audio, you can use the \fIabove_periods\fR
+to reliably trim all audio from what looks like the front of the file.
+Then reverse the file again to get back to normal.
+
+To remove silence from the middle of a file, specify a
+\fIbelow_periods\fR that is negative. This value is then
+treated as a positive value and is also used to indicate the
+effect should restart processing as specified by the
+\fIabove_periods\fR, making it suitable for removing periods of
+silence in the middle of the sound file.
+
+The \fIperiod\fR counts are in units of samples. \fIDuration\fR counts may be in the format of hh:mm:ss.frac, or the exact count of samples. \fIThreshold\fR numbers may be suffixed iwth d, or % to indicate the value is in decibels or a percentage of maximum value of the sample value (0% specifies pure digital silence).
.TP 10
speed [ -c ] \fIfactor\fB
Speed up or down the sound, as a magnetic tape with a speed control.
--- a/sox.txt
+++ b/sox.txt
@@ -1015,99 +1015,142 @@
[ below_periods duration
threshold[ d | % ]]
- Removes silence from the beginning or end of a sound file.
- Silence is anything below a specified threshold.
- When trimming silence from the beginning of a sound file, you
- specify a duration of audio that is above a given silence
- threshold before audio data is processed. You can also spec-
- ify the count of periods of none-silence you want to detect
- before processing audio data. Specify a period of 0 if you
- do not want to trim data from the front of the sound file.
- When optionally trimming silence from the end of a sound
- file, you specify the duration of audio that must be below a
- given threshold before stopping to process audio data. A
- count of periods that occur below the threshold may also be
- specified. If this options are not specified then data is
- not trimmed from the end of the audio file. If below_periods
- is negative, it is treated as a positive value and is also
- used to indicate the effect should restart processing as
- specified by the above_periods, making it suitable for remov-
- ing periods of silence in the middle of a sound file.
- Duration counts may be in the format of time, hh:mm:ss.frac,
- or in the exact count of samples.
- Threshold may be suffixed with d, or % to indicated the value
- is in decibels or a percentage of max value of the sample
- value. A value of ’0%’ will look for total silence.
+ Removes silence from the beginning, middle, or end of a sound
+ file. Silence is anything below a specified threshold.
+ The above_periods value is used to indicate if sound should
+ be trimmed at the beginning of the audio file. A value of
+ zero indicates no silence should be trimmed from the begin-
+ ning. When specifing an non-zero above_periods, it trims
+ audio up until it finds non-silence. Normally, when trimming
+ silence from beginning of audio the above_periods will be 1
+ but it can be increased to higher values to trim all data up
+ to a specific count of non-silence periods. For example, if
+ you had an audio file with two songs that each contained 2
+ seconds of silence before the song, you could specify an
+ above_period of 2 to strip out both silence periods and the
+ first song.
+
+ When above_periods is non-zero, you must also specify a dura-
+ tion and threshold. Duration indications the amount of time
+ that non-silence must be detected before it stops trimming
+ data. By increasing the duration, burst of noise can be
+ treated as silence and trimmed off.
+
+ Threshold is used to indicate what sample value you should
+ treat as silence. For digital audio, a value of 0 may be
+ fine but for audio recorded from analog, you may wish to
+ increase ths value to account for background noise.
+
+ When optionally trimming silence from the end of a sound
+ file, you specify a below_periods count. In this case,
+ below_period means to remove all audio data after silence is
+ detected. Normally, this will be a value 1 of but it can be
+ increased to skip over periods of silence that are wanted.
+ For example, if you have a song with 2 seconds of silence in
+ the middle and 2 second at the end, you could set
+ below_period to a value of 2 to skip over the silence in the
+ middle of the audio file.
+
+ For below_periods, duration specifies a period of silence
+ that must exist before data is not copied any more. By spec-
+ ifying a higher duration, silence that is wanted can be left
+ in the audio. For example, if you have a song with an
+ expected 1 second of silence in the middle and 2 seconds of
+ silence at the end, a duration of 2 seconds could be used to
+ skip over the middle silence.
+
+ Unfortunetly, you must know the length of the silence at the
+ end of your audio file to trim off silence reliably. A work
+ around is to use the silence effect in combination with the
+ reverse effect. By first reversing the audio, you can use
+ the above_periods to reliably trim all audio from what looks
+ like the front of the file. Then reverse the file again to
+ get back to normal.
+
+ To remove silence from the middle of a file, specify a
+ below_periods that is negative. This value is then treated
+ as a positive value and is also used to indicate the effect
+ should restart processing as specified by the above_periods,
+ making it suitable for removing periods of silence in the
+ middle of the sound file.
+
+ The period counts are in units of samples. Duration counts
+ may be in the format of hh:mm:ss.frac, or the exact count of
+ samples. Threshold numbers may be suffixed iwth d, or % to
+ indicate the value is in decibels or a percentage of maximum
+ value of the sample value (0% specifies pure digital
+ silence).
+
speed [ -c ] factor
- Speed up or down the sound, as a magnetic tape with a speed
- control. It affects both pitch and time. A factor of 1.0
+ Speed up or down the sound, as a magnetic tape with a speed
+ control. It affects both pitch and time. A factor of 1.0
means no change, and is the default. 2.0 doubles speed, thus
- time length is cut by a half and pitch is one octave higher.
- 0.5 halves speed thus time length doubles and pitch is one
- octave lower. If the optional -c parameter is used then the
+ time length is cut by a half and pitch is one octave higher.
+ 0.5 halves speed thus time length doubles and pitch is one
+ octave lower. If the optional -c parameter is used then the
factor is specified in "cents".
stat [ -s n ] [-rms ] [ -v ] [ -d ]
- Do a statistical check on the input file, and print results
- on the standard error file. Audio data is passed unmodified
- from input to output file unless used along with the -e
+ Do a statistical check on the input file, and print results
+ on the standard error file. Audio data is passed unmodified
+ from input to output file unless used along with the -e
option.
- The "Volume Adjustment:" field in the statistics gives you
- the argument to the -v number which will make the sample as
+ The "Volume Adjustment:" field in the statistics gives you
+ the argument to the -v number which will make the sample as
loud as possible without clipping.
The option -v will print out the "Volume Adjustment:" field’s
- value only and return. This could be of use in scripts to
+ value only and return. This could be of use in scripts to
auto convert the volume.
- The -s n option is used to scale the input data by a given
- factor. The default value of n is the max value of a signed
- long variable (0x7fffffff). Internal effects always work
- with signed long PCM data and so the value should relate to
+ The -s n option is used to scale the input data by a given
+ factor. The default value of n is the max value of a signed
+ long variable (0x7fffffff). Internal effects always work
+ with signed long PCM data and so the value should relate to
this fact.
- The -rms option will convert all output average values to
+ The -rms option will convert all output average values to
root mean square format.
- There is also an optional parameter -d that will print out a
- hex dump of the sound file from the internal buffer that is
- in 32-bit signed PCM data. This is mainly only of use in
- tracking down endian problems that creep in to SoX on cross-
+ There is also an optional parameter -d that will print out a
+ hex dump of the sound file from the internal buffer that is
+ in 32-bit signed PCM data. This is mainly only of use in
+ tracking down endian problems that creep in to SoX on cross-
platform versions.
stretch factor [window fade shift fading]
- Time stretch file by a given factor. Change duration without
- affecting the pitch. factor of stretching: >1.0 lengthen,
- <1.0 shorten duration. window size is in ms. Default is
- 20ms. The fade option, can be "lin". shift ratio, in [0.0
- 1.0]. Default depends on stretch factor. 1.0 to shorten, 0.8
+ Time stretch file by a given factor. Change duration without
+ affecting the pitch. factor of stretching: >1.0 lengthen,
+ <1.0 shorten duration. window size is in ms. Default is
+ 20ms. The fade option, can be "lin". shift ratio, in [0.0
+ 1.0]. Default depends on stretch factor. 1.0 to shorten, 0.8
to lengthen. The fading ratio, in [0.0 0.5]. The amount of a
fade’s default depends on factor and shift.
swap [ 1 2 | 1 2 3 4 ]
- Swap channels in multi-channel sound files. Optionally, you
- may specify the channel order you would like the output in.
- This defaults to output channel 2 and then 1 for stereo and
+ Swap channels in multi-channel sound files. Optionally, you
+ may specify the channel order you would like the output in.
+ This defaults to output channel 2 and then 1 for stereo and
2, 1, 4, 3 for quad-channels. An interesting feature is that
- you may duplicate a given channel by overwriting another.
- This is done by repeating an output channel on the command
- line. For example, swap 2 2 will overwrite channel 1 with
- channel 2’s data; creating a stereo file with both channels
+ you may duplicate a given channel by overwriting another.
+ This is done by repeating an output channel on the command
+ line. For example, swap 2 2 will overwrite channel 1 with
+ channel 2’s data; creating a stereo file with both channels
containing the same audio data.
synth [ length ] type mix [ freq [ -freq2 ]
[ off ] [ ph ] [ p1 ] [ p2 ] [ p3 ]
- The synth effect will generate various types of audio data.
+ The synth effect will generate various types of audio data.
Although this effect is used to generate audio data, an input
- file must be specified. The length of the input audio file
+ file must be specified. The length of the input audio file
determines the length of the output audio file.
<length> length in sec or hh:mm:ss.frac, 0=inputlength,
default=0
- <type> is sine, square, triangle, sawtooth, trapetz, exp,
+ <type> is sine, square, triangle, sawtooth, trapetz, exp,
whitenoise, pinknoise, brownnoise, default=sine
<mix> is create, mix, amod, default=create
<freq> frequency at beginning in Hz, not used for noise..
@@ -1115,66 +1158,66 @@
<freq/2> can be given as %%n, where ’n’ is the number of half
notes in respect to A (440Hz)
<off> Bias (DC-offset) of signal in percent, default=0
- <ph> phase shift 0..100 shift phase 0..2*Pi, not used for
+ <ph> phase shift 0..100 shift phase 0..2*Pi, not used for
noise..
- <p1> square: Ton/Toff, triangle+trapetz: rising slope time
+ <p1> square: Ton/Toff, triangle+trapetz: rising slope time
(0..100)
<p2> trapetz: ON time (0..100)
<p3> trapetz: falling slope position (0..100)
trim start [ length ]
- Trim can trim off unwanted audio data from the beginning and
- end of the audio file. Audio samples are not sent to the
+ Trim can trim off unwanted audio data from the beginning and
+ end of the audio file. Audio samples are not sent to the
output stream until the start location is reached.
- The optional length parameter tells the number of samples to
- output after the start sample and is used to trim off the
- back side of the audio data. Using a value of 0 for the
+ The optional length parameter tells the number of samples to
+ output after the start sample and is used to trim off the
+ back side of the audio data. Using a value of 0 for the
start parameter will allow trimming off the back side only.
- Both options can be specified using either an amount of time
- and an exact count of samples. The format for specifying
- lengths in time is hh:mm:ss.frac. A start value of 1:30.5
- will not start until 1 minute, thirty and 1/2 seconds into
- the audio data. The format for specifying sample counts is
- the number of samples with the letter ’s’ appended to it. A
- value of 8000s will wait until 8000 samples are read before
+ Both options can be specified using either an amount of time
+ and an exact count of samples. The format for specifying
+ lengths in time is hh:mm:ss.frac. A start value of 1:30.5
+ will not start until 1 minute, thirty and 1/2 seconds into
+ the audio data. The format for specifying sample counts is
+ the number of samples with the letter ’s’ appended to it. A
+ value of 8000s will wait until 8000 samples are read before
starting to process audio data.
vibro speed [ depth ]
- Add the world-famous Fender Vibro-Champ sound effect to a
- sound sample by using a sine wave as the volume knob. Speed
- gives the Hertz value of the wave. This must be under 30.
- Depth gives the amount the volume is cut into by the sine
+ Add the world-famous Fender Vibro-Champ sound effect to a
+ sound sample by using a sine wave as the volume knob. Speed
+ gives the Hertz value of the wave. This must be under 30.
+ Depth gives the amount the volume is cut into by the sine
wave, ranging 0.0 to 1.0 and defaulting to 0.5.
vol gain [ type [ limitergain ] ]
- The vol effect is much like the command line option -v. It
- allows you to adjust the volume of an input file and allows
- you to specify the adjustment in relation to amplitude,
- power, or dB. If type is not specified then it defaults to
+ The vol effect is much like the command line option -v. It
+ allows you to adjust the volume of an input file and allows
+ you to specify the adjustment in relation to amplitude,
+ power, or dB. If type is not specified then it defaults to
amplitude.
- When type is amplitude then a linear change of the amplitude
- is performed based on the gain. Therefore, a value of 1.0
- will keep the volume the same, 0.0 to < 1.0 will cause the
- volume to decrease and values of > 1.0 will cause the volume
- to increase. Beware of clipping audio data when the gain is
+ When type is amplitude then a linear change of the amplitude
+ is performed based on the gain. Therefore, a value of 1.0
+ will keep the volume the same, 0.0 to < 1.0 will cause the
+ volume to decrease and values of > 1.0 will cause the volume
+ to increase. Beware of clipping audio data when the gain is
greater then 1.0. A negative value performs the same adjust-
ment while also changing the phase.
- When type is power then a value of 1.0 also means no change
+ When type is power then a value of 1.0 also means no change
in volume.
- When type is dB the amplitude is changed logarithmically.
+ When type is dB the amplitude is changed logarithmically.
0.0 is constant while +6 doubles the amplitude.
- An optional limitergain value can be specified and should be
+ An optional limitergain value can be specified and should be
a value much less then 1.0 (ie 0.05 or 0.02) and is used only
- on peaks to prevent clipping. Not specifying this parameter
- will cause no limiter to be used. In verbose mode, this
- effect will display the percentage of audio data that needed
+ on peaks to prevent clipping. Not specifying this parameter
+ will cause no limiter to be used. In verbose mode, this
+ effect will display the percentage of audio data that needed
to be limited.
BUGS
- The syntax is horrific. Thats the breaks when trying to handle all
+ The syntax is horrific. Thats the breaks when trying to handle all
things from the command line.
- Please report any bugs found in this version of SoX to Chris Bagwell
+ Please report any bugs found in this version of SoX to Chris Bagwell
(cbagwell@users.sourceforge.net)
FILES
@@ -1182,9 +1225,9 @@
play(1), rec(1), soxexam(1)
NOTICES
- The version of SoX that accompanies this manual page is support by
+ The version of SoX that accompanies this manual page is support by
Chris Bagwell (cbagwell@users.sourceforge.net). Please refer any ques-
- tions regarding it to this address. You may obtain the latest version
+ tions regarding it to this address. You may obtain the latest version
at the the web site http://sox.sourceforge.net/
AUTHOR