FANDOM


OPTIONSEdit

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. 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 cannot 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 to set 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 behaviour.

−−combine concatenate|merge|mix|mix−power|multiply|sequence

Select the input file combining method; for some of these, short options are available: −m selects ‘mix’, −M selects ‘merge’, and −T selects ‘multiply’.

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

−D, −−no−dither

Disable automatic dither - see ‘Dithering’ above. An example of why this might occasionally be useful is if a file has been converted from 16 to 24 bit with the intention of doing some processing on it, but in fact no processing is needed after all and the original 16 bit file has been lost, then, strictly speaking, no dither is needed if converting the file back to 16 bit. See also the stats effect for how to determine the actual bit depth of the audio within a file.

−−effects−file FILENAME

Use FILENAME to obtain all effects and their arguments. The file is parsed as if the values were specified on the command line. A new line can be used in place of the special : marker to separate effect chains. For convenience, such markers at the end of the file are normally ignored; if you want to specify an empty last effects chain, use an explicit : by itself on the last line of the file. This option causes any effects specified on the command line to be discarded.

−G, −−guard

Automatically invoke the gain effect to guard against clipping. E.g.

   sox −G infile −b 16 outfile rate 44100 dither −s

is shorthand for

   sox infile −b 16 outfile gain −h rate 44100 gain −rh dither −s

See also −V, −−norm, and the gain effect.

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

−−help−format NAME

Show information about the specified file format. The name all can be used to show information on all formats.

−−i, −−info

Only if given as the first parameter to sox, behave as soxi(1).

−m|−M

Equivalent to −−combine mix and −−combine merge, respectively.

−−magic

If SoX has been built with the optional ‘libmagic’ library then this option can be given to enable its use in helping to detect audio file types.

−−multi−threaded | −−single−threaded

By default, SoX is ‘single threaded’. If the −−multi−threaded option is given however then SoX will process audio channels for most multi-channel effects in parallel on hyper-threading/multi-core architectures. This may reduce processing time, though sometimes it may be necessary to use this option in conjuction with a larger buffer size than is the default to gain any benefit from multi-threaded processing (e.g. 131072; see −−buffer above).

−−no−clobber

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 recommended. SOX_OPTS (above), a ‘shell’ alias, script, or batch file may be an appropriate way of permanently enabling it.

−−norm[=dB-level]

Automatically invoke the gain effect to guard against clipping and to normalise the audio. E.g.

   sox −−norm infile −b 16 outfile rate 44100 dither −s

is shorthand for

   sox infile −b 16 outfile gain −h rate 44100 gain −nh dither −s

Optionally, the audio can be normalized to a given level (usually) below 0 dBFS:

   sox −−norm=−3 infile outfile

See also −V, −G, and the gain effect.

−−play−rate−arg ARG

Selects a quality option to be used when the ‘rate’ effect is automatically invoked whilst playing audio. This option is typically set via the SOX_OPTS environment variable (see above).

−−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 > highpass.plt
   octave highpass.plt

−q, −−no−show−progress

Run in quiet mode when SoX wouldn’t otherwise do so. This is the opposite of the −S option.

−R

Run in ‘repeatable’ mode. When this option is given, where applicable, SoX will embed a fixed time-stamp in the output file (e.g. AIFF) and will ‘seed’ pseudo random number generators (e.g. dither) with a fixed number, thus ensuring that successive SoX invocations with the same inputs and the same parameters yield the same output.

−−replay−gain track|album|off

Select whether or not to apply replay-gain adjustment to input files. The default is off for sox and rec, album for play where (at least) the first two input files are tagged with the same Artist and Album names, and track for play otherwise.

−S, −−show−progress

Display input file format/header information, and processing progress as input file(s) percentage complete, elapsed time, and remaining time (if known; shown in brackets), and the number of samples written to the output file. Also shown is a peak-level meter, and an indication if clipping has occurred. The peak-level meter shows up to two channels and is calibrated for digital audio as follows (right channel shown):

A three-second peak-held value of headroom in dBs will be shown to the right of the meter if this is below 6dB.

This option is enabled by default when using SoX to play or record audio.

−T

Equivalent to −−combine multiply.

−−temp DIRECTORY

Specify that any temporary files should be created in the given DIRECTORY. This can be useful if there are permission or free-space problems with the default location. In this case, using ‘−−temp .’ (to use the current directory) is often a good solution.

−−version

Show SoX’s version number and exit.

−V[level]

Set verbosity. This is particularly useful for seeing how any automatic effects have been invoked by SoX.

SoX displays messages on the console (stderr) according to the following verbosity levels:

0

No messages are shown at all; use the exit status to determine if an error has occurred.

1

Only error messages are shown. These are generated if SoX cannot complete the requested commands.

2

Warning messages are also shown. 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 shown. Useful for seeing exactly how SoX is processing your audio.

4 and above

Messages to help with debugging SoX are also shown.

By default, the verbosity level is set to 2 (shows errors and warnings). 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. −−ignore−length

Override an (incorrect) audio length given in an audio file’s header. If this option is given then SoX will keep reading audio until it reaches the end of the input file.

−v, −−volume FACTOR

Intended for use when combining multiple input files, this option adjusts the volume of the file that follows it on the command line by a factor of FACTOR. This allows it to be ‘balanced’ w.r.t. the other input files. This is a linear (amplitude) adjustment, so a number less than 1 decreases the volume and a number 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 norm, vol, and gain effects, and see 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. −b BITS, −−bits BITS

The number of bits (a.k.a. bit-depth or sometimes word-length) in each encoded sample. Not applicable to complex encodings such as MP3 or GSM. Not necessary with encodings that have a fixed number of bits, e.g. A/μ-law, ADPCM.

For an input file, the most common use for this option is to inform SoX of the number of bits per sample in a ‘raw’ (‘headerless’) audio file. For example

   sox −r 16k −e signed −b 8 input.raw output.wav

converts a particular ‘raw’ file to a self-describing ‘WAV’ file.

For an output file, this option can be used (perhaps along with −e) to set the output encoding size. By default (i.e. if this option is not given), the output encoding size will (providing it is supported by the output file type) be set to the input encoding size. For example

   sox input.cdda −b 24 output.wav

converts raw CD digital audio (16-bit, signed-integer) to a 24-bit (signed-integer) ‘WAV’ file.

−1/−2/−3/−4/−8

The number of bytes in each encoded sample. Deprecated aliases for −b 8, −b 16, −b 24, −b 32, −b 64 respectively.

−c CHANNELS, −−channels CHANNELS

The number of audio channels in the audio file. This can be any number greater than zero.

For an input file, the most common use for this option is to inform SoX of the number of channels in a ‘raw’ (‘headerless’) audio file. Occasionally, it may be useful to use this option with a ‘headered’ file, in order to override the (presumably incorrect) value in the header - note that this is only supported with certain file types. Examples:

   sox −r 48k −e float −b 32 −c 2 input.raw output.wav

converts a particular ‘raw’ file to a self-describing ‘WAV’ file.

   play −c 1 music.wav

interprets the file data as belonging to a single channel regardless of what is indicated in the file header. Note that if the file does in fact have two channels, this will result in the file playing at half speed.

For an output file, this option provides a shorthand for specifying that the channels effect should be invoked in order to change (if necessary) the number of channels in the audio signal to the number given. For example, the following two commands are equivalent:

   sox input.wav −c 1 output.wav bass −b 24
   sox input.wav      output.wav bass −b 24 channels 1

though the second form is more flexible as it allows the effects to be ordered arbitrarily.

−e ENCODING, −−encoding ENCODING

The audio encoding type. Sometimes needed with file-types that support more than one encoding type. For example, with raw, WAV, or AU (but not, for example, with MP3 or FLAC). The available encoding types are as follows: signed-integer

PCM data stored as signed (‘two’s complement’) integers. Commonly used with a 16 or 24 −bit encoding size. A value of 0 represents minimum signal power.

unsigned-integer

PCM data stored as unsigned integers. Commonly used with an 8-bit encoding size. A value of 0 represents maximum signal power.

floating-point

PCM data stored as IEEE 753 single precision (32-bit) or double precision (64-bit) floating-point (‘real’) numbers. A value of 0 represents minimum signal power.

a-law

International telephony standard for logarithmic encoding to 8 bits per sample. It has a precision equivalent to roughly 13-bit PCM and is sometimes encoded with reversed bit-ordering (see the −X option).

u-law, mu-law

North American telephony standard for logarithmic encoding to 8 bits per sample. A.k.a. μ-law. It has a precision equivalent to roughly 14-bit PCM and is sometimes encoded with reversed bit-ordering (see the −X option).

oki-adpcm

OKI (a.k.a. VOX, Dialogic, or Intel) 4-bit ADPCM; it has a precision equivalent to roughly 12-bit PCM. ADPCM is a form of audio compression that has a good compromise between audio quality and encoding/decoding speed.

ima-adpcm

IMA (a.k.a. DVI) 4-bit ADPCM; it has a precision equivalent to roughly 13-bit PCM.

ms-adpcm

Microsoft 4-bit ADPCM; it has a precision equivalent to roughly 14-bit PCM.

gsm-full-rate

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.

Encoding names can be abbreviated where this would not be ambiguous; e.g. ‘unsigned-integer’ can be given as ‘un’, but not ‘u’ (ambiguous with ‘u-law’).

For an input file, the most common use for this option is to inform SoX of the encoding of a ‘raw’ (‘headerless’) audio file (see the examples in −b and −c above).

For an output file, this option can be used (perhaps along with −b) to set the output encoding type For example

   sox input.cdda −e float output1.wav


   sox input.cdda −b 64 −e float output2.wav

convert raw CD digital audio (16-bit, signed-integer) to floating-point ‘WAV’ files (single & double precision respectively).

By default (i.e. if this option is not given), the output encoding type will (providing it is supported by the output file type) be set to the input encoding type.

−s/−u/−f/−A/−U/−o/−i/−a/−g

Deprecated aliases for specifying the encoding types signed-integer, unsigned-integer, floating-point, a-law, mu-law, oki-adpcm, ima-adpcm, ms-adpcm, gsm-full-rate respectively (see −e above).

−−no−glob

Specifies that filename ‘globbing’ (wild-card matching) should not be performed by SoX on the following filename. For example, if the current directory contains the two files ‘five-seconds.wav’ and ‘five*.wav’, then

   play −−no−glob "five*.wav"

can be used to play just the single file ‘five*.wav’.

−r, −−rate RATE[k]

Gives the sample rate in Hz (or kHz if appended with ‘k’) of the file.

For an input file, the most common use for this option is to inform SoX of the sample rate of a ‘raw’ (‘headerless’) audio file (see the examples in −b and −c above). Occasionally it may be useful to use this option with a ‘headered’ file, in order to override the (presumably incorrect) value in the header - note that this is only supported with certain file types. For example, if audio was recorded with a sample-rate of say 48k from a source that played back a little, say 1.5%, too slowly, then

   sox −r 48720 input.wav output.wav

effectively corrects the speed by changing only the file header (but see also the speed effect for the more usual solution to this problem).

For an output file, this option provides a shorthand for specifying that the rate effect should be invoked in order to change (if necessary) the sample rate of the audio signal to the given value. For example, the following two commands are equivalent:

   sox input.wav −r 48k output.wav bass −b 24
   sox input.wav        output.wav bass −b 24 rate 48k

though the second form is more flexible as it allows rate options to be given, and allows the effects to be ordered arbitrarily.

−t, −−type FILE-TYPE

Gives the type of the audio file. For both input and output files, this option is commonly used to inform SoX of the type a ‘headerless’ audio file (e.g. raw, mp3) where the actual/desired type cannot be determined from a given filename extension. For example:

   another-command | sox −t mp3 − output.wav

   sox input.wav −t raw output.bin

It 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 floating-point, or 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 other 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.s16 trimmed.s16 trim 2

trimmed.s16 will be created as little-endian;

   sox −B audio.s16 −B trimmed.s16 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.

Output File Format Options
These options apply only to the output file and may precede only the output filename on the command line. −−add−comment TEXT

Append a comment in the output file header (where applicable).

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

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

Community content is available under CC-BY-SA unless otherwise noted.