Man page for apt-get sox Command
This tutorial shows the man page for man sox in linux.
Open terminal with 'su' access and type the command as shown below:
man sox
Result of the Command Execution shown below:
SoX(1) Sound eXchange SoX(1)
NAME
SoX Sound eXchange, the Swiss Army knife of audio manipulation
SYNOPSIS
sox [global options] [format options] infile1
[[format options] infile2] ... [format options] outfile
[effect [effect options]] ...
play [global options] [format options] infile1
[[format options] infile2] ... [format options]
[effect [effect options]] ...
rec [global options] [format options] outfile
[effect [effect options]] ...
DESCRIPTION
Introduction
SoX reads and writes audio files in most popular formats and can
optionally apply effects to them; it can combine multiple input
sources, synthesise audio, and, on many systems, act as a general pur
pose audio player or a multi track audio recorder. It also has limited
ability to split the input in to multiple output files.
All SoX functionality is available using just the sox command, however,
to simplify playing and recording audio, if SoX is invoked as play the
output file is automatically set to be the default sound device and if
invoked as rec the default sound device is used as an input source.
Additionally, the soxi(1) command provides a convenient way to just
query audio file header information.
The heart of SoX is a library called libSoX. Those interested in
extending SoX or using it in other programs should refer to the libSoX
manual page: libsox(3).
SoX is a command line audio processing tool, particularly suited to
making quick, simple edits and to batch processing. If you need an
interactive, graphical audio editor, use audacity(1).
* * *
The overall SoX processing chain can be summarised as follows:
Input(s) > Combiner > Effects > Output(s)
Note however, that on the SoX command line, the positions of the Out
put(s) and the Effects are swapped w.r.t. the logical flow just shown.
Note also that whilst options pertaining to files are placed before
their respective file name, the opposite is true for effects. To show
how this works in practice, here is a selection of examples of how SoX
might be used. The simple
sox recital.au recital.wav
translates an audio file in Sun AU format to a Microsoft WAV file,
whilst
sox recital.au b 16 recital.wav channels 1 rate 16k fade 3 norm
performs the same format translation, but also applies four effects
(down mix to one channel, sample rate change, fade in, nomalize), and
stores the result at a bit depth of 16.
sox r 16k e signed b 8 c 1 voice memo.raw voice memo.wav
converts `raw' (a.k.a. `headerless') audio to a self describing file
format,
sox slow.aiff fixed.aiff speed 1.027
adjusts audio speed,
sox short.wav long.wav longer.wav
concatenates two audio files, and
sox m music.mp3 voice.wav mixed.flac
mixes together two audio files.
play "The Moonbeams/Greatest/*.ogg" bass +3
plays a collection of audio files whilst applying a bass boosting
effect,
play n c1 synth sin % 12 sin % 9 sin % 5 sin % 2 fade h 0.1 1 0.1
plays a synthesised `A minor seventh' chord with a pipe organ sound,
rec c 2 radio.aiff trim 0 30:00
records half an hour of stereo audio, and
rec M take1.aiff take1 dub.aiff
records a new track in a multi track recording. Finally,
rec r 44100 b 16 s p silence 1 0.50 0.1% 1 10:00 0.1% | \
sox p song.ogg silence 1 0.50 0.1% 1 2.0 0.1% : \
newfile : restart
records a stream of audio such as LP/cassette and splits in to multiple
audio files at points with 2 seconds of silence. Also, it does not
start recording until it detects audio is playing and stops after it
sees 10 minutes of silence.
N.B. The above is just an overview of SoX's capabilities; detailed
explanations of how to use all SoX parameters, file formats, and
effects can be found below in this manual, in soxformat(7), and in
soxi(1).
File Format Types
There are two types of audio file format that SoX can work with: `self
describing' these (e.g. WAV, FLAC) have a header that completely
describes the signal and encoding attributes of the audio data that
follows, and `raw' (or `headerless') audio the audio characteristics
of these must, when reading a raw file, be described using the SoX com
mand line, and, when writing a raw file, be set using the command line
(or inferred from those of the input file).
The following four characteristics are used to describe the format of
audio data such that it can be processed with SoX:
sample rate
The sample rate in samples per second (`Hertz' or `Hz'). For
example, digital telephony traditionally uses a sample rate of
8000 Hz (8 kHz), though these days, 16 and even 32 kHz are
becoming more common; audio Compact Discs use 44100 Hz
(44.1 kHz); Digital Audio Tape and many computer systems use
48 kHz; professional audio systems often use 96 kHz.
sample size
The number of bits used to store each sample. Today, 16 bit is
commonly used; 8 bit was popular in the early days of computer
audio; 24 bit is used in the professional audio arena; other
sizes are also used.
data encoding
The way in which each audio sample is represented (or
`encoded'). Some encodings have variants with different byte
orderings or bit orderings; some `compress' the audio data, i.e.
the stored audio data takes up less space (i.e. disk space or
transmission band width) than the other format parameters and
the number of samples would imply. Commonly used encoding types
include floating point, u law, ADPCM, signed integer PCM, MP3,
and FLAC.
channels
The number of audio channels contained in the file. One
(`mono') and two (`stereo') are widely used. `Surround sound'
audio typically contains six or more channels.
The term `bit rate' is a measure of the amount of storage occupied by
an encoded audio signal over a unit of time. It can depend on all of
the above and is typically denoted as a number of kilo bits per second
(kbps). An A law telephony signal has a bit rate of 64 kbs;
MP3 encoded stereo music typically has a bit rate of 128 196 kbps;
FLAC encoded stereo music typically has a bit rate of 550 760 kbps.
Most self describing formats also allow textual `comments' to be embed
ded in the file that can be used to describe the audio in some way,
e.g. for music, the title, the author, etc.
One important use of audio file comments is to convey `Replay Gain'
information. SoX supports applying Replay Gain information, but not
generating it. Note that by default, SoX copies input file comments to
output files that support comments, so output files may contain Replay
Gain information if some was present in the input file. In this case,
if anything other than a simple format conversion was performed then
the output file Replay Gain information is likely to be incorrect and
so should be recalculated using a tool that supports this (not SoX).
The soxi(1) command can be used to display information from audio file
headers.
Determining & Setting The File Format
There are several mechanisms available for SoX to use to determine or
set the format characteristics of an audio file. Depending on the cir
cumstances, individual characteristics may be determined or set using
different mechanisms.
To determine the format of an input file, SoX will use, in order of
precedence and as given or available:
1. Command line format options.
2. The contents of the file header.
3. The filename extension.
To set the output file format, SoX will use, in order of precedence and
as given or available:
1. Command line format options.
2. The filename extension.
3. The input file format characteristics, or the closest to them that
is supported by the output file type.
For all files, SoX will exit with an error if the file type cannot be
determined; command line format options may need to be added or changed
to resolve the problem.
Playing & Recording Audio
The play and rec commands are provided so that basic playing and
recording is as simple as
play existing file.wav
and
rec new file.wav
These two commands are functionally equivalent to
sox existing file.wav d
and
sox d new file.wav
Of course, further options and effects (as described below) can be
added to the commands in either form.
* * *
Some systems provide more than one type of (SoX compatible) audio
driver, e.g. ALSA & OSS, or SUNAU & AO. Systems can also have more
than one audio device (a.k.a. `sound card'). If more than one audio
driver has been built in to SoX, and the default selected by SoX when
recording or playing is not the one that is wanted, then the AUDIO
DRIVER environment variable can be used to override the default. For
example (on many systems):
set AUDIODRIVER=oss
play ...
The AUDIODEV environment variable can be used to override the default
audio device; e.g.
set AUDIODEV=/dev/dsp2
play ...
sox ... t oss
or
set AUDIODEV=hw:soundwave,1,2
play ...
sox ... t alsa
Note that the way of setting environment variables varies from system
to system for some specific examples, see `SOX_OPTS' below.
When playing a file with a sample rate that is not supported by the
audio output device, SoX will automatically invoke the rate effect to
perform the necessary sample rate conversion. For compatibility with
old hardware, here, the default rate quality level is set to `low';
however, this can be changed if desired, by explicitly specifying the
rate effect with a different quality level, e.g.
play ... rate m
or by using the play rate arg option (see below).
* * *
On some systems, SoX allows audio playback volume to be adjusted whilst
using play; where supported, this is achieved by tapping the `v' & `V'
keys during playback.
To help with setting a suitable recording level, SoX includes a peak
level meter which can be invoked (before making the actual recording)
as follows:
rec n
The recording level should be adjusted (using the system provided mixer
program, not SoX) so that the meter is at most occasionally full scale,
and never `in the red' (an exclamation mark is shown). See also S
below.
Accuracy
Many file formats that compress audio discard some of the audio signal
information whilst doing so; converting to such a format then convert
ing back again will not produce an exact copy of the original audio.
This is the case for many formats used in telephony (e.g. A law, GSM)
where low signal bandwidth is more important than high audio fidelity,
and for many formats used in portable music players (e.g. MP3, Vorbis)
where adequate fidelity can be retained even with the large compression
ratios that are needed to make portable players practical.
Formats that discard audio signal information are called `lossy', and
formats that do not, `lossless'. The term `quality' is used as a mea
sure of how closely the original audio signal can be reproduced when
using a lossy format.
Audio file conversion with SoX is lossless when it can be, i.e. when
not using lossy compression, when not reducing the sampling rate or
number of channels, and when the number of bits used in the destination
format is not less than in the source format. E.g. converting from an
8 bit PCM format to a 16 bit PCM format is lossless but converting from
an 8 bit PCM format to (8 bit) A law isn't.
N.B. SoX converts all audio files to an internal uncompressed format
before performing any audio processing; this means that manipulating a
file that is stored in a lossy format can cause further losses in audio
fidelity. E.g. with
sox long.mp3 short.mp3 trim 10
SoX first decompresses the input MP3 file, then applies the trim
effect, and finally creates the output MP3 file by re compressing the
audio with a possible reduction in fidelity above that which occurred
when the input file was created. Hence, if what is ultimately desired
is lossily compressed audio, it is highly recommended to perform all
audio processing using lossless file formats and then convert to the
lossy format only at the final stage.
N.B. Applying multiple effects with a single SoX invocation will, in
general, produce more accurate results than those produced using multi
ple SoX invocations; hence this is also recommended.
Dithering
Dithering is a technique used to maximise the dynamic range of audio
stored at a particular bit depth: any distortion introduced by quanti
sation is decorrelated by adding a small amount of white noise to the
signal. In most cases, SoX can determine whether the selected process
ing requires dither and will add it during output formatting if appro
priate.
Specifically, by default, SoX automatically adds TPDF dither when the
output bit depth is less than 24 and any of the following are true:
o bit depth reduction has been specified explicitly using a command
line option
o the output file format supports only bit depths lower than that of
the input file format
o an effect has increased effective bit depth within the internal
processing chain
For example, adjusting volume with vol 0.25 requires two additional
bits in which to losslessly store its results (since 0.25 decimal
equals 0.01 binary). So if the input file bit depth is 16, then SoX's
internal representation will utilise 18 bits after processing this vol
ume change. In order to store the output at the same depth as the
input, dithering is used to remove the additional bits.
Use the V option to see what processing SoX has automatically added;
the D option may be given to override automatic dithering. To invoke
dithering manually (e.g. to select a noise shaping curve), see the
dither effect.
Clipping
Clipping is distortion that occurs when an audio signal level (or `vol
ume') exceeds the range of the chosen representation. In most cases,
clipping is undesirable and so should be corrected by adjusting the
level prior to the point (in the processing chain) at which it occurs.
In SoX, clipping could occur, as you might expect, when using the vol
or gain effects to increase the audio volume, but could also occur with
many other effects, when converting one format to another, and even
when simply playing the audio.
Playing an audio file often involves resampling, and processing by ana
logue components that can introduce a small DC offset and/or amplifica
tion, all of which can produce distortion if the audio signal level was
initially too close to the clipping point.
For these reasons, it is usual to make sure that an audio file's signal
level has some `headroom', i.e. it does not exceed a particular level
below the maximum possible level for the given representation. Some
standards bodies recommend as much as 9dB headroom, but in most cases,
3dB (~~ 70% linear) will probably suffice. Note that this wisdom seems
to have been lost in modern music production; in fact, many CDs, MP3s,
etc. are now mastered at levels above 0dBFS i.e. the audio is clipped
as delivered.
SoX's stat and stats effects can assist in determining the signal level
in an audio file; the gain or vol effect can be used to prevent clip
ping, e.g.
sox dull.wav bright.wav gain 6 treble +6
guarantees that the treble boost will not clip.
If clipping occurs at any point during processing, then SoX will dis
play a warning message to that effect.
See also G and the gain and norm effects.
Input File Combining
SoX's input combiner can be configured (see OPTIONS below) to combine
multiple files using any of the following methods: `concatenate',
`sequence', `mix', `mix power', or `merge'. The default method is
`sequence' for play, and `concatenate' for rec and sox.
For all methods other than `sequence', multiple input files must have
the same sampling rate; if necessary, separate SoX invocations can be
used to make sampling rate adjustments prior to combining.
If the `concatenate' combining method is selected (usually, this will
be by default) then the input files must also have the same number of
channels. The audio from each input will be concatenated in the order
given to form the output file.
The `sequence' combining method is selected automatically for play. It
is similar to `concatenate' in that the audio from each input file is
sent serially to the output file, however here the output file may be
closed and reopened at the corresponding transition between input files
this may be just what is needed when sending different types of audio
to an output device, but is not generally useful when the output is a
normal file.
If either the `mix' or `mix power' combining method is selected, then
two or more input files must be given and will be mixed together to
form the output file. The number of channels in each input file need
not be the same, however, SoX will issue a warning if they are not and
some channels in the output file will not contain audio from every
input file. A mixed audio file cannot be un mixed (without reference
to the original input files).
If the `merge' combining method is selected, then two or more input
files must be given and will be merged together to form the output
file. The number of channels in each input file need not be the same.
A merged audio file comprises all of the channels from all of the input
files; un merging is possible using multiple invocations of SoX with
the remix effect. For example, two mono files could be merged to form
one stereo file; the first and second mono files would become the left
and right channels of the stereo file.
When combining input files, SoX applies any specified effects (includ
ing, for example, the vol volume adjustment effect) after the audio has
been combined; however, it is often useful to be able to set the volume
of (i.e. `balance') the inputs individually, before combining takes
place.
For all combining methods, input file volume adjustments can be made
manually using the v option (below) which can be given for one or more
input files; if it is given for only some of the input files then the
others receive no volume adjustment. In some circumstances, automatic
volume adjustments may be applied (see below).
The V option (below) can be used to show the input file volume adjust
ments that have been selected (either manually or automatically).
There are some special considerations that need to made when mixing
input files:
Unlike the other methods, `mix' combining has the potential to cause
clipping in the combiner if no balancing is performed. So here, if
manual volume adjustments are not given, to ensure that clipping does
not occur, SoX will automatically adjust the volume (amplitude) of each
input signal by a factor of 1/n, where n is the number of input files.
If this results in audio that is too quiet or otherwise unbalanced then
the input file volumes can be set manually as described above; using
the norm effect on the mix is another alternative.
If mixed audio seems loud enough at some points through the mixed audio
but too quiet in others, then dynamic range compression should be
applied to correct this see the compand effect.
With the `mix power' combine method, the mixed volume is appropriately
equal to that of one of the input signals. This is achieved by balanc
ing using a factor of 1/\/n instead of 1/n. Note that this balancing
factor does not guarantee that no clipping will occur, however, in many
cases, the number of clips will be low and the resultant distortion
imperceptible.
Output Files
SoX's default behaviour is to take one or more input files and write
them to a single output file.
This behaviour can be changed by specifying the pseudo effect `newfile'
within the effects list. SoX will then enter multiple output mode.
In multiple output mode, a new file is created when the effects prior
to the `newfile' indicate they are done. The effects chain listed
after `newfile' is then started up and its output is saved to the new
file.
In multiple output mode, a unique number will automatically be appended
to the end of all filenames. If the filename has an extension then the
number is inserted before the extension. This behaviour can be custom
ized by placing a %n anywhere in the filename where the number should
be substituted. An optional number can be placed after the % to indi
cate a minimum fixed width for the number.
Multiple output mode is not very useful unless an effect that will stop
the effects chain early is specified before the `newfile'. If end of
file is reached before the effects chain stops itself then no new file
will be created as it would be empty.
The following is an example of splitting the first 60 seconds of an
input file in to two 30 second files and ignoring the rest.
sox song.wav ringtone%1n.wav trim 0 30 : newfile : trim 0 30
Stopping SoX
Usually SoX will complete its processing and exit automatically once it
has read all available audio data from the input files.
If desired, it can be terminated earlier by sending an interrupt signal
to the process (usually by pressing the keyboard interrupt key which is
normally Ctrl C). This is a natural requirement in some circumstances,
e.g. when using SoX to make a recording. Note that when using SoX to
play multiple files, Ctrl C behaves slightly differently: pressing it
once causes SoX to skip to the next file; pressing it twice in quick
succession causes SoX to exit.
Another option to stop processing early is to use an effect that has a
time period or sample count to determine the stopping point. The trim
effect is an example of this. Once all effects chains have stopped
then SoX will also stop.
FILENAMES
Filenames can be simple file names, absolute or relative path names, or
URLs (input files only). Note that URL support requires that wget(1)
is available.
Note: Giving SoX an input or output filename that is the same as a SoX
effect name will not work since SoX will treat it as an effect
specification. The only work around to this is to avoid such
filenames; however, this is generally not difficult since most audio
filenames have a filename `extension', whilst effect names do not.
Special Filenames
The following special filenames may be used in certain circumstances in
place of a normal filename on the command line:
SoX can be used in simple pipeline operations by using the
special filename ` ' which, if used as an input filename, will
cause SoX will read audio data from `standard input' (stdin),
and which, if used as the output filename, will cause SoX will
send audio data to `standard output' (stdout). Note that when
using this option for the output file, and sometimes when using
it for an input file, the file type (see t below) must also be
given.
"|program [options] ..."
This can be used in place of an input filename to specify the
the given program's standard output (stdout) be used as an input
file. Unlike (above), this can be used for several inputs to
one SoX command. For example, if `genw' generates mono WAV
formatted signals to its standard output, then the following
command makes a stereo file from two generated signals:
sox M "|genw imd " "|genw thd " out.wav
For headerless (raw) audio, t (and perhaps other format
options) will need to be given, preceding the input command.
"wildcard filename"
Specifies that filename `globbing' (wild card matching) should
be performed by SoX instead of the shell. This allows a single
set of file options to be applied to a group of files. For
example, if the current directory contains three `vox' files:
file1.vox, file2.vox, and file3.vox, then
play rate 6k *.vox
will be expanded by the `shell' (in most environments) to
play rate 6k file1.vox file2.vox file3.vox
which will treat only the first vox file as having a sample rate
of 6k; but with
play rate 6k "*.vox"
the given sample rate option will be applied to all three vox
files.
p, sox pipe
This can be used in place of an output filename to specify that
the SoX command should be used as in input pipe to another SoX
command. For example, the command:
play "|sox n p synth 2" "|sox n p synth 2 tremolo 10" stat
plays two `files' in succession, each with different effects.
p is in fact an alias for ` t sox '.
d, default device
This can be used in place of an input or output filename to
specify that the default audio device (if one has been built
into SoX) is to be used. This is akin to invoking rec or play
(as described above).
n, null
This can be used in place of an input or output filename to
specify that a `null file' is to be used. Note that here, `null
file' refers to a SoX specific mechanism and is not related to
any operating system mechanism with a similar name.
Using a null file to input audio is equivalent to using a normal
audio file that contains an infinite amount of silence, and as
such is not generally useful unless used with an effect that
specifies a finite time length (such as trim or synth).
Using a null file to output audio amounts to discarding the
audio and is useful mainly with effects that produce information
about the audio instead of affecting it (such as noiseprof or
stat).
The sampling rate associated with a null file is by default
48 kHz, but, as with a normal file, this can be overridden if
desired using command line format options (see below).
Supported File & Audio Device Types
See soxformat(7) for a list and description of the supported file for
mats and audio device drivers.
OPTIONS
Global Options
These options can be specified on the command line at any point before
the first effect name.
The SOX_OPTS environment variable can be used to provide alternative
default values for SoX's global options. For example:
SOX_OPTS=" buffer 20000 play rate arg hs temp /mnt/temp"
Note that setting SOX_OPTS can potentially create unwanted changes in
the behaviour of scripts or other programs that invoke SoX. So
SOX_OPTS might best be used for things (such as in the given example)
that reflect the environment in which SoX is being run. Enabling
options such as no clobber as default might be handled better using a
shell alias since a shell alias will not affect operation in scripts
etc.
One way to ensure that a script can not be affected by SOX_OPTS, is to
clear SOX_OPTS at the start of the script (but this of course loses the
benefit of SOX_OPTS carrying some system wide default options). An
alternative approach is to explicitly invoke SoX with default option
values, e.g.
SOX_OPTS=" V no clobber"
...
sox V2 clobber $input $output ...
Note that the way of setting environment variables varies from system
to system here are some examples:
Unix bash:
export SOX_OPTS=" V no clobber"
Unix csh:
setenv SOX_OPTS " V no clobber"
MS DOS/MS Windows:
set SOX_OPTS= V no clobber
MS Windows GUI: via Control Panel : System : Advanced : Environment
Variables
Mac OS X GUI: Refer to Apple's Technical Q&A QA1067 document.
buffer BYTES, input buffer BYTES
Set the size in bytes of the buffers used for processing audio
(default 8192). buffer applies to input, effects, and output
processing; input buffer applies only to input processing (for
which it overrides buffer if both are given).
Be aware that large values for buffer will cause SoX to be
become slow to respond to requests to terminate or to skip the
current input file.
clobber
Don't prompt before overwriting an existing file with the same
name as that given for the output file. This is the default be
haviour.
D, no dither
Disable automatic dither see `Dither' above. An example of
why this might occasionally be useful is if a file has been con
verted from 16 to 24 bit with the intention of doing some pro
cessing on it, but in fact no processing is needed after all and
the original 16 bit file has been lost, then, strictly speaking,
no di
Español
русский
中国