AdLib Instrument Bank Format

From ModdingWiki
Jump to: navigation, search
AdLib Instrument Bank Format
Format typeMusical Instrument
HardwareOPL
Number of instruments65535
Instruments named?Yes, 8 chars
Games

The Ad Lib BNK Format is an instrument bank file created by the Ad Lib Corporation. It was designed for version 1.5 of AdLib Visual Composer in 1989, to work in conjunction with ROL Format music files. It had been discovered that the ~80-byte individual instrument files were actually using closer to 1,024 bytes of disk space each, due to the way the DOS FAT filesystem allocates at least one cluster per file. By combining all the instruments into a single .bnk file, disk space could be drastically reduced.

BNK files contain all of the custom instrument data for a set of ROL songs which contained the notes to play. Games that feature music composed with AdLib Visual Composer usually have BNK files as well, although in the case of id Software titles, the two files were converted into IMF Format during game development. Also this format used by Human Machine Interfaces sound engine for music instruments in HMP and HMI files.

The format can be opened and edited by the Instrument Maker program that came with AdLib Visual Composer.

File format

The file begins with a header:

Data type Name Description
UINT8 verMajor Major version number
UINT8 verMinor Minor version number
char signature "ADLIB-"
UINT16LE numUsed Number of instrument records in use
UINT16LE numInstruments Number of instrument records in the file
UINT32LE offsetName Offset where instrument names begin
UINT32LE offsetData Offset where instrument data begins
BYTE[8] pad Padded with 0x00

This is followed by a list of instrument names, repeated numInstruments times:

Data type Name Description
UINT16LE index Index into data section
Calculation: offsetInstr = offsetData + (index * sizeof(PackedTimbre))
UINT8 flags 0 if this record is not used, else 1
char[9] name Instrument name - must be NULL-terminated

It's important that it must be sorted by instrument name in alphabetical order to be correctly processed by Ad Lib tools.

At this point, the current position should be the same as offsetData. The actual instrument data follows, again repeated once for each instrument. The instrument data is in the following format, which is almost identical to the AdLib Instrument Format except with only one byte to store each field instead of two.

Data type Name Description
UINT8 iPercussive 0: Melodic instrument
1: Percussive instrument
UINT8 iVoiceNum Voice number (percussive only)
OPLREGS oplModulator Register values for the Modulator operator (op 0)
OPLREGS oplCarrier Register values for the Carrier operator (op 1)
UINT8 iModWaveSel Modulator wave select (OPL base register 0xE0)
UINT8 iCarWaveSel Carrier wave select (OPL base register 0xE0)

The OPLREGS structure is defined as:

Data type Name Description OPL base register Value range
UINT8 ksl Key scaling level 0x40 (bits 6-7)
UINT8 multiple Frequency multiplier 0x20 (bits 0-3) iMultiple & 0x0F is sent to OPL register [verify this]
UINT8 feedback Feedback [op 0 only, op 1 ignored] 0xC0 (bits 1-3)
UINT8 attack Attack rate 0x60 (upper four bits) [verify this]
UINT8 sustain Sustain level 0x80 (upper four bits) [verify this]
UINT8 eg Envelope gain (nonzero value is on) 0x20 (bit 5) [verify this]
UINT8 decay Decay rate 0x60 (lower four bits) [verify this]
UINT8 releaseRate Release rate 0x80 (lower four bits) [verify this]
UINT8 totalLevel Total output level 0x40 (bit 0-5) [verify this]
UINT8 am Amplitude modulation (Tremolo) 0x20 (bit 7) [verify this]
UINT8 vib Frequency Vibrato 0x20 (bit 6) [verify this]
UINT8 ksr Key scaling/envelope rate 0x20 (bit 4) [verify this]
UINT8 con Connector [op 0 only, op 1 ignored] 0xC0 (bit 0, inverted) 0: OPL bit set to 1
other: OPL bit set to 0

This structure is almost identical to an individual instrument in AdLib Instrument Format, but with UINT8 fields instead of UINT16LE.

Human Machine Interfaces version ("Version 0.0")

! Find out more about what is altered and how this version could be worked with.

The version of this format associated with HMP/HMI files is altered and incompatible with most tools that work with BNK files. Known differences include:

  • The major and minor version numbers in the header are both zero.
  • The flags byte in the instrument names list may have values other than 0 or 1, and a null flags byte might not be indicative of an unused sample.

The header and names list otherwise appear to follow the format spec. The instrument data itself has not yet been inspected for differences.

Known examples of games that include files of this version include two possibly standardized file names: DRUMS.BNK and MELODIC.BNK. Dark Legions also includes a BNKDRUM.BNK. All of the known "version 0.0" files are 5,404 bytes in length, with 128 instrument records reported in the header, but have differing contents.

Tools

The following tools are able to work with files in this format.

Name PlatformPlay? Create new? Modify? Convert/export to other? Import from other? Access hidden data? Edit metadata? Notes
AdLib bankmng.exe DOSNoYesYesYes; .insYes; .insNoNo Part of AdLib Visual Composer and AdLib Programmer's Manual
SBTimbre DOSYesNoNoYes; .ibkNoNoNo