shithub: sox

ref: 00c5f228e698c24e9b98f169ef05c4e57449e3b3
dir: /sox.txt/

View raw version



SoX(1)							   SoX(1)


NAME
       sox - Sound eXchange : universal sound sample translator

SYNOPSIS
       sox infile outfile
       sox infile outfile [ effect [ effect options ... ] ]
       sox infile -e effect [ effect options ... ]
       sox [ general options  ] [ format options  ] infile [ for-
       mat options  ] outfile [ effect [ effect options ... ] ]

       General options: [ -e ] [ -h ] [ -p ] [ -v volume ] [ -V ]

       Format	options:   [   -t  filetype  ]	[  -r  rate  ]	[
       -s/-u/-U/-A/-a/-i/-g ] [ -b/-w/-l/-f/-d/-D ] [ -c channels
       ] [ -x ]

       Effects:
	    avg [ -l | -r ]
	    band [ -n ] center [ width ]
	    check
	    chorus  gain-in  gain  out	delay  decay  speed depth
		 -s | -t [ delay decay speed depth -s | -fI-t ]
	    compand attack1,decay1[,attack2,decay2...]
		    in-dB1,out-dB1[,in-dB2,out-dB2...]
		    [gain] [initial-volume]
	    copy
	    cut
	    deemph
	    echo gain-in gain-out delay decay [ delay decay  ...]
	    echos gain-in gain-out delay decay [ delay decay ...]
	    filter [ low ]-[ high ] [ window-len [ beta ]]
	    flanger gain-in gain-out delay decay speed -s | -fI-t
	    highp center
	    lowp center
	    map
	    mask
	    phaser gain-in gain-out delay decay speed -s | -t
	    pick
	    polyphase [ -w < nut / ham > ]
		      [	 -width <  long	 / short  / # > ]
		      [ -cutoff #  ]
	    rate
	    resample
	    reverb gain-out reverb-time delay [ delay ... ]
	    reverse
	    split
	    stat [ debug | -v ]
	    swap [ 1 2 3 4 ]
	    vibro speed [ depth ]

DESCRIPTION
       SoX  is a command line program that can convert most popu-
       lar audio files to most other popular audio file	 formats.
       It  can optionally apply a sound effect to the file during



			December 10, 1999			1





SoX(1)							   SoX(1)


       this translation.

       There are two types of audio files formats  that	 SoX  can
       work  with.   The  first are self-describing file formats.
       These contain a header that completely describe the  char-
       acteristics of the audio data that follows.

       The  second  type are headerless data, or sometimes called
       raw data.  A user must pass enough information to  SoX  on
       the  command  line  so  that it knows what type of data it
       contains.

       Audio data can usually be totally described by four  char-
       acteristics:

       rate	 The  sample  rate is in samples per second.  For
		 example, CD sample rates are at 44100.

       data type What format the data is stored in.  Most popular
		 are 8-bit or 16-bit words.

       data format
		 What  encoding the data type uses.  Examples are
		 u-law, ADPCM, or signed linear data.

       channels	 How many channels are	contained  in  the  audio
		 data.	 Mono and Stereo are the two most common.

       Please refer to the soxexam(1)  manual  page  for  a  long
       description  with  examples on how to use sox with various
       types of file formats.

OPTIONS
       The option syntax is a little grotty, but in essence:

	    sox file.au file.voc

       translates a sound file in SUN Sparc  .AU  format  into	a
       SoundBlaster .VOC file, while

	    sox -v 0.5 file.au -r 12000 file.voc rate

       does  the  same	format	translation  but  also lowers the
       amplitude by 1/2 and changes the sampling rate  from  8000
       hertz to 12000 hertz via the rate sound effect loop.

       Format options:

       Format  options effect the audio samples that they immedi-
       ately percede.  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 out-
       put data.  By taking advantage of this, you can override a
       input file's currupted header or produce	 an  output  file



			December 10, 1999			2





SoX(1)							   SoX(1)


       that is totally different style then the input file.

       -t filetype
		 gives the type of the sound sample file.

       -r rate	 Give sample rate in Hertz of file.  To cause the
		 output file to have a different sample rate than
		 the  input  file,  include  this option with the
		 appropriate rate value	 along	with  the  output
		 options.   If	the  input  and output files have
		 different rates then a sample rate change effect
		 must  be  ran.	 If a sample rate changing effect
		 is not specified then a default one will be used
		 with its default parameters.

       -s/-u/-U/-A/-a/-i/-g
		 The  sample  data  format  is signed linear (2's
		 complement), unsigned linear,	U-law  (logarith-
		 mic),	A-law (logarithmic), ADPCM, IMA_ADPCM, or
		 GSM.  U-law and A-law are the U.S. and	 interna-
		 tional standards for logarithmic telephone sound
		 compression.  ADPCM is form of sound compression
		 that  has  a  good compromise between good sound
		 quality   and	 fast	encoding/decoding   time.
		 IMA_ADPCM  is	also a form of adpcm compression,
		 slightly simpler  and	slightly  lower	 fidelity
		 than  Microsoft's flavor of ADPCM.  IMA_ADPCM is
		 also called DVI_ADPCM.	 GSM is a  standard  used
		 for  telephone	 sound	compression  in	 European
		 countries and its gaining popularity because  of
		 its quality.

       -b/-w/-l/-f/-d/-D
		 The  sample data type is in bytes, 16-bit words,
		 32-bit longwords, 32-bit floats,  64-bit  double
		 floats,  or 80-bit IEEE floats.  Floats and dou-
		 ble floats are in native machine format.

       -x	 The sample data is in XINU format; that  is,  it
		 comes	from  a	 machine  with	the opposite word
		 order than yours and must be  swapped	according
		 to  the  word-size given above.  Only 16-bit and
		 32-bit integer data may  be  swapped.	 Machine-
		 format	 floating-point	 data  is  not	portable.
		 IEEE floats are a fixed, portable format.

       -c channels
		 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  appro-
		 raite	value  with  the output file options.  If
		 the input  and	 output	 file  have  a	different



			December 10, 1999			3





SoX(1)							   SoX(1)


		 number	 of  channels then the avg effect must be
		 used.	If the avg effect is not specified on the
		 command  line	it  will  be invoked with default
		 parameters.

       General options:

       -e	 When used after  the  input  file  (so	 that  it
		 applies  to  the  output  file) it allows you to
		 avoid giving an output	 filename  and	will  not
		 produce an output file.  It will apply any spec-
		 ified effects to the input file.  This is mainly
		 useful with the stat effect but can be used with
		 others.

       -h	 Print version number and usage information.

       -p	 Run in preview mode and  run  fast.   This  will
		 somewhat speed up sox when the output format has
		 a different number of channels and  a	different
		 rate  than  the  input file.  The order that the
		 effects are run in will be arranged for  maximum
		 speed and not quality.

       -v volume Change amplitude (floating point); less than 1.0
		 decreases, greater than 1.0 increases.	 Note: we
		 perceive  volume  logarithmically, not linearly.
		 Note: see the stat effect.

       -V	 Print a description of processing phases.   Use-
		 ful for figuring out exactly how sox is mangling
		 your sound samples.

FILE TYPES
       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 "-t"	 option	 on  the  command
       line.

       The  input  and	output files may be read from standard in
       and out.	 This is done by specifing '-' as the filename.

       File formats which  have	 headers  are  checked,	 if  that
       header  doesn't	seem  right,  the  program  exits with an
       appropriate message.

       The following file formats are supported:


       .8svx	 Amiga 8SVX musical instrument	description  for-
		 mat.

       .aiff	 AIFF  files  used  on	Apple  IIc/IIgs	 and SGI.
		 Note: the AIFF format	supports  only	one  SSND



			December 10, 1999			4





SoX(1)							   SoX(1)


		 chunk.	  It  does  not	 support  multiple  sound
		 chunks, or the 8SVX musical instrument	 descrip-
		 tion format.  AIFF files are multimedia archives
		 and and can  have  multiple  audio  and  picture
		 chunks.   You	may  need  a separate archiver to
		 work with them.

       .au	 SUN Microsystems AU files.  There are apparently
		 many  types  of  .au files; DEC has invented its
		 own with  a  different	 magic	number	and  word
		 order.	 The .au handler can read these files but
		 will not write them.  Some .au files have  valid
		 AU  headers  and  some	 do  not.  The latter are
		 probably original SUN	u-law  8000  hz	 samples.
		 These	can  be	 dealt	with using the .ul format
		 (see below).

       .avr	 Audio Visual Research
		 The AVR format is produced by a number	 of  com-
		 mercial packages on the Mac.

       .cdr	 CD-R
		 CD-R  files  are used in mastering music Compact
		 Disks.	 The file format is, as you might expect,
		 raw  stereo raw unsigned samples at 44khz.  But,
		 there's some blocking/padding oddity in the for-
		 mat, so it needs its own handler.

       .cvs	 Continuously Variable Slope Delta modulation
		 Used  to  compress speech audio for applications
		 such as voice mail.

       .dat	 Text Data files
		 These files contain a textual representation  of
		 the  sample  data.   There  is	 one  line at the
		 beginning that contains the sample rate.  Subse-
		 quent	lines contain two numeric data items: the
		 time since the beginning of the sample	 and  the
		 sample value.	Values are normalized so that the
		 maximum and minimum are 1.00  and  -1.00.   This
		 file format can be used to create data files for
		 external programs such as FFT analyzers or graph
		 routines.   SoX  can also convert a file in this
		 format back into one of the other file	 formats.

       .gsm	 GSM 06.10 Lossy Speech Compression
		 A  standard for compressing speech which is used
		 in the Global Standard for Mobil  telecommunica-
		 tions	(GSM).	Its good for its purpose, shrink-
		 ing audio data size, but it will introduce  lots
		 of  noise  when  a given sound sample is encoded
		 and decoded multiple times.  This format is used
		 by  some  voice mail applications.  It is rather
		 CPU intensive.	  GSM  in  sox	is  optional  and



			December 10, 1999			5





SoX(1)							   SoX(1)


		 requires  access to an external GSM library.  To
		 see if there is support for gsm run sox  -h  and
		 look  for  it	under  the list of supported file
		 formats.

       .hcom	 Macintosh HCOM files.	 These	are  (apparently)
		 Mac FSSD files with some variant of Huffman com-
		 pression.  The Macintosh has wacky file  formats
		 and  this format handler apparently doesn't han-
		 dle all the ones it should.  Mac users will need
		 your  usual  arsenal  of file converters to deal
		 with an HCOM file under Unix or DOS.

       .maud	 An Amiga format
		 An IFF-conform sound file type, registered by MS
		 MacroSystem  Computer GmbH, published along with
		 the "Toccata" sound-card on the  Amiga.   Allows
		 8bit  linear, 16bit linear, A-Law, u-law in mono
		 and stereo.

       ossdsp	 OSS /dev/dsp device driver
		 This is a pseudo-file type and can be optionally
		 compiled  into	 Sox.	Run  sox -h to see if you
		 have support for  this	 file  type.   When  this
		 driver	 is used it allows you to open up the OSS
		 /dev/dsp file and configure it to use	the  same
		 data  type  as	 passed	 in to Sox.  It works for
		 both playing and recording sound samples.   When
		 playing  sound	 files	it attempts to set up the
		 OSS driver to use the same format as  the  input
		 file.	 It  is	 suggested to always override the
		 output values to use the highest quality samples
		 your  sound card can handle.  Example: -t ossdsp
		 -w -s /dev/dsp

       .sf	 IRCAM Sound Files.
		 SoundFiles are used by academic  music	 software
		 such  as  the	CSound	package,  and the MixView
		 sound sample editor.

       .smp	 Turtle Beach SampleVision files.
		 SMP files are for use with  the  PC-DOS  package
		 SampleVision  by  Turtle  Beach  Softworks. This
		 package is for	 communication	to  several  MIDI
		 samplers.  All sample rates are supported by the
		 package, although not all are supported  by  the
		 samplers  themselves.	Currently loop points are
		 ignored.

       sunau	 Sun /dev/audio device driver
		 This is a pseudo-file type and can be optionally
		 compiled  into	 Sox.	Run  sox -h to see if you
		 have support for  this	 file  type.   When  this
		 driver	 is  used  it allows you to open up a Sun



			December 10, 1999			6





SoX(1)							   SoX(1)


		 /dev/audio file and configure it to use the same
		 data  type  as	 passed	 in to Sox.  It works for
		 both playing and recording sound samples.   When
		 playing  sound	 files	it attempts to set up the
		 audio driver to use the same format as the input
		 file.	 It  is	 suggested to always override the
		 output values to use the highest quality samples
		 your  hardware can handle.  Example: -t sunau -w
		 -s /dev/audio or -t sunau -U -c 1 /dev/audio for
		 older sun equipment.

       .txw	 Yamaha TX-16W sampler.
		 A  file  format  from a Yamaha sampling keyboard
		 which wrote IBM-PC format 3.5"	 floppies.   Han-
		 dles reading of files which do not have the sam-
		 ple rate field set to one  of	the  expected  by
		 looking  at  some other bytes in the attack/loop
		 length fields, and defaulting to  33kHz  if  the
		 sample rate is still unknown.

       .vms	 More info to come.
		 Used  to  compress speech audio for applications
		 such as voice mail.

       .voc	 Sound Blaster VOC files.
		 VOC files are	multi-part  and	 contain  silence
		 parts,	 looping,  and different sample rates for
		 different chunks.  On input, the  silence  parts
		 are  filled  out, loops are rejected, and sample
		 data  with  a	new  sample  rate  is	rejected.
		 Silence  with	a different sample rate is gener-
		 ated appropriately.  On output, silence  is  not
		 detected, nor are impossible sample rates.

       .wav	 Microsoft .WAV RIFF files.
		 These	appear	to  be very similar to IFF files,
		 but not the same.  They  are  the  native  sound
		 file format of Windows.  (Obviously, Windows was
		 of such incredible importance	to  the	 computer
		 industry  that it just had to have its own sound
		 file format.)	Normally .wav files have all for-
		 matting  information in their headers, and so do
		 not need any format  options  specified  for  an
		 input	file.  If any are, they will override the
		 file header, and you  will  be	 warned	 to  this
		 effect.  You had better know what you are doing!
		 Output format options will cause a  format  con-
		 version,  and	the  .wav  will written appropri-
		 ately.	 Sox currently can read PCM, ULAW,  ALAW,
		 MS  ADPCM, and IMA (or DVI) ADPCM.  It can write
		 all of these formats including (NEW!)	the ADPCM
		 styles.

       .wve	 Psion 8-bit alaw



			December 10, 1999			7





SoX(1)							   SoX(1)


		 These	are  8-bit a-law 8khz sound files used on
		 the Psion palmtop portable computer.

       .raw	 Raw files (no header).
		 The sample rate, size	(byte,	word,  etc),  and
		 style	(signed,  unsigned,  etc.)  of the sample
		 file must be  given.	The  number  of	 channels
		 defaults to 1.

       .ub, .sb, .uw, .sw, .ul, .sl
		 These	are  several  suffices	which  serve as a
		 shorthand for raw files with a	 given	size  and
		 style.	  Thus,	 ub, sb, uw, sw, ul and sl corre-
		 spond	to  "unsigned	byte",	 "signed   byte",
		 "unsigned  word",  "signed word", "ulaw" (byte),
		 and "signed long".  The sample rate defaults  to
		 8000 hz if not explicitly set, and the number of
		 channels (as always) defaults to 1.   There  are
		 lots  of  Sparc samples floating around in u-law
		 format with no header and fixed at a sample rate
		 of  8000 hz.  (Certain sound management software
		 cheerfully  ignores  the  headers.)   Similarly,
		 most Mac sound files are in unsigned byte format
		 with a sample rate of 11025 or 22050 hz.

       .auto	 This is a ``meta-type'':  specifying  this  type
		 for  an input file triggers some code that tries
		 to guess the real  type  by  looking  for  magic
		 words	in  the	 header.   If  the  type can't be
		 guessed, the program exits with  an  error  mes-
		 sage.	 The  input  must  be a plain file, not a
		 pipe.	This type can't be used for output files.

EFFECTS
       Only one effect from the palette may be applied to a sound
       sample.	To do multiple effects you'll need to run sox  in
       a pipeline.

       avg [ -l | -r ]
		 Reduce	 the  number of channels by averaging the
		 samples, or duplicate channels to  increase  the
		 number	 of  channels.	 This effect is automati-
		 cally used when the number of input samples dif-
		 fer  from  the	 number of output channels.  When
		 reducing the number of channels it  is	 possible
		 to  manually  specify the avg effect and use the
		 -l and -r options to select  only  the	 left  or
		 right	channel for the output instead of averag-
		 ing the two channels.

       band [ -n ] center [ width ]
		 Apply	a  band-pass   filter.	  The	frequency
		 response drops logarithmically around the center
		 frequency.  The width gives  the  slope  of  the



			December 10, 1999			8





SoX(1)							   SoX(1)


		 drop.	 The  frequencies  at  center + width and
		 center - width will be half  of  their	 original
		 amplitudes.  Band defaults to a mode oriented to
		 pitched signals, i.e. voice, singing, or instru-
		 mental	 music.	  The  -n (for noise) option uses
		 the  alternate	 mode  for  un-pitched	 signals.
		 Warning:  -n  introduces  a  power-gain of about
		 11dB in the filter, so beware	of  output  clip-
		 ping.	Band introduces noise in the shape of the
		 filter, i.e. peaking at the center frequency and
		 settling  around  it.	See filter for a bandpass
		 effect with steeper shoulders.

       bandpass	 Butterworth bandpass filter. Description  coming
		 soon!

       bandreject
		 Butterworth bandreject filter.	 Description com-
		 ing soon!

       chorus gain-in gain-out delay decay speed depth

	      -s | -t [ delay decay speed depth -s | -t ... ]
		 Add a chorus to a sound sample.  Each	quadtuple
		 delay/decay/speed/depth  gives the delay in mil-
		 liseconds and the decay  (relative  to	 gain-in)
		 with  a  modulation  speed  in Hz using depth in
		 milliseconds.	The modulation is either sinodial
		 (-s) or triangular (-t).  Gain-out is the volume
		 of the output.

       compand attack1,decay1[,attack2,decay2...]

	       in-dB1,out-dB1[,in-dB2,out-dB2...]

	       [gain] [initial-volume]
		 Compand (compress or expand) the  dynamic  range
		 of  a sample.	The attack and decay time specify
		 the integration time  over  which  the	 absolute
		 value	of  the	 input	signal	is  integrated to
		 determine its volume.	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 chan-
		 nels.	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 func-
		 tion  does  not have to be monotonically rising.
		 The special value -inf may be used  to	 indicate
		 that  the input volume should be associated out-
		 put volume.  The points -inf,-inf  and	 0,0  are
		 assumed;  the	latter may be overridden, but the



			December 10, 1999			9





SoX(1)							   SoX(1)


		 former may not.  The third (optional)	parameter
		 is  a postprocessing 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 nomi-
		 nal 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.

       copy	 Copy the input file to the output file.  This is
		 the  default  effect if both files have the same
		 sampling rate.

       cut loopnumber
		 Extract loop #N from a sample.

       deemph	 Apply a treble attenuation  shelving  filter  to
		 samples  in  audio  cd	 format.   The	frequency
		 response of pre-emphasized recordings is  recti-
		 fied.	 The filtering is defined in the standard
		 document ISO 908.

       echo gain-in gain-out delay decay [ delay decay ... ]
		 Add echoing to a sound sample.	 Each delay/decay
		 part  gives  the  delay  in milliseconds and the
		 decay (relative to gain-in) of that echo.  Gain-
		 out is the volume of the output.

       echos gain-in gain-out delay decay [ delay decay ... ]
		 Add a sequence of echos to a sound sample.  Each
		 delay/decay part gives the delay in milliseconds
		 and  the  decay  (relative  to	 gain-in) of that
		 echo.	Gain-out is the volume of the output.

       filter [ low ]-[ high ] [ window-len [ beta ] ]
		 Apply	a  Sinc-windowed  lowpass,  highpass,  or
		 bandpass  filter  of  given window length to the
		 signal.  low refers  to  the  frequency  of  the
		 lower	6dB corner of the filter.  high refers to
		 the frequency of the upper  6dB  corner  of  the
		 filter.

		 A  lowpass  filter  is	 obtained  by leaving low
		 unspecified,  or  0.	A  highpass   filter   is
		 obtained  by  leaving high unspecified, or 0, or
		 greater than or equal to the Nyquist  frequency.

		 The window-len, if unspecified, defaults to 128.
		 Longer windows give a	sharper	 cutoff,  smaller



			December 10, 1999		       10





SoX(1)							   SoX(1)


		 windows a more gradual cutoff.

		 The  beta, if unspecified, defaults to 16.  This
		 selects a Kaiser window.  You can select a  Nut-
		 tall  window by specifying anything <= 2.0 here.
		 For more discussion  of  beta,	 look  under  the
		 resample effect.


       flanger gain-in gain-out delay decay speed -s | -t
		 Add  a	 flanger  to a sound sample.  Each triple
		 delay/decay/speed gives the delay  in	millisec-
		 onds  and the decay (relative to gain-in) with a
		 modulation  speed  in	Hz.   The  modulation  is
		 either	 sinodial (-s) or triangular (-t).  Gain-
		 out is the volume of the output.

       highp center
		 Apply	a  high-pass   filter.	  The	frequency
		 response  drops logarithmically with center fre-
		 quency in the middle of the drop.  The slope  of
		 the  filter  is  quite gentle.	 See filter for a
		 highpass effect with sharper cutoff.

       highpass	 Butterworth highpass filter.	Description  com-
		 ming soon!

       lowp center
		 Apply a low-pass filter.  The frequency response
		 drops logarithmically with center  frequency  in
		 the middle of the drop.  The slope of the filter
		 is quite  gentle.   See  filter  for  a  lowpass
		 effect with sharper cutoff.

       lowpass	 Butterworth  lowpass filter.  Description coming
		 soon!

       map	 Display a list of loops in a sample, and miscel-
		 laneous loop info.

       mask	 Add  "masking	noise"	to  signal.   This effect
		 deliberately adds white  noise	 to  a	sound  in
		 order	to  mask quantization effects, created by
		 the process of playing a  sound  digitally.   It
		 tends	to  mask buzzing voices, for example.  It
		 adds 1/2 bit of noise to the sound file  at  the
		 output bit depth.

       phaser gain-in gain-out delay decay speed -s | -t
		 Add  a	 phaser	 to  a sound sample.  Each triple
		 delay/decay/speed gives the delay  in	millisec-
		 onds  and the decay (relative to gain-in) with a
		 modulation  speed  in	Hz.   The  modulation  is
		 either	 sinodial  (-s)	 or triangular (-t).  The



			December 10, 1999		       11





SoX(1)							   SoX(1)


		 decay should be less than 0.5 to avoid feedback.
		 Gain-out is the volume of the output.

       pick	 Select	 the  left  or	right channel of a stereo
		 sample, or one of four	 channels  in  a  quadro-
		 phonic sample.

       polyphase [ -w < nut / ham > ]

		 [  -width <  long  / short  / # > ]

		 [ -cutoff #  ]
		 Translate input sampling rate to output sampling
		 rate via polyphase interpolation,  a  DSP  algo-
		 rithm.	  This	method	is  slow and uses lots of
		 RAM, but gives much better results than rate.
		 -w < nut / ham > : select either a  Nuttal  (~90
		 dB  stopband)	or Hamming (~43 dB stopband) win-
		 dow.  Default is nut.
		 -width long / short / # : specify the	(approxi-
		 mate)	width  of  the filter.	long is 1024 sam-
		 ples; short is 128 samples.   Alternatively,  an
		 exact number can be used.  Default is long.  The
		 short option is not recommended, as it	 produces
		 poor quality results.
		 -cutoff  # : specify the filter cutoff frequency
		 in terms of fraction of  bandwidth.   If  upsam-
		 pling, 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.


       rate	 Translate input sampling rate to output sampling
		 rate via linear interpolation to the Least  Com-
		 mon Multiple of the two sampling rates.  This is
		 the default effect if the two files have differ-
		 ent  sampling	rates and the preview options was
		 specified.  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  resample  or
		 polyphase.  If you are wondering which of  SoX's
		 rate  changing	 effects to use, you will want to
		 read a detailed  analysis  of	all  of	 them  at
		 http://eakaw2.et.tu-dresden.de/~andreas/resam-
		 ple/resample.html [Nov,1999: These tests need to
		 be  updated for sox-12.17, which has bugfixes to
		 the resample and polyphase code.]





			December 10, 1999		       12





SoX(1)							   SoX(1)


       resample [ -qs | -q | -ql ] [ rolloff [ beta ] ]
		 Translate input sampling rate to output sampling
		 rate  via  simulated  analog  filtration.   This
		 method is slower than rate, but gives much  bet-
		 ter results.

		 The  -qs,  -q,	 or -ql 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.
		 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 -q*  options  use
		 quadratic  interpolation of filter coefficients,
		 resulting in about 24 bits precision.
		 Following is a table of the reasonable	 defaults
		 which are built-in to sox:
		    Option  Window rolloff beta interpolation
		    ------  ------ ------- ---- -------------
		    (none)    45    0.80    16	   linear
		      -qs     45    0.80    16	  quadratic
		      -q      75    0.875   16	  quadratic
		      -ql    149    0.94    16	  quadratic
		    ------  ------ ------- ---- -------------
		 -qs, -q, or -ql 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
		 slower execution times.

		 rolloff  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
		 indicated above.

		 The beta 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.  If unspecified, the default is
		 a Kaiser window with beta 16.

		 In the case of Kaiser window (beta > 2.0), lower
		 betas	produce a somewhat faster transition from
		 passband to stopband, at the cost of  noticeable
		 artifacts.   A	 beta  of 16 is the default, beta
		 less than 10 is not recommended.  If you want	a
		 sharper  cutoff,  don't  use  low  beta's, use a
		 longer	 sample	 window.   A  Nuttall  window  is
		 selected  by specifying any 'beta' <= 2, and the
		 Nuttall window has somewhat steeper cutoff  than
		 the  default  Kaiser  window.	You will probably



			December 10, 1999		       13





SoX(1)							   SoX(1)


		 not need to  use  the	beta  parameter	 at  all,
		 unless	 you are just curious about comparing the
		 effects of Nuttall vs. Kaiser windows.

		 This is the default effect if the two files have
		 different  sampling  rates.   Default parameters
		 are, as indicated above, Kaiser window of length
		 45, rolloff 0.80, beta 16, linear interpolation.

		 NOTE: -qs is  only  slightly  slower,	but  more
		 accurate for 16-bit or higher precision.

		 NOTE:	In many cases of up-sampling, no interpo-
		 lation is needed, as exact  filter  coefficients
		 can be computed in a reasonable amount of space.
		 To be precise, this is done when

			    input_rate < output_rate
				       &&
		   output_rate/gcd(input_rate,output_rate) <= 511

       reverb gain-out delay [ delay ... ]
		 Add reverberation to a sound sample.  Each delay
		 is given in milliseconds  and	its  feedback  is
		 depending  on	the  reverb-time in milliseconds.
		 Each delay should be in the  range  of	 half  to
		 quarter of reverb-time to get a realistic rever-
		 beration.  Gain-out is the volume of the output.

       reverse	 Reverse  the  sound sample completely.	 Included
		 for finding Satanic subliminals.

       split	 Turn a mono sample into a stereo sample by copy-
		 ing  the  input  channel  to  the left and right
		 channels.

       stat [ debug | -v ]
		 Do a statistical check on the	input  file,  and
		 print	results on the standard error file.  stat
		 may copy the file untouched from input	 to  out-
		 put,  if you select an output file.  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.
		 There	is  an	optional  parameter  -v that will
		 print out the "Volume Adjustment:" field's value
		 and  return.  This could be of use in scripts to
		 auto convert the volume.  There is  an	 also  an
		 optional  parameter  debug  that  will place sox
		 into debug mode and 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.



			December 10, 1999		       14





SoX(1)							   SoX(1)


       swap [ 1 2 3 4 ]
		 Swap channels in multi-channel sound files.   In
		 files	with more than 2 channels you may specify
		 the order that the channels should be rearranged
		 in.

       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
		 wave, ranging 0.0 to 1.0 and defaulting to  0.5.

       Sox  enforces certain effects.  If the two files have dif-
       ferent sampling rates, the requested effect must be one of
       copy,  or rate, If the two files have different numbers of
       channels, the avg effect must be requested.

BUGS
       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 (cbagwell@sprynet.com)

FILES
SEE ALSO
       play(1), rec(1), soxexam(1)

NOTICES
       The version of Sox that accompanies this	 manual	 page  is
       support	by  Chris Bagwell (cbagwell@sprynet.com).  Please
       refer any questions regarding it to this address.  You may
       obtain	the   latest   version	 at   the  the	web  site
       http://home.sprynet.com/~cbagwell/sox.html





















			December 10, 1999		       15