NEW - incremental update, August 2012
OS X Note: these versions no longer support 10.4(Tiger). The other programs are unchanged.
Download+Donate (Windows, OS X)
CDP Home Page
About the Multi-Channel Toolkit.
The CDP Multi-Channel Toolkit provides a number of basic command line tools (Windows, OS X) for managing multi-channel files. The focus is on two file formats: Microsoft's WAVEFORMATEXTENSIBLE (WAVE_EX), and the AMB format for Ambisonic B-Format streams based on WAVE_EX.The programs also support generic multi-channel AIFF and AIFF-C files. Unlike WAVE_EX, these formats do not support defined speaker positions.
The .amb file
extension is now standardised for
B-Format WAVE_EX soundfiles up to third order. Many examples (mainly first-order) are
free download from the ambisonia website (NB: requires BitTorrent to download files - may be slow!). They range from live music recordings to soundscapes, aircraft flybys, and nature recordings. The programs also recognise the extension .wxyz as signifying a plain (WAVE) multi-channel file containing a B-Format stream.
The Toolkit programs do not perform any signal processing on the audio (except where B-Format encoding or decoding is applied). For a comprehensive suite of command-line tools for processing multi-channel files (with on Windows a choice of GUI front-ends), take a look at the full CDP system.
B-Format decoding - Furse-Malham and David Moore.
This update includes expanded encoding and decoding options, the latter for both soundfile output (fmdcode) and real-time playback(paplay). B-Format decoding involves the use of a set of numbers ("coefficients") by which each channel is scaled and mixed for each speaker position. For decoding to the regular layouts (square, hexagon, octagon, etc) the canonical set of coefficients for first and second order published by Richard Furse and David Malham is employed. These coefficients are also used in the Csound opcode bformdec1, with which the Toolkit programs are therefore compatible. Such coefficients arise directly out of the mathematical theory of spherical harmonics on which B-Format is based, and depend in turn on the use of regular speaker layouts such as those described (equidistant in space, with the listener at the centre).
B-Format decoding to irregular layouts such as the ubiquitous 5.1 used for cinema surround is much more difficult, and compromised in quality compared to regular layouts. While direct theoretical solutions exist, an important class of decoding solutions is based on "exhaustive" algorithmic searches for optimum coefficients. The 5.1 decoding coefficients employed in the Toolkit have been kindly supplied by David Moore. He employed some advanced massively-parallel computing hardware in the form of a pair of Clearspeed cards, which greatly accelerated this computationally demanding task. At the time of releasing this update, a website describing this work in detail is still under construction. The project was described in a paper presented at the 126th AES Convention in Munich, The Potential of High Performance Computing in Audio Engineering. This is an example of High-Performance Audio Computing (HiPAC), where massively-parallel hardware is employed to realise computationally demanding audio processes. Note that it is generally acknowledged that second-order sources decode much better to 5.1 than do first-order sources. The new program abfpan2 has been introduced to demonstrate simple second-order panning.
Note that despite the references to 5.1, the LFE channel is not used in B-Format decoding. The programs offer the option to decode to 5.0 (a five-channel stream) or to 5.1 (a six-channel stream with a silent LFE channel).
Supported sample formats (WAVE, WAVE_EX,AIFF, AIFF_C)
32bit floating-point (AIFF written in AIFF-C format)
Note: a few older programs are now deprecated, and are no longer supported; they may be omitted from future releases:.
All the programs support soundfiles up to the maximum 4GB.
Separate Zipped archives are provided for Windows (Command Prompt) and OS X (Terminal). After unpacking, the programs can be placed in any convenient directory. For the most general use, this directory should be on the user's PATH so that they can be invoked from any directory.
I have occasionally been asked about paid support options for the Toolkit. Rather than formulate some arbitrary tariff, I have decided simply to invite donations via Paypal to support and encourage further development, or to reflect significant use in professional contexts. I suggest £5.00 for individual users - more is always welcome! The Toolkit is also supplied as part of the CDP system, and is fully supported for CDP users on the same basis as the rest of the system.
Benefits of donations.
Bugfixes: rather than make very frequent updates, I will generally collect them over some time before publishing an update. Anyone registered via a donation will receive priority notice of updates, and can have them posted directly. Donors will also receive special attention with respect to appropriate suggestions for additions and enhancements!
OS X: mctools12-08-osx.zip
See the included document Toolkit.pdf for full documentation.
ABFDCODE : Simple horizonal decoding of a generic or AMB format file to quad layout.
abfdcode [-x] infile outfile -x : write WAVE_EX (Quad) outfile format (requires .wav extension)
This program is now deprecated - use FMDCODE instead.
ABFPAN :apply fixed or orbiting 1st-order B-Format pan to (mono) infile.
abfpan [-b][-x][-oN] infile outfile startpos endpos 0.0 <= startpos <= 1.0 (0.0 and 1.0 = Centre Front) endpos : endpos < 0.0 gives anticlockwise rotation, endpos > 0.0 gives clockwise rotation. Units give number of revolutions, fraction gives final position. Set endpos = startpos for fixed pan. -b : write output as horizontal Ambisonic B-format (.amb), (i.e. bypass B-Format decoding). -x : write (WAVE_EX) format file (.wav). Default: write standard m/c soundfile (WAVE,AIFF). NB: -b overrides -x - no meaning in using both. -oN : number of B-Format output channels: N = 3 or 4 only. Default: write 4-ch file.
ABFPAN2 : apply fixed or orbiting 2nd-order B-Format pan to infile
abfpan2 [-gGAIN][-w] [-p[DEG]] infile outfile startpos endpos
infile : mono source. outfile : 2nd order B-format output. 0.0 <= startpos <= 1.0 (0.0 and 1.0 = Centre Front). endpos : endpos < 0.0 gives anticlockwise rotation, endpos > 0.0 gives clockwise rotation. Units give number of revolutions. Fraction gives final position. Set endpos = startpos for fixed pan. -gGAIN : scale infile amplitude by GAIN (GAIN > 0). -w : Write standard soundfile (wave, aiff) Default: WAVEX B-Format; use .amb extension. -p[DEG] : write full 9-channel (periphonic) B-Format file. Default: write 5-channel (2nd-order horizontal) file. DEG: optional fixed height argument (degrees). Range = -180 to +180, where -90 = nadir, +90 = zenith (directly above). Default: DEG=0; height channels (Z,R,S,T) will be empty.
CHANNELX : extract selected channels from m/c file
channelx [-oBASENAME] infile chan_no [chan_no...] -oBASENAME : base name (with extension) of outfiles (appended *_cN for ch N)
CHORDER : reorder soundfile channels. Channels can be duplicated and/or omitted.
chorder infile outfile orderstring
orderstring = any combination of characters a-z inclusive. Infile channels are mapped in order as a=1,b=2...z=26 (For example: channels in a 4-channel file are represented by the characters abcd; any other character is an error). Characters must be lower case, and may be used more than once. Duplicate characters duplicate the corresponding input channel. The zero character (0) may be used to set a silent channel. A maximum of 26 channels is supported for both input and output. NB: infile (WAVEX) speaker positions are discarded. The .amb extension is supported for the outfile.
CHXFORMAT : modify WAVE_EX header to change GUID and/or speaker positions
chxformat [-m | [[-t] [-gGUID] [-sMASK]] filename
-gGUID : change GUID type between PCM and AMB. Plain WAVEX: GUID = 1 AMB: GUID = 2 -sMASK : change speaker position mask. MASK = 0: unset channel mask else set to MASK MASK may be given in decimal or hex (prefix '0x'). -m : (not in combination with other options) NOTE: speaker positions are only supported for WAVEX PCM files. If GUID is set to 2, the -s option should not be used. Any existing speaker positions will be set to zero. Type chxformat -m to see list of WAVEX mask values. -t : Test only: do not modify file. If only infile given, program prints current GUID type and speaker mask.In test mode, program checks file, and prints current and new channel masks as binary if -s option set.
COPYSFX : copy soundfiles; convert from one format to another
Fixed in this version: corrected WAVE_EX mask value for mono files
copysfx [-d][-hN][-sN][-tN] infile outfile
-s : force output sample type to type N. Available sample types: 1 : 16bit integers (shorts) 2 : 32bit integer (longs) 3 : 32bit floating-point 4 : 24bit integer 'packed' Default: format of infile. -h : write mimimum header (no extra data). Default: include PEAK data. -tN : write outfile format as type N Possible formats: 0 : standard soundfile (.wav, .aif, .afc, .aifc) 1 : generic WAVE_EX (no speaker assignments) 2 : WAVE_EX mono/stereo/quad(LF,RF,LR,RR) - infile nchans must match 3 : WAVE_EX quad surround (L,C,R,S) - infile must be quad 4 : WAVE_EX 5.1 format surround - infile must be 6-channel 5 : WAVE_EX Ambisonic B-format (W,X,Y,Z...)- extension .amb supported 6 : WAVE_EX 5.0 Surround - infile must be 5-channel 7 : WAVE_EX 7.1 Surround - infile must be 8-channel 8 : WAVE_EX Cube Surround - infile must be 8-channel default in all cases: outfile has format of infile NB: types 1 to 8 are for WAV format only
FMDCODE : decode 1st or 2nd-order B-Format file to a choice of speaker layouts.
fmdcode [-x][-w] infile outfile layout -w : write plain WAVE outfile format (.wav default - use generic wavex format). -x : write std WAVEX speaker positions to header (applies to compatible layouts only; requires .wav extension). layout : one of the choices below. Output channel order is anticlockwise from centre front except where indicated. Layouts indicated with * are compatible with WAVEX speaker position order. Available speaker layouts: 1 : * mono (= W signal only) 2 : * stereo (quasi mid/side, = W +- Y) 3 : square 4 : * quad FL,FR,RL,RR order 5 : pentagon 6 : * 5.0 surround (WAVEX order) 7 : * 5.1 surround (WAVEX order, silent LFE) 8 : hexagon 9 : octagon 1 (front pair, 45deg) 10 : octagon 2 (front centre speaker) 11 : cube (as 3, low-high interleaved. Csound-compatible.) 12 : * cube (as 4, low quad followed by high quad).
INTERLX : interleave two or more files to make a multi-channel file
interlx [-tN] outfile infile1 infile2 [infile3...] Up to 16 files may be interleaved. Output format is taken from infile1. Files must match sample rate and number of channels, but can have different sample types. To create a silent channel, for infile2 onwards, use 0 (zero) as filename. Infile1 must be a soundfile. NB: Speaker-positions in WAVE_EX infiles are ignored Note that the same infile can be listed multiple times, for example, to write a mono file as stereo, quad, etc. The .amb B-Format extension is supported: the program warns if channel count is anomalous. Known Bformat channel counts: 3,4,5,6,7,8,9,11,16. -tN : Write outfile format as type N Available formats: 0 : (default) standard soundfile (.wav, .aif, .afc, .aifc) 1 : generic WAVE_EX (no speaker assignments) 2 : WAVE_EX mono/stereo/quad(LF,RF,LR,RR)- total chans must match 3 : WAVE_EX quad surround (L,C,R,S) - total chans must be quad 4 : WAVE_EX 5.1 format surround - total chans must be 6-channel 5 : WAVE_EX Ambisonic B-format (W,X,Y,Z...) - .amb supported 6 : WAVE_EX 5.0 surround - total chans must be 5-channel 7 : WAVE_EX 7.1 Surround - total chans must be 8-channel 8 : WAVE_EX Cube Surround - total chans must be 8-channel In all cases: outfile has sample format of infile1 NB: types 1 to 8 are for WAV format only
NJOIN concatenate multiple soundfiles, with optional CUE list output for CD burning.
njoin [-sSECS | -SSECS][-cCUEFILE][-x] filelist.txt [outfile] filelist.txt: text file containing list of sfiles in order. One file per line. Channel spec (if present) must be the same, but files with no spec assumed compatible. -cCUEFILE : if outfile used, generate cue textfile as CUEFILE. -sSECS : separate files with silence of SECS seconds -SSECS : as above, but no silence before first file. Default: files are joined with no gap. -x : strict: allow only CD-compatible files: Must use sr=44100, minimum duration 4 secs. NB: Files must match sample rate and number of channels, but can have different sample types. Output sample format taken from file with highest precision. If no outfile given: program scans files and prints report.
Mixes two m/c files together, with optional offset for the second file.
nmix [-d][-f][-oOFFSET] infile1 infile2 outfile
-d : apply TPDF dither (16bit format output only). -f : set output sample type to floats. Default: outfile type is that of infile 1 -oOFFSET : start infile2 at OFFSET seconds. Files must have the same channel count. WAVE-EX files must have the same speaker layout
PAPLAY : command line soundfile player (using the Portaudio library).
Decodes first and second order AMB Files to a choice of speaker (channel) layouts.
NEW: Version 3:
Windows version supports ASIO devices as well as DirectSound.
OS X version supports Jack as well as Core Audio
paplay [-BN] [-dN] [-gN] [-hN] [-i] [-l] [-bN | -mS] [-u] [-x] soundfile [from] [to]
-dN : use output Device N. -gN : apply gain factor N to input. -BN : set software buffer size to N frames (default: 32768). N must be a power of 2 (e.g 4096, 8192, 16384 etc). -hN : set hardware blocksize to N frames (32 < N <= BN/4), default 4096. (N recommended to be a power of two size). : NB: for sample rates > 48KHz, buffer sizes are doubled internally. -i : play immediately (do not wait for keypress). -l : loop file continuously, from start-time to end-time. -m[S] : render using chorder-style channel map string S. Use -m without parameter for usage. -u : suppress elapsed time updates -x : apply WAVE_EX infile channel mask to DS audio stream\n" (Windows only; ignored if -m or -b used) from : set start time (secs) for playback and looping. Default: 0. to : set end time (secs) for playback and looping. Default: EOF. -b[N] : apply 1st-order B-Format decoding to standard soundfile.
(file must have at least 3 channels) B-Format files (.amb) will be decoded automatically. N sets speaker layout to one of the following: 1 : * mono (= W signal only) 2 : * stereo (quasi mid/side, = W +- Y) 3 : square 4 : * quad FL,FR,RL,RR order (default) 5 : pentagon 6 : * 5.0 surround (WAVEX order) 7 : * 5.1 surround (WAVEX order, silent LFE) 8 : hexagon 9 : octagon 1 (front pair, 45deg) 10 : octagon 2 (front centre speaker) 11 : cube (as 3, low-high interleaved.(as Csound) 12 : * cube (as 4, low quad followed by high quad).
Windows: use -x flag option to write WAVE_EX speaker positions (for starred layouts) to the hardware.
The default is to send a zero mask, so that channels map directly to successive hardware outputs.
RECSF: multi-channel recording NEW: Version 1.0 OS X version supports Jack as well as Core Audio
recsf [-BN][-cN][-dN][-hN][-i][-p][-rN][-tN] outfile [dur] outfile: output file in WAVE,AIFF or AIFC formats, determined by the file extension. Use extension .amb to create a B-Format file. -BN : set software buffer size to N frames (default: 32768). N must be a power of 2 (e.g 4096, 8192, 16384 etc). -cN : set channels to N (default: 2). -hN : set hardware buffer size to N frames (default: 4096) -p : suppress running peak level indicator -rN : set sample rate to N Hz (default: 44100) -tN : set sample type to N (default: 1) 0 : 16 bits 1 : 24 bits 2 : 32bit floats dur : optional fixed duration for outfile (overriden by Ctrl-C) Otherwise, use Ctrl_C to terminate recording. -dN : use input device N -i : start recording immediately (default: wait for keypress)
Note in particular that by default RECSF generates a 24bit soundfile. While recording, it prints a simple running peak level indicator to the console.
RMSINFO : scan file and report rms power and average level statistics for each channel.
rmsinfo [-n] infile [startpos [endpos]] Standard output shows: RMS level Average level DC level (bipolar average) -n : Include equivalent 0dBFS-normalised RMS and AVG levels. startpos : start file scan from <startpos> seconds. endpos : finish file scan at <endpos> seconds. To stop a scan early, use CTRL-C. Program will report levels up to that point.
SFPROPS : report properties of a soundfile.
display soundfile properties to console. Displays PEAK data if available, and speaker positions in a WAVE-EX file.
Usage: sfprops infile
This is a purely informative program. In addition to reporting the standard properties of a soundfile it gives details of any WAVE_EX speaker positions and identifies the layout where one of the standard ones (as supported by other Toolkit programs). It prints all PEAK information if present, including level values in dB.
Use CHXFORMAT to find low-level information on the WAVE_EX speaker mask.
If you have comments or feature requests, feel free to email me
Last updated: August 2012