Ultra Bank Files

These files store the data and metadata for soundfonts/soundbanks. UBNK files store instrument and percussion information and UWSD files store sound effects.

Byte Order: Big-Endian

Current Version: 2.3 (bubnk), 2.0 (buwsd) (As of 2023/08/05)

File Format (bubnk)

Header

Header Size: 0x10

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Identifier ("UBNK")
0x04	u16	2	Byte-Order Mark	Should be 0xFEFF for Big-Endian
0x06	s8	1	Major Version	Major version ID of file
0x07	s8	1	Minor Version	Minor version ID of file
0x08	u32	4	File Size	This is the size of the total file, including the full header.
0x0C	s16	2	Header Size	This is the size of the full header.
0x0E	s16	2	Chunk Count	Number of chunks in this file, after the header.

META Chunk

Bank metadata.

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Chunk Identifier ("META")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	u32	4	UID	UID of soundfont/soundbank. 0 if field empty.
0x0C	s8	1	Medium	Default load medium. (See common enums)
0x0D	s8	1	Cache Policy	Default cache policy. (See common enums)
0x0E	u8	1	Reference Flags	Flags describing how wave references are stored. (See below)
0x0F	u8	1	Wave Arc Count	Number of linked wave archives. 0 if these are not noted.
0x10	s8[n]	VAR	Wave Arc Indices	Indices of linked wave archives.
VAR	u8[]	4 - (4%n)	(Padding)	Padding to multiple of 4 bytes.
VAR	u32	4	WSD Link	UID of linked WSD file. 0 if field empty. (It is usually not needed)

ENVL Chunk

Describes all envelopes used by this bank.

Offset	Type	Size	Field Name	Description	Versions
0x00	char[4]	4	Magic Number	Chunk Identifier ("ENVL")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	s16	2	Envelope Count	Number of envelope entries in chunk.
0x0A	s16[n]	2n	Envelope Offset Table	Offset of envelope at each index relative to start of chunk (from "ENVL")
VAR	s16[n][m][2]	VAR	Envelope Data	Envelope data (see envelope page for how to read envelopes)
VAR	u8[]	4 - (4 % size)	(Padding)	Padding to multiple of 4 bytes.	2.2+

INST Chunk

Articulation data for standard instruments. A Z64 soundbank has 126 standard instrument slots (0 - 125).

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Chunk Identifier ("INST")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	s32	4	Instrument Count	Number of unique instruments.
0x0C	u16[126]	252	Instrument Table	Offset table - specifies offset from chunk start ("INST") to entry for instrument assigned to that program slot. 0 denotes an empty slot.
0x88	u8[4]	4	(Padding)	Padding to bring table size to 256.
0x8C	InstEntry[n]	32n	Instrument Data	Array of instrument data entries. Size will be the unique instrument count.

Instrument Record (InstEntry)

Offset	Type	Size	Field Name	Description
0x00	u8	1	(Padding)	Padding to allow instrument record format to mimic native struct format.
0x01	s8	1	Low Region Top	Highest MIDI note of the low region (exclusive), if in use. Set to 0 if no low region.
0x02	s8	1	High Region Bottom	Lowest MIDI note of the high region (exclusive), if in use. Set to 127 if no high region.
0x03	u8	1	Release	Index into table of release times. Generally, a higher value means a shorter release.
0x04	s32	4	Envelope Index	Index in ENVL chunk of envelope used for this instrument. -1 if unset.
0x08	u32	4	Low Region Wave	Reference to sample to use for low region. Set to 0 if unused.
0x0C	f32	4	Low Region Tune	Low region tuning (playback speed at middle C). Set to 0 if unused.
0x10	u32	4	Main Region Wave	Reference to sample to use for main region.
0x14	f32	4	Main Region Tune	Main region tuning (playback speed at middle C).
0x18	u32	4	High Region Wave	Reference to sample to use for high region. Set to 0 if unused.
0x1C	f32	4	High Region Tune	High region tuning (playback speed at middle C). Set to 0 if unused.

PERC Chunk

Articulation data for percussion program, if present. Percussion is always assigned to program 127.

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Chunk Identifier ("PERC")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	s32	4	Region Count	Number of percussion regions (set of adjacent notes with same base articulation data).
0x0C	PercEntry[n]	12n	Region Data	Percussion region table.

Percussion Region Record (PercEntry) - Version 2.1+

Offset	Type	Size	Field Name	Description
0x00	u8	1	Release	Index into table of release times. Generally, a higher value means a shorter release.
0x01	s8	1	Pan	Pan of drum region. May be overridden by sequence during playback.
0x02	s8	1	Region Bottom	Percussion slot index (NOT MIDI note) of lowest note in region (inclusive).
0x03	s8	1	Region Top	Percussion slot index (NOT MIDI note) of highest note in region (inclusive).
0x04	u32	4	Wave Reference	Reference to sample wave for this region.
0x08	s8	1	Unity Key	MIDI note where sample is played back at native sample rate.
0x09	s8	1	Fine Tune	Fine tune, in cents.
0x0A	s16	2	Envelope Index	Index in ENVL chunk of envelope used for this region. -1 if unset.

LABL Chunk

Display names for individual instruments and percussion regions. For user friendliness - not used by N64.

The names are stored together with no pointer table. The chunk is meant to be read serially. It is ordered first by unique instrument, in the order the instrument data chunk appears in the INST block, then by percussion region, again in order of appearance in the PERC block.

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Chunk Identifier ("LABL")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	VLS 2x2 [n]	VAR	String Data	Strings assigned to each unique instrument and perc region. One after another.

IENM Chunk

Instrument enum labels. This is for recomp outputs. Enum names assigned to each of the 126 instrument slots.

Like LABL, the strings are stored one after another and meant to be read serially. There will always be 126 string slots, even if a program is unused.

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Chunk Identifier ("IENM")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	VLS 2x2 [126]	VAR	String Data	Enum strings for each program slot.

PENM Chunk

Percussion enum labels. This is for recomp outputs. Enum names assigned to each of the 64 percussion slots.

Like LABL, the strings are stored one after another and meant to be read serially. There will always be 64 string slots, even if a program is unused.

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Chunk Identifier ("PENM")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	VLS 2x2 [64]	VAR	String Data	Enum strings for each percussion slot.

File Format (buwsd)

Header

Header Size: 0x10

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Identifier ("UWSD")
0x04	u16	2	Byte-Order Mark	Should be 0xFEFF for Big-Endian
0x06	s8	1	Major Version	Major version ID of file
0x07	s8	1	Minor Version	Minor version ID of file
0x08	u32	4	File Size	This is the size of the total file, including the full header.
0x0C	s16	2	Header Size	This is the size of the full header.
0x0E	s16	2	Chunk Count	Number of chunks in this file, after the header.

META Chunk

WSD collection metadata. Will usually be redundant to main bank's.

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Chunk Identifier ("META")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	u32	4	UID	UID of soundfont/soundbank or wsd collection itself. 0 if field empty.
0x0C	u8	1	Reference Flags	Flags describing how wave references are stored. (See below)
0x0D	u8	1	Wave Arc Count	Number of linked wave archives. 0 if these are not noted.
0x0E	s8[n]	VAR	Wave Arc Indices	Indices of linked wave archives.
VAR	u8[]	4 - (4%n)	(Padding)	Padding to multiple of 4 bytes.

DATA Chunk

Sound effect slot assignments, samples, and tuning.

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Chunk Identifier ("DATA")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	s32	4	SFX Count	Number of SFX slot records following this field.
0x0C	SFXEntry[n]	8n	SFX Table	SFX articulation data table.

SFX Articulation Data Entry (SFXEntry)

Sound effect slot assignments, samples, and tuning.

Offset	Type	Size	Field Name	Description
0x00	u32	4	Wave Reference	Reference to sample wave attached to this SFX slot. 0 if unused.
0x04	f32	4	Tuning	Playback speed for sample (at note correlating to this slot). 0 if unused.

ENUM Chunk

SFX slot enum labels. This is for recomp outputs. Enum names assigned to each slot present in the DATA chunk.

Like the string chunks in UBNK, the strings are stored one after another and meant to be read serially.

Offset	Type	Size	Field Name	Description
0x00	char[4]	4	Magic Number	Chunk Identifier ("ENUM")
0x04	u32	4	Chunk Size	Size of chunk in bytes, after this field.
0x08	VLS 2x2 [n]	VAR	String Data	Enum strings for each SFX slot.

Flags & Enums

Wave Reference Flags

Bit	Description
0	If set, wave sample reference fields are wave GUIDs.