Overview
Introduction
SoX reads and writes audio files in most popular formats and can optionally apply effects to them. It can combine multiple input sources, synthesize audio and, on many systems, act as a general purpose audio player or as a multitrack audio recorder. It can also split the input into multiple output files.
All SoX functionality is available using just the sox_ng command. To simplify playing and recording audio, if SoX is invoked as play_ng, the output file is automatically set to be the default sound device and, if invoked as rec_ng, the default sound device is used as an input source. Additionally, the soxi_ng command provides a convenient way to query audio file header information.
The heart of SoX is a library called libsox_ng. Those interested in extending SoX or using it in other programs should refer to the libsox_ng manual page.
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 summarized as follows:
| Input(s) → Combiner → Effects → Output(s) |
On the SoX command line, the positions of the Output(s) and the Effects are swapped w.r.t. the logical flow just shown and, while options pertaining to files are placed before their respective file names, 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_ng recital.au recital.wav
translates an audio file in Sun AU format to a Microsoft WAV file, while
sox_ng 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 and normalize) and stores the result at a bit-depth of 16.
sox_ng -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_ng slow.aiff fixed.aiff speed 1.027
adjusts audio speed,
sox_ng short.wav long.wav longer.wav
concatenates two audio files and
sox_ng -m music.mp3 voice.wav mixed.flac
mixes together two audio files.
play_ng "The Moonbeams/Greatest/*.ogg" bass +3
plays a collection of audio files applying a bass boosting effect,
play_ng -n -c1 synth sin %-12 sin %-9 sin %-5 sin %-2 fade h 0.1 1 0.1
plays a synthesized `A minor seventh' chord with a pipe organ sound,
rec_ng -c 2 radio.aiff trim 0 30:00
records half an hour of stereo audio and
play_ng -q take1.aiff & rec -M take1.aiff take1-dub.aiff
(with a POSIX shell and where supported by hardware) records a new track in a multitrack recording. Finally,
rec_ng -r 44100 -b 16 -e signed-integer -p \
silence 1 0.50 0.1% 1 10:00 0.1% | \
sox_ng -p song.ogg silence 1 0.50 0.1% 1 2.0 0.1% : \
newfile : restart
records a stream of audio such as an LP or cassette and splits it into multiple audio files at points where there are two seconds of silence. Also, it does not start recording until it detects some sound and stops after it sees ten minutes of silence.
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_ng(7) and in soxi_ng(1).
File Format Types
SoX can work with `self-describing' and `raw' audio files. `Self-describing' formats (e.g. WAV, FLAC, MP3) have a header that completely describes the signal and encoding attributes of the audio data that follows. `raw' or `headerless' formats do not contain this information, so the audio characteristics of these must be described on the SoX command line, except for a few which can be inferred from the filename extension such as .gsm, always -c1 -r8000 -e gsm, and named raw formats like .f32, .s16 and .ul which give the encoding but not the sample rate or number of channels.
The following four characteristics are used to describe the format of audio data:
- sample rate
-
The sample rate in samples per second (`Hertz' or `Hz'). Digital telephony traditionally uses a sample rate of 8000Hz (8kHz) though 16 and even 32kHz are becoming more common. Audio Compact Discs use 44100Hz (44.1kHz), Digital Audio Tape and many computer systems use 48kHz and professional audio systems often use 96kHz.
- 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 and 24-bit is used in the professional audio arena.
- 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 so that it takes up less disk space or transmission bandwidth than uncompressed formats. Commonly-used encoding types include floating point, μ-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 and `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 per unit of time. It can depend on all of the above and is typically denoted as a number of kilobits per second (kbps). An A-law telephony signal has a bit rate of 64 kbps, MP3-encoded stereo music typically has a bit rate of 128-196 kbps and FLAC-encoded stereo music typically has a bit rate of 550-760 kbps.
Most self-describing formats also allow textual `comments' to be embedded 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 can apply Replay Gain automatically for formats that contain comments but does not generate it. By default, SoX copies comments from the first input file to output files that support comments, so output files may contain Replay Gain information which is incorrect. This can be fixed, when converting input files with --replay-gain enabled, by removing all comments using --comment "" or removing just the REPLAYGAIN comment with
soxi_ng -a in.au | grep -v REPLAYGAIN > comments
sox_ng --replay-gain=track in.au --comment-file comments out.au
Determining and setting the File Format
SoX uses several mechanisms to determine or set the format of an audio file. Depending on the circumstances, individual characteristics may be determined or set using different mechanisms.
To determine the format of an input file, SoX uses, 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 uses, 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 that is supported by the output file type.
For all files, SoX exits 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_ng and rec_ng commands are provided so that basic playing and recording is as simple as
play_ng existing-file.wav
and
rec_ng new-file.wav
These two commands are functionally equivalent to
sox_ng existing-file.wav -d
and
sox_ng -d new-file.wav
Further options and effects (as described below) can be added to the commands in either form.
When playing a file with a sample rate that is not supported by the audio output device, SoX automatically invokes the rate effect to perform the necessary sample rate conversion. For compatibility with old hardware, the default rate quality level is set to `low'. This can be changed by explicitly specifying the rate effect with a different quality level, e.g.
play_ng ... rate -m
or by using the --play-rate-arg option (see below).
On some systems, SoX allows the audio playback volume to be adjusted while using play_ng. Where supported, this is achieved by tapping the `v' & `V' keys during playback. If there is a softvol effect in the chain, these keys will adjust that instead of the hardware mixer.
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_ng -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 the -S (--show-progress) option below.
Accuracy
Many file formats that compress audio discard some of the audio signal information. Converting to such a format and 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 formats used in portable music players (e.g. MP3, Ogg 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'. Formats that do not are called `lossless'. The term `quality' is used as a measure of how closely the original audio signal is 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. For example, 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.
SoX converts all audio files to an internal, uncompressed 32-bit 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_ng 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 recompressing 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 best to perform all audio processing using lossless file formats and then convert to the lossy format only at the final stage. Applying multiple effects with a single SoX invocation will, in general, produce more accurate results than those produced using multiple SoX invocations.
Dithering
Dithering is a technique used to maximize the dynamic range of audio stored at a particular bit-depth. Any distortion introduced by quantization is decorrelated by adding a small amount of white noise to the signal. In most cases, SoX can determine whether the selected processing requires dither and will add it during output formatting if appropriate.
By default, SoX automatically adds TPDF dither when the output bit-depth is less than 24 and any of the following are true:
- •
-
bit-depth reduction has been specified explicitly using a command-line option
- •
-
the output file format supports only bit-depths lower than that of the input file format
- •
-
an effect has increased the effective bit-depth within the internal processing chain
For example, adjusting the 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, SoX's internal representation will use 18 bits after processing this volume 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 (--no-dither) option may be given to override automatic dithering. To invoke dithering manually (e.g. to select a noise-shaping curve) use the dither effect.
Clipping
Clipping is distortion that occurs when an audio signal level (or `volume') 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 can happen when using the vol or gain effects to increase the audio volume. Clipping can 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 analog components and that can introduce a DC offset or amplification, 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 of the given representation. Some standards bodies recommend as much as 9dB headroom, but in most cases, 3dB (≈ 70% linear) is enough. 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 and the audio is clipped as delivered.
SoX's stat and stats effects can assist in determining the signal level of an audio file. The gain or vol effect can be used to prevent clipping, e.g.
sox_ng dull.wav bright.wav gain -6 treble +6
guarantees that the treble boost will not clip.
If clipping occurs at any point during processing, SoX displays a warning message to that effect.
See the global -G (--guard) option and the gain and norm effects.
Input File Combining
SoX's input combiner can be configured with the --combine global option to combine multiple files using one of the following methods: concatenate, sequence, mix, mix-power, merge and multiply, with shorthands -m for --combine mix, -M for merge and -T for multiply.
The default is sequence for play_ng, and concatenate for sox_ng.
For 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 them. and, with concatenate, the input files must also have the same number of channels.
The sequence combining method is similar to concatenate in that the audio from each input file is sent serially to the output file but here, the output file may be closed and reopened at the 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.
With the mix or mix-power combining methods, the number of channels in each input file need not be the same but SoX issues 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 unmixed without reference to the original input files.
If the merge combining method is selected the number of channels in each input file need not be the same and a merged audio file comprises all channels from all the input files and unmerging is possible using multiple invocations of SoX with the remix effect. For example, two mono files could be merged to form one stereo file and the first and second mono files would become the left and right channels of the stereo file.
The multiply combining method multiplies the sample values of corresponding channels treated as numbers in the interval -1 to +1. If the number of channels in the input files is not the same, the missing channels will contain silence.
When combining input files, SoX applies any specified effects (including, 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 the inputs individually (i.e. `balance' them) before combining takes place. For all combining methods, input file volume adjustments can be made manually using the -v option, which can be given for one or more input files. If it is given for only some of the input files, the others receive no volume adjustment. In some circumstances, automatic volume adjustments may be applied. The global -V option can be used to show the input file volume adjustments that have been selected manually or automatically.
Some special considerations need to made when mixing input files:
Unlike the other methods, mix combining can cause clipping in the combiner if no balancing is performed. In this case, if manual volume adjustments are not given, SoX tries to ensure that clipping does not occur by automatically adjusting the volume (amplitude) of each input signal by a factor of ¹/n, where n is the number of input files. If this results in audio that is too quiet or otherwise unbalanced, the input file volumes can be set manually with -v. Using the norm effect on the mix is another alternative.
If mixed audio seems loud enough at some points but too quiet in others, dynamic range compression can be applied to correct this - see the compand effect.
With the mix-power combine method, the mixed volume is approximately equal to that of one of the input signals. This is achieved by balancing using a factor of ¹/√n instead of ¹/n. Note that this balancing factor does not guarantee that clipping will not occur but the number of clips will usually be low and the resulting distortion is usually 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 placing the newfile pseudo-effect within the effects list and SoX will enter multiple output mode.
In multiple output mode, a new file is created when the effects prior to the newfile indicate that 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 is appended automatically to all filenames and, if the filename has an extension, the number is inserted before the extension. This behaviour can be customized by placing %n in the filename where the number should be substituted. An optional number can be placed after the % to indicate a minimum width for the number with leading zeroes. %n defaults to two digits or, if no %n is included, to three digits before the filename extension.
Multiple output mode is not very useful unless an effect that stops the effects chain is specified before newfile. If the end of the file is reached before the effects chain stops, no new file is created as it would be empty.
The following is an example of splitting the first 60 seconds of an input file into two 30 second files and ignoring the rest.
sox_ng song.wav ringtone%1n.wav trim 0 30 : newfile : trim 0 30
Stopping SoX
Usually, SoX completes its processing and exits automatically once it has read all audio data from the input files.
It can also be terminated earlier by sending it an interrupt signal, usually by pressing the keyboard interrupt key which is normally Ctrl-C. This is required It is needed when using SoX to make a recording.
When SoX is playing multiple files, Ctrl-C behaves slightly differently: pressing it once skips to the next file; pressing it twice in quick succession causes SoX to exit. However, when playing multiple files decoded with ffmpeg, this will kill all the pending file reads, resulting in a second or so of each - what each process had already written to its pipe.
Another way to stop processing early is to use an effect that has a time period or sample count; the trim effect is an example of this. Once all effects chains have stopped, SoX stops.