N64 Programming Manual Chapter 19

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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