shithub: sox

--- a/Makefile.am

+++ b/Makefile.am

@@ -9,8 +9,8 @@

 # man pages are not considered to be sources, so need to add "dist_"

 # prefix to ensure they are added to the distribution.

-dist_man_MANS = sox.1 soxexam.7 libsox.3

-EXTRA_DIST = sox.txt soxexam.txt libsox.txt

+dist_man_MANS = sox.1 soxeffect.7 soxformat.7 soxexam.7 libsox.3

+EXTRA_DIST = sox.txt soxeffect.txt soxformat.txt soxexam.txt libsox.txt

 play.1 rec.1: sox.1

 	$(RM) $@ && $(LN_S) $< $@

@@ -19,13 +19,13 @@

 .1.txt .3.txt .7.txt:

 	tbl $(srcdir)/$< | nroff -man | col -b > $@

-txt: sox.txt soxexam.txt libsox.txt

+txt: sox.txt soxeffect.txt soxformat.txt soxexam.txt libsox.txt

 # Rule for making PDF man pages

 .1.pdf .3.pdf .7.pdf:

 	tbl $(srcdir)/$< | groff -man -Tps | ps2pdf - $@

-pdf: sox.pdf soxexam.pdf libsox.pdf

+pdf: sox.pdf soxeffect.pdf soxformat.pdf soxexam.pdf libsox.pdf

 install-data-hook:

 	cd $(DESTDIR)$(mandir)/man1 && $(RM) play.1 && $(LN_S) sox.1 play.1

--- a/sox.1

+++ b/sox.1

@@ -119,9 +119,8 @@

 records a new track in a multi-track recording.

.SP

 Further examples are included throughout this manual;

-more-detailed examples can be found in the separate

-.BR soxexam (7)

-manual.

+more-detailed examples can be found in

+.BR soxexam (7).

 .SS File Formats

 There are two types of audio file format that SoX can work with.  The

 first is `self-describing'; these formats include a header that

@@ -624,7 +623,9 @@

 header, SoX will exit with an appropriate error message if such a

 header is not actually present.

.SP

-See \fBFILE TYPES\fR below for a list of supported file types.

+See

+.BR soxformat (7)

+for a list of supported file types.

.PP

 \fB\-L\fR, \fB\-\-endian little\fR

.br

@@ -717,13 +718,6 @@

.TP

 \fB\-1\fR\^/\fB\-2\fR\^/\fB\-3\fR\^/\fB\-4\fR\^/\fB\-8\fR

 The sample datum size is 1, 2, 3, 4, or 8 bytes; i.e. 8, 16, 24, 32, or 64 bits.

-.TP

-The flags

-\fB\-b\fR\^/\fB\-w\fR\^/\fB\-l\fR\^/\fB\-d\fR

-which are respectively aliases for

-\fB\-1\fR\^/\fB\-2\fR\^/\fB\-4\fR\^/\fB\-8\fR,

-and abbreviate byte, word, long word, double long (long long) word,

-are retained for backwards compatibility only.

 .SS Output File Format Options

 These options apply only to the output file and may precede only the output

 filename on the command line.

@@ -733,1558 +727,9 @@

 this option is not given, then a default compression factor will apply.

 The compression factor is interpreted differently for different

 compressing file formats.  See the description of the file formats that

-use this option for more information.

-.SH FILE TYPES

-File types can be set by the filename extension or the

-.B \-t

-option (see above). File types that can be determined by a filename

-extension are listed with their names preceded by a dot. File types

-that require an external library, such as ffmpeg or libsndfile, are

-marked e.g. `\fB(ffmpeg)\fR'. File types that can be handled by an

-external library via its pseudo file type (currently libsndfile or

-ffmpeg) are marked e.g. `\fB(also with \-t sndfile)\fR'. This might be

-useful if you have a file that doesn't work with SoX's default format

-readers and writers, and there's an external reader or writer for that

-format.

-.SP

-.TP

-.B .raw (also with \-t sndfile)

-Raw (headerless) audio files.  The sample rate, sample size, and data

-encoding must be given using command-line format options; the number of

-channels defaults to 1.

-.TP

-\&\fB.ub\fR, \fB.sb\fR, \fB.uw\fR, \fB.sw\fR, \fB.ul\fR, \fB.al\fR, \fB.lu\fR, \fB.la\fR, \fB.sl\fR \fB(also with \-t sndfile)\fR

-These filename extensions serve as shorthand for identifying the format

-of headerless audio files.  Thus, \fBub\fR, \fBsb\fR, \fBuw\fR,

-\fBsw\fR, \fBul\fR, \fBal\fR, \fBlu\fR, \fBla\fR and \fBsl\fR indicate a

-file with a single audio channel, sample rate of 8000\ Hz, and samples

-encoded as `unsigned byte', `signed byte', `unsigned word', `signed

-word', `\(*m-law' (byte), `A-law' (byte), inverse bit order `\(*m-law',

-inverse bit order `A-law', or `signed long' respectively.  Command-line

-format options can also be given to modify the selected format if it

-does not provide an exact match for a particular file.

-.SP

-Headerless audio files on a SPARC computer are likely to be of format

-\fBul\fR;  on a Mac, they're likely to be \fBub\fR but with a

-sample rate of 11025 or 22050\ Hz.

-.TP

-.B .8svx (also with \-t sndfile)

-Amiga 8SVX musical instrument description format.

-.TP

-\&\fB.aiff\fR, \fB.aif\fR \fB(also with \-t sndfile)\fR

-AIFF files used on Apple IIc/IIgs and SGI.

-Note: the AIFF format supports only one SSND chunk.

-It does not support multiple audio chunks,

-or the 8SVX musical instrument description format.

-AIFF files are multimedia archives and

-can have multiple audio and picture chunks.

-You may need a separate archiver to work with them.

-.TP

-\&\fB.aiffc\fR, \fB.aifc\fR \fB(also with \-t sndfile)\fR

-AIFF-C (not compressed, linear), defined in DAVIC 1.4 Part 9 Annex B.

-This format is referred from ARIB STD-B24, which is specified for

-Japanese data broadcasting.  Any private chunks are not supported.

-.SP

-Note: The input file is currently processed as .aiff.

-.TP

-.B alsa

-ALSA device driver.

-This is a pseudo-file type and can be optionally compiled into SoX.  Run

-.EX

-	sox -h

-.EE

-to see if you have support for this file type.  When this driver is used

-it allows you to open up a ALSA device and configure it to

-use the same data format as passed in to SoX.

-It works for both playing and recording audio files.  When playing audio

-files it attempts to set up the ALSA driver to use the same format as the

-input file.  It is suggested to always override the output values to use

-the highest quality format your ALSA system can handle.  Example:

-.EX

-	sox infile -t alsa default

-.EE

-.TP

-\&\fB.amr\-wb\fR

-Adaptive Multi Rate\*mWideband speech codec; a lossy format used in 3rd

-generation mobile telephony and defined in 3GPP TS 26.173.

-.SP

-AMR-WB audio has a fixed sampling rate of 16 kHz and supports encoding

-to the following bit-rates (as selected by the

-.B \-C

-option): 0 = 6\*d6 kbit/s, 1 = 8\*d85 kbit/s, 2 = 12\*d65 kbit/s, 3 =

-14\*d25 kbit/s, 4 = 15\*d85 kbit/s 5 = 18\*d25 kbit/s, 6 = 19\*d85

-kbit/s, 7 = 23\*d05 kbit/s, 8 = 23\*d85 kbit/s

-.TP

-.B ao

-libao device driver.

-This is a pseudo-file type and can be optionally compiled into SoX.  Run

-.EX

-	sox -h

-.EE

-to see if you have support for this file type. It works only for

-playing audio files. It can play to a wide range of devices and sound

-systems. See its documentation for the full range. At the moment SoX's

-use of libao cannot be configured directly; you must use libao

-configuration files.

-.TP

-\&\fB.au\fR, \fB.snd\fR \fB(also with \-t sndfile)\fR

-Sun Microsystems AU files.

-There are many types of AU file;

-DEC has invented its own with a different magic number

-and byte order.

-SoX can read these files but will not write them.

-Some .au files are known to have invalid AU headers; these

-are probably original Sun \(*m-law 8000\ Hz files and

-can be dealt with using the

-.B .ul

-format (see below).

-.SP

-It is possible to override AU file header information

-with the

-.B \-r

-and

-.B \-c

-options, in which case SoX will issue a warning to that effect.

-.TP

-\fBauto\fR

-This format type name exists for backwards compatibility only.

-If given for an input file it will be silently ignored,

-if given for an output file it will cause SoX to exit with an error.

-.TP

-.B .avr

-Audio Visual Research.

-The AVR format is produced by a number of commercial packages

-on the Mac.

-.TP

-.B .caf (libsndfile)

-Core Audio File format.

-.TP

-\&\fB.cdda\fR, \fB.cdr\fR

-`Red Book' Compact Disc Digital Audio.

-CDDA has two audio channels formatted as 16-bit

-signed integers at a sample rate of 44\*d1\ kHz.  The number of (stereo)

-samples in each CDDA track is always a multiple of 588 which is why it

-needs its own handler.

-.TP

-\&\fB.cvsd\fR, \fB.cvs\fR

-Continuously Variable Slope Delta modulation.

-A headerless format used to compress speech audio for applications such as voice mail.

-This format is sometimes used with bit-reversed samples\*mthe

-.B \-X

-format option can be used to set the bit-order.

-.TP

-.B .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.  Subsequent lines

-contain two numeric data items: the time since

-the beginning of the first sample and the sample value.

-Values are normalized so that the maximum and minimum

-are 1 and \-1.  This file format can be used to

-create data files for external programs such as

-FFT analysers or graph routines.  SoX can also convert

-a file in this format back into one of the other file

-formats.

-.TP

-\&\fB.dvms\fR, \fB.vms\fR

-Used in Germany to compress speech audio for voice mail.

-A self-describing variant of

-.BR cvsd .

-.TP

-.B .fap (libsndfile)

-See

-.BR .paf .

-.TP

-.B ffmpeg

-This is a pseudo-type that forces ffmpeg to be used. The actual file

-type is deduced from the file name (it cannot be used on stdio). This

-pseudo-type depends on SoX having been built with optional ffmpeg

-support. It can read a wide range of audio files, not all of which are

-documented here, and also the audio track of many video files

-(including AVI, WMV and MPEG). At present only the first audio track

-of a file can be read.

-.TP

-.B .flac (also with \-t sndfile)

-Free Lossless Audio CODEC compressed audio.

-FLAC is an open, patent-free CODEC designed for compressing

-music.  It is similar to MP3 and Ogg Vorbis, but lossless,

-meaning that audio is compressed in FLAC without any loss in

-quality.

-.SP

-SoX can decode native FLAC files (.flac) but not Ogg FLAC files (.ogg).

-[But see

-.B .ogg

-below for information relating to support for Ogg

-Vorbis files.]

-.SP

-SoX has basic support for writing FLAC files: it can encode to

-native FLAC using compression levels 0 to 8.  8 is the default

-compression level and gives the best (but slowest) compression;

-0 gives the least (but fastest) compression.  The compression

-level can be selected using the

-.B \-C

-option (see above) with a whole number from 0 to 8.

-.SP

-FLAC support in

-SoX is optional and requires optional FLAC libraries.  To

-see if there is support for FLAC run

-.EX

-	sox -h

-.EE

-and look for

-it under the list of supported file formats as `flac'.

-.TP

-.B .fssd

-An alias for the

-.B .ub

-format.

-.TP

-.B .gsm (also with \-t sndfile)

-GSM 06.10 Lossy Speech Compression.

-A lossy format for compressing speech which is used in the

-Global Standard for Mobile telecommunications (GSM).  It's good

-for its purpose, shrinking audio data size, but it will introduce

-lots of noise when a given audio signal is encoded and decoded

-multiple times.  This format is used by some voice mail applications.

-It is rather CPU intensive.

-.SP

-GSM in

-SoX is optional and requires access to an external GSM library.  To see

-if there is support for GSM run

-.EX

-	sox -h

-.EE

-and look for it under the list of supported file formats.

-.TP

-.B .hcom

-Macintosh HCOM files.

-These are (apparently) Mac FSSD files with some variant

-of Huffman compression.

-The Macintosh has wacky file formats and this format

-handler apparently doesn't handle all the ones it should.

-Mac users will need their usual arsenal of file converters

-to deal with an HCOM file on other systems.

-.TP

-.B ircam (also with \-t sndfile)

-Another name for

-.BR .sf .

-.TP

-.B .ima (also with \-t sndfile)

-A headerless file of IMA ADPCM audio data. IMA ADPCM claims 16-bit precision

-packed into only 4 bits, but in fact sounds no better than

-.BR .vox .

-.TP

-\&\fB.lpc\fR, \fB.lpc10\fR

-LPC-10 is a compression scheme for speech developed in the United

-States. See http://www.arl.wustl.edu/~jaf/lpc/ for details. There is

-no associated file format, so SoX's implementation is headerless.

-.TP

-\&\fB.mat\fR, \fB.mat4\fR, \fB.mat5\fR \fB(libsndfile)\fR

-Matlab 4.2/5.0 (respectively GNU Octave 2.0/2.1) format (.mat is the same as .mat4).

-.TP

-.B .m3u

-A

-.I playlist

-format; contains a list of audio files.

-See [5] for details of this format.

-.TP

-.B .maud

-An IFF-conforming audio 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, \(*m-law

-in mono and stereo.

-.TP

-\&\fB.mp3\fR, \fB.mp2\fR

-MP3 compressed audio.  MP3 (MPEG Layer 3) is part of the

-MPEG standards for audio and video compression.  It is a lossy

-compression format that achieves good compression rates with little

-quality loss.  See also

-.B Ogg Vorbis

-for a similar format.

-.SP

-MP3 support in

-SoX is optional and requires access to either or both the external

-libmad and libmp3lame libraries. To see if there is support for MP3 run

-.EX

-	sox -h

-.EE

-and look for it under the list of supported file formats as `mp3'.

-.SP

-.TP

-\&\fB.mp4\fR, \fB.m4a\fR \fB(ffmpeg)\fR

-MP4 compressed audio.  MP3 (MPEG 4) is part of the

-MPEG standards for audio and video compression.  See

-.B mp3

+use this option in

+.BR soxformat (7)

 for more information.

-.SP

-MP4 support in SoX is optional and requires access to the external

-ffmpeg libraries.

-.TP

-.B .nist (also with \-t sndfile)

-See \fB.sph\fR.

-.TP

-\&\fB.ogg\fR, \fB.vorbis\fR

-Ogg Vorbis compressed audio.

-Ogg Vorbis is a open, patent-free CODEC designed for compressing music

-and streaming audio.  It is a lossy compression format (similar to MP3,

-VQF & AAC) that achieves good compression rates with a minimum amount of

-quality loss.  See also

-.B MP3

-for a similar format.

-.SP

-SoX can decode all types of Ogg Vorbis files, and can encode at different

-compression levels/qualities given as a number from \-1 (highest

-compression/lowest quality) to 10 (lowest compression, highest quality).

-By default the encoding quality level is 3 (which gives an encoded rate

-of approx. 112kbps), but this can be changed using the

-.B \-C

-option (see above) with a number from \-1 to 10; fractional numbers (e.g.

-3\*d6) are also allowed.

-.SP

-Decoding is somewhat CPU intensive and encoding is very CPU intensive.

-.SP

-Ogg Vorbis in

-SoX is optional and requires access to external Ogg Vorbis libraries.  To

-see if there is support for Ogg Vorbis run

-.EX

-	sox -h

-.EE

-and look for it under the list of supported file formats as `vorbis'.

-.TP

-.B oss

-OSS /dev/dsp device driver.

-This is a pseudo-file that can be optionally compiled into SoX.  Run

-.EX

-	sox -h

-.EE

-to see if it is supported. When this driver is used it allows you to

-play and record sounds on supported systems. When playing audio

-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 format your OSS system can handle. Example:

-.EX

-	sox infile -t oss -2 -s /dev/dsp

-.EE

-.TP

-\&\fB.paf\fR, \fB.fap\fR \fB(libsndfile)\fR

-Ensoniq PARIS file format (big and little-endian respectively).

-.TP

-.B .pls

-A

-.I playlist

-format; contains a list of audio files.

-See [6] for details of this format.

-Note: SHOUTcast PLS is only partially supported.

-.TP

-.B .prc

-Psion Record. Used in Psion EPOC PDAs (Series 5, Revo and similar) for

-System alarms and recordings made by the built-in Record application.

-When writing, SoX defaults to A-law, which is recommended; if you must

-use ADPCM, then use the \fB\-i\fR switch. The sound quality is poor

-because Psion Record seems to insist on frames of 800 samples or

-fewer, so that the ADPCM CODEC has to be reset at every 800 frames,

-which causes the sound to glitch every tenth of a second.

-.TP

-.B .pvf (libsndfile)

-Portable Voice Format.

-.TP

-.B .sd2 (libsndfile)

-Sound Designer 2 format.

-.TP

-.B .sds (libsndfile)

-MIDI Sample Dump Standard.

-.TP

-.B .sf (also with \-t sndfile)

-IRCAM SDIF (Institut de Recherche et Coordination Acoustique/Musique

-Sound Description Interchange Format). Used by academic music software

-such as the CSound package, and the MixView sound sample editor.

-.TP

-\&\fB.sph\fR, \fB.nist\fR \fB(also with \-t sndfile)\fR

-SPHERE (SPeech HEader Resources) is a file format defined by NIST

-(National Institute of Standards and Technology) and is used with

-speech audio.  SoX can read these files when they contain

-\(*m-law and PCM data.  It will ignore any header information that

-says the data is compressed using \fIshorten\fR compression and

-will treat the data as either \(*m-law or PCM.  This will allow SoX

-and the command line \fIshorten\fR program to be run together using

-pipes to encompasses the data and then pass the result to SoX for processing.

-.TP

-.B .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.

-.TP

-.B .snd

-See

-.BR .au .

-.TP

-.B sndfile

-This is a pseudo-type that forces libsndfile to be used. For writing files, the

-actual file type is then taken from the output file name; for reading

-them, it is deduced from the file.

-This pseudo-type depends on SoX having been built with optional

-libsndfile support.

-.TP

-.B .sndt

-SoundTool files. This is an older DOS file format.

-.TP

-.B .sou

-An alias for the

-.B .ub

-format.

-.TP

-.B sunau

-Sun /dev/audio device driver.

-This is a pseudo-file type and can be optionally compiled into SoX.  Run

-.EX

-	sox -h

-.EE

-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 audio files.  When playing audio

-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 format your hardware can handle.  Example:

-.EX

-	sox infile -t sunau -2 -s /dev/audio

-.EE

-or

-.EX

-	sox infile -t sunau -U -c 1 /dev/audio

-.EE

-for older sun equipment.

-.TP

-.B .txw

-Yamaha TX-16W sampler.

-A file format from a Yamaha sampling keyboard which wrote IBM-PC

-format 3\*d5\(dq 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

-33\ kHz if the sample rate is still unknown.

-.TP

-.B .vms

-See

-.BR .dvms .

-.TP

-.B .voc (also with \-t sndfile)

-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 appropriately.

-On output, silence is not detected, nor are impossible sample rates.

-Note, this version now supports playing VOC files with multiple

-blocks and supports playing files containing \(*m-law and A-law samples.

-.TP

-.B .vorbis

-See

-.BR .ogg .

-.TP

-.B .vox (also with \-t sndfile)

-A headerless file of Dialogic/OKI ADPCM audio data commonly comes with the

-extension .vox.  This ADPCM data has 12-bit precision packed into only 4-bits.

-.TP

-.B .w64 (libsndfile)

-Sonic Foundry's 64-bit RIFF/WAV format.

-.TP

-.B .wav \fB(also with \-t sndfile)\fR

-Microsoft .WAV RIFF files.

-This is the native audio file format of Windows, and widely used for uncompressed audio.

-.SP

-Normally \fB.wav\fR 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 \fB.wav\fR

-will written appropriately.

-.SP

-SoX currently can read PCM, \(*m-law, A-law, MS ADPCM, and IMA (or DVI) ADPCM.

-It can write all of these formats including the ADPCM encoding.

-Big endian versions of RIFF files, called RIFX, can also be read

-and written.  To write a RIFX file, use the

-.B \-B

-option with the output file options.

-.TP

-.B .wve

-Psion 8-bit A-law.  Used on Psion SIBO PDAs (Series 3 and similar).

-.TP

-.B .xa

-Maxis XA files.

-These are 16-bit ADPCM audio files used by Maxis games.  Writing .xa files is

-currently not supported, although adding write support should not be very

-difficult.

-.TP

-.B .xi (libsndfile)

-Fasttracker 2 Extended Instrument format.

-.SH EFFECTS

-Multiple effects may be applied to the audio by specifying them

-one after another at the end of the command line.

-.SP

-.I Note:

-Brackets [ ] are used to denote parameters that are optional, braces

-{ } to denote those that are both optional and repeatable,

-and angle brackets < > to denote those that are repeatable but not

-optional.

-.TP

-\fBallpass\fR \fIfrequency width\fR[\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]

-Apply a two-pole all-pass filter with central frequency (in Hz)

-\fIfrequency\fR, and filter-width \fIwidth\fR: in Hz (the default, or if

-appended with `\fBh\fR'), in octaves (if appended with `\fBo\fR'), or as

-a Q-factor (if appended with `\fBq\fR').  An all-pass filter changes the

-audio's frequency to phase relationship without changing its frequency

-to amplitude relationship.  The filter is described in detail in [1].

-.SP

-This effect supports the \fB\-\-plot\fR global option.

-.TP

-\fBband\fR [\fB\-n\fR] \fIcenter\fR [width\fR[\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]]

-Apply a band-pass filter.

-The frequency response drops logarithmically

-around the

-.I center

-frequency.

-The

-.I width

-in Hz (the default, or if appended with `\fBh\fR'), in octaves (if

-appended with `\fBo\fR'), or as a Q-factor (if appended with `\fBq\fR'),

-gives the slope of the drop.

-The frequencies at

-.I center

-+

-.I width

-and

-.I center

-\-

-.I width

-will be half of their original amplitudes.

-.B band

-defaults to a mode oriented to pitched audio,

-i.e. voice, singing, or instrumental music.

-The \fB\-n\fR (for noise) option uses the alternate mode

-for un-pitched audio (e.g. percussion).

-.B Warning:

-\fB\-n\fR introduces a power-gain of about 11dB in the filter, so beware

-of output clipping.

-.B band

-introduces noise in the shape of the filter,

-i.e. peaking at the

-.I center

-frequency and settling around it.

-.SP

-This effect supports the \fB\-\-plot\fR global option.

-.SP

-See also \fBfilter\fR for a bandpass filter with steeper shoulders.

-.TP

-\fBbandpass\fR\^|\^\fBbandreject\fR [\fB\-c\fR] \fIfrequency width\fR[\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]

-Apply a two-pole Butterworth band-pass or band-reject filter with

-central frequency (in Hz) \fIfrequency\fR, and (3dB-point) band-width

-\fIwidth\fR: in Hz (the default, or if appended with `\fBh\fR'), in

-octaves (if appended with `\fBo\fR'), or as a Q-factor (if appended with

-`\fBq\fR').  The

-.B \-c

-option applies only to

-.B bandpass

-and selects a constant skirt gain (peak gain = Q) instead of the

-default: constant 0dB peak gain.

-The filters roll off at 6dB per octave (20dB per decade)

-and are described in detail in [1].

-.SP

-These effects support the \fB\-\-plot\fR global option.

-.SP

-See also \fBfilter\fR for a bandpass filter with steeper shoulders.

-.TP

-\fBbandreject \fIfrequency width\fR[\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]

-Apply a band-reject filter.

-See the description of the \fBbandpass\fR effect for details.

-.TP

-\fBbass\fR\^|\^\fBtreble \fIgain\fR [\fIfrequency\fR [\fIwidth\fR[\fBs\fR\^|\^\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]]]

-Boost or cut the bass (lower) or treble (upper) frequencies of the audio

-using a two-pole shelving filter with a response similar to that

-of a standard hi-fi's (Baxandall) tone-controls.  This is also

-known as shelving equalisation (EQ).

-.SP

-\fIgain\fR gives the dB gain at 0\ Hz (for \fBbass\fR), or whichever is

-the lower of \(ap22\ kHz and the Nyquist frequency (for \fBtreble\fR).  Its

-useful range is about \-20 (for a large cut) to +20 (for a large

-boost).

-Beware of

-.B Clipping

-when using a positive \fIgain\fR.

-.SP

-If desired, the filter can be fine-tuned using the following

-optional parameters:

-.SP

-\fIfrequency\fR sets the filter's central frequency and so can be

-used to extend or reduce the frequency range to be boosted or

-cut.  The default value is 100\ Hz (for \fBbass\fR) or 3\ kHz (for

-\fBtreble\fR).

-.SP

-\fIwidth\fR

-determines how

-steep the filter's shelf transition is and can be expressed as:

-a `slope' (the default, or if appended with `\fBs\fR'),

-a Q-factor (if appended with `\fBq\fR'),

-the transition width in octaves (if appended with `\fBo\fR'),

-or the transition width in Hz (if appended with `\fBh\fR').

-The useful range of `slope' is

-about 0\*d3, for a gentle slope, to 1 (the maximum), for a steep slope; the

-default value is 0\*d5.

-.SP

-The filters are described in detail in [1].

-.SP

-These effects support the \fB\-\-plot\fR global option.

-.SP

-See also \fBequalizer\fR for a peaking equalisation effect.

-.TP

-\fBchorus \fIgain-in gain-out\fR <\fIdelay decay speed depth \fB\-s\fR\^|\^\fB\-t\fR>

-Add a chorus effect to the audio.  Each four-tuple

-delay/decay/speed/depth gives the delay in milliseconds

-and the decay (relative to gain-in) with a modulation

-speed in Hz using depth in milliseconds.

-The modulation is either sinusoidal (\fB\-s\fR) or triangular

-(\fB\-t\fR).  Gain-out is the volume of the output.

-.TP

-\fBcompand \fIattack1\fB,\fIdecay1\fR{\fB,\fIattack2\fB,\fIdecay2\fR}

-[\fIsoft-knee-dB\fB:\fR]\fIin-dB1\fR[\fB,\fIout-dB1\fR]{\fB,\fIin-dB2\fB,\fIout-dB2\fR}

-.br

-[\fIgain\fR [\fIinitial-volume-dB\fR [\fIdelay\fR]]]

-.SP

-Compand (compress or expand) the dynamic range of the audio.  The

-attack and decay time specify the integration time over which the

-absolute value of the input signal is integrated to determine its

-volume; attacks refer to increases in volume and decays refer to

-decreases.  Where more than one pair of attack/decay parameters are

-specified, each channel is treated separately and the number of pairs

-must agree with the number of input channels.  The second parameter is

-a list of points on the compander's transfer function specified in dB

-relative to the maximum possible signal amplitude.  The input values

-must be in a strictly increasing order but the transfer function does

-not have to be monotonically rising.  The special value \fB\-inf\fR may

-be used to indicate that the input volume should be associated output

-volume.  The points \fB\-inf,\-inf\fR and \fB0,0\fR are assumed; the

-latter may be overridden, but the former may not.

-.SP

-The third

-(optional) parameter is a post-processing gain in dB which is applied

-after the compression has taken place; the fourth (optional) parameter

-is an initial volume to be assumed for each channel when the effect

-starts.  This permits the user to supply a nominal level initially, so

-that, for example, a very large gain is not applied to initial signal

-levels before the companding action has begun to operate: it is quite

-probable that in such an event, the output would be severely clipped

-while the compander gain properly adjusts itself.

-.SP

-The fifth (optional) parameter is a delay in seconds.

-The input signal is analysed immediately to control the compander, but

-it is delayed before being fed to the volume adjuster.

-Specifying a delay approximately equal to the attack/decay times

-allows the compander to effectively operate in a `predictive' rather than a

-reactive mode.

-.SP

-This effect supports the \fB\-\-plot\fR global option (for the transfer function).

-.SP

-See also

-.B mcompand

-for a multiple-band companding effect.

-.TP

-\fBdcshift \fIshift\fR [\fIlimitergain\fR]

-DC Shift the audio, with basic linear amplitude formula.

-This is most useful if your audio tends to not be centered around

-a value of 0.  Shifting it back will allow you to get the most volume

-adjustments without clipping.

-.SP

-The first option is the \fIdcshift\fR value.  It is a floating point number that

-indicates the amount to shift.

-.SP

-An optional

-.I limitergain

-can be specified as well.  It should have a value much less than 1

-(e.g. 0\*d05 or 0\*d02) and is used only on peaks to prevent clipping.

-.TP

-\fBdeemph\fR

-Apply a treble attenuation shelving filter to audio in

-audio-CD format.  The frequency response of pre-emphasized

-recordings is rectified.  The filter is defined in the

-standard document ISO 908.

-.SP

-This effect supports the \fB\-\-plot\fR global option.

-.SP

-See also the \fBbass\fR and \fBtreble\fR shelving equalisation effects.

-.TP

-\fBdither\fR [\fIdepth\fR]

-Apply dithering to the audio.

-Dithering deliberately adds digital white noise to the signal

-in order to mask audible quantization effects that

-can occur if the output sample size is less than 24 bits.

-By default, the amount of noise added is \(12 bit;

-the optional \fIdepth\fR parameter is a (linear or voltage)

-multiplier of this amount.

-.SP

-This effect should not be followed by any other effect that

-affects the audio.

-.TP

-\fBearwax\fR

-Makes audio easier to listen to on headphones.

-Adds `cues' to audio in audio-CD format so that

-when listened to on headphones the stereo image is

-moved from inside

-your head (standard for headphones) to outside and in front of the

-listener (standard for speakers).  See

-http://www.geocities.com/beinges

-for a full explanation.

-.TP

-\fBecho \fIgain-in gain-out\fR <\fIdelay decay\fR>

-Add echoing to the audio.

-Each

-.I "delay decay"

-pair gives the delay in milliseconds

-and the decay (relative to gain-in) of that echo.

-Gain-out is the volume of the output.

-.TP

-\fBechos \fIgain-in gain-out\fR <\fIdelay decay\fR>

-Add a sequence of echos to the audio.

-Each

-.I "delay decay"

-pair gives the delay in milliseconds

-and the decay (relative to gain-in) of that echo.

-Gain-out is the volume of the output.

-.TP

-\fBequalizer \fIfrequency width\fR[\fBq\fR\^|\^\fBo\fR\^|\^\fBh\fR] \fIgain\fR

-Apply a two-pole peaking equalisation (EQ) filter.

-With this filter, the signal-level at and around a selected frequency

-can be increased or decreased, whilst (unlike band-pass and band-reject

-filters) that at all other frequencies is unchanged.

-.SP

-\fIfrequency\fR gives the filter's central frequency in Hz,

-\fIwidth\fR, the band-width,

-as a Q-factor [2] (the default, or if appended with `\fBq\fR'),

-in octaves (if appended with `\fBo\fR'),

-or in Hz (if appended with `\fBh\fR'),

-and \fIgain\fR the required gain

-or attenuation in dB.

-Beware of

-.B Clipping

-when using a positive \fIgain\fR.

-.SP

-In order to produce complex equalisation curves, this effect

-can be given several times, each with a different central frequency.

-.SP

-The filter is described in detail in [1].

-.SP

-This effect supports the \fB\-\-plot\fR global option.

-.SP

-See also \fBbass\fR and \fBtreble\fR for shelving equalisation effects.

-.TP

-\fBfade\fR [\fItype\fR] \fIfade-in-length\fR [\fIstop-time\fR [\fIfade-out-length\fR]]

-Add a fade effect to the beginning, end, or both of the audio.

-.SP

-For fade-ins, this starts from the first sample and ramps the volume of the audio from 0 to full volume over \fIfade-in-length\fR seconds.  Specify 0 seconds if no fade-in is wanted.

-.SP

-For fade-outs, the audio will be truncated at

-.I stop-time

-and

-the volume will be ramped from full volume down to 0 starting at

-\fIfade-out-length\fR seconds before the \fIstop-time\fR.  If

-.I fade-out-length

-is not specified, it defaults to the same value as

-\fIfade-in-length\fR.

-No fade-out is performed if

-.I stop-time

-is not specified.

-.SP

-All times can be specified in either periods of time or sample counts.

-To specify time periods use the format hh:mm:ss.frac format.  To specify

-using sample counts, specify the number of samples and append the letter `s'

-to the sample count (for example `8000s').

-.SP

-An optional \fItype\fR can be specified to change the type of envelope.  Choices are \fBq\fR for quarter of a sine wave, \fBh\fR for half a sine wave, \fBt\fR for linear slope, \fBl\fR for logarithmic, and \fBp\fR for inverted parabola.  The default is a linear slope.

-.TP

-\fBfilter\fR [\fIlow\fR]\fB\-\fR[\fIhigh\fR] [\fIwindow-len\fR [\fIbeta\fR]]

-Apply a sinc-windowed lowpass, highpass, or bandpass filter of given

-window length to the signal.

-\fIlow\fR refers to the frequency of the lower 6dB corner of the filter.

-\fIhigh\fR refers to the frequency of the upper 6dB corner of the filter.

-.SP

-A low-pass filter is obtained by leaving \fIlow\fR unspecified, or 0.

-A high-pass filter is obtained by leaving \fIhigh\fR unspecified, or 0,

-or greater than or equal to the Nyquist frequency.

-.SP

-The \fIwindow-len\fR, if unspecified, defaults to 128.

-Longer windows give a sharper cutoff, smaller windows a more gradual cutoff.

-.SP

-The \fIbeta\fR, if unspecified, defaults to 16.  This selects a Kaiser window.

-You can select a Nuttall window by specifying anything \(<= 2 here.

-For more discussion of beta, look under the \fBresample\fR effect.

-.SP

-.TP

-\fBflanger\fR [\fIdelay depth regen width speed shape phase interp\fR]

-Apply a flanging effect to the audio.

-All parameters are optional (right to left).

-.TS

-center box;

-cB cB cB lB

-cI c c l.

-\ 	Range	Default	Description

-delay	0 \- 10	0	Base delay in milliseconds.

-depth	0 \- 10	2	Added swept delay in milliseconds.

-regen	\-95 \- 95	0	T{

-.na

-Percentage regeneration (delayed signal feedback).

-T}

-width	0 \- 100	71	T{

-.na

-Percentage of delayed signal mixed with original.

-T}

-speed	0\*d1 \- 10	0\*d5	Sweeps per second (Hz).

-shape	\ 	sin	Swept wave shape: \fBsine\fR\^|\^\fBtriangle\fR.

-phase	0 \- 100	25	T{

-.na

-Swept wave percentage phase-shift for multi-channel (e.g. stereo) flange;

-0 = 100 = same phase on each channel.

-T}

-interp	\ 	lin	T{

-.na

-Digital delay-line interpolation: \fBlinear\fR\^|\^\fBquadratic\fR.

-T}

-.TE

-.DT

-.SP

-See [3] for a detailed description of flanging.

-.TP

-\fBhighpass\fR\^|\^\fBlowpass\fR [\fB-1\fR|\fB-2\fR] \fIfrequency\fR [\fRwidth\fR[\fBq\fR\^|\^\fBo\fR\^|\^\fBh\fR]]

-Apply a high-pass or low-pass filter with 3dB point \fIfrequency\fR.

-The filter can be either single-pole (with

-.BR \-1 ),

-or double-pole (the default, or with

-.BR \-2 ).

-.I width

-applies only to double-pole filters and is the filter-width: as a

-Q-factor (the default, or if appended with `\fBq\fR'), in octaves (if

-appended with `\fBo\fR'), or in Hz (if appended with `\fBh\fR');

-the default Q is 0\*d707 and gives a Butterworth response.  The filters

-roll off at 6dB per pole per octave (20dB per pole per decade).  The

-double-pole filters are described in detail in [1].

-.SP

-These effects support the \fB\-\-plot\fR global option.

-.SP

-See also \fBfilter\fR for filters with a steeper roll-off.

-.TP

-\fBlowpass\fR [\fB-1\fR|\fB-2\fR] \fIfrequency\fR [\fRwidth\fR[\fBq\fR\^|\^\fBo\fR\^|\^\fBh\fR]]

-Apply a low-pass filter.

-See the description of the \fBhighpass\fR effect for details.

-.TP

-\fBmcompand\fR \(dq\fIattack1\fB,\fIdecay1\fR{\fB,\fIattack2\fB,\fIdecay2\fR}

-[\fIsoft-knee-dB\fB:\fR]\fIin-dB1\fR[\fB,\fIout-dB1\fR]{\fB,\fIin-dB2\fB,\fIout-dB2\fR}

-.br

-[\fIgain\fR [\fIinitial-volume-dB\fR [\fIdelay\fR]]]\(dq {\fIxover-freq\fR \(dqattack1,...\(dq}

-.SP

-The multi-band compander is similar to the single-band compander but the

-audio is first divided into bands using Butterworth cross-over filters

-and a separately specifiable compander run on each band.  See the

-\fBcompand\fR effect for the definition of its parameters.  Compand

-parameters are specified between double quotes and the crossover

-frequency for that band is given by \fIxover-freq\fR; these can be

-repeated to create multiple bands.

-.SP

-See also

-.B compand

-for a single-band companding effect.

-.TP

-\fBmixer\fR [ \fB\-l\fR\^|\^\fB\-r\fR\^|\^\fB\-f\fR\^|\^\fB\-b\fR\^|\^\fB\-1\fR\^|\^\fB\-2\fR\^|\^\fB\-3\fR\^|\^\fB\-4\fR\^|\^\fIn\fR{\fB,\fIn\fR} ]

-Reduce the number of audio channels by mixing or selecting channels,

-or increase the number of channels by duplicating channels.

-Note: this effect operates on the audio

-.I channels

-within the SoX effects processing chain; it should not be confused with the

-.B \-m

-global option (where multiple

-.I files

-are mix-combined before entering the effects chain).

-.SP

-This effect is automatically used when the number of input

-channels differ from the number of output channels.  When reducing

-the number of channels it is possible to manually specify the

-.B mixer

-effect and use the \fB\-l\fR, \fB\-r\fR, \fB\-f\fR, \fB\-b\fR,

-\fB\-1\fR, \fB\-2\fR, \fB\-3\fR, \fB\-4\fR, options to select only

-the left, right, front, back channel(s) or specific channel

-for the output instead of averaging the channels.

-The \fB\-l\fR, and \fB\-r\fR options will do averaging

-in quad-channel files so select the exact channel to prevent this.

-.SP

-The

-.B mixer

-effect can also be invoked with up to 16

-numbers, separated by commas, which specify the proportion (0 = 0% and 1 = 100%)

-of each input channel that is to be mixed into each output channel.

-In two-channel mode, 4 numbers are given: l \*(RA l, l \*(RA r, r \*(RA l, and r \*(RA r,

-respectively.

-In four-channel mode, the first 4 numbers give the proportions for the

-left-front output channel, as follows: lf \*(RA lf, rf \*(RA lf, lb \*(RA lf, and

-rb \*(RA rf.

-The next 4 give the right-front output in the same order, then

-left-back and right-back.

-.SP

-It is also possible to use the 16 numbers to expand or reduce the

-channel count; just specify 0 for unused channels.

-.SP

-Finally, certain reduced combination of numbers can be specified

-for certain input/output channel combinations.

-.TS

-center box ;

-cB cB cB lB

-c c c l .

-In Ch	Out Ch	Num	Mappings

-2	1	2	l \*(RA l, r \*(RA l

-2	2	1	adjust balance

-4	1	4	lf \*(RA l, rf \*(RA l, lb \*(RA l, rb \*(RA l

-4	2	2	lf \*(RA l&rf \*(RA r, lb \*(RA l&rb \*(RA r

-4	4	1	adjust balance

-4	4	2	front balance, back balance

-.TE

-.DT

-.SP

-.TP

-\fBnoiseprof\fR [\fIprofile-file\fR]

-Calculate a profile of the audio for use in noise reduction.

-See the description of the \fBnoisered\fR effect for details.

-.TP

-\fBnoisered \fIprofile-file\fR [\fIthreshold\fR]

-Noise reduction filter with profiling.  This filter is moderately effective at

-removing consistent background noise such as hiss or hum.  To use it, first run

-the \fBnoiseprof\fR effect on a section of audio that ideally would

-contain silence but in fact contains noise.

-The \fBnoiseprof\fR effect will write out a noise profile

-to \fIprofile-file\fR, or to stdout if no \fIprofile-file\fR is specified.

-If there is audio output on stdout then the profile will instead be directed to

-stderr.

-.SP

-To actually remove the noise, run

-SoX again with the \fInoisered\fR filter.  The

-filter needs one parameter, \fIprofile-file\fR, which contains the noise profile

-from \fBnoiseprof\fR.  \fIthreshold\fR specifies how much noise should be removed, and

-may be between 0 and 1 with a default of 0\*d5.  Higher values will remove more

-noise but present a greater likelihood of distorting the desired audio signal.

-Using headphones to check the results, experiment with different

-threshold values to find the optimal one for your audio; pay special

-attention to quieter sections.

-.TP

-\fBpad\fR { \fIlength\fR[\fB@\fIposition\fR] }

-Pad the audio with silence, at the beginning, the end, or any

-specified points through the audio.

-Both

-.I length

-and

-.I position

-can specify a time or, if appended with an `s', a number of samples.

-.I length

-is the amount of silence to insert and

-.I position

-the position in the input audio stream at which to insert it.

-Any number of lengths and positions may be specified, provided that

-a specified position is not less that the previous one.

-.I position

-is optional for the first and last lengths specified and

-if omitted correspond to the beginning and the end of the audio respectively.

-For example:

-.B pad 1\*d5 1\*d5

-adds 1\*d5 seconds of silence padding at each end of the audio, whilst

-.B pad 4000s@3:00

-inserts 4000 samples of silence 3 minutes into the audio.

-If silence is wanted only at the end of the audio, specify either the end

-position or specify a zero-length pad at the start.

-.TP

-\fBpan \fIdirection\fR

-Pan the audio from one channel to another.  This is done by

-changing the volume of the input channels so that it fades out on one

-channel and fades-in on another.  If the number of input channels is

-different then the number of output channels then this effect tries to

-intelligently handle this.  For instance, if the input contains 1 channel

-and the output contains 2 channels, then it will create the missing channel

-itself.  The

-.I direction

-is a value from \-1 to 1.  \-1 represents

-far left and 1 represents far right.  Numbers in between will start the

-pan effect without totally muting the opposite channel.

-.TP

-\fBphaser \fIgain-in gain-out delay decay speed\fR [\fB\-s\fR\^|\^\fB\-t\fR]

-Add a phasing effect to the audio.

-delay/decay/speed gives the delay in milliseconds

-and the decay (relative to gain-in) with a modulation

-speed in Hz.

-The modulation is either sinusoidal (\fB\-s\fR) or triangular

-(\fB\-t\fR).  The decay should be less than 0\*d5 to avoid

-feedback.  Gain-out is the volume of the output.

-.TP

-\fBpitch \fIshift\fR [\fIwidth interpolate fade\fR]

-Change the pitch of file without affecting its duration by cross-fading

-shifted samples.

-.I shift

-is given in cents.  Use a positive value to shift to treble, negative value to shift to bass.

-Default shift is 0.

-.I width

-of window is in ms.  Default width is 20ms.  Try 30ms to lower pitch,

-and 10ms to raise pitch.

-.I interpolate

-option, can be \fBcubic\fR or \fBlinear\fR.  Default is \fBcubic\fR.  The

-.I fade

-option, can be \fBcos\fR, \fBhamming\fR, \fBlinear\fR or

-\fBtrapezoid\fR; the default is \fBcos\fR.

-.TP

-\fBpolyphase\fR [\fB\-w nut\fR\^|\^\fBham\fR] [\fB\-width \fIn\fR] [\fB\-cutoff \fIc\fR]

-Change the sampling rate using `polyphase interpolation', a DSP algorithm.

-This method is relatively slow and memory intensive.

-.SP

-If the \fB\-w\fR parameter is \fBnut\fR, then a Nuttall (~90 dB

-stop-band) window will be used; \fBham\fR selects a Hamming (~43

-dB stop-band) window.  The default is Nuttall.

-.SP

-The \fB\-width\fR parameter specifies the (approximate) width of the filter. The default is 1024 samples, which produces reasonable results.

-.SP

-The \fB\-cutoff\fR value (\fIc\fR) specifies the filter cutoff frequency in terms of fraction of

-frequency bandwidth, also know as the Nyquist frequency.  See

-the \fBresample\fR effect for

-further information on Nyquist frequency.  If up-sampling, then this is the

-fraction of the original signal

-that should go through.  If down-sampling, this is the fraction of the

-signal left after down-sampling.  The default is 0\*d95.

-.SP

-See also

-.B rabbit

-and

-.B resample

-for other sample-rate changing effects.

-.TP

-\fBrabbit\fR [\fB\-c0\fR\^|\^\fB\-c1\fR\^|\^\fB\-c2\fR\^|\^\fB\-c3\fR\^|\^\fB\-c4\fR]

-Change the sampling rate using `libsamplerate', also known as `Secret Rabbit

-Code'.  This effect is

-optional and must have been selected at compile time of SoX.  See

-http://www.mega-nerd.com/SRC for details of the algorithms.  Algorithms

-0 through 2 are progressively faster and lower quality versions of the

-sinc algorithm; the default is \fB\-c0\fR, which is probably the best

-quality algorithm for general use currently available in SoX.

-Algorithm 3 is zero-order hold, and 4 is linear interpolation.

-.SP

-See also

-.B polyphase

-and

-.B resample

-for other sample-rate changing effects, and see

-\fBresample\fR for more discussion of resampling.

-.TP

-\fBrepeat \fIcount\fR

-Repeat the entire audio \fIcount\fR times.

-Requires disk space to store the data to be repeated.

-Note that repeating once yields two copies: the original audio and the

-repeated audio.

-.TP

-\fBresample\fR [\fB\-qs\fR\^|\^\fB\-q\fR\^|\^\fB\-ql\fR] [\fIrolloff\fR [\fIbeta\fR]]

-Change the sampling rate using simulated

-analog filtration.  Other rate changing effects available are

-\fBpolyphase\fR and \fBrabbit\fR.  There is a detailed analysis of

-\fBresample\fR and \fBpolyphase\fR at

-http://leute.server.de/wilde/resample.html; see \fBrabbit\fR for a

-pointer to its own documentation.

-.SP

-By default, linear interpolation is used,

-with a window width about 45 samples at the lower of the two rates.

-This gives an accuracy of about 16 bits, but insufficient stop-band rejection

-in the case that you want to have roll-off greater than about 0\*d8 of

-the Nyquist frequency.

-.SP

-The \fB\-q*\fR options will change the default values for roll-off and beta

-as well as use quadratic interpolation of filter

-coefficients, resulting in about 24 bits precision.

-The \fB\-qs\fR, \fB\-q\fR, or \fB\-ql\fR options specify increased accuracy

-at the cost of lower execution speed.  It is optional to specify

-roll-off and beta parameters when using the \fB\-q*\fR options.

-.SP

-Following is a table of the reasonable defaults which are built-in to

-SoX:

-.SP

-.TS

-center box;

-cB cB cB cB cB

-c c n c c

-cB c n c c.

-Option	Window	Roll-off	Beta	Interpolation

-(none)	45	0\*d80	16	linear

-\-qs	45	0\*d80	16	quadratic

-\-q	75	0\*d875	16	quadratic

-\-ql	149	0\*d94	16	quadratic

-.TE

-.DT

-.SP

-\fB\-qs\fR, \fB\-q\fR, or \fB\-ql\fR 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.

-.SP

-\fIrolloff\fR 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 practise 0\*d8\-0\*d95.  The defaults are

-indicated above.

-.SP

-The \fINyquist frequency\fR is equal to half the sample rate.  Logically,

-this is because the A/D converter needs at least 2 samples to detect 1

-cycle at the Nyquist frequency.  Frequencies higher then the Nyquist

-will actually appear as lower frequencies to the A/D converter and

-is called aliasing.  Normally, A/D converts run the signal through

-a lowpass filter first to avoid these problems.

-.SP

-Similar problems will happen in software when reducing the sample rate of

-an audio file (frequencies above the new Nyquist frequency can be aliased

-to lower frequencies).  Therefore, a good resample effect

-will remove all frequency information above the new Nyquist frequency.

-.SP

-The \fIrolloff\fR refers to how close to the Nyquist frequency this cutoff

-is, with closer being better.  When increasing the sample rate of an

-audio file you would not expect to have any frequencies exist that are

-past the original Nyquist frequency.  Because of resampling properties, it

-is common to have aliasing artifacts created above the old

-Nyquist frequency.  In that case the \fIrolloff\fR refers to how close

-to the original Nyquist frequency to use a highpass filter to remove

-these artifacts, with closer also being better.

-.SP

-The \fIbeta\fR parameter

-determines the type of filter window used.  Any value greater than 2 is

-the beta for a Kaiser window.  Beta \(<= 2 selects a Nuttall window.

-If unspecified, the default is a Kaiser window with beta 16.

-.SP

-In the case of Kaiser window (beta > 2), lower betas produce a somewhat

-faster transition from pass-band to stop-band, 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 not need to use the beta parameter at all, unless you are

-just curious about comparing the effects of Nuttall vs. Kaiser windows.

-.SP

-This is the default effect if the two files have different sampling rates.

-Default parameters are, as indicated above, Kaiser window of length 45,

-roll-off 0\*d80, beta 16, linear interpolation.

-.SP

-Note: \fB\-qs\fR is only slightly slower, but more accurate for

-16-bit or higher precision.

-.SP

-Note: In many cases of up-sampling, no interpolation is needed,

-as exact filter coefficients can be computed in a reasonable amount of space.

-To be precise, this is done when both input-rate < output-rate, and

-output-rate \(di gcd(input-rate, output-rate) \(<= 511.

-.TP

-\fBreverb \fIgain-out reverb-time\fR <\fIdelay\fR>

-Add reverberation to the audio.  Each

-.I delay

-is given

-in milliseconds and its feedback is depending on the

-.I reverb-time

-in milliseconds.  Each

-.I delay

-should be in

-the range of half to quarter of

-.I reverb-time

-to get a realistic reverberation.

-.I gain-out

-is the volume of the output.

-.TP

-\fBreverse\fR

-Reverse the audio completely.

-Requires disk space to store the data to be reversed.

-.TP

-\fBsilence \fR[\fB\-l\fR] \fIabove-periods\fR [\fIduration threshold\fR[\fBd\fR\^|\^\fB%\fR] [\fIbelow-periods duration threshold\fR[\fBd\fR\^|\^\fB%\fR]]

-.SP

-Removes silence from the beginning, middle, or end of the audio.  Silence is anything below a specified threshold.

-.SP

-The \fIabove-periods\fR value is used to indicate if audio should be trimmed at

-the beginning of the audio.  A value of zero indicates no silence

-should be trimmed from the beginning.  When specifying 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 audio 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.

-.SP

-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 audio.  By increasing the duration, burst of noise can be treated as silence and trimmed off.

-.SP

-\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 the value to account

-for background noise.

-.SP

-When optionally trimming silence from the end of the audio, you specify

-a \fIbelow-periods\fR count.  In this case, \fIbelow-period\fR means

-to remove all audio 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.

-.SP

-For \fIbelow-periods\fR, \fIduration\fR specifies a period of silence

-that must exist before audio 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.

-.SP

-Unfortunately, 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 \fBsilence\fR effect in combination with the \fBreverse\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.

-.SP

-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 audio.

-.SP

-The option

-.B \-l

-indicates that \fIbelow-periods\fR \fIduration\fR length of audio

-should be left intact at the beginning of each period of silence.

-For example, if you want to remove long pauses between words

-but do not want to remove the pauses completely.

-.SP

-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 with

-.B d

-to indicate the value is in decibels, or

-.B %

-to indicate a percentage of maximum value of the sample value (\fB0%\fR specifies pure digital silence).

-.TP

-\fBspeed \fIfactor\fR[\fBc\fR]

-Adjust the audio speed (pitch and tempo together).  \fIfactor\fR

-is either the ratio of the new speed to the old speed: greater

-than 1 speeds up, less than 1 slows down, or, if appended with the

-letter

-`c', the number of cents (i.e. 100ths of a semitone) by

-which the pitch (and tempo) should be adjusted: greater than 0

-increases, less than 0 decreases.

-.SP

-By default, the speed change is performed by the \fBresample\fR

-effect with its default parameters.  For higher quality

-resampling, in addition to the \fBspeed\fR effect, specify

-either the \fBresample\fR or the \fBrabbit\fR effect with

-appropriate parameters.

-.TP

-\fBstat\fR [\fB\-s \fIn\fR] [\fB\-rms\fR] [\fB\-freq\fR] [\fB\-v\fR] [\fB\-d\fR]

-Do a statistical check on the input file,

-and print results on the standard error file.  Audio is passed

-unmodified through the SoX processing chain.

-.SP

-The `Volume Adjustment:' field in the statistics

-gives you the parameter to the

-.B \-v

-.I number

-which will make the audio as loud as possible without clipping.

-Note: See the discussion on

-.B Clipping

-above for reasons why it is rarely a good idea to actually do this.

-.SP

-The option

-.B \-v

-will print out the `Volume Adjustment:' field's value only and

-return.  This could be of use in scripts to auto convert the

-volume.

-.SP

-The

-.B \-s

-option is used to scale the input data by a given factor.  The default value

-of

-.I 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.

-.SP

-The

-.B \-rms

-option will convert all output average values to `root mean square'

-format.

-.SP

-The

-.B \-freq

-option calculates the input's power spectrum and prints it to standard error.

-.SP

-There is also an optional parameter

-.B \-d

-that will print out a hex dump of the

-audio 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.

-.TP

-\fBstretch \fIfactor\fR [\fIwindow fade shift fading\fR]

-Time stretch the audio by the given factor.  Changes duration without affecting the pitch.

-.I factor

-of stretching: >1 lengthen, <1 shorten duration.

-.I window

-size is in ms.  Default is 20ms.  The

-.I fade

-option, can be `lin'.

-.I shift

-ratio, in [0 1].  Default depends on stretch factor. 1

-to shorten, 0\*d8 to lengthen.  The

-.I fading

-ratio, in [0 0\*d5].  The amount of a fade's default depends on

-.I factor

-and \fIshift\fR.

-.TP

-\fBswap\fR [\fI1 2\fR | \fI1 2 3 4\fR]

-Swap channels in multi-channel audio 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,

-.B swap 2 2

-will overwrite channel 1 with channel 2; creating a stereo

-file with both channels containing the same audio.

-.TP

-\fBsynth\fR [\fIlen\fR] {[\fItype\fR] [\fIcombine\fR] [\fIfreq\fR[\fI\-freq2\fR]] [\fIoff\fR] [\fIph\fR] [\fIp1\fR] [\fIp2\fR] [\fIp3\fR]}

-This effect can be used to generate fixed or swept frequency audio tones

-with various wave shapes, or to generate wide-band noise of various

-`colours'.

-Multiple synth effects can be cascaded to produce more complex

-waveforms; at each stage it is possible to choose whether the generated

-waveform will be mixed with, or modulated onto

-the output from the previous stage.

-Audio for each channel in a multi-channel audio file can be synthesised

-independently.

-.SP

-Though this effect is used to generate audio, an input file must still

-be given, the characteristics of which will be used to set the

-synthesised audio length, the number of channels, and the sampling rate;

-however, since the input file's audio is not normally needed, a `null

-file' (with the special name \fB-n\fR) is often given instead (and the

-length specified as a parameter to \fBsynth\fR or by another given

-effect that can has an associated length).

-.SP

-For example, the following produces a 3 second, 44\*d1\ kHz,

-stereo audio file containing a sine-wave swept from 300 to 3300\ Hz:

-.EX

-	sox -n output.au synth 3 sine 300-3300

-.EE

-and this produces an 8\ kHz mono version:

-.EX

-	sox -r 8000 -c 1 -n output.au synth 3 sine 300-3300

-.EE

-Multiple channels can be synthesised by specifying the set of

-parameters shown between braces multiple times;

-the following puts the swept tone in the left channel and adds `brown'

-noise in the right:

-.EX

-	sox -n output.au synth 3 sine 300-3300 brownnoise

-.EE

-The following example shows how two synth effects can be cascaded

-to create a more complex waveform:

-.EX

-	sox -n output.au synth 0\*d5 sine 200-500 \(rs

-		synth 0\*d5 sine fmod 700-100

-.EE

-Frequencies can also be given as a number of musical semitones relative

-to `middle A' (440\ Hz) by prefixing a `%' character;  for example, the

-following could be used to help tune a guitar's `E' strings:

-.EX

-	play -n synth sine %-17

-.EE

-.B N.B.

-This effect generates audio at maximum volume, which means that there

-is a high chance of clipping when using the audio subsequently, so

-in most cases, you will want to follow this effect with the \fBvol\fR

-effect to prevent this from happening. (See also

-.B Clipping

-above.)

-.SP

-A detailed description of each

-.B synth

-parameter follows:

-.SP

-\fIlen\fR is the length of audio to synthesise expressed as a time

-or as a number of samples;

-0=inputlength, default=0.

-.SP

-The format for specifying lengths in time is hh:mm:ss.frac.  The format

-for specifying sample counts is the number of samples with the letter

-`s' appended to it.

-.SP

-\fItype\fR is one of sine, square, triangle, sawtooth, trapezium, exp,

-[white]noise, pinknoise, brownnoise; default=sine

-.SP

-\fIcombine\fR is one of create, mix, amod (amplitude modulation), fmod

-(frequency modulation); default=create

-.SP

-\fIfreq\fR/\fIfreq2\fR are the frequencies at the beginning/end of

-synthesis in Hz or, if preceded with `%', semitones relative to A

-(440\ Hz); for both, default=%0.  If

-.I freq2

-is given, then

-.I len

-must also have been given.

-Not used for noise.

-.SP

-\fIoff\fR is the bias (DC-offset) of the signal in percent; default=0.

-.SP

-\fIph\fR is the phase shift in percentage of 1 cycle; default=0.  Not

-used for noise.

-.SP

-\fIp1\fR is the percentage of each cycle that is `on' (square), or

-`rising' (triangle, exp, trapezium); default=50 (square, triangle, exp),

-default=10 (trapezium).

-.SP

-\fIp2\fR (trapezium): the percentage through each cycle at which `falling'

-begins; default=50. exp: the amplitude in percent; default=100.

-.SP

-\fIp3\fR (trapezium): the percentage through each cycle at which `falling'

-ends; default=60.

-.TP

-\fBtreble \fIgain\fR [\fIfrequency\fR [\fIwidth\fR[\fBs\fR\^|\^\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]]]

-Apply a treble tone-control effect.

-See the description of the \fBbass\fR effect for details.

-.TP

-\fBtremolo \fIspeed\fR [\fIdepth\fR]

-Apply a tremolo (low frequency amplitude modulation) effect to the audio.

-The tremolo frequency in Hz is given by

-.IR speed ,

-and the depth as a percentage by

-.I depth

-(default 40).

-.SP

-Note: This effect is a special case of the

-.B synth

-effect.

-.TP

-\fBtrim \fIstart\fR [\fIlength\fR]

-Trim can trim off unwanted audio from the beginning and end of the

-audio.  Audio is not sent to the output stream until

-the \fIstart\fR location is reached.

-.SP

-The optional \fIlength\fR parameter tells the number of samples to output

-after the \fIstart\fR sample and is used to trim off the back side of the

-audio.  Using a value of 0 for the \fIstart\fR parameter will allow

-trimming off the back side only.

-.SP

-Both options can be specified using either an amount of time or an

-exact count of samples.  The format for specifying lengths in time is

-hh:mm:ss.frac.  A start value of 1:30\*d5 will not start until 1 minute,

-thirty and \(12 seconds into the audio.  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.

-.TP

-\fBvol \fIgain\fR[[ ]\fItype\fR [\fIlimitergain\fR]]

-Apply an amplification or an attenuation to the audio signal.

-Unlike the

-.B \-v

-option (which is used for balancing multiple input files as they enter the

-SoX effects processing chain),

-.B vol

-is an effect like any other so can be applied anywhere, and several times

-if necessary, during the processing chain.

-.SP

-The amount to change the volume is given by

-.I gain

-which is interpreted, according to the given \fItype\fR, as follows: if

-.I type

-is \fBamplitude\fR (or is omitted), then

-.I gain

-is an amplitude (i.e. voltage or linear) ratio,

-if \fBpower\fR, then a power (i.e. wattage or voltage-squared) ratio,

-and if \fBdB\fR, then a power change in dB.

-.SP

-When

-.I type

-is \fBamplitude\fR or \fBpower\fR, a

-.I gain

-of 1 leaves the volume unchanged,

-less than 1 decreases it,

-and greater than 1 increases it;

-a negative

-.I gain

-inverts the audio signal in addition to adjusting its volume.

-.SP

-When

-.I type

-is \fBdB\fR, a

-.I gain

-of 0 leaves the volume unchanged,

-less than 0 decreases it,

-and greater than 0 increases it.

-.SP

-See [4]

-for a detailed discussion on electrical (and hence audio signal)

-voltage and power ratios.

-.SP

-Beware of

-.B Clipping

-when the increasing the volume.

-.SP

-An optional \fIlimitergain\fR value can be specified and should be a

-value much less

-than 1 (e.g. 0\*d05 or 0\*d02) 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 the audio that needed to be

-limited.

-.SP

-See also

-.B compand

-for a dynamic-range compression/expansion/limiting effect.

-.SS Deprecated Effects

-The following effects have been renamed or have their functionality

-included in another effect.  They continue to work in this version of

-SoX but may be removed in future.

-.TP

-\fBavg\fR [ \fB\-l\fR\^|\^\fB\-r\fR\^|\^\fB\-f\fR\^|\^\fB\-b\fR\^|\^\fB\-1\fR\^|\^\fB\-2\fR\^|\^\fB\-3\fR\^|\^\fB\-4\fR\^|\^\fIn\fR{\fB,\fIn\fR} ]

-Reduce the number of audio channels by mixing or selecting channels,

-or duplicate channels to increase the number of channels.

-This effect is just an alias of the

-.B mixer

-effect and is retained for backwards compatibility only.

-.TP

-\fBhighp\fR \fIfrequency\fR

-Apply a high-pass filter.

-This effect is just an alias for the

-.B highpass

-effect used with its

-.B \-1

-option; it is retained for backwards compatibility only.

-.TP

-\fBlowp \fIfrequency\fR

-Apply a low-pass filter.

-This effect is just an alias for the

-.B lowpass

-effect used with its

-.B \-1

-option; it is retained for backwards compatibility only.

-.TP

-\fBmask\fR [\fIdepth\fR]

-This effect is just a deprecated alias for the \fBdither\fR effect, left for historical reasons.

-.TP

-\fBpick\fR [ \fB\-l\fR\^|\^\fB\-r\fR\^|\^\fB\-f\fR\^|\^\fB\-b\fR\^|\^\fB\-1\fR\^|\^\fB\-2\fR\^|\^\fB\-3\fR\^|\^\fB\-4\fR\^|\^\fIn\fR{\fB,\fIn\fR} ]

-Pick a subset of channels to be copied into the output file.

-This effect is just an alias of the

-.B mixer

-effect and is retained for backwards compatibility only.

-.TP

-\fBrate\fR

-Does the same as \fBresample\fR with no parameters; it exists for

-backwards compatibility.

-.TP

-\fBvibro \fIspeed\fR [\fIdepth\fR]

-This is a deprecated alias for the

-.B tremolo

-effect.  It differs in that the depth parameter ranges from 0 to 1 and defaults to 0\*d5.

 .SH DIAGNOSTICS

 Exit status is 0 for no error, 1 if there is a problem with the

 command-line parameters, or 2 if an error occurs during file processing.

@@ -2292,44 +737,15 @@

 Please report any bugs found in this version of SoX to the mailing list

 (sox-users@lists.sourceforge.net).

 .SH SEE ALSO

+.BR soxexam (7),

+.BR soxformat (7),

+.BR soxeffect (7),

 .BR gnuplot (1),

-.BR libsox (3),

 .BR octave (1),

-.BR soxexam (7),

-.BR wget (1)

+.BR wget (1),

+.BR libsox (3)

.SP

-The SoX web page at http://sox.sourceforge.net

-.SS References

-.TP

-[1]

-R. Bristow-Johnson,

-.IR "Cookbook formulae for audio EQ biquad filter coefficients" ,

-http://musicdsp.org/files/Audio-EQ-Cookbook.txt

-.TP

-[2]

-Wikipedia,

-.IR "Q-factor" ,

-http://en.wikipedia.org/wiki/Q_factor

-.TP

-[3]

-Scott Lehman,

-.IR "Flanging" ,

-http://harmony-central.com/Effects/Articles/Flanging

-.TP

-[4]

-Wikipedia,

-.IR "Decibel" ,

-http://en.wikipedia.org/wiki/Decibel

-.TP

-[5]

-Wikipedia,

-.IR "M3U" ,

-http://en.wikipedia.org/wiki/M3U

-.TP

-[6]

-Wikipedia,

-.IR "PLS" ,

-http://en.wikipedia.org/wiki/PLS_(file_format)

+The SoX web site at http://sox.sourceforge.net

 .SH LICENSE

 Copyright 1991 Lance Norskog and Sundry Contributors.

 Copyright 1998\-2007 by Chris Bagwell and SoX Contributors.

--- /dev/null

+++ b/soxeffect.7

@@ -1,0 +1,1129 @@

+'\" t

+'\" The line above instructs most `man' programs to invoke tbl

+'\"

+'\" Separate paragraphs; not the same as PP which resets indent level.

+.de SP

+.if t .sp .5

+.if n .sp

+..

+'\"

+'\" Replacement em-dash for nroff (default is too short).

+.ie n .ds m " -

+.el .ds m \(em

+'\"

+'\" Placeholder macro for if longer nroff arrow is needed.

+.ds RA \(->

+'\"

+'\" Decimal point set slightly raised

+.if t .ds d \v'-.15m'.\v'+.15m'

+.if n .ds d .

+'\"

+'\" Enclosure macro for examples

+.de EX

+.SP

+.nf

+.ft CW

+..

+.de EE

+.ft R

+.SP

+.fi

+..

+.TH SoX 7 "April 17, 2007" "soxeffect" "Sound eXchange"

+.SH NAME

+SoX \- Sound eXchange, the Swiss Army knife of audio manipulation

+.SH DESCRIPTION

+Multiple effects may be applied to the audio by specifying them

+one after another at the end of the command line.

+.SP

+.I Note:

+Brackets [ ] are used to denote parameters that are optional, braces

+{ } to denote those that are both optional and repeatable,

+and angle brackets < > to denote those that are repeatable but not

+optional.

+.TP

+\fBallpass\fR \fIfrequency width\fR[\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]

+Apply a two-pole all-pass filter with central frequency (in Hz)

+\fIfrequency\fR, and filter-width \fIwidth\fR: in Hz (the default, or if

+appended with `\fBh\fR'), in octaves (if appended with `\fBo\fR'), or as

+a Q-factor (if appended with `\fBq\fR').  An all-pass filter changes the

+audio's frequency to phase relationship without changing its frequency

+to amplitude relationship.  The filter is described in detail in [1].

+.SP

+This effect supports the \fB\-\-plot\fR global option.

+.TP

+\fBband\fR [\fB\-n\fR] \fIcenter\fR [width\fR[\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]]

+Apply a band-pass filter.

+The frequency response drops logarithmically

+around the

+.I center

+frequency.

+The

+.I width

+in Hz (the default, or if appended with `\fBh\fR'), in octaves (if

+appended with `\fBo\fR'), or as a Q-factor (if appended with `\fBq\fR'),

+gives the slope of the drop.

+The frequencies at

+.I center

++

+.I width

+and

+.I center

+\-

+.I width

+will be half of their original amplitudes.

+.B band

+defaults to a mode oriented to pitched audio,

+i.e. voice, singing, or instrumental music.

+The \fB\-n\fR (for noise) option uses the alternate mode

+for un-pitched audio (e.g. percussion).

+.B Warning:

+\fB\-n\fR introduces a power-gain of about 11dB in the filter, so beware

+of output clipping.

+.B band

+introduces noise in the shape of the filter,

+i.e. peaking at the

+.I center

+frequency and settling around it.

+.SP

+This effect supports the \fB\-\-plot\fR global option.

+.SP

+See also \fBfilter\fR for a bandpass filter with steeper shoulders.

+.TP

+\fBbandpass\fR\^|\^\fBbandreject\fR [\fB\-c\fR] \fIfrequency width\fR[\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]

+Apply a two-pole Butterworth band-pass or band-reject filter with

+central frequency (in Hz) \fIfrequency\fR, and (3dB-point) band-width

+\fIwidth\fR: in Hz (the default, or if appended with `\fBh\fR'), in

+octaves (if appended with `\fBo\fR'), or as a Q-factor (if appended with

+`\fBq\fR').  The

+.B \-c

+option applies only to

+.B bandpass

+and selects a constant skirt gain (peak gain = Q) instead of the

+default: constant 0dB peak gain.

+The filters roll off at 6dB per octave (20dB per decade)

+and are described in detail in [1].

+.SP

+These effects support the \fB\-\-plot\fR global option.

+.SP

+See also \fBfilter\fR for a bandpass filter with steeper shoulders.

+.TP

+\fBbandreject \fIfrequency width\fR[\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]

+Apply a band-reject filter.

+See the description of the \fBbandpass\fR effect for details.

+.TP

+\fBbass\fR\^|\^\fBtreble \fIgain\fR [\fIfrequency\fR [\fIwidth\fR[\fBs\fR\^|\^\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]]]

+Boost or cut the bass (lower) or treble (upper) frequencies of the audio

+using a two-pole shelving filter with a response similar to that

+of a standard hi-fi's (Baxandall) tone-controls.  This is also

+known as shelving equalisation (EQ).

+.SP

+\fIgain\fR gives the dB gain at 0\ Hz (for \fBbass\fR), or whichever is

+the lower of \(ap22\ kHz and the Nyquist frequency (for \fBtreble\fR).  Its

+useful range is about \-20 (for a large cut) to +20 (for a large

+boost).

+Beware of

+.B Clipping

+when using a positive \fIgain\fR.

+.SP

+If desired, the filter can be fine-tuned using the following

+optional parameters:

+.SP

+\fIfrequency\fR sets the filter's central frequency and so can be

+used to extend or reduce the frequency range to be boosted or

+cut.  The default value is 100\ Hz (for \fBbass\fR) or 3\ kHz (for

+\fBtreble\fR).

+.SP

+\fIwidth\fR

+determines how

+steep the filter's shelf transition is and can be expressed as:

+a `slope' (the default, or if appended with `\fBs\fR'),

+a Q-factor (if appended with `\fBq\fR'),

+the transition width in octaves (if appended with `\fBo\fR'),

+or the transition width in Hz (if appended with `\fBh\fR').

+The useful range of `slope' is

+about 0\*d3, for a gentle slope, to 1 (the maximum), for a steep slope; the

+default value is 0\*d5.

+.SP

+The filters are described in detail in [1].

+.SP

+These effects support the \fB\-\-plot\fR global option.

+.SP

+See also \fBequalizer\fR for a peaking equalisation effect.

+.TP

+\fBchorus \fIgain-in gain-out\fR <\fIdelay decay speed depth \fB\-s\fR\^|\^\fB\-t\fR>

+Add a chorus effect to the audio.  Each four-tuple

+delay/decay/speed/depth gives the delay in milliseconds

+and the decay (relative to gain-in) with a modulation

+speed in Hz using depth in milliseconds.

+The modulation is either sinusoidal (\fB\-s\fR) or triangular

+(\fB\-t\fR).  Gain-out is the volume of the output.

+.TP

+\fBcompand \fIattack1\fB,\fIdecay1\fR{\fB,\fIattack2\fB,\fIdecay2\fR}

+[\fIsoft-knee-dB\fB:\fR]\fIin-dB1\fR[\fB,\fIout-dB1\fR]{\fB,\fIin-dB2\fB,\fIout-dB2\fR}

+.br

+[\fIgain\fR [\fIinitial-volume-dB\fR [\fIdelay\fR]]]

+.SP

+Compand (compress or expand) the dynamic range of the audio.  The

+attack and decay time specify the integration time over which the

+absolute value of the input signal is integrated to determine its

+volume; attacks refer to increases in volume and decays refer to

+decreases.  Where more than one pair of attack/decay parameters are

+specified, each channel is treated separately and the number of pairs

+must agree with the number of input channels.  The second parameter is

+a list of points on the compander's transfer function specified in dB

+relative to the maximum possible signal amplitude.  The input values

+must be in a strictly increasing order but the transfer function does

+not have to be monotonically rising.  The special value \fB\-inf\fR may

+be used to indicate that the input volume should be associated output

+volume.  The points \fB\-inf,\-inf\fR and \fB0,0\fR are assumed; the

+latter may be overridden, but the former may not.

+.SP

+The third

+(optional) parameter is a post-processing gain in dB which is applied

+after the compression has taken place; the fourth (optional) parameter

+is an initial volume to be assumed for each channel when the effect

+starts.  This permits the user to supply a nominal level initially, so

+that, for example, a very large gain is not applied to initial signal

+levels before the companding action has begun to operate: it is quite

+probable that in such an event, the output would be severely clipped

+while the compander gain properly adjusts itself.

+.SP

+The fifth (optional) parameter is a delay in seconds.

+The input signal is analysed immediately to control the compander, but

+it is delayed before being fed to the volume adjuster.

+Specifying a delay approximately equal to the attack/decay times

+allows the compander to effectively operate in a `predictive' rather than a

+reactive mode.

+.SP

+This effect supports the \fB\-\-plot\fR global option (for the transfer function).

+.SP

+See also

+.B mcompand

+for a multiple-band companding effect.

+.TP

+\fBdcshift \fIshift\fR [\fIlimitergain\fR]

+DC Shift the audio, with basic linear amplitude formula.

+This is most useful if your audio tends to not be centered around

+a value of 0.  Shifting it back will allow you to get the most volume

+adjustments without clipping.

+.SP

+The first option is the \fIdcshift\fR value.  It is a floating point number that

+indicates the amount to shift.

+.SP

+An optional

+.I limitergain

+can be specified as well.  It should have a value much less than 1

+(e.g. 0\*d05 or 0\*d02) and is used only on peaks to prevent clipping.

+.TP

+\fBdeemph\fR

+Apply a treble attenuation shelving filter to audio in

+audio-CD format.  The frequency response of pre-emphasized

+recordings is rectified.  The filter is defined in the

+standard document ISO 908.

+.SP

+This effect supports the \fB\-\-plot\fR global option.

+.SP

+See also the \fBbass\fR and \fBtreble\fR shelving equalisation effects.

+.TP

+\fBdither\fR [\fIdepth\fR]

+Apply dithering to the audio.

+Dithering deliberately adds digital white noise to the signal

+in order to mask audible quantization effects that

+can occur if the output sample size is less than 24 bits.

+By default, the amount of noise added is \(12 bit;

+the optional \fIdepth\fR parameter is a (linear or voltage)

+multiplier of this amount.

+.SP

+This effect should not be followed by any other effect that

+affects the audio.

+.TP

+\fBearwax\fR

+Makes audio easier to listen to on headphones.

+Adds `cues' to audio in audio-CD format so that

+when listened to on headphones the stereo image is

+moved from inside

+your head (standard for headphones) to outside and in front of the

+listener (standard for speakers).  See

+http://www.geocities.com/beinges

+for a full explanation.

+.TP

+\fBecho \fIgain-in gain-out\fR <\fIdelay decay\fR>

+Add echoing to the audio.

+Each

+.I "delay decay"

+pair gives the delay in milliseconds

+and the decay (relative to gain-in) of that echo.

+Gain-out is the volume of the output.

+.TP

+\fBechos \fIgain-in gain-out\fR <\fIdelay decay\fR>

+Add a sequence of echos to the audio.

+Each

+.I "delay decay"

+pair gives the delay in milliseconds

+and the decay (relative to gain-in) of that echo.

+Gain-out is the volume of the output.

+.TP

+\fBequalizer \fIfrequency width\fR[\fBq\fR\^|\^\fBo\fR\^|\^\fBh\fR] \fIgain\fR

+Apply a two-pole peaking equalisation (EQ) filter.

+With this filter, the signal-level at and around a selected frequency

+can be increased or decreased, whilst (unlike band-pass and band-reject

+filters) that at all other frequencies is unchanged.

+.SP

+\fIfrequency\fR gives the filter's central frequency in Hz,

+\fIwidth\fR, the band-width,

+as a Q-factor [2] (the default, or if appended with `\fBq\fR'),

+in octaves (if appended with `\fBo\fR'),

+or in Hz (if appended with `\fBh\fR'),

+and \fIgain\fR the required gain

+or attenuation in dB.

+Beware of

+.B Clipping

+when using a positive \fIgain\fR.

+.SP

+In order to produce complex equalisation curves, this effect

+can be given several times, each with a different central frequency.

+.SP

+The filter is described in detail in [1].

+.SP

+This effect supports the \fB\-\-plot\fR global option.

+.SP

+See also \fBbass\fR and \fBtreble\fR for shelving equalisation effects.

+.TP

+\fBfade\fR [\fItype\fR] \fIfade-in-length\fR [\fIstop-time\fR [\fIfade-out-length\fR]]

+Add a fade effect to the beginning, end, or both of the audio.

+.SP

+For fade-ins, this starts from the first sample and ramps the volume of the audio from 0 to full volume over \fIfade-in-length\fR seconds.  Specify 0 seconds if no fade-in is wanted.

+.SP

+For fade-outs, the audio will be truncated at

+.I stop-time

+and

+the volume will be ramped from full volume down to 0 starting at

+\fIfade-out-length\fR seconds before the \fIstop-time\fR.  If

+.I fade-out-length

+is not specified, it defaults to the same value as

+\fIfade-in-length\fR.

+No fade-out is performed if

+.I stop-time

+is not specified.

+.SP

+All times can be specified in either periods of time or sample counts.

+To specify time periods use the format hh:mm:ss.frac format.  To specify

+using sample counts, specify the number of samples and append the letter `s'

+to the sample count (for example `8000s').

+.SP

+An optional \fItype\fR can be specified to change the type of envelope.  Choices are \fBq\fR for quarter of a sine wave, \fBh\fR for half a sine wave, \fBt\fR for linear slope, \fBl\fR for logarithmic, and \fBp\fR for inverted parabola.  The default is a linear slope.

+.TP

+\fBfilter\fR [\fIlow\fR]\fB\-\fR[\fIhigh\fR] [\fIwindow-len\fR [\fIbeta\fR]]

+Apply a sinc-windowed lowpass, highpass, or bandpass filter of given

+window length to the signal.

+\fIlow\fR refers to the frequency of the lower 6dB corner of the filter.

+\fIhigh\fR refers to the frequency of the upper 6dB corner of the filter.

+.SP

+A low-pass filter is obtained by leaving \fIlow\fR unspecified, or 0.

+A high-pass filter is obtained by leaving \fIhigh\fR unspecified, or 0,

+or greater than or equal to the Nyquist frequency.

+.SP

+The \fIwindow-len\fR, if unspecified, defaults to 128.

+Longer windows give a sharper cutoff, smaller windows a more gradual cutoff.

+.SP

+The \fIbeta\fR, if unspecified, defaults to 16.  This selects a Kaiser window.

+You can select a Nuttall window by specifying anything \(<= 2 here.

+For more discussion of beta, look under the \fBresample\fR effect.

+.SP

+.TP

+\fBflanger\fR [\fIdelay depth regen width speed shape phase interp\fR]

+Apply a flanging effect to the audio.

+All parameters are optional (right to left).

+.TS

+center box;

+cB cB cB lB

+cI c c l.

+\ 	Range	Default	Description

+delay	0 \- 10	0	Base delay in milliseconds.

+depth	0 \- 10	2	Added swept delay in milliseconds.

+regen	\-95 \- 95	0	T{

+.na

+Percentage regeneration (delayed signal feedback).

+T}

+width	0 \- 100	71	T{

+.na

+Percentage of delayed signal mixed with original.

+T}

+speed	0\*d1 \- 10	0\*d5	Sweeps per second (Hz).

+shape	\ 	sin	Swept wave shape: \fBsine\fR\^|\^\fBtriangle\fR.

+phase	0 \- 100	25	T{

+.na

+Swept wave percentage phase-shift for multi-channel (e.g. stereo) flange;

+0 = 100 = same phase on each channel.

+T}

+interp	\ 	lin	T{

+.na

+Digital delay-line interpolation: \fBlinear\fR\^|\^\fBquadratic\fR.

+T}

+.TE

+.DT

+.SP

+See [3] for a detailed description of flanging.

+.TP

+\fBhighpass\fR\^|\^\fBlowpass\fR [\fB-1\fR|\fB-2\fR] \fIfrequency\fR [\fRwidth\fR[\fBq\fR\^|\^\fBo\fR\^|\^\fBh\fR]]

+Apply a high-pass or low-pass filter with 3dB point \fIfrequency\fR.

+The filter can be either single-pole (with

+.BR \-1 ),

+or double-pole (the default, or with

+.BR \-2 ).

+.I width

+applies only to double-pole filters and is the filter-width: as a

+Q-factor (the default, or if appended with `\fBq\fR'), in octaves (if

+appended with `\fBo\fR'), or in Hz (if appended with `\fBh\fR');

+the default Q is 0\*d707 and gives a Butterworth response.  The filters

+roll off at 6dB per pole per octave (20dB per pole per decade).  The

+double-pole filters are described in detail in [1].

+.SP

+These effects support the \fB\-\-plot\fR global option.

+.SP

+See also \fBfilter\fR for filters with a steeper roll-off.

+.TP

+\fBlowpass\fR [\fB-1\fR|\fB-2\fR] \fIfrequency\fR [\fRwidth\fR[\fBq\fR\^|\^\fBo\fR\^|\^\fBh\fR]]

+Apply a low-pass filter.

+See the description of the \fBhighpass\fR effect for details.

+.TP

+\fBmcompand\fR \(dq\fIattack1\fB,\fIdecay1\fR{\fB,\fIattack2\fB,\fIdecay2\fR}

+[\fIsoft-knee-dB\fB:\fR]\fIin-dB1\fR[\fB,\fIout-dB1\fR]{\fB,\fIin-dB2\fB,\fIout-dB2\fR}

+.br

+[\fIgain\fR [\fIinitial-volume-dB\fR [\fIdelay\fR]]]\(dq {\fIxover-freq\fR \(dqattack1,...\(dq}

+.SP

+The multi-band compander is similar to the single-band compander but the

+audio is first divided into bands using Butterworth cross-over filters

+and a separately specifiable compander run on each band.  See the

+\fBcompand\fR effect for the definition of its parameters.  Compand

+parameters are specified between double quotes and the crossover

+frequency for that band is given by \fIxover-freq\fR; these can be

+repeated to create multiple bands.

+.SP

+See also

+.B compand

+for a single-band companding effect.

+.TP

+\fBmixer\fR [ \fB\-l\fR\^|\^\fB\-r\fR\^|\^\fB\-f\fR\^|\^\fB\-b\fR\^|\^\fB\-1\fR\^|\^\fB\-2\fR\^|\^\fB\-3\fR\^|\^\fB\-4\fR\^|\^\fIn\fR{\fB,\fIn\fR} ]

+Reduce the number of audio channels by mixing or selecting channels,

+or increase the number of channels by duplicating channels.

+Note: this effect operates on the audio

+.I channels

+within the SoX effects processing chain; it should not be confused with the

+.B \-m

+global option (where multiple

+.I files

+are mix-combined before entering the effects chain).

+.SP

+This effect is automatically used when the number of input

+channels differ from the number of output channels.  When reducing

+the number of channels it is possible to manually specify the

+.B mixer

+effect and use the \fB\-l\fR, \fB\-r\fR, \fB\-f\fR, \fB\-b\fR,

+\fB\-1\fR, \fB\-2\fR, \fB\-3\fR, \fB\-4\fR, options to select only

+the left, right, front, back channel(s) or specific channel

+for the output instead of averaging the channels.

+The \fB\-l\fR, and \fB\-r\fR options will do averaging

+in quad-channel files so select the exact channel to prevent this.

+.SP

+The

+.B mixer

+effect can also be invoked with up to 16

+numbers, separated by commas, which specify the proportion (0 = 0% and 1 = 100%)

+of each input channel that is to be mixed into each output channel.

+In two-channel mode, 4 numbers are given: l \*(RA l, l \*(RA r, r \*(RA l, and r \*(RA r,

+respectively.

+In four-channel mode, the first 4 numbers give the proportions for the

+left-front output channel, as follows: lf \*(RA lf, rf \*(RA lf, lb \*(RA lf, and

+rb \*(RA rf.

+The next 4 give the right-front output in the same order, then

+left-back and right-back.

+.SP

+It is also possible to use the 16 numbers to expand or reduce the

+channel count; just specify 0 for unused channels.

+.SP

+Finally, certain reduced combination of numbers can be specified

+for certain input/output channel combinations.

+.TS

+center box ;

+cB cB cB lB

+c c c l .

+In Ch	Out Ch	Num	Mappings

+2	1	2	l \*(RA l, r \*(RA l

+2	2	1	adjust balance

+4	1	4	lf \*(RA l, rf \*(RA l, lb \*(RA l, rb \*(RA l

+4	2	2	lf \*(RA l&rf \*(RA r, lb \*(RA l&rb \*(RA r

+4	4	1	adjust balance

+4	4	2	front balance, back balance

+.TE

+.DT

+.SP

+.TP

+\fBnoiseprof\fR [\fIprofile-file\fR]

+Calculate a profile of the audio for use in noise reduction.

+See the description of the \fBnoisered\fR effect for details.

+.TP

+\fBnoisered \fIprofile-file\fR [\fIthreshold\fR]

+Noise reduction filter with profiling.  This filter is moderately effective at

+removing consistent background noise such as hiss or hum.  To use it, first run

+the \fBnoiseprof\fR effect on a section of audio that ideally would

+contain silence but in fact contains noise.

+The \fBnoiseprof\fR effect will write out a noise profile

+to \fIprofile-file\fR, or to stdout if no \fIprofile-file\fR is specified.

+If there is audio output on stdout then the profile will instead be directed to

+stderr.

+.SP

+To actually remove the noise, run

+SoX again with the \fInoisered\fR filter.  The

+filter needs one parameter, \fIprofile-file\fR, which contains the noise profile

+from \fBnoiseprof\fR.  \fIthreshold\fR specifies how much noise should be removed, and

+may be between 0 and 1 with a default of 0\*d5.  Higher values will remove more

+noise but present a greater likelihood of distorting the desired audio signal.

+Using headphones to check the results, experiment with different

+threshold values to find the optimal one for your audio; pay special

+attention to quieter sections.

+.TP

+\fBpad\fR { \fIlength\fR[\fB@\fIposition\fR] }

+Pad the audio with silence, at the beginning, the end, or any

+specified points through the audio.

+Both

+.I length

+and

+.I position

+can specify a time or, if appended with an `s', a number of samples.

+.I length

+is the amount of silence to insert and

+.I position

+the position in the input audio stream at which to insert it.

+Any number of lengths and positions may be specified, provided that

+a specified position is not less that the previous one.

+.I position

+is optional for the first and last lengths specified and

+if omitted correspond to the beginning and the end of the audio respectively.

+For example:

+.B pad 1\*d5 1\*d5

+adds 1\*d5 seconds of silence padding at each end of the audio, whilst

+.B pad 4000s@3:00

+inserts 4000 samples of silence 3 minutes into the audio.

+If silence is wanted only at the end of the audio, specify either the end

+position or specify a zero-length pad at the start.

+.TP

+\fBpan \fIdirection\fR

+Pan the audio from one channel to another.  This is done by

+changing the volume of the input channels so that it fades out on one

+channel and fades-in on another.  If the number of input channels is

+different then the number of output channels then this effect tries to

+intelligently handle this.  For instance, if the input contains 1 channel

+and the output contains 2 channels, then it will create the missing channel

+itself.  The

+.I direction

+is a value from \-1 to 1.  \-1 represents

+far left and 1 represents far right.  Numbers in between will start the

+pan effect without totally muting the opposite channel.

+.TP

+\fBphaser \fIgain-in gain-out delay decay speed\fR [\fB\-s\fR\^|\^\fB\-t\fR]

+Add a phasing effect to the audio.

+delay/decay/speed gives the delay in milliseconds

+and the decay (relative to gain-in) with a modulation

+speed in Hz.

+The modulation is either sinusoidal (\fB\-s\fR) or triangular

+(\fB\-t\fR).  The decay should be less than 0\*d5 to avoid

+feedback.  Gain-out is the volume of the output.

+.TP

+\fBpitch \fIshift\fR [\fIwidth interpolate fade\fR]

+Change the pitch of file without affecting its duration by cross-fading

+shifted samples.

+.I shift

+is given in cents.  Use a positive value to shift to treble, negative value to shift to bass.

+Default shift is 0.

+.I width

+of window is in ms.  Default width is 20ms.  Try 30ms to lower pitch,

+and 10ms to raise pitch.

+.I interpolate

+option, can be \fBcubic\fR or \fBlinear\fR.  Default is \fBcubic\fR.  The

+.I fade

+option, can be \fBcos\fR, \fBhamming\fR, \fBlinear\fR or

+\fBtrapezoid\fR; the default is \fBcos\fR.

+.TP

+\fBpolyphase\fR [\fB\-w nut\fR\^|\^\fBham\fR] [\fB\-width \fIn\fR] [\fB\-cutoff \fIc\fR]

+Change the sampling rate using `polyphase interpolation', a DSP algorithm.

+This method is relatively slow and memory intensive.

+.SP

+If the \fB\-w\fR parameter is \fBnut\fR, then a Nuttall (~90 dB

+stop-band) window will be used; \fBham\fR selects a Hamming (~43

+dB stop-band) window.  The default is Nuttall.

+.SP

+The \fB\-width\fR parameter specifies the (approximate) width of the filter. The default is 1024 samples, which produces reasonable results.

+.SP

+The \fB\-cutoff\fR value (\fIc\fR) specifies the filter cutoff frequency in terms of fraction of

+frequency bandwidth, also know as the Nyquist frequency.  See

+the \fBresample\fR effect for

+further information on Nyquist frequency.  If up-sampling, then this is the

+fraction of the original signal

+that should go through.  If down-sampling, this is the fraction of the

+signal left after down-sampling.  The default is 0\*d95.

+.SP

+See also

+.B rabbit

+and

+.B resample

+for other sample-rate changing effects.

+.TP

+\fBrabbit\fR [\fB\-c0\fR\^|\^\fB\-c1\fR\^|\^\fB\-c2\fR\^|\^\fB\-c3\fR\^|\^\fB\-c4\fR]

+Change the sampling rate using `libsamplerate', also known as `Secret Rabbit

+Code'.  This effect is

+optional and must have been selected at compile time of SoX.  See

+http://www.mega-nerd.com/SRC for details of the algorithms.  Algorithms

+0 through 2 are progressively faster and lower quality versions of the

+sinc algorithm; the default is \fB\-c0\fR, which is probably the best

+quality algorithm for general use currently available in SoX.

+Algorithm 3 is zero-order hold, and 4 is linear interpolation.

+.SP

+See also

+.B polyphase

+and

+.B resample

+for other sample-rate changing effects, and see

+\fBresample\fR for more discussion of resampling.

+.TP

+\fBrepeat \fIcount\fR

+Repeat the entire audio \fIcount\fR times.

+Requires disk space to store the data to be repeated.

+Note that repeating once yields two copies: the original audio and the

+repeated audio.

+.TP

+\fBresample\fR [\fB\-qs\fR\^|\^\fB\-q\fR\^|\^\fB\-ql\fR] [\fIrolloff\fR [\fIbeta\fR]]

+Change the sampling rate using simulated

+analog filtration.  Other rate changing effects available are

+\fBpolyphase\fR and \fBrabbit\fR.  There is a detailed analysis of

+\fBresample\fR and \fBpolyphase\fR at

+http://leute.server.de/wilde/resample.html; see \fBrabbit\fR for a

+pointer to its own documentation.

+.SP

+By default, linear interpolation is used,

+with a window width about 45 samples at the lower of the two rates.

+This gives an accuracy of about 16 bits, but insufficient stop-band rejection

+in the case that you want to have roll-off greater than about 0\*d8 of

+the Nyquist frequency.

+.SP

+The \fB\-q*\fR options will change the default values for roll-off and beta

+as well as use quadratic interpolation of filter

+coefficients, resulting in about 24 bits precision.

+The \fB\-qs\fR, \fB\-q\fR, or \fB\-ql\fR options specify increased accuracy

+at the cost of lower execution speed.  It is optional to specify

+roll-off and beta parameters when using the \fB\-q*\fR options.

+.SP

+Following is a table of the reasonable defaults which are built-in to

+SoX:

+.SP

+.TS

+center box;

+cB cB cB cB cB

+c c n c c

+cB c n c c.

+Option	Window	Roll-off	Beta	Interpolation

+(none)	45	0\*d80	16	linear

+\-qs	45	0\*d80	16	quadratic

+\-q	75	0\*d875	16	quadratic

+\-ql	149	0\*d94	16	quadratic

+.TE

+.DT

+.SP

+\fB\-qs\fR, \fB\-q\fR, or \fB\-ql\fR 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.

+.SP

+\fIrolloff\fR 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 practise 0\*d8\-0\*d95.  The defaults are

+indicated above.

+.SP

+The \fINyquist frequency\fR is equal to half the sample rate.  Logically,

+this is because the A/D converter needs at least 2 samples to detect 1

+cycle at the Nyquist frequency.  Frequencies higher then the Nyquist

+will actually appear as lower frequencies to the A/D converter and

+is called aliasing.  Normally, A/D converts run the signal through

+a lowpass filter first to avoid these problems.

+.SP

+Similar problems will happen in software when reducing the sample rate of

+an audio file (frequencies above the new Nyquist frequency can be aliased

+to lower frequencies).  Therefore, a good resample effect

+will remove all frequency information above the new Nyquist frequency.

+.SP

+The \fIrolloff\fR refers to how close to the Nyquist frequency this cutoff

+is, with closer being better.  When increasing the sample rate of an

+audio file you would not expect to have any frequencies exist that are

+past the original Nyquist frequency.  Because of resampling properties, it

+is common to have aliasing artifacts created above the old

+Nyquist frequency.  In that case the \fIrolloff\fR refers to how close

+to the original Nyquist frequency to use a highpass filter to remove

+these artifacts, with closer also being better.

+.SP

+The \fIbeta\fR parameter

+determines the type of filter window used.  Any value greater than 2 is

+the beta for a Kaiser window.  Beta \(<= 2 selects a Nuttall window.

+If unspecified, the default is a Kaiser window with beta 16.

+.SP

+In the case of Kaiser window (beta > 2), lower betas produce a somewhat

+faster transition from pass-band to stop-band, 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 not need to use the beta parameter at all, unless you are

+just curious about comparing the effects of Nuttall vs. Kaiser windows.

+.SP

+This is the default effect if the two files have different sampling rates.

+Default parameters are, as indicated above, Kaiser window of length 45,

+roll-off 0\*d80, beta 16, linear interpolation.

+.SP

+Note: \fB\-qs\fR is only slightly slower, but more accurate for

+16-bit or higher precision.

+.SP

+Note: In many cases of up-sampling, no interpolation is needed,

+as exact filter coefficients can be computed in a reasonable amount of space.

+To be precise, this is done when both input-rate < output-rate, and

+output-rate \(di gcd(input-rate, output-rate) \(<= 511.

+.TP

+\fBreverb \fIgain-out reverb-time\fR <\fIdelay\fR>

+Add reverberation to the audio.  Each

+.I delay

+is given

+in milliseconds and its feedback is depending on the

+.I reverb-time

+in milliseconds.  Each

+.I delay

+should be in

+the range of half to quarter of

+.I reverb-time

+to get a realistic reverberation.

+.I gain-out

+is the volume of the output.

+.TP

+\fBreverse\fR

+Reverse the audio completely.

+Requires disk space to store the data to be reversed.

+.TP

+\fBsilence \fR[\fB\-l\fR] \fIabove-periods\fR [\fIduration threshold\fR[\fBd\fR\^|\^\fB%\fR] [\fIbelow-periods duration threshold\fR[\fBd\fR\^|\^\fB%\fR]]

+.SP

+Removes silence from the beginning, middle, or end of the audio.  Silence is anything below a specified threshold.

+.SP

+The \fIabove-periods\fR value is used to indicate if audio should be trimmed at

+the beginning of the audio.  A value of zero indicates no silence

+should be trimmed from the beginning.  When specifying 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 audio 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.

+.SP

+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 audio.  By increasing the duration, burst of noise can be treated as silence and trimmed off.

+.SP

+\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 the value to account

+for background noise.

+.SP

+When optionally trimming silence from the end of the audio, you specify

+a \fIbelow-periods\fR count.  In this case, \fIbelow-period\fR means

+to remove all audio 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.

+.SP

+For \fIbelow-periods\fR, \fIduration\fR specifies a period of silence

+that must exist before audio 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.

+.SP

+Unfortunately, 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 \fBsilence\fR effect in combination with the \fBreverse\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.

+.SP

+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 audio.

+.SP

+The option

+.B \-l

+indicates that \fIbelow-periods\fR \fIduration\fR length of audio

+should be left intact at the beginning of each period of silence.

+For example, if you want to remove long pauses between words

+but do not want to remove the pauses completely.

+.SP

+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 with

+.B d

+to indicate the value is in decibels, or

+.B %

+to indicate a percentage of maximum value of the sample value (\fB0%\fR specifies pure digital silence).

+.TP

+\fBspeed \fIfactor\fR[\fBc\fR]

+Adjust the audio speed (pitch and tempo together).  \fIfactor\fR

+is either the ratio of the new speed to the old speed: greater

+than 1 speeds up, less than 1 slows down, or, if appended with the

+letter

+`c', the number of cents (i.e. 100ths of a semitone) by

+which the pitch (and tempo) should be adjusted: greater than 0

+increases, less than 0 decreases.

+.SP

+By default, the speed change is performed by the \fBresample\fR

+effect with its default parameters.  For higher quality

+resampling, in addition to the \fBspeed\fR effect, specify

+either the \fBresample\fR or the \fBrabbit\fR effect with

+appropriate parameters.

+.TP

+\fBstat\fR [\fB\-s \fIn\fR] [\fB\-rms\fR] [\fB\-freq\fR] [\fB\-v\fR] [\fB\-d\fR]

+Do a statistical check on the input file,

+and print results on the standard error file.  Audio is passed

+unmodified through the SoX processing chain.

+.SP

+The `Volume Adjustment:' field in the statistics

+gives you the parameter to the

+.B \-v

+.I number

+which will make the audio as loud as possible without clipping.

+Note: See the discussion on

+.B Clipping

+above for reasons why it is rarely a good idea to actually do this.

+.SP

+The option

+.B \-v

+will print out the `Volume Adjustment:' field's value only and

+return.  This could be of use in scripts to auto convert the

+volume.

+.SP

+The

+.B \-s

+option is used to scale the input data by a given factor.  The default value

+of

+.I 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.

+.SP

+The

+.B \-rms

+option will convert all output average values to `root mean square'

+format.

+.SP

+The

+.B \-freq

+option calculates the input's power spectrum and prints it to standard error.

+.SP

+There is also an optional parameter

+.B \-d

+that will print out a hex dump of the

+audio 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.

+.TP

+\fBstretch \fIfactor\fR [\fIwindow fade shift fading\fR]

+Time stretch the audio by the given factor.  Changes duration without affecting the pitch.

+.I factor

+of stretching: >1 lengthen, <1 shorten duration.

+.I window

+size is in ms.  Default is 20ms.  The

+.I fade

+option, can be `lin'.

+.I shift

+ratio, in [0 1].  Default depends on stretch factor. 1

+to shorten, 0\*d8 to lengthen.  The

+.I fading

+ratio, in [0 0\*d5].  The amount of a fade's default depends on

+.I factor

+and \fIshift\fR.

+.TP

+\fBswap\fR [\fI1 2\fR | \fI1 2 3 4\fR]

+Swap channels in multi-channel audio 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,

+.B swap 2 2

+will overwrite channel 1 with channel 2; creating a stereo

+file with both channels containing the same audio.

+.TP

+\fBsynth\fR [\fIlen\fR] {[\fItype\fR] [\fIcombine\fR] [\fIfreq\fR[\fI\-freq2\fR]] [\fIoff\fR] [\fIph\fR] [\fIp1\fR] [\fIp2\fR] [\fIp3\fR]}

+This effect can be used to generate fixed or swept frequency audio tones

+with various wave shapes, or to generate wide-band noise of various

+`colours'.

+Multiple synth effects can be cascaded to produce more complex

+waveforms; at each stage it is possible to choose whether the generated

+waveform will be mixed with, or modulated onto

+the output from the previous stage.

+Audio for each channel in a multi-channel audio file can be synthesised

+independently.

+.SP

+Though this effect is used to generate audio, an input file must still

+be given, the characteristics of which will be used to set the

+synthesised audio length, the number of channels, and the sampling rate;

+however, since the input file's audio is not normally needed, a `null

+file' (with the special name \fB-n\fR) is often given instead (and the

+length specified as a parameter to \fBsynth\fR or by another given

+effect that can has an associated length).

+.SP

+For example, the following produces a 3 second, 44\*d1\ kHz,

+stereo audio file containing a sine-wave swept from 300 to 3300\ Hz:

+.EX

+	sox -n output.au synth 3 sine 300-3300

+.EE

+and this produces an 8\ kHz mono version:

+.EX

+	sox -r 8000 -c 1 -n output.au synth 3 sine 300-3300

+.EE

+Multiple channels can be synthesised by specifying the set of

+parameters shown between braces multiple times;

+the following puts the swept tone in the left channel and adds `brown'

+noise in the right:

+.EX

+	sox -n output.au synth 3 sine 300-3300 brownnoise

+.EE

+The following example shows how two synth effects can be cascaded

+to create a more complex waveform:

+.EX

+	sox -n output.au synth 0\*d5 sine 200-500 \(rs

+		synth 0\*d5 sine fmod 700-100

+.EE

+Frequencies can also be given as a number of musical semitones relative

+to `middle A' (440\ Hz) by prefixing a `%' character;  for example, the

+following could be used to help tune a guitar's `E' strings:

+.EX

+	play -n synth sine %-17

+.EE

+.B N.B.

+This effect generates audio at maximum volume, which means that there

+is a high chance of clipping when using the audio subsequently, so

+in most cases, you will want to follow this effect with the \fBvol\fR

+effect to prevent this from happening. (See also

+.B Clipping

+above.)

+.SP

+A detailed description of each

+.B synth

+parameter follows:

+.SP

+\fIlen\fR is the length of audio to synthesise expressed as a time

+or as a number of samples;

+0=inputlength, default=0.

+.SP

+The format for specifying lengths in time is hh:mm:ss.frac.  The format

+for specifying sample counts is the number of samples with the letter

+`s' appended to it.

+.SP

+\fItype\fR is one of sine, square, triangle, sawtooth, trapezium, exp,

+[white]noise, pinknoise, brownnoise; default=sine

+.SP

+\fIcombine\fR is one of create, mix, amod (amplitude modulation), fmod

+(frequency modulation); default=create

+.SP

+\fIfreq\fR/\fIfreq2\fR are the frequencies at the beginning/end of

+synthesis in Hz or, if preceded with `%', semitones relative to A

+(440\ Hz); for both, default=%0.  If

+.I freq2

+is given, then

+.I len

+must also have been given.

+Not used for noise.

+.SP

+\fIoff\fR is the bias (DC-offset) of the signal in percent; default=0.

+.SP

+\fIph\fR is the phase shift in percentage of 1 cycle; default=0.  Not

+used for noise.

+.SP

+\fIp1\fR is the percentage of each cycle that is `on' (square), or

+`rising' (triangle, exp, trapezium); default=50 (square, triangle, exp),

+default=10 (trapezium).

+.SP

+\fIp2\fR (trapezium): the percentage through each cycle at which `falling'

+begins; default=50. exp: the amplitude in percent; default=100.

+.SP

+\fIp3\fR (trapezium): the percentage through each cycle at which `falling'

+ends; default=60.

+.TP

+\fBtreble \fIgain\fR [\fIfrequency\fR [\fIwidth\fR[\fBs\fR\^|\^\fBh\fR\^|\^\fBo\fR\^|\^\fBq\fR]]]

+Apply a treble tone-control effect.

+See the description of the \fBbass\fR effect for details.

+.TP

+\fBtremolo \fIspeed\fR [\fIdepth\fR]

+Apply a tremolo (low frequency amplitude modulation) effect to the audio.

+The tremolo frequency in Hz is given by

+.IR speed ,

+and the depth as a percentage by

+.I depth

+(default 40).

+.SP

+Note: This effect is a special case of the

+.B synth

+effect.

+.TP

+\fBtrim \fIstart\fR [\fIlength\fR]

+Trim can trim off unwanted audio from the beginning and end of the

+audio.  Audio is not sent to the output stream until

+the \fIstart\fR location is reached.

+.SP

+The optional \fIlength\fR parameter tells the number of samples to output

+after the \fIstart\fR sample and is used to trim off the back side of the

+audio.  Using a value of 0 for the \fIstart\fR parameter will allow

+trimming off the back side only.

+.SP

+Both options can be specified using either an amount of time or an

+exact count of samples.  The format for specifying lengths in time is

+hh:mm:ss.frac.  A start value of 1:30\*d5 will not start until 1 minute,

+thirty and \(12 seconds into the audio.  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.

+.TP

+\fBvol \fIgain\fR[[ ]\fItype\fR [\fIlimitergain\fR]]

+Apply an amplification or an attenuation to the audio signal.

+Unlike the

+.B \-v

+option (which is used for balancing multiple input files as they enter the

+SoX effects processing chain),

+.B vol

+is an effect like any other so can be applied anywhere, and several times

+if necessary, during the processing chain.

+.SP

+The amount to change the volume is given by

+.I gain

+which is interpreted, according to the given \fItype\fR, as follows: if

+.I type

+is \fBamplitude\fR (or is omitted), then

+.I gain

+is an amplitude (i.e. voltage or linear) ratio,

+if \fBpower\fR, then a power (i.e. wattage or voltage-squared) ratio,

+and if \fBdB\fR, then a power change in dB.

+.SP

+When

+.I type

+is \fBamplitude\fR or \fBpower\fR, a

+.I gain

+of 1 leaves the volume unchanged,

+less than 1 decreases it,

+and greater than 1 increases it;

+a negative

+.I gain

+inverts the audio signal in addition to adjusting its volume.

+.SP

+When

+.I type

+is \fBdB\fR, a

+.I gain

+of 0 leaves the volume unchanged,

+less than 0 decreases it,

+and greater than 0 increases it.

+.SP

+See [4]

+for a detailed discussion on electrical (and hence audio signal)

+voltage and power ratios.

+.SP

+Beware of

+.B Clipping

+when the increasing the volume.

+.SP

+An optional \fIlimitergain\fR value can be specified and should be a

+value much less

+than 1 (e.g. 0\*d05 or 0\*d02) 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 the audio that needed to be

+limited.

+.SP

+See also

+.B compand

+for a dynamic-range compression/expansion/limiting effect.

+.SS Deprecated Effects

+The following effects have been renamed or have their functionality

+included in another effect.  They continue to work in this version of

+SoX but may be removed in future.

+.TP

+\fBavg\fR [ \fB\-l\fR\^|\^\fB\-r\fR\^|\^\fB\-f\fR\^|\^\fB\-b\fR\^|\^\fB\-1\fR\^|\^\fB\-2\fR\^|\^\fB\-3\fR\^|\^\fB\-4\fR\^|\^\fIn\fR{\fB,\fIn\fR} ]

+Reduce the number of audio channels by mixing or selecting channels,

+or duplicate channels to increase the number of channels.

+This effect is just an alias of the

+.B mixer

+effect and is retained for backwards compatibility only.

+.TP

+\fBhighp\fR \fIfrequency\fR

+Apply a high-pass filter.

+This effect is just an alias for the

+.B highpass

+effect used with its

+.B \-1

+option; it is retained for backwards compatibility only.

+.TP

+\fBlowp \fIfrequency\fR

+Apply a low-pass filter.

+This effect is just an alias for the

+.B lowpass

+effect used with its

+.B \-1

+option; it is retained for backwards compatibility only.

+.TP

+\fBmask\fR [\fIdepth\fR]

+This effect is just a deprecated alias for the \fBdither\fR effect, left for historical reasons.

+.TP

+\fBpick\fR [ \fB\-l\fR\^|\^\fB\-r\fR\^|\^\fB\-f\fR\^|\^\fB\-b\fR\^|\^\fB\-1\fR\^|\^\fB\-2\fR\^|\^\fB\-3\fR\^|\^\fB\-4\fR\^|\^\fIn\fR{\fB,\fIn\fR} ]

+Pick a subset of channels to be copied into the output file.

+This effect is just an alias of the

+.B mixer

+effect and is retained for backwards compatibility only.

+.TP

+\fBrate\fR

+Does the same as \fBresample\fR with no parameters; it exists for

+backwards compatibility.

+.TP

+\fBvibro \fIspeed\fR [\fIdepth\fR]

+This is a deprecated alias for the

+.B tremolo

+effect.  It differs in that the depth parameter ranges from 0 to 1 and defaults to 0\*d5.

+.SH SEE ALSO

+.BR sox (1),

+.BR soxformat (7),

+.BR libsox (3),

+.BR soxexam (7),

+.BR wget (1)

+.SP

+The SoX web page at http://sox.sourceforge.net

+.SS References

+.TP

+[1]

+R. Bristow-Johnson,

+.IR "Cookbook formulae for audio EQ biquad filter coefficients" ,

+http://musicdsp.org/files/Audio-EQ-Cookbook.txt

+.TP

+[2]

+Wikipedia,

+.IR "Q-factor" ,

+http://en.wikipedia.org/wiki/Q_factor

+.TP

+[3]

+Scott Lehman,

+.IR "Flanging" ,

+http://harmony-central.com/Effects/Articles/Flanging

+.TP

+[4]

+Wikipedia,

+.IR "Decibel" ,

+http://en.wikipedia.org/wiki/Decibel

+.SH AUTHORS

+Chris Bagwell (cbagwell@users.sourceforge.net).

+Other authors and contributors are listed in the AUTHORS file that

+is distributed with the source code.

--- /dev/null

+++ b/soxformat.7

@@ -1,0 +1,547 @@

+'\" t

+'\" The line above instructs most `man' programs to invoke tbl

+'\"

+'\" Separate paragraphs; not the same as PP which resets indent level.

+.de SP

+.if t .sp .5

+.if n .sp

+..

+'\"

+'\" Replacement em-dash for nroff (default is too short).

+.ie n .ds m " -

+.el .ds m \(em

+'\"

+'\" Placeholder macro for if longer nroff arrow is needed.

+.ds RA \(->

+'\"

+'\" Decimal point set slightly raised

+.if t .ds d \v'-.15m'.\v'+.15m'

+.if n .ds d .

+'\"

+'\" Enclosure macro for examples

+.de EX

+.SP

+.nf

+.ft CW

+..

+.de EE

+.ft R

+.SP

+.fi

+..

+.TH SoX 7 "April 17, 2007" "soxformat" "Sound eXchange"

+.SH NAME

+SoX \- Sound eXchange, the Swiss Army knife of audio manipulation

+.SH DESCRIPTION

+File types can be set by the filename extension or the

+.B \-t

+option (see above). File types that can be determined by a filename

+extension are listed with their names preceded by a dot. File types

+that require an external library, such as ffmpeg or libsndfile, are

+marked e.g. `\fB(ffmpeg)\fR'. File types that can be handled by an

+external library via its pseudo file type (currently libsndfile or

+ffmpeg) are marked e.g. `\fB(also with \-t sndfile)\fR'. This might be

+useful if you have a file that doesn't work with SoX's default format

+readers and writers, and there's an external reader or writer for that

+format.

+.SP

+.TP

+.B .raw (also with \-t sndfile)

+Raw (headerless) audio files.  The sample rate, sample size, and data

+encoding must be given using command-line format options; the number of

+channels defaults to 1.

+.TP

+\&\fB.ub\fR, \fB.sb\fR, \fB.uw\fR, \fB.sw\fR, \fB.ul\fR, \fB.al\fR, \fB.lu\fR, \fB.la\fR, \fB.sl\fR \fB(also with \-t sndfile)\fR

+These filename extensions serve as shorthand for identifying the format

+of headerless audio files.  Thus, \fBub\fR, \fBsb\fR, \fBuw\fR,

+\fBsw\fR, \fBul\fR, \fBal\fR, \fBlu\fR, \fBla\fR and \fBsl\fR indicate a

+file with a single audio channel, sample rate of 8000\ Hz, and samples

+encoded as `unsigned byte', `signed byte', `unsigned word', `signed

+word', `\(*m-law' (byte), `A-law' (byte), inverse bit order `\(*m-law',

+inverse bit order `A-law', or `signed long' respectively.  Command-line

+format options can also be given to modify the selected format if it

+does not provide an exact match for a particular file.

+.SP

+Headerless audio files on a SPARC computer are likely to be of format

+\fBul\fR;  on a Mac, they're likely to be \fBub\fR but with a

+sample rate of 11025 or 22050\ Hz.

+.TP

+.B .8svx (also with \-t sndfile)

+Amiga 8SVX musical instrument description format.

+.TP

+\&\fB.aiff\fR, \fB.aif\fR \fB(also with \-t sndfile)\fR

+AIFF files used on Apple IIc/IIgs and SGI.

+Note: the AIFF format supports only one SSND chunk.

+It does not support multiple audio chunks,

+or the 8SVX musical instrument description format.

+AIFF files are multimedia archives and

+can have multiple audio and picture chunks.

+You may need a separate archiver to work with them.

+.TP

+\&\fB.aiffc\fR, \fB.aifc\fR \fB(also with \-t sndfile)\fR

+AIFF-C (not compressed, linear), defined in DAVIC 1.4 Part 9 Annex B.

+This format is referred from ARIB STD-B24, which is specified for

+Japanese data broadcasting.  Any private chunks are not supported.

+.SP

+Note: The input file is currently processed as .aiff.

+.TP

+.B alsa

+ALSA device driver.

+This is a pseudo-file type and can be optionally compiled into SoX.  Run

+.EX

+	sox -h

+.EE

+to see if you have support for this file type.  When this driver is used

+it allows you to open up a ALSA device and configure it to

+use the same data format as passed in to SoX.

+It works for both playing and recording audio files.  When playing audio

+files it attempts to set up the ALSA driver to use the same format as the

+input file.  It is suggested to always override the output values to use

+the highest quality format your ALSA system can handle.  Example:

+.EX

+	sox infile -t alsa default

+.EE

+.TP

+\&\fB.amr\-wb\fR

+Adaptive Multi Rate\*mWideband speech codec; a lossy format used in 3rd

+generation mobile telephony and defined in 3GPP TS 26.173.

+.SP

+AMR-WB audio has a fixed sampling rate of 16 kHz and supports encoding

+to the following bit-rates (as selected by the

+.B \-C

+option): 0 = 6\*d6 kbit/s, 1 = 8\*d85 kbit/s, 2 = 12\*d65 kbit/s, 3 =

+14\*d25 kbit/s, 4 = 15\*d85 kbit/s 5 = 18\*d25 kbit/s, 6 = 19\*d85

+kbit/s, 7 = 23\*d05 kbit/s, 8 = 23\*d85 kbit/s

+.TP

+.B ao

+libao device driver.

+This is a pseudo-file type and can be optionally compiled into SoX.  Run

+.EX

+	sox -h

+.EE

+to see if you have support for this file type. It works only for

+playing audio files. It can play to a wide range of devices and sound

+systems. See its documentation for the full range. At the moment SoX's

+use of libao cannot be configured directly; you must use libao

+configuration files.

+.TP

+\&\fB.au\fR, \fB.snd\fR \fB(also with \-t sndfile)\fR

+Sun Microsystems AU files.

+There are many types of AU file;

+DEC has invented its own with a different magic number

+and byte order.

+SoX can read these files but will not write them.

+Some .au files are known to have invalid AU headers; these

+are probably original Sun \(*m-law 8000\ Hz files and

+can be dealt with using the

+.B .ul

+format (see below).

+.SP

+It is possible to override AU file header information

+with the

+.B \-r

+and

+.B \-c

+options, in which case SoX will issue a warning to that effect.

+.TP

+\fBauto\fR

+This format type name exists for backwards compatibility only.

+If given for an input file it will be silently ignored,

+if given for an output file it will cause SoX to exit with an error.

+.TP

+.B .avr

+Audio Visual Research.

+The AVR format is produced by a number of commercial packages

+on the Mac.

+.TP

+.B .caf (libsndfile)

+Core Audio File format.

+.TP

+\&\fB.cdda\fR, \fB.cdr\fR

+`Red Book' Compact Disc Digital Audio.

+CDDA has two audio channels formatted as 16-bit

+signed integers at a sample rate of 44\*d1\ kHz.  The number of (stereo)

+samples in each CDDA track is always a multiple of 588 which is why it

+needs its own handler.

+.TP

+\&\fB.cvsd\fR, \fB.cvs\fR

+Continuously Variable Slope Delta modulation.

+A headerless format used to compress speech audio for applications such as voice mail.

+This format is sometimes used with bit-reversed samples\*mthe

+.B \-X

+format option can be used to set the bit-order.

+.TP

+.B .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.  Subsequent lines

+contain two numeric data items: the time since

+the beginning of the first sample and the sample value.

+Values are normalized so that the maximum and minimum

+are 1 and \-1.  This file format can be used to

+create data files for external programs such as

+FFT analysers or graph routines.  SoX can also convert

+a file in this format back into one of the other file

+formats.

+.TP

+\&\fB.dvms\fR, \fB.vms\fR

+Used in Germany to compress speech audio for voice mail.

+A self-describing variant of

+.BR cvsd .

+.TP

+.B .fap (libsndfile)

+See

+.BR .paf .

+.TP

+.B ffmpeg

+This is a pseudo-type that forces ffmpeg to be used. The actual file

+type is deduced from the file name (it cannot be used on stdio). This

+pseudo-type depends on SoX having been built with optional ffmpeg

+support. It can read a wide range of audio files, not all of which are

+documented here, and also the audio track of many video files

+(including AVI, WMV and MPEG). At present only the first audio track

+of a file can be read.

+.TP

+.B .flac (also with \-t sndfile)

+Free Lossless Audio CODEC compressed audio.

+FLAC is an open, patent-free CODEC designed for compressing

+music.  It is similar to MP3 and Ogg Vorbis, but lossless,

+meaning that audio is compressed in FLAC without any loss in

+quality.

+.SP

+SoX can decode native FLAC files (.flac) but not Ogg FLAC files (.ogg).

+[But see

+.B .ogg

+below for information relating to support for Ogg

+Vorbis files.]

+.SP

+SoX has basic support for writing FLAC files: it can encode to

+native FLAC using compression levels 0 to 8.  8 is the default

+compression level and gives the best (but slowest) compression;

+0 gives the least (but fastest) compression.  The compression

+level can be selected using the

+.B \-C

+option (see above) with a whole number from 0 to 8.

+.SP

+FLAC support in

+SoX is optional and requires optional FLAC libraries.  To

+see if there is support for FLAC run

+.EX

+	sox -h

+.EE

+and look for

+it under the list of supported file formats as `flac'.

+.TP

+.B .fssd

+An alias for the

+.B .ub

+format.

+.TP

+.B .gsm (also with \-t sndfile)

+GSM 06.10 Lossy Speech Compression.

+A lossy format for compressing speech which is used in the

+Global Standard for Mobile telecommunications (GSM).  It's good

+for its purpose, shrinking audio data size, but it will introduce

+lots of noise when a given audio signal is encoded and decoded

+multiple times.  This format is used by some voice mail applications.

+It is rather CPU intensive.

+.SP

+GSM in

+SoX is optional and requires access to an external GSM library.  To see

+if there is support for GSM run

+.EX

+	sox -h

+.EE

+and look for it under the list of supported file formats.

+.TP

+.B .hcom

+Macintosh HCOM files.

+These are (apparently) Mac FSSD files with some variant

+of Huffman compression.

+The Macintosh has wacky file formats and this format

+handler apparently doesn't handle all the ones it should.

+Mac users will need their usual arsenal of file converters

+to deal with an HCOM file on other systems.

+.TP

+.B ircam (also with \-t sndfile)

+Another name for

+.BR .sf .

+.TP

+.B .ima (also with \-t sndfile)

+A headerless file of IMA ADPCM audio data. IMA ADPCM claims 16-bit precision

+packed into only 4 bits, but in fact sounds no better than

+.BR .vox .

+.TP

+\&\fB.lpc\fR, \fB.lpc10\fR

+LPC-10 is a compression scheme for speech developed in the United

+States. See http://www.arl.wustl.edu/~jaf/lpc/ for details. There is

+no associated file format, so SoX's implementation is headerless.

+.TP

+\&\fB.mat\fR, \fB.mat4\fR, \fB.mat5\fR \fB(libsndfile)\fR

+Matlab 4.2/5.0 (respectively GNU Octave 2.0/2.1) format (.mat is the same as .mat4).

+.TP

+.B .m3u

+A

+.I playlist

+format; contains a list of audio files.

+See [1] for details of this format.

+.TP

+.B .maud

+An IFF-conforming audio 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, \(*m-law

+in mono and stereo.

+.TP

+\&\fB.mp3\fR, \fB.mp2\fR

+MP3 compressed audio.  MP3 (MPEG Layer 3) is part of the

+MPEG standards for audio and video compression.  It is a lossy

+compression format that achieves good compression rates with little

+quality loss.  See also

+.B Ogg Vorbis

+for a similar format.

+.SP

+MP3 support in

+SoX is optional and requires access to either or both the external

+libmad and libmp3lame libraries. To see if there is support for MP3 run

+.EX

+	sox -h

+.EE

+and look for it under the list of supported file formats as `mp3'.

+.SP

+.TP

+\&\fB.mp4\fR, \fB.m4a\fR \fB(ffmpeg)\fR

+MP4 compressed audio.  MP3 (MPEG 4) is part of the

+MPEG standards for audio and video compression.  See

+.B mp3

+for more information.

+.SP

+MP4 support in SoX is optional and requires access to the external

+ffmpeg libraries.

+.TP

+.B .nist (also with \-t sndfile)

+See \fB.sph\fR.

+.TP

+\&\fB.ogg\fR, \fB.vorbis\fR

+Ogg Vorbis compressed audio.

+Ogg Vorbis is a open, patent-free CODEC designed for compressing music

+and streaming audio.  It is a lossy compression format (similar to MP3,

+VQF & AAC) that achieves good compression rates with a minimum amount of

+quality loss.  See also

+.B MP3

+for a similar format.

+.SP

+SoX can decode all types of Ogg Vorbis files, and can encode at different

+compression levels/qualities given as a number from \-1 (highest

+compression/lowest quality) to 10 (lowest compression, highest quality).

+By default the encoding quality level is 3 (which gives an encoded rate

+of approx. 112kbps), but this can be changed using the

+.B \-C

+option (see above) with a number from \-1 to 10; fractional numbers (e.g.

+3\*d6) are also allowed.

+.SP

+Decoding is somewhat CPU intensive and encoding is very CPU intensive.

+.SP

+Ogg Vorbis in

+SoX is optional and requires access to external Ogg Vorbis libraries.  To

+see if there is support for Ogg Vorbis run

+.EX

+	sox -h

+.EE

+and look for it under the list of supported file formats as `vorbis'.

+.TP

+.B oss

+OSS /dev/dsp device driver.

+This is a pseudo-file that can be optionally compiled into SoX.  Run

+.EX

+	sox -h

+.EE

+to see if it is supported. When this driver is used it allows you to

+play and record sounds on supported systems. When playing audio

+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 format your OSS system can handle. Example:

+.EX

+	sox infile -t oss -2 -s /dev/dsp

+.EE

+.TP

+\&\fB.paf\fR, \fB.fap\fR \fB(libsndfile)\fR

+Ensoniq PARIS file format (big and little-endian respectively).

+.TP

+.B .pls

+A

+.I playlist

+format; contains a list of audio files.

+See [2] for details of this format.

+Note: SHOUTcast PLS is only partially supported.

+.TP

+.B .prc

+Psion Record. Used in Psion EPOC PDAs (Series 5, Revo and similar) for

+System alarms and recordings made by the built-in Record application.

+When writing, SoX defaults to A-law, which is recommended; if you must

+use ADPCM, then use the \fB\-i\fR switch. The sound quality is poor

+because Psion Record seems to insist on frames of 800 samples or

+fewer, so that the ADPCM CODEC has to be reset at every 800 frames,

+which causes the sound to glitch every tenth of a second.

+.TP

+.B .pvf (libsndfile)

+Portable Voice Format.

+.TP

+.B .sd2 (libsndfile)

+Sound Designer 2 format.

+.TP

+.B .sds (libsndfile)

+MIDI Sample Dump Standard.

+.TP

+.B .sf (also with \-t sndfile)

+IRCAM SDIF (Institut de Recherche et Coordination Acoustique/Musique

+Sound Description Interchange Format). Used by academic music software

+such as the CSound package, and the MixView sound sample editor.

+.TP

+\&\fB.sph\fR, \fB.nist\fR \fB(also with \-t sndfile)\fR

+SPHERE (SPeech HEader Resources) is a file format defined by NIST

+(National Institute of Standards and Technology) and is used with

+speech audio.  SoX can read these files when they contain

+\(*m-law and PCM data.  It will ignore any header information that

+says the data is compressed using \fIshorten\fR compression and

+will treat the data as either \(*m-law or PCM.  This will allow SoX

+and the command line \fIshorten\fR program to be run together using

+pipes to encompasses the data and then pass the result to SoX for processing.

+.TP

+.B .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.

+.TP

+.B .snd

+See

+.BR .au .

+.TP

+.B sndfile

+This is a pseudo-type that forces libsndfile to be used. For writing files, the

+actual file type is then taken from the output file name; for reading

+them, it is deduced from the file.

+This pseudo-type depends on SoX having been built with optional

+libsndfile support.

+.TP

+.B .sndt

+SoundTool files. This is an older DOS file format.

+.TP

+.B .sou

+An alias for the

+.B .ub

+format.

+.TP

+.B sunau

+Sun /dev/audio device driver.

+This is a pseudo-file type and can be optionally compiled into SoX.  Run

+.EX

+	sox -h

+.EE

+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 audio files.  When playing audio

+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 format your hardware can handle.  Example:

+.EX

+	sox infile -t sunau -2 -s /dev/audio

+.EE

+or

+.EX

+	sox infile -t sunau -U -c 1 /dev/audio

+.EE

+for older sun equipment.

+.TP

+.B .txw

+Yamaha TX-16W sampler.

+A file format from a Yamaha sampling keyboard which wrote IBM-PC

+format 3\*d5\(dq 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

+33\ kHz if the sample rate is still unknown.

+.TP

+.B .vms

+See

+.BR .dvms .

+.TP

+.B .voc (also with \-t sndfile)

+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 appropriately.

+On output, silence is not detected, nor are impossible sample rates.

+Note, this version now supports playing VOC files with multiple

+blocks and supports playing files containing \(*m-law and A-law samples.

+.TP

+.B .vorbis

+See

+.BR .ogg .

+.TP

+.B .vox (also with \-t sndfile)

+A headerless file of Dialogic/OKI ADPCM audio data commonly comes with the

+extension .vox.  This ADPCM data has 12-bit precision packed into only 4-bits.

+.TP

+.B .w64 (libsndfile)

+Sonic Foundry's 64-bit RIFF/WAV format.

+.TP

+.B .wav \fB(also with \-t sndfile)\fR

+Microsoft .WAV RIFF files.

+This is the native audio file format of Windows, and widely used for uncompressed audio.

+.SP

+Normally \fB.wav\fR 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 \fB.wav\fR

+will written appropriately.

+.SP

+SoX currently can read PCM, \(*m-law, A-law, MS ADPCM, and IMA (or DVI) ADPCM.

+It can write all of these formats including the ADPCM encoding.

+Big endian versions of RIFF files, called RIFX, can also be read

+and written.  To write a RIFX file, use the

+.B \-B

+option with the output file options.

+.TP

+.B .wve

+Psion 8-bit A-law.  Used on Psion SIBO PDAs (Series 3 and similar).

+.TP

+.B .xa

+Maxis XA files.

+These are 16-bit ADPCM audio files used by Maxis games.  Writing .xa files is

+currently not supported, although adding write support should not be very

+difficult.

+.TP

+.B .xi (libsndfile)

+Fasttracker 2 Extended Instrument format.

+.SH SEE ALSO

+.BR sox (1),

+.BR soxeffect (7),

+.BR libsox (3),

+.BR octave (1),

+.BR soxexam (7),

+.BR wget (1)

+.SP

+The SoX web page at http://sox.sourceforge.net

+.SS References

+.TP

+[1]

+Wikipedia,

+.IR "M3U" ,

+http://en.wikipedia.org/wiki/M3U

+.TP

+[2]

+Wikipedia,

+.IR "PLS" ,

+http://en.wikipedia.org/wiki/PLS_(file_format)

+.SH AUTHORS

+Chris Bagwell (cbagwell@users.sourceforge.net).

+Other authors and contributors are listed in the AUTHORS file that

+is distributed with the source code.