ref: db8233ee12ca153efd73fc990b7233a3079d654b
parent: 24d144e4f7a11ff2b2359eadcd3e6ae96bfb9733
author: robs <robs>
date: Sun Jul 20 10:02:54 EDT 2008
doc clean-up
--- a/ChangeLog
+++ b/ChangeLog
@@ -131,7 +131,7 @@
Internal improvements:
o Use FORTIFY_SOURCE with gcc. (robs)
- o Fixed all compiler warnings (AFAICT). (robs)
+ o Fixed all compiler warnings (with gcc 4.2.3). (robs)
o Reimplement (separately) SoundTool & Sounder format handlers. (robs)
o Allow formats & effects to have any size of private data. (robs)
--- a/README
+++ b/README
@@ -1,24 +1,56 @@
- SoX: Sound eXchange
- -------------------
+ SoX: Sound eXchange
+ -------------------
-SoX (Sound eXchange) is the Swiss Army knife of sound processing
-tools: it translates sound files between many different file formats,
-and can apply many sound effects and transforms, as well as doing
-basic analysis and providing input to more capable analysis and
-plotting tools.
+SoX (Sound eXchange) is the Swiss Army knife of sound processing tools: it
+can convert sound files between many different file formats & audio devices,
+and can apply many sound effects & transformations, as well as doing basic
+analysis and providing input to more capable analysis and plotting tools.
-SoX is distributed under the GNU GPL and GNU LGPL. To be precise: the
-sox program is distributed under the GPL, while the library libsox, in
-which most of SoX's functionality resides, is dual-licensed. Note that
-some optional components of libsox are GPL only: if you use these, you
-must use libsox under the GPL.
+SoX is licensed under the GNU GPL and GNU LGPL. To be precise, the `sox'
+and `soxi' programs are distributed under the GPL, while the library
+`libsox' (in which most of SoX's functionality resides) is dual-licensed.
+Note that some optional components of libsox are GPL only: if you use these,
+you must use libsox under the GPL.
-Send bug fixes, enhancements and feature requests to
-sox-devel@lists.sourceforge.net, or post them to the relevant tracker
-at http://sourceforge.net/projects/sox/.
+If this distribution is of source code (as opposed to pre-built binaries),
+then you will need to compile and install SoX as described in the `INSTALL'
+file.
-This release understands:
+Changes between this release and previous releases of SoX can be found in
+the `ChangeLog' file; a summary of the file formats and effects supported in
+this release can be found below. Detailed documentation for using SoX can
+be found in the distributed `man' pages:
+ o sox(1)
+ o soxi(1)
+ o soxformat(7)
+ o soxeffect(7)
+ o soxexam(7)
+ o libsox(3)
+
+or in plain text or PDF files for those systems without man.
+
+The majority of SoX features and fixes are contributed by SoX users - thank
+you very much for making SoX a success! There are several new features
+wanted for SoX, listed on the feature request tracker at the SoX project
+home-page:
+ http://sourceforge.net/projects/sox
+
+users are encouraged to implement them!
+
+Please submit bug reports, new feature requests, and patches to the relevant
+tracker at the above address, or by email:
+
+ mailto:sox-devel@lists.sourceforge.net
+
+Also accessible via the project home-page is the SoX users' discussion
+mailing list which you can join to discuss all matters SoX with other SoX
+users; the mail address for this list is:
+
+ mailto:sox-users@lists.sourceforge.net
+
+This release handles the following audio file formats:
+
o Raw files in various binary formats
o Raw textual data
o Amiga 8svx files
@@ -29,7 +61,7 @@
o mutant DEC .au files
o NeXT .snd files
o AVR files
- o CD-R (music CD format)
+ o CDDA (Compact Disc Digital Audio format)
o CVS and VMS files (continuous variable slope)
o GSM files
o HTK files
@@ -43,13 +75,13 @@
o AVI, WMV, Ogg Theora, MPEG video files (with optional ffmpeg
library)
o Ogg Vorbis files (with optional Ogg Vorbis libraries)
- o FLAC files (with optional libflac)
+ o FLAC files (with optional libFLAC)
o IRCAM SoundFile files
o NIST SPHERE files
o Turtle beach SampleVision files
- o Soundtool (DOS) files
+ o Sounder & Soundtool (DOS) files
o Yamaha TX-16W sampler files
- o Sound Blaster .VOC files
+ o SoundBlaster .VOC files
o Dialogic/OKI ADPCM files (.VOX)
o Microsoft .WAV files
o PCM, u-law, A-law
@@ -64,67 +96,84 @@
from most audio devices
o The "null" pseudo-file that reads and writes from/to nowhere
-Most sound formats are auto-detected.
+The audio effects/tools included in this release are as follows:
-The sound effects include:
+ o Tone/filter effects
+ o allpass RBJ all-pass biquad IIR filter
+ o bandpass RBJ band-pass biquad IIR filter
+ o bandreject RBJ band-reject biquad IIR filter
+ o band SPKit resonator band-pass IIR filter
+ o bass Tone control: RBJ shelving biquad IIR filter
+ o deemph ISO 908 CD de-emphasis (shelving) IIR filter
+ o equalizer RBJ peaking equalisation biquad IIR filter
+ o filter JOS low/high/band pass FIR filter with many taps
+ o highpass High-pass filter: Single pole or RBJ biquad IIR
+ o lowpass Low-pass filter: single pole or RBJ biquad IIR
+ o treble Tone control: RBJ shelving biquad IIR filter
- o Channel averaging, duplication, and removal (general mixer)
- o Band-pass filters
- o Band-reject filter
- o Bass tone control
- o Compress and Expand (compand) the dynamic range of a sample
- o Contrast enhancement effect
- o Chorus effect
- o DC-shift audio - useful to get the best volume adjustments
- o De-emphasis filter
- o Delay one or more channels
- o Move sound stage of CD audio to in front of you (for headphone
- use)
- o Add an echo
- o Add a sequence of echos
- o Fade in and out
- o Apply a flanger effect
- o Apply a high-pass filter
- o Apply a low-pass filter
- o Apply an equalizer effect
- o Add dithering/masking noise to a signal
- o Multi-band compander
- o Normalise the audio level
- o Pad with silence
- o Pan sound between channels
- o Apply a phaser effect
- o Change the key (pitch) of a sound file without affecting its speed
- o Repeat audio data
- o Change sampling rate
- o Apply a reverb effect
- o Reverse the sound samples (to search for Satanic messages ;-)
- o Detect periods of silence and start and stop processing based on
- it
- o Create a spectrogram PNG
- o Change speed (pitch and tempo together)
- o Splice together audio sections
- o Display general stats on a sound sample
- o Change the tempo an audio file (without affecting pitch)
- o Swap stereo channels
- o Create sounds with a simple synthesizer
- o Treble tone control
- o Trim audio data from beginning and end of file
- o Apply a tremolo effect
- o Volume adjustment
- o Noise elimination using frequency profiling
- o Resample using libsamplerate (aka Secret Rabbit code, optional
- external library)
- o Apply LADSPA (Linux Audio Developer's Simple Plugin API) effects
- such as cmt (Computer Music Toolkit)
+ o Production effects
+ o chorus Make a single instrument sound like many
+ o delay Delay one or more channels
+ o echo Add an echo
+ o echos Add a sequence of echoes
+ o flanger Stereo flanger
+ o phaser Phase shifter
+ o repeat Loop the audio a number of times
+ o reverb Add reverberation
+ o reverse Reverse the audio (to search for Satanic messages ;-)
+ o tremolo Sinusoidal volume modulation
-Unless you're using a pre-compiled binary version, you will need to
-compile SoX as described in the INSTALL file.
+ o Volume/level effects
+ o compand Signal level compression/expansion/limiting
+ o contrast Phase contrast volume enhancement
+ o dcshift Apply or remove DC offset
+ o fade Apply a fade-in and/or fade-out to the audio
+ o gain Apply gain or attenuation
+ o mcompand Multi-band compression/expansion/limiting
+ o norm Normalise the audio to 0dB or to a specified value
+ o vol Adjust audio volume
-SoX is distributed with man pages, with plain text versions for those
-on systems without man.
+ o Editting effects
+ o pad Pad (usually) the ends of the audio with silence
+ o silence Remove portions of silence from the audio
+ o splice Perform the equivalent of a crossfaded tape splice
+ o trim Trim the ends of the audio
-The majority of SoX features and source code are contributed by users.
-Thank you very much for making SoX a success! There are many new
-features wanted for SoX, listed on the feature request tracker at
-http://sourceforge.net/projects/sox/. Users are encouraged to
-implement them!
+ o Mixing effects
+ o mixer Mix up to 4 channels in certain ways
+ o pan Fade from one channel to another
+ o remix Produce arbirarily mixed output channels
+ o swap Swap stereo channels
+
+ o Key/tempo effects
+ o key Adjust key (= pitch) without changing tempo
+ o speed Adjust key & tempo together
+ o tempo Adjust tempo without changing key
+
+ o Mastering effects
+ o dither Add dither noise to increase SNR of <= 16-bit audio
+ o rate Change audio sampling rate
+
+ o Specialised filters/mixers
+ o earwax Process CD audio to best effect for headphone use
+ o noisered Filter out noise from the audio
+ o oops Out Of Phase Stereo (or `Karaoke') effect
+
+ o Analysis `effects'
+ o noiseprof Produce a DFT profile of the audio (use with noisered)
+ o spectrogram Produce a graph of signal level vs. frequency & time
+ (with optional libpng library)
+ o stat Enumerate audio peak & rms levels, approx. freq., etc.
+
+ o Miscellaneous effects
+ o ladspa Apply LADSPA (Linux Audio Developer's Simple Plugin API)
+ effects such as cmt (Computer Music Toolkit)
+ o synth Synthesise/modulate audio tones or noise signals
+
+In this release, multiple audio files can be combined (and then further
+processed with effects) using any one of the following combiner methods:
+
+ o concatenate
+ o mix
+ o merge E.g. two mono files to one stereo file
+ o sequence For playing multiple audio files/streams
--- a/soxeffect.7
+++ b/soxeffect.7
@@ -289,6 +289,14 @@
.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.
+.SP
+An alternative approach to removing a DC offset (albeit with a short delay)
+is to use the
+.B highpass
+filter effect at a frequency of say 10Hz; i.e.
+.EX
+ sox -n out.au synth 5 sin %0 50 highpass 10
+.EE
.TP
\fBdeemph\fR
Apply a treble attenuation shelving filter to audio in