Bank Files

This chapter describes the file formats used for Nintendo 64 audio development.

The first section details the bank format used by the Sequence Player. The second section provides information about the Standard MIDI File format as it relates to Project Reality.

Note: All multi-byte data types (short, long, and so on) are stored with the high byte first. This is the opposite of the Intel ordering found in PCs.

Bank Files
Bank files store the audio and control information needed to create audio from sequencer MIDI events. On the Nintendo 64, this information is encapsulated in two files: the bank file and the wavetable file.

The Bank (.bnk) file contains control information such as program number to instrument assignment, key mapping, tuning, and envelope descriptions. It is loaded into the Nintendo 64 DRAM during playback.

The Wavetable (.tbl) file contains ADPCM compressed audio data. Because of the size of the data, it is streamed into DRAM (and then to the RCP) only when it is needed.

The formats for both files are optimized for the Nintendo 64 to be efficiently used with the Sequence Player and the Sound Player. They are not intended to be interchange file formats, and contain no textual information or other data not directly related to playing back audio. Many features commonly found in standard patch and wavetable formats (for example, AIFF files) were sacrificed in favor of smaller files in ROM.

Note: References to objects are stored as offsets in the Bank files, but the alBnkfNew() call converts the offsets to pointers.

ALBankFile
Bank files must begin with an ALBankFile structure. This structure allows the software to locate data for a specific bank.

    typedef struct {
    	s16	revision;
    	s16	bankCount;
    	s32	bankArray[1];
    } ALBankFile;

The ALBankFile fields are summarized in the following table.

Table 1 ALBankFile Structure

Field | Description
revision | File format revision number.
bankCount | Number of banks contained in the Bank file.
bankArray | Array of offsets of the ALBank structures in the bank file.

ALBank
The ALBank structure specifies the instruments that make up the bank, as well as the default sample rate and percussion instrument. Banks may contain any number of programs.

Note: The percussion field specifies an instrument for the Sequence Player to use as a default MIDI channel 10 (drum channel) instrument.

    typedef struct {
    	s16	instCount;
    	u8	flags;
    	u8	pad;
    	s32	sampleRate;
    	s32	percussion;
    	s32	instArray[1];
    } ALBank;

Table 2 ALBank Structure

Field | Description
instCount | Number of programs (instruments) in the bank.
flags | =0 if instArray contains offset, and =1 if instArray contains pointers.
pad | Currently unused byte.
sampleRate | The sample rate at which this bank is inteded to be played. percussion The offset (or pointer) to the default percussion instrument.
instArray | Array of offsets (or pointers) to ALInstrument structures that make up this bank.

ALInstrument
The ALInstrument structure contains performance information.

    typedef struct {
    	u8	volume;
    	u8	pan;
    	u8	priority;
    	u8	flags;
    	u8	tremType;
    	u8	tremRate;
    	u8	tremDepth;
    	u8	tremDelay;
    	u8	vibType;
    	u8	vibRate;
    	u8	vibDepth;
    	u8	vibDelay;
    	s16	bendRange;
    	s16	soundCount;
    	s32	soundArray[1];
    } ALInstrument;

Table 3 ALInstrument Structure

Field | Description
volume | Overall instrument playback volume. 0x0 = off, 0x7f = full scale pan Pan position. 0 = left, 64 = center, 127 = right.
priority | The priority for voices for this instrument. 0 = lowest priority, 10 = highest priority.
flags | If soundArray values are offsets, flags = 0. If they are pointers, flags = 1.
bandRange | Pitch bend range in cents.
soundCount | Number of sounds in the soundArray array.
soundArray | Offsets of (or pointers to) the ALSound objects in the instrument.

ALSound
The ALSound structure contains information about the individual sounds that make up an instrument.

    typedef struct Sound_s {
    	s32	envelope;
    	s32	keyMap;
    	s32	wavetable;
    	u8	samplePan;
    	u8	sampleVolume;
    	u8	flags
    } ALSound;

Table 4 ALSound Structure

Field | Description
envelope | Offset of (or pointer to ) the ALEnvelope object assigned to the sound.
keyMap | Offset of (or pointer to) the ALKeyMap object assigned to this sound. wavetable Offset of (or pointer to) ALWavetable objects assigned to the sound.
samplePan | Pan position of the sound in the stereo field: 0 = full left, 0x7f = full right sampleVolume Overall sample volume. 0 = off, 0x7f = full scale.
flags | If envelope, keyMap, and wavetable are specified as offsets, flags = 0. If they are pointers, flags = 1.

ALEnvelope
The ALEnvelope structure describes the attack-decay-sustain-release (ADSR) envelope for a sound.

Note: Release volume is assumed to be 0.

    typedef struct {
    	s32 attackTime;
    	s32 decayTime;
    	s32 releaseTime;
    	s16 attackVolume;
    	s16 decayVolume;
    } ALEnvelope;

Table 5 ALEnvelope Structure

Field | Description
attackTime | Time, in microseconds, to ramp from zero gain to attackVolume. attackVolume Target volume for the attack segment of the envelope.
decayTime | Time, in microseconds, to ramp from the attackVolume to the decayVolume.
decayVolume | Target volume for the decay segment of the envelope. The sustain loop holds at the decayVolume.
releaseTime | Time, in microseconds, to ramp to zero volume.

ALKeyMap
The ALKeyMap describes how the sound is mapped to the keyboard. It allows the sequencer to determine at what pitch to play a sound, given its MIDI key number and note on velocity.

Note: C4 is considered to be middle C (MIDI note number 60). Bank files may not contain keymaps that have overlapping key or velocity ranges.

    typedef struct {
    	u8 velocityMin;
    	u8 velocityMax;
    	u8 keyMin;
    	u8 keyMax;
    	u8 keyBase;
    	u8 detune;
    } ALKeyMap;

Table 6 ALKeyMap Structure

Field | Description
velocityMin | Minimum note on velocity for this map. 0 = off, 0x7f = full scale.
velocityMax | Maxumum note on velocity for this map. 0 = off, 0x7f = full scale.
keyMin | Lowest note in this key map. Notes are defines as in the MIDI specification.
keyMax | Highest note in this key map. Notes are defined as in the MIDI specification.
keyBase | The MIDI note equivalent to the sound played at unity pitch. detune Amount, in cents, to fine-tune this sample. Range is -50 to +50.

ALWavetable
The ALWavetable structure describes the sample data to be played for the given sound. It is described in detail below, along with the structures it contains.

    enum    {AL_ADPCM_WAVE = 0,
             AL_RAW16_WAVE};

    typedef struct {
        s32 order;
        s32 npredictors;
        s16 book[1];        /* Must be 8-byte aligned */
    } ALADPCMBook;

    typedef struct {
        u32         start;
        u32         end;
        u32         count;
        ADPCM_STATE state;
    } ALADPCMloop;

    typedef struct {
        u32         start;
        u32         end;
        u32         count;
    } ALRawLoop;

    typedef struct {
        ALADPCMloop *loop;
        ALADPCMBook *book;
    } ALADPCMWaveInfo;

    typedef struct {
        ALRawLoop *loop;
    } ALRAWWaveInfo;

    typedef struct {
    	s32	base;
    	s32	len;*/
    	u8	type;
    	u8	flags;
    	union {
    		ALADPCMWaveInfo adpcmWave;
    		ALRAWWaveInfo   rawWave;
    	} waveInfo;
    } ALWaveTable;

Table 7 ALWavetable Structure

Field | Description
base | Offset of (or pointer to) the start of the raw or ADPCM compressed wavetable in the table (.tbl) file.
len | Length, in bytes, of the wavetable.
type | The type (AL_ADPCM_WAVE or AL_RAW16_WAVE) of the wavetable structure.
flags | If the base field contains an offset, flags =0. If it contains a pointer, flags = 1.
waveInfo | Wavetable type specific information.

Table 8 ALADPCMWaveInfo structure

Field | Description
loop | Offset or pointer to the ADPCM-specific loop structure.
book | Offset or pointer to the ADPCM-specific code book.

Table 9 ALRawWaveInfo structure

Field | Description
loop | Offset or pointer to the raw sound loop structure.

Table 10 ALADPCMLoop structure

Field | Description
start | Sample offset of the loop start point.
end | Sample offset of the loop end point count Number of times the wavetable is to loop. A value of -1 means loop forever.
state | ADPCM decoder state information.

Table 11 ALADPCMBook structure

Field | Description
order | Order of the ADPCM predictor.
npredictors | Number of ADPCM predictors.
book | Array of code book data.

Table 12 ALRawLoop structure

Field | Description
start | Sample offset of loop start point.
end | Sample offset of loop end point.
count | Number of times the wavetable is to loop. A value of -1 means loop forever.

Copyright © 1999 Nintendo of America Inc. All Rights Reserved Nintendo and N64 are registered trademarks of Nintendo Last Updated January, 1999