Multi-DSPADPCM Overview

DSPADPCM is a data conversion utility for the Nintendo Cafe audio subsystem. This tool can convert standard multi-channel WAV or AIFF files into the multi-DSP-ADPCM format. This format is specific to the hardware decoder built into the audio DSP and provides good data compression while retaining high fidelity.

The DSPADPCM tool can also convert multi-DSP-ADPCM data back into separate WAV or AIFF formats. The conversion process models the DSP decoder exactly and provides a convenient method for previewing compressed data without relying on Nintendo Cafe hardware.

$CAFE_ROOT/system/bin/win32/dspadpcm.exe
$CAFE_ROOT/system/bin/win64/dspadpcm64.exe

Usage

DSPADPCM is a Win32 console application. It has the following command-line syntax and parameters:

DSPADPCM - <mode> <inputfile> [<outputfile>] [-<option><argument> //]

-<mode> <mode> must be "i" (for "encode interleaved multichannel") or "d" (for "decode"). This is a required parameter and specifies the operational mode of the tool.

If encoding is requested, the tool will convert a multi-channel WAV file (as specified by <inputfile>) into a multi-DSPADPCM file (as specified by [<outputfile>]).
NOTE:
The [<outputfile>] parameter is optional. If omitted, the default output file name will be the input file with a ".mdsp" extension.
If decoding is requested, the tool will convert a multi-DSP-ADPCM file (as specified by <inputfile>) into separate WAV files (one per channel, as specified by [<outputfile>]). Again, the [<outputfile>] parameter is optional. If omitted, the default output file name will be the input file with a channel number and ".wav" extension.
<inputfile> Specifies the file to be converted. This is a required parameter.
[<outputfile>] Specifies the file that will store the converted data. If omitted, the tool will generate a filename based on <inputfile> (see <mode> above). If the user has specified decode mode and the output file already exists, the tool will abort to prevent inadvertent destruction of source data.

The DSPADPCM tool also supports the following options:

-l<start>-<end> For encode mode only; specifies the loop points for the sample data in each channel to be converted. The <start> parameter is the raw sample address at which the loop begins. The <end> parameter is the raw sample address at which the loop ends. Both addresses are expressed in decimal. For example, "-l100-232" indicates that the loop starts at sample 100, and ends at sample 232. Samples are counted from zero, meaning that "sample zero" is the first sample in the file; "sample 100" is actually the one hundred-first sample in the file.
-a<endaddr> For encode mode only; this parameter is ignored if a loop has been specified. The <endaddr> specifies the last sample in each channel to be played by the DSP. If omitted, DSPADPCM uses the sample count (minus one) of the WAV file as a default value.
-c<textfile> Instructs DSPADPCM to dump the ADPCM file’s header information into <textfile>. If <textfile> is omitted, DSPADPCM will use <inputfile> with a ".txt" extension. If the text file already exists, its contents will be destroyed.
-v Turns on verbose mode. The tool will dump header data and processing status to stdin.
-f When decoding, generates an AIFF file. Loop points specified in the DSP header of the source file will be preserved.
-w When decoding, generates a WAV file. Loop points specified in the DSP header of the source file will be lost (because WAV files do not support loop points). This is the default setting.
-h Displays help information.

Data Formats

WAV files

DSPADPCM converts standard multi-channel WAV files into multi-DSP-ADPCM format. The multi-channel WAV files must contain one to six channel, 16-bit PCM data.

NOTE:
Loop points in the WAV are not guaranteed to be converted.

AIFF files

DSPADPCM can also convert AIFF files into DSP-ADPCM format. The AIFF files must contain one to six channel, 16-bit PCM data.

NOTE:
Loop points in the AIFF file will be read automatically and programmed into the header of the DSP-ADPCM output file.

DSP ADPCM files

When converting data into multi-DSP-ADPCM format, the tool will preface the output data with one to six headers. The structure of the headers is defined below:

     // all data in this structure is in BIG-ENDIAN FORMAT!!!!

     typedef struct
     {
     // for header generation during decode
         u32 num_samples;       // total number of RAW samples
         u32 num_adpcm_nibbles; // number of ADPCM nibbles (including frame headers)
         u32 sample_rate;       // Sample rate, in Hz

     // DSP addressing and decode context
         u16 loop_flag;    // 1=LOOPED, 0=NOT LOOPED
         u16 format;       // Always 0x0000, for ADPCM
         u32 sa;           // Start offset address for looped samples (2 for non-looped)
         u32 ea;           // End offset address for looped samples
         u32 ca;           // always 2
         u16 coef[16];     // decode coefficients (eight pairs of 16-bit words)

     // DSP decoder initial state
         u16 gain;         // always zero for ADPCM
         u16 ps;           // predictor/scale
         u16 yn1;          // sample history
         u16 yn2;          // sample history

     // DSP decoder loop context
         u16 lps;          // predictor/scale for loop context
         u16 lyn1;         // sample history (n-1) for loop context
         u16 lyn2;         // sample history (n-2) for loop context

     // Multi-DSP 
         u16 multi_ch_count;    // number of interleaved adpcm channels (1 through 6) or 0 for single channel
         u16 block_frame_count; // Number of ADPCM frames (8-bytes per frame) in each interleaved channel block.  Default is currently 1024 resulting in 8192 bytes per interleaved channel block.

     // Reserved
         u16 pad[9];

     } DSPADPCM;

     // Header is 96 bytes long

This header contains information needed by the Nintendo Cafe audio DSP to decode and play the associated sample.

NOTE:
All data in the header is stored in big-endian format. This facilitates transfer of the data to a Nintendo Cafe runtime application. Much of the data may be used verbatim to program the DSP for sample playback. Consult the Audio Library (AX) section in this guide for application details.
NOTE:
Sample offsets are specified relative to the location of sample 0 in memory. This is the start of the data following the DSPADPCM header and does not include the header bytes themselves.

When decoding multi-DSP-ADPCM data into WAV or AIFF format, the tool will assume that this header (up to six consecutive) is present at the start of the multi-DSP-ADPCM file. The DSPADPCM tool needs the first two parameters of the headers (and last two parameters of the first header) to regenerate each WAV header information during decode:

num_samples Number of raw, uncompressed samples in the file. Used for WAV/AIFF header generation during decode.
num_adpcm_nibbles Number of ADPCM nibbles (including frame headers) generated for this sample.
sampling_rate Sampling rate of the data, expressed in Hertz. Used for WAV/AIFF header generation during decode.
multi_ch_count Set in the first header only. Number of interleaved ADPCM channels (1 through 6) or 0 for single channel.
block_frame_count Set in the first header only. Number of 8-byte ADPCM frames per interleaved block. Default is 1024 for a total byte count of 8192 per interleaved block.

The remaining parameters in each of the headers are required by the audio DSP to decode and play the associated ADPCM sample data:

loop_flag Specifies whether the sample is looped. This parameter is stored in big-endian format and is used by the DSP for sample playback.
format Specifies the data format of the sample. Always 2 (the first two nibbles are frame header values, not samples). Used by the DSP for sample playback.
sa Loop start offset, in nibbles, relative to the start of the samples data following the DSPADPCM header.
ea Loop end offset, in nibbles, relative to the start of the samples data following the DSPADPCM header.
ca Initial offset value, in nibbles, relative to the start of the samples data following the DSPADPCM header. This will always be 2 (the first two nibbles are frame header values, not samples)
coef[16] Decoder coefficients. This coefficient corresponds to AXPBADPCM Structure member a[ ][ ] in the following way.
a[0][0] = coef[0];
a[0][1] = coef[1];
a[1][0] = coef[2];
a[1][1] = coef[3];
a[2][0] = coef[4];
a[2][1] = coef[5];
a[3][0] = coef[6];
a[3][1] = coef[7];
a[4][0] = coef[8];
a[4][1] = coef[9];
a[5][0] = coef[10];
a[5][1] = coef[11];
a[6][0] = coef[12];
a[6][1] = coef[13];
a[7][0] = coef[14];
a[7][1] = coef[15];
gain Gain factor. Always zero for ADPCM samples.
ps Predictor and scale. This will be initialized to the predictor and scale value of the sample’s first frame.
yn1 History data; used to maintain decoder state during sample playback.
yn2 History data; used to maintain decoder state during sample playback.
lps Predictor/scale for the loop point frame. If the sample does not loop, this value is zero.
lyn1 History data for the loop point. If the sample does not loop, this value is zero.
lyn2 History data for the loop point. If the sample does not loop, this value is zero.

Some notes about decoder addressing

NOTE:
Individual ADPCM sound effects must start on 8-byte boundaries and must be at least a multiple of 8 bytes in length. When loading one or more ADPCM samples into memory, the samples must be packed such that the start of each sample falls on an 8-byte boundary.

See Also

dspadpcm_overview

Revision History

2015/03/19 Formatted as 'NOTE'.
2013/12/18 Initial version.


CONFIDENTIAL