shithub: sox

Download patch

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