sox-async

A wrapper around SoX. Transcode audio files easily!

Examples

Simple transcode:

const SoxAsync = require('sox-async')
const sox = new SoxAsync()
sox.run({
    inputFile: 'song.wav',
    outputFile: 'song.flac'
})
.then(outputFilePath => {
    console.log(outputFilePath) // => song2.flac
})
.catch(err => console.log(err))

Lower volume:

const SoxAsync = require('sox-async')
const sox = new SoxAsync()
sox.run({
    input: { volume: 0.8 },
    inputFile: 'song.flac',
    outputFile: 'song2.flac'
})
.then(outputFilePath => {
    console.log(outputFilePath) // => song2.flac
})
.catch(err => console.log(err))
 

Transcode with options and effects:

const SoxAsync = require('sox-async')
const sox = new SoxAsync('C:\\Program Files (x86)\\sox-14-4-2\\sox.exe')
sox.run({
    inputFile: 'song.ogg',
    output: {
        bits: 16,
        rate: 44100,
        channels: 2
    },
    outputFile: 'song.wav'
    effects: 'phaser 0.6 0.66 3 0.6 2 −t'
})
.then(outputFilePath => {
    console.log(outputFilePath) // => song2.flac
})
.catch(err => console.log(err))

API

const SoxAsync = require('sox-async')
const sox = new SoxAsync()

new SoxAsync(soxPath)

• soxPath string optional - The path to SoX. E.g. 'C:\Program Files\Sox\sox.exe'. Defaults to 'sox', which works if the SoX binary is in your path.

sox.run(options)

• options object required - The following parameters are supported:
  • global object optional - Global SoX options
  • inputFile string required - The file path of the input file
  • outputFile string required - The file path of the output file
  • input object optional - These options will be used to interpret the incoming stream.
  • output object optional - These options will be used to format the outgoing stream. When an output option isn't supplied, the output file will have the same format as the input file where possible.
  • effects string|array of strings/numbers optional

options object

An object of options. Every option is optional except options.inputFile and options.outputFile.

If you want an exhaustive list of each option in depth, take a look at the SoX documentation.

Internally, these options are transformed into the command-line arguments passed to a SoX child process.

options.inputFile / options.outputFile string, required

A file path, like './song.wav'.

options.global object|array of strings/numbers

You can supply an array of strings/numbers, or an object that will be transformed into an array of strings/numbers using hash-to-array.

Currently, sox-stream only supports one input file, so some of these options don't really make sense.

Command(s)	Functionality
{ buffer: BYTES }	Set the size of all processing buffers (default 8192)
{ combine: 'concatenate' }	Concatenate all input files (default for sox, rec)
{ combine: 'sequence' }	Sequence all input files (default for play)
'-m', { m: true }, { combine: 'mix' }	Mix multiple input files (instead of concatenating)
{ combine: 'mix-power' }	Mix to equal power (instead of concatenating)
'-M', { M: true }, { combine: 'merge' }	Merge multiple input files (instead of concatenating)
'-T', { T: true }, { combine: 'multiply' }	Multiply samples of corresponding channels from all input files (instead of concatenating)
'-D', { D: true }, { 'no-dither': true }	Don't dither automatically
{ 'effects-file': FILENAME }	File containing effects and options
'-G', { G: true }, { guard: true }	Use temporary files to guard against clipping
{ input-buffer: BYTES }	Override the input buffer size (default: same as --buffer; 8192)
'--norm', { norm: true }	Guard (see --guard) & normalise
{ play-rate-arg: ARG }	Default rate argument for auto-resample with `play'
{ plot: 'gnuplot'|'octave' }	Generate script to plot response of filter effect
{ 'replay-gain': 'track'|'album'|'off' }	Default: 'off' (sox, rec), track (play)
'-R', { R: true }	Use default random numbers (same on each run of SoX)
'--single-threaded', { 'single-threaded': true }	Disable parallel effects channels processing
{ temp: DIRECTORY }	Specify the directory to use for temporary files

sox.run({
    global: {
        buffer: 4096,
        norm: true,
        'single-threaded': true
    },
    output: { type: 'ogg' }
})
.then(result => {...})
.catch(err => {...})

options.input / options.output object|array of strings/numbers

You can supply an array of strings/numbers, or an object that will be transformed into an array of strings/numbers using hash-to-array.

Input	Output	Command(s)	Functionality
✓	X	{ v: FACTOR }, { volume: FACTOR }	Input file volume adjustment factor (Floating point number between 0 and 1)
✓	X	{ ignore-length: true }	Ignore input file length given in header; read to EOF
✓	✓	{ t: FILETYPE }, { type: FILETYPE }	Audio file type. E.g. 'wav', 'ogg'
✓	✓	{ e: ENCODING }, { encoding: ENCODING }	ENCODING can be 'signed-integer', 'unsigned-integer', 'floating-point', 'mu-law', 'a-law', 'ima-adpcm', 'ms-adpcm', or 'gsm-full-rate'
✓	✓	'-b', { b: BITS }, { bits: BITS }	Encoded sample size in bits, A.K.A. the bit depth. E.g. 16, 24. (Not applicable to complex encodings such as MP3 or GSM.)
✓	✓	'-N', { N: true }, { 'reverse-nibbles': true }	Encoded nibble-order
✓	✓	'-X', { X: true }, { 'reverse-bits': true }	Encoded bit-order
✓	✓	'-L', { endian: 'little' }, { L: true }	Encoded byte-order: Little endian
✓	✓	'-B', { endian: 'big' }, { B: true }	Encoded byte-order: Big endian
✓	✓	'-x', { endian: 'swap' }, { x: true }	Encoded byte-order: swap means opposite to default
✓	✓	{ c: CHANNELS }, { channels: CHANNELS }	Number of channels of audio data. E.g. 2 for stereo
✓	✓	'--no-glob', { 'no-glob': true }	Don't `glob' wildcard match the following filename
✓	✓	{ r: RATE }, { rate: RATE }	Sample rate of audio. E.g. 44100, 48000
X	✓	{ C: FACTOR }, { compression: FACTOR }	Compression factor. See SoX format docs for more information.
X	✓	{ 'add-comment': TEXT }	Append output file comment
X	✓	{ comment: TEXT }	Specify comment text for the output file
X	✓	{ 'comment-file': FILENAME }	File containing comment text for the output file

sox.run({
    input: [
        [ '--volume', 1.1 ],
        [ '--endian', 'big' ],
        [ '--no-glob' ]
    ],
    output: { type: 'ogg' }
})
.then(result => {...})
.catch(err => {...})
// same as
sox.run({
    input: {
        volume: 1.1,
        endian: 'big',
        'no-glob': true
    ],
    output: [
        '--type', 'ogg'
    ]
}, cb)
// same as
sox.run({
    input: '--volume 1.1 --endian big --no-glob',
    output: '--type ogg'
})
.then(result => {...})
.catch(err => {...})

options.effects string|array of strings/numbers/arrays

Please see the SoX Documentation on Effects to see all the options.

You can put strings/numbers into sub-arrays, which will be flattened internally.

Pass them into sox.js like this:

sox.run({
    input: { type: 'ogg' },
    output: { type: 'wav' },
 
 
    effects: 'speed 1.5 swap'
    // same as
    effects: [
        'speed 1.5 swap'
    ]
    // same as
    effects: [
        'speed', 1.5,
        'swap'
    ]
    // same as
    effects: [
        [ 'speed', '1.5' ],
        'swap'
    ]
})
.then(result => {...})
.catch(err => {...})

Install

• Install SoX. You can download it, or you can do apt-get install sox.
• Install this package with npm: npm install sox-async

Test

To run the tests, you must also have SoX in your PATH. Then run: npm test

I run the tests using SoX 14.4.2, but other versions of SoX should work fine.

Codec Support

FLAC

• Problem: FLAC was disabled accidentally in 14.4.1. [Stack Overflow]
• Solution: Install SoX 14.4.2.

MP3

• Problem: MP3 is proprietary.
• Solution: Compile the LAME encoder, and/or the MAD decoder.
• Links:
  • Windows (Precompiled)
  • Windows (How-To)
  • Ubuntu (How-To)
  • Ubuntu (How-To) 2
  • CentOS (How-To)

License

MIT