AdLib Instrument Bank Format
|
This article is partially complete. This means that all known information is here, but there is still more information that needs to be discovered and/or reverse engineered. If you know some of the missing information, you can help the ModdingWiki by adding this info yourself. |
| Format type | Musical Instrument |
|---|---|
| Hardware | OPL |
| Number of instruments | 65535 |
| 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 | Platform | Play? | Create new? | Modify? | Convert/export to other? | Import from other? | Access hidden data? | Edit metadata? | Notes |
|---|---|---|---|---|---|---|---|---|---|
| AdLib bankmng.exe | DOS | No | Yes | Yes | Yes; .ins | Yes; .ins | No | No | Part of AdLib Visual Composer and AdLib Programmer's Manual |
| SBTimbre | DOS | Yes | No | No | Yes; .ibk | No | No | No | |
| OPL3 Bank Editor | Linux, Windows, macOS | Yes | Yes | Yes | Yes; many | Yes; many | No | Yes | Can load HMI's .BNK variant |