shithub: sox

ref: a188768fb3df7ca7cce2c0abaa58ff945cdf4ea4
dir: /sox.txt/

View raw version



User Commands						   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	] ifile	[  format
     options  ]	ofile [	effect [ effect	options	... ] ]

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

     Format options:  [	-t filetype ] [	-r rate	 ]  [  -s/-u/-U/-
     A/-a/-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 < num / 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 translates sound files	from one format	to another,  pos-
     sibly doing a sound effect.



SunOS 5.6	  Last change: November	8, 1999			1






User Commands						   SoX(1)



OPTIONS
     The option	syntax is a little grotty, but in essence:
	  sox file.au file.voc
     translates	a sound	sample 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  ampli-
     tude 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 file that  they	immediately  per-
     cede.   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.  It
     is	also possible to read a	given file in and  output  it  in
     any  supported  data  format  by  specifying  output  format
     options.

     -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 then
	       the input  file,	 include  this	option	with  the
	       appropriate  rate  value	 along	with  the  output
	       options.	 If the	input and output files have  dif-
	       ferent 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/-g
	       The sample data is signed linear	(2's complement),
	       unsigned	linear,	U-law (logarithmic), A-law (loga-
	       rithmic), ADPCM,	or GSM.	 U-law and A-law are  the
	       U.S.  and  international	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.	  GSM  is a standard used
	       for telephone sound compression in European  coun-
	       tries  and  its	gaining	popularity because of its
	       quality.

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




SunOS 5.6	  Last change: November	8, 1999			2






User Commands						   SoX(1)



     -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 then the input file,
	       include this option with	the approraite 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	command	line it	will  be  invoked
	       with default parameters.

     General options:

     -e	       after the input file allows you to avoid	giving an
	       output  file  and  just	name  an effect.  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 some-
	       what  speed  up	sox  when the output format has	a
	       different number	of channels and	a different  rate
	       then  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.   Useful
	       for  figuring out exactly how sox is mangling your
	       sound samples.

     The input and output files	may be standard	input and output.
     This  is specified	by '-'.	 The -t	type option must be given
     in	this case, else	sox will not know the format of	the given
     file.   The  -t,  -r,  -s/-u/-U/-A, -b/-w/-l/-f/-d/-D and -x
     options refer to the input	data when given	before the  input
     file name.	 After,	they refer to the output data.




SunOS 5.6	  Last change: November	8, 1999			3






User Commands						   SoX(1)



     If	you don't give an output file name, sox	 will  just  read
     the  input	 file.	 This is useful	for validating structured
     file formats; the stat effect may also be used  via  the  -e
     option.

FILE TYPES
     Sox needs to know the formats of the input	and output files.
     File  formats which have headers are checked, if that header
     doesn't seem right, the program exits  with  an  appropriate
     message.	Currently,  raw	 (no  header)  binary and textual
     data, Amiga 8SVX, Apple/SGI AIFF, SPARC .AU (w/header), AVR,
     NeXT  .SND,  CD-R,	 CVSD,	GSM  06.10, Mac	HCOM, Sound Tools
     MAUD, OSS device drivers, Turtle Beach .SMP, Sound	 Blaster,
     Sndtool, and Sounder, Sun Audio device driver, Yamaha TX-16W
     Sampler, IRCAM Sound Files,  Creative Labs	VOC, Psion  .WVE,
     and Microsoft RIFF/WAV are	supported.

     .8svx     Amiga 8SVX musical instrument description format.

     .aiff     AIFF files used on Apple	IIc/IIgs and SGI.   Note:
	       the  AIFF format	supports only one SSND chunk.  It
	       does not	support	multiple  sound	 chunks,  or  the
	       8SVX  musical instrument	description 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  commer-
	       cial 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



SunOS 5.6	  Last change: November	8, 1999			4






User Commands						   SoX(1)



	       These files contain a  textual  representation  of
	       the  sample data.  There	is one line at the begin-
	       ning that contains the  sample  rate.   Subsequent
	       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 pro-
	       grams 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 telecommunications
	       (GSM).  Its good	for its	purpose, shrinking  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 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 compres-
	       sion.  The Macintosh has	wacky  file  formats  and
	       this  format handler apparently doesn't handle 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 psuedo-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



SunOS 5.6	  Last change: November	8, 1999			5






User Commands						   SoX(1)



	       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 Sam-
	       pleVision  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 psuedo-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 /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.  Handles
	       reading of files	which do not have the sample 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 generated	appropri-
	       ately.  On output, silence is  not  detected,  nor
	       are impossible sample rates.



SunOS 5.6	  Last change: November	8, 1999			6






User Commands						   SoX(1)



     .wav      Microsoft .WAV RIFF files.
	       These appear to be very similar to IFF files,  but
	       not  the	same. They are the native sound	file for-
	       mat of Windows.	(Obviously, Windows was	 of  such
	       incredible  importance  to  the	computer industry
	       that it just had	to have	its own	sound  file  for-
	       mat.)   Normally	 .wav  files  have all formatting
	       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 conversion,	and the	.wav will
	       written appropriately.  Note that it  is	 possible
	       to  write  data of a type that cannot be	specified
	       by the .wav header, and you will	 be  warned  that
	       you a writing a bad file	!  Sox currently can read
	       PCM, ULAW, ALAW,	MS ADPCM, and IMA (or DVI) ADPCM.
	       It  can	output	all  of	 these formats except the
	       ADPCM styles.

     .wve      Psion 8-bit alaw
	       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
	       These are several suffices which	serve as a short-
	       hand  for  raw  files with a given size and style.
	       Thus,  ub,  sb,	uw,  sw,  and  ul  correspond  to
	       "unsigned  byte",  "signed byte", "unsigned word",
	       "signed word", and "ulaw" (byte).  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.)   Simi-
	       larly,  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  message.   The  input
	       must be a plain file, not a pipe.  This type can't
	       be used for output files.



SunOS 5.6	  Last change: November	8, 1999			7






User Commands						   SoX(1)



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  automatically
	       used  when the number of	input samples differ then
	       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 averaging the two  chan-
	       nels.

     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	drop.	The  fre-
	       quencies	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 instrumental  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 clipping.  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.

     chorus gain-in gain-out delay decay speed deptch

	    -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 mil-
	       liseconds.  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



SunOS 5.6	  Last change: November	8, 1999			8






User Commands						   SoX(1)



	       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 channels.  The second parame-
	       ter  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 monoton-
	       ically rising.  The special value -inf may be used
	       to indicate that	the input volume should	be  asso-
	       ciated  output  volume.	 The points -inf,-inf and
	       0,0 are assumed;	the latter may be overridden, but
	       the  former may not.  The third (optional) parame-
	       ter 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 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 com-
	       pander 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 sam-
	       ples  in	 audio cd format.  The frequency response
	       of pre-emphasized recordings  is	 rectified.   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.




SunOS 5.6	  Last change: November	8, 1999			9






User Commands						   SoX(1)



     filter [ low ]-[ high ] [ window-len [ beta ] ]
	       Apply  a	 Sinc-windowed	lowpass,   highpass,   or
	       bandpass	filter of given	window length to the sig-
	       nal.  low refers	to the frequency of the	lower 6dB
	       corner  of  the	filter.	  high refers to the fre-
	       quency 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 freq.

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

	       The beta, if unspecified, defaults  to  16.   This
	       selects a Kaiser	window.	 You can select	a Nuttall
	       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 milliseconds
	       and the decay (relative to gain-in) with	a modula-
	       tion  speed in Hz.  The modulation is either sino-
	       dial (-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 frequency in the
	       middle of the drop.  The	slope of  the  filter  is
	       quite  gentle.	See  filter for	a highpass effect
	       with sharper cutoff.

     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.

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

     mask      Add "masking noise" to signal.  This effect  deli-
	       berately	 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



SunOS 5.6	  Last change: November	8, 1999		       10






User Commands						   SoX(1)



	       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 milliseconds
	       and the decay (relative to gain-in) with	a modula-
	       tion  speed in Hz.  The modulation is either sino-
	       dial (-s) or triangular (-t).  The 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  sam-
	       ple,  or	 one  of  four channels	in a quadrophonic
	       sample.

     polyphase [ -w < num / ham	> ]

	       [  -width <  long  / short  / # > ]

	       [ -cutoff #  ]
	       Translate input sampling	rate to	 output	 sampling
	       rate via	polyphase interpolation, a DSP algorithm.
	       This method is slow and	uses  lots  of	RAM,  but
	       gives much better results then rate.
	       -w < nut	/ ham >	: select either	a Nuttal (~90  dB
	       stopband)  or  Hamming  (~43  dB	stopband) window.
	       Warning:	Nuttall	windows	require	 2x  length  than
	       Hamming windows.	 Default is nut.
	       -width long / short / # : specify the width of the
	       filter.	 long  is 1024 samples;	short is 128 sam-
	       ples.  Alternatively, an	exact number can be used.
	       Default is long.
	       -cutoff # : specify the filter cutoff frequency in
	       terms  of  fraction  of bandwidth.  If upsampling,
	       then this is the	fraction of  the  orignal  signal
	       that  should go through.	 If downsampling, this is
	       the fraction of the  signal  left  after	 downsam-
	       pling.	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 Common
	       Multiple	of the two sampling rates.  This  is  the
	       default	effect	if  the	 two files have	different
	       sampling	rates and the preview options was  speci-
	       fied.   This  is	 fast but noisy:  the spectrum of
	       the original sound will	be  shifted  upwards  and
	       duplicated faintly when up-translating by a multi-
	       ple.  Lerp-ing is acceptable for	cheap 8-bit sound
	       hardware,  but  for  CD-quality	sound  you should



SunOS 5.6	  Last change: November	8, 1999		       11






User Commands						   SoX(1)



	       instead use either resample or polyphase.  If  you
	       are wondering which of Sox's rate changing effects
	       to ues, you will	want to	read a detailed	 analysis
	       of    all    of	 them	at   http://eakaw2.et.tu-
	       dresden.de/~andreas/resample/resample.html
	       [Nov,1999:  These  tests	 need  to  be updated for
	       sox-12.18, which	has bugfixes to	the resample  and
	       polyphase code.]

     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   better
	       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 win-
	       dow  width  about  37  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.85
	       of  the	Nyquist	 frequency.   The -q* options use
	       quadratic interpolation	of  filter  coefficients,
	       resulting in about 22 bits precision.  -qs, -q, or
	       -ql use window lengths of 37, 75, or 150	 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 default is 0.8.

	       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	 specify-
	       ing  any	 'beta'	 <= 2, and the Nuttall window has
	       somewhat	steeper	cutoff than  the  default  Kaiser



SunOS 5.6	  Last change: November	8, 1999		       12






User Commands						   SoX(1)



	       window.	 You  will  probably  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
	       Kaiser window of	length 37, rolloff 0.80, beta 16,
	       linear	interpolation.	  -qs  is  only	 slightly
	       slower, but more	accurate  for  16-bit  or  higher
	       precision.


     reverb gain-out delay [ delay ... ]
	       Add reverbation to a sound sample.  Each	delay  is
	       given  in milliseconds and its feedback is depend-
	       ing on  the  reverb-time	 in  milliseconds.   Each
	       delay should be in the range of half to quarter of
	       reverb-time  to	get  a	 realistic   reverbation.
	       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 copying
	       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  output,
	       if  you select an output	file. The "Volume Adjust-
	       ment:" field in the statistics gives you	the argu-
	       ment  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  parame-
	       ter  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.

     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.




SunOS 5.6	  Last change: November	8, 1999		       13






User Commands						   SoX(1)



     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.  It's very	 tempting  to  include	a
     default  system  that  allows  an effect name as the program
     name and just pipes a sound sample	from  standard	input  to
     standard  output,	but  the  problem of inputting the sample
     rates makes this unworkable.

     Please report any bugs found in this version of sox to Chris
     Bagwell (cbagwell@sprynet.com)

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

NOTICES
     The  echoplex  effect  is:	  Copyright  (C)  1989	 by   Jef
     Poskanzer.

     Permission	 to  use,  copy,  modify,  and	distribute   this
     software  and  its	documentation for any purpose and without
     fee is hereby granted, provided  that  the	 above	copyright
     notice  appear  in	 all  copies and that both that	copyright
     notice and	this permission	notice appear in supporting docu-
     mentation.	  This	software  is  provided	"as  is"  without
     express or	implied	warranty.

     The version of Sox	that accompanies this manual page is sup-
     port  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











SunOS 5.6	  Last change: November	8, 1999		       14