sox

Sommaire

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

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 purpose audio player or a multi-track audio recorder.

The entire 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.

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

The overall SoX processing chain can be summarised as follows:

Input(s) → Balancing → Combiner → Effects → Output

To show how this works in practise, here are some 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 -r 12000 -1 -c 1 recital.wav vol 0.7 dither
performs the same format translation, but also changes the audio sampling rate & sample size, down-mixes to mono, and applies the vol and dither effects. 
         sox -r 8000 -u -1 -c 1 voice-memo.raw voice-memo.wav
adds a header to a raw audio file, 
         sox slow.aiff fixed.aiff speed 1.027 rabbit -c0
adjusts audio speed using the most accurate rabbit algorithm, 
         sox short.au long.au longer.au
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 q 0.1 1 0.1
plays a synthesised `A minor seventh' chord with a pipe-organ sound, 
         rec -c 2 test.aiff trim 0 10
records 10 seconds of stereo audio, and 
         rec -M take1.aiff take1-dub.aiff
records a new track in a multi-track recording.

Further examples are included throughout this manual; more-detailed examples can be found in soxexam(7).

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 completely describes the characteristics of the audio data that follows. The second type is `headerless' (or `raw data'); here, the audio data characteristics must be described using the SoX command line.

The following four characteristics are sufficient 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); audio Compact Discs use 44100 Hz (44.1 kHz).
sample size
The number of bits used to store each sample. Most popular are 8-bit (one byte) and 16-bit (two bytes). (Since many now-common sound formats were invented when most computers used a 16-bit word, two bytes is often called a `word', but since current personal computers overwhelmingly have 32-bit or 64-bit words, this usage is confusing, and is not used in the SoX documentation.)
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, μ-law, ADPCM, signed linear, and FLAC.
channels
The number of audio channels contained in the file. One (`mono') and two (`stereo') are widely used.

The term `bit-rate' is sometimes used as an overall measure of an audio format and may incorporate elements of all of the above.

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

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 circumstances, 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.

Accuracy

Many file formats that compress audio discard some of the audio signal information whilst doing so; converting to such a format then converting 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 measure 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 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 highly recommended to perform all audio processing using lossless file formats and then convert to the lossy format 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 multiple SoX invocations; hence this is also recommended.

Clipping

Clipping is distortion that occurs when an audio signal level (or `volume') exceeds the range of the chosen representation. It is nearly always undesirable and so should usually be corrected by adjusting the volume prior to the point at which clipping occurs.

In SoX, clipping could occur, as you might expect, when using the vol effect 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 re-sampling, and processing by analogue components that can introduce a small DC offset and/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 does not exceed around 70% of the maximum (linear) range available, as this will avoid the majority of clipping problems. SoX's stat effect can assist in determining the signal level in an audio file; the vol effect can be used to prevent clipping, e.g.

         sox dull.au bright.au vol -6 dB treble +6
guarantees that the treble boost will not clip.

If clipping occurs at any point during processing, then SoX will display a warning message to that effect.

Input File Combining

SoX's input combiner can combine multiple files using one of four different methods: `concatenate', `sequence', `mix', 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 audio to an output device, but is not generally useful when the output file is a normal file.

If the `mix' combining method is selected (with -m) 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.

If the `merge' combining method is selected (with -M), 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 mixer 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 (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 (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 adjustments 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 ¹/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 should be set manually as described above.

If mixed audio seems loud enough at some points through the audio but too quiet in others, then dynamic-range compression should be applied to correct this - see the compand effect.

Stopping SoX

Usually SoX will complete its processing and exit automatically, however if desired, it can be terminated by pressing the keyboard interrupt key (usually 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.

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.

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 pipeline operations by using the special filename `-' which, if used in place of an input filename, will cause SoX will read audio data from `standard input' (stdin), and which, if used in place of the output filename, will cause SoX will send audio data to `standard output' (stdout). Note that when using this option, the file-type (see -t below) must also be given.
-n
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 44.1 kHz, but, as with a normal file, this can be overridden if desired using command-line format options (see below).

One other use of -n is to use it in conjunction with -V to display information from the audio file header without having to read any further into the file, e.g.

         sox -V *.wav -n
will display header information for each `WAV' file in the current directory.
-e
This is an alias of -n and is retained for backwards compatibility only.

OPTIONS

Global Options

These options can be specified on the command line at any point before the first effect name.
-h, --help
Show version number and usage information.
--help-effect=NAME
Show usage information on the specified effect. The name all can be used to show usage on all effects.
--interactive
Prompt before overwriting an existing file with the same name as that given for the output file.

N.B. Unintentionally overwriting a file is easier than you might think, for example, if you accidentally enter

         sox file1 file2 effect1 effect2 ...
when what you really meant was 
         play file1 file2 effect1 effect2 ...
then, without this option, file2 will be overwritten. Hence, using this option is strongly recommended; a `shell' alias, script, or batch file may be an appropriate way of permanently enabling it.
--buffer BYTES
Set the size in bytes of the buffers used for reading and writing sound data (default 8192).
-m|-M|--combine concatenate|merge|mix|sequence
Select the input file combining method; -m selects `mix', -M selects `merge',

See Input File Combining above for a description of the different combining methods.

--plot gnuplot|octave|off
If not set to off (the default if --plot is not given), run in a mode that can be used, in conjunction with the gnuplot program or the GNU Octave program, to assist with the selection and configuration of many of the transfer-function based effects. For the first given effect that supports the selected plotting program, SoX will output commands to plot the effect's transfer function, and then exit without actually processing any audio. E.g. 
         sox --plot octave input-file -n highpass 1320 > plot.m
         octave plot.m
-q, --no-show-progress
Run in quiet mode when SoX wouldn't otherwise do so; this is the opposite of the -S option.
--replay-gain track|album|off
Select whether or not to apply replay-gain adjustment to input files. The default is track for play and off otherwise.
-S, --show-progress
Display input file format/header information and input file(s) processing progress in terms of elapsed/remaining time and percentage complete. This option is enabled by default when using SoX to play or record audio.
--version
Show version number and exit.
-V[level]
Set verbosity. SoX prints messages to the console (stderr) according to the following verbosity levels:
0
No messages are printed at all; use the exit status to determine if an error has occurred.
1
Only error messages are printed. These are generated if SoX cannot complete the requested commands.
2
Warning messages are also printed. These are generated if SoX can complete the requested commands, but not exactly according to the requested command parameters, or if clipping occurs.
3
Descriptions of SoX's processing phases are also printed. Useful for seeing exactly how SoX is mangling your audio.
4 and above
Messages to help with debugging SoX are also printed.
By default, the verbosity level is set to 2. Each occurrence of the -V option increases the verbosity level by 1. Alternatively, the verbosity level can be set to an absolute number by specifying it immediately after the -V e.g. -V0 sets it to 0.

Input File Options

These options apply only to input files and may precede only input filenames on the command line.
-v, --volume FACTOR
Adjust volume by a factor of FACTOR. This is a linear (amplitude) adjustment, so a number less than 1 decreases the volume; greater than 1 increases it. If a negative number is given, then in addition to the volume adjustment, the audio signal will be inverted.

See also the stat effect for information on how to find the maximum volume of an audio file; this can be used to help select suitable values for this option.

See also Input File Balancing above.

Input & Output File Format Options

These options apply to the input or output file whose name they immediately precede on the command line and are used mainly when working with headerless file formats or when specifying a format for the output file that is different to that of the input file.
-c, --channels CHANNELS
The number of audio channels in the audio file. This may be 1, 2, or 4; for mono, stereo, or quad audio. To cause the output file to have a different number of channels than the input file, include this option with the output file options. If the input and output file have a different number of channels then the mixer effect must be used. If the mixer effect is not specified on the command line it will be invoked internally with default parameters.
--comment TEXT
Specify the comment text to store in the output file header (where applicable).

SoX will provide a default comment if this option (or --comment-file) is not given; to specify that no comment should be stored in the output file, use --comment "" .

--comment-file FILENAME
Specify a file containing the comment text to store in the output file header (where applicable).
-r, --rate RATE
Gives the sample rate in Hz of the file. To cause the output file to have a different sample rate than the input file, include this option with the output file format options.

If the input and output files have different rates then a sample rate change effect must be run. Since SoX has multiple rate changing effects, the user can specify which to use as an effect. If no rate change effect is specified then a default one will be chosen.

-t, --type file-type
Gives the type of the audio file. This is useful when the file extension is non-standard or when the type can not be determined by looking at the header of the file.

The -t option can also be used to override the type implied by an input filename extension, but if overriding with a type that has a header, SoX will exit with an appropriate error message if such a header is not actually present.

See soxformat(7) for a list of supported file types.

-L, --endian little
-B, --endian big
-x, --endian swap

 
These options specify whether the byte-order of the audio data is, respectively, `little endian', `big endian', or the opposite to that of the system on which SoX is being used. Endianness applies only to data encoded as signed or unsigned integers of 16 or more bits. It is often necessary to specify one of these options for headerless files, and sometimes necessary for (otherwise) self-describing files. A given endian-setting option may be ignored for an input file whose header contains a specific endianness identifier, or for an output file that is actually an audio device.

N.B. Unlike normal format characteristics, the endianness (byte, nibble, & bit ordering) of the input file is not automatically used for the output file; so, for example, when the following is run on a little-endian system:

         sox -B audio.uw trimmed.uw trim 2
trimmed.uw will be created as little-endian; 
         sox -B audio.uw -B trimmed.uw trim 2
must be used to preserve big-endianness in the output file.

The -V option can be used to check the selected orderings.

-N, --reverse-nibbles
Specifies that the nibble ordering (i.e. the 2 halves of a byte) of the samples should be reversed; sometimes useful with ADPCM-based formats.

N.B. See also N.B. in section on -x above.

-X, --reverse-bits
Specifies that the bit ordering of the samples should be reversed; sometimes useful with a few (mostly headerless) formats.

N.B. See also N.B. in section on -x above.

-s/-u/-U/-A/-a/-i/-g/-f
The audio data encoding is signed linear (2's complement), unsigned linear, μ-law (logarithmic), A-law (logarithmic), ADPCM, IMA-ADPCM, GSM, or floating-point.

μ-law (or mu-law) and A-law are the U.S. and international standards for logarithmic telephone audio compression. When uncompressed μ-law has roughly the precision of 14-bit PCM audio and A-law has roughly the precision of 13-bit PCM audio.

A-law and μ-law are sometimes encoded using reversed bit-ordering (i.e. MSB becomes LSB). If you need this support then you can use the -X option or the pseudo file types of `.la' and `.lu' to inform SoX of the encoding. See supported file types for more information.

ADPCM is a form of audio compression that has a good compromise between good audio quality and fast encoding/decoding time. It is used for telephone audio compression and places were full fidelity is not as important. When uncompressed it has roughly the precision of 16-bit PCM audio. Popular version of ADPCM include G.726, MS ADPCM, and IMA ADPCM. The -a flag has different meanings in different file handlers. In .wav files it represents MS ADPCM files, in all others it means G.726 ADPCM. IMA ADPCM is a specific form of ADPCM compression, slightly simpler and slightly lower fidelity than Microsoft's flavor of ADPCM. IMA ADPCM is also called DVI ADPCM.

GSM is currently used for the vast majority of the world's digital wireless telephone calls. It utilises several audio formats with different bit-rates and associated speech quality. SoX has support for GSM's original 13kbps `Full Rate' audio format. It is usually CPU intensive to work with GSM audio.

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

Output File Format Options

These options apply only to the output file and may precede only the output filename on the command line.
-C, --compression FACTOR
The compression factor for variably compressing output file formats. If 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 in soxformat(7) for more information.

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.

BUGS

Please report any bugs found in this version of SoX to the mailing list (sox-users@lists.sourceforge.net).

SEE ALSO

soxexam(7), soxformat(7), soxeffect(7), gnuplot(1), octave(1), wget(1), libsox(3)

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

LICENSE

Copyright 1991 Lance Norskog and Sundry Contributors. Copyright 1998-2007 by Chris Bagwell and SoX Contributors.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

AUTHORS

Chris Bagwell (cbagwell@users.sourceforge.net). Other authors and contributors are listed in the AUTHORS file that is distributed with the source code.