ModdingWiki - User contributions [en-gb]

OP2 Bank Format

2025-11-02T23:52:59Z

Wohlstand: /* Instrument */ Clarify note offsets descriptions

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 175
| Names = Yes, 31 char
| Games =
{{Game|Chex Quest}}
{{Game|Chex Quest 2}}
{{Game|Doom}}
{{Game|Doom 2}}
{{Game|Heretic}}
{{Game|Hexen}}
{{Game|Raptor}}
{{Game|Strife}}
}}

The '''OP2 Bank Format''' is an instrument bank format used by the DMX sound library developed by Paul Radek of Digital Expressions, Inc. The 128 melodic and 47 percussion instrument limit was most likely chosen so that a single OP2 file could store all the instruments for a General MIDI song. This bank has support for two-voice instruments to provide support for pseudo four-operator instruments. File of this format usually has <tt>GENMIDI</tt> name without extension as embedded WAD resource, but also can have <tt>.OP2</tt> extension.

==File format==

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][8] || magic || <tt>#OPL_II#</tt> signature, doesn't null terminated
|-
| [[BYTE]][175][36] || instrument || Set of 175 instrument entry
|-
| [[char]][175][32] || names || Instrument names per every instrument entry, must be null terminated
|}

===Instrument===

Each bank contains 128 melodic and 47 percussion instruments.

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT16LE]] || flags || N/A || Instrument flags: 0x01 - fixed note, 0x02 - delayed vibrato (unused), 0x04 - Double-voice mode
|-
| [[UINT8]] || fineTune || N/A || Second voice detune level
|-
| [[UINT8]] || noteNum || N/A || Percussion note number, or the note to play when fixed note flag is enabled (between 0 and 128)
|-
!colspan=4|First voice
|-
| [[UINT8]] || iModChar1 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack1 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain1 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel1 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale1 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel1 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback1 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar1 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack1 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain1 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel1 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale1 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel1 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved1 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset1 || N/A || MIDI note offset for a first voice (ignored when "fixed note" flag is set)
|-
!colspan=4|Second voice
|-
| [[UINT8]] || iModChar2 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack2 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain2 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel2 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale2 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel2 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback2 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar2 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack2 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain2 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel2 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale2 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel2 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved2 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset2 || N/A || MIDI note offset for a second voice (ignored when "fixed note" flag is set)
|}

===Instrument names===
After 175'th instrument is folowing an array of 32-byte null-terminated instrument names

=== Fine tune ===
Fine tune value is an index offset of frequencies table. 128 is a center, i.e. don't detune. Formula of index offset is: <tt>(fine_tune / 2) - 64</tt>. Each unit of fine tune field is approximately equal to 1/0.015625 of tone.

=== Percussion instruments ===
Percussion instruments are in range between 35 (Bass drum 1) and 81 (Open Triangle) MIDI indeces.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://www.vgmpf.com/Wiki/index.php/IMF_Creator IMF Creator]
| Platform = Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; .op2
| canImport = Yes; many
| editHidden = Yes; delayed vibrato
| editMetadata = Yes
| notes = Utility by Adam Biser to create IMF music. Also includes OP2 bank editor.
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

DRO Format

2025-09-14T20:01:25Z

Wohlstand: /* Tools */ Added OPL3 Bank Editor that can import instruments from DRO files

{{Music Infobox
| Type = OPL
| Instruments = OPL
| NumChannels = 9 or 11 (OPL2), 18 or 22 (Dual OPL2 and OPL3)
| NumTracks = 1
}}
The DOSBox Raw OPL (DRO) format is used for storing captured OPL data from a game running in the cross-platform DOS emulator [http://dosbox.sourceforge.net DOSBox].

== File format ==

The file begins with a header:

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[8]||cSignature||"DBRAWOPL" (not NULL-terminated)
|-
|UINT16LE||iVersionMajor||Version number (high)
|-
|UINT16LE||iVersionMinor||Version number (low)
|}

The rest of the header depends on the version. If iVersionMajor is 5 and iVersionMinor is 6, then the version would be called "5.6" here.

=== Version 0.1 ===

The first version of the DRO Format was used up to and including DOSBox version 0.72. Note that the major and minor field names were swapped beginning with DOSBox 0.73, so this version used to be 1.0, but after DOSBox 0.73 it became 0.1 instead.

==== Header ====

The version 0.1 header follows on directly from the main file header.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT32LE||iLengthMS||Length of the song in milliseconds
|-
|UINT32LE||iLengthBytes||Length of the song data in bytes
|-
|UINT8||iHardwareType||Flag listing the hardware used in the song
|-
|UINT8[3]||iHardwareExtra||Rest of hardware type or song data (see below)
|}

''iHardwareType'' is one of the following values:

{|class="wikitable"
!''iHardwareType''!!Description
|-
|0||OPL2
|-
|1||OPL3
|-
|2||Dual OPL2
|}

In early files, the field was a UINT8, however in most common (recent) files it is a UINT32LE with only the first byte used. Unfortunately the version number was not changed between these revisions, so the only way to correctly identify the formats is to check the three <tt>iHardwareExtra</tt> bytes. If these are all zero then they can safely be ignored (iHardwareType was a UINT32.) If any of the three bytes in <tt>iHardwareExtra</tt> are non-zero, then this is an early revision of the format and those three bytes are actually song data<ref>In the [http://adplug.sourceforge.net AdPlug distribution], tests/samurai.dro is the early one-byte format, and doofus.dro is the later four-byte variant.</ref>.

==== Song data ====

Directly following the header is ''iLengthBytes'' bytes of OPL data. The first byte in the song data will be the OPL register, followed by the byte to send to that register. The "register" can also be one of these control values:

{|class="wikitable"
!Register value!!Data size!!Purpose
|-
|0x00||1||Delay. The single data byte following should be incremented by one, and is then the delay in milliseconds.
|-
|0x01||2||Delay. Same as above only there are two bytes following, in the form of a UINT16LE integer.
|-
|0x02||0||Switch to "low" OPL chip (#0)
|-
|0x03||0||Switch to "high" OPL chip (#1)
|-
|0x04||2||Escape - the next two bytes are normal register/value pairs even though the register might be 0x00-0x04
|-
|Other||1||Anything else should be treated as an OPL register, with the byte following being the data to send to that register.
|}

The delays all need to be incremented by one, as having a delay of zero milliseconds would be a waste of space. Codes 0x02 and 0x03 switch between two OPL chips in dual OPL2 mode, or between register banks in OPL3 mode. These should only be used if the hardware flag in the header indicates the file is in dual-OPL2 or OPL3 format.

All delays are in milliseconds (which can be treated as 1000Hz if converting between other formats.)

=== Version 2.0 ===

Version 2.0 of the DRO Format was introduced with DOSBox 0.73.

==== Header ====

The version 2.0 header also follows on directly from the main file header.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT32LE||iLengthPairs||Length of the song in register/value pairs (TODO: confirm - 1 == one register + one value, or two bytes)
|-
|UINT32LE||iLengthMS||Length of the song data ("chunk" -?) in milliseconds
|-
|UINT8||iHardwareType||Flag listing the hardware used in the song
|-
|UINT8||iFormat||Data arrangement
|-
|UINT8||iCompression||Compression type, zero means no compression (currently only zero is used)
|-
|UINT8||iShortDelayCode||Command code for short delay (1-256ms)
|-
|UINT8||iLongDelayCode||Command code for short delay (> 256ms)
|-
|UINT8||iCodemapLength||Number of entries in codemap table
|-
|UINT8[iCodemapLength]||iCodemap||Codemap table (see below)
|}

''iHardwareType'' is one of the following values: (which are different in v1.0 and v2.0)
{|class="wikitable"
!''iHardwareType''!!Description
|-
|0||OPL2
|-
|1||Dual OPL2
|-
|2||OPL3
|}
''iFormat'' is one of the following values:
{|class="wikitable"
!''iFormat''!!Description
|-
|0||Commands and data are interleaved (default/as per v1.0)
|-
|1||Maybe all commands, followed by all data (unused? - TODO: Confirm)
|}

Notes:
* ''iLengthMS'' is at a different offset in v1.0 and v2.0
* The ''iShortDelayCode'' value must have one added to it, as per v1.0 (so a short delay of 2 == a 3ms delay)
* The ''iLongDelayCode'' value must have one added to it, then be multiplied by 256 (or "<< 8"), so a long delay of 2 == a 768ms delay
* Because the high bit in each codeword is used to refer to the second OPL2 chip (or the second set of registers in an OPL3), there are only 128 possible codewords (0-127). Therefore ''iCodemapLength'' must always be 128 or less.
* DOSBox dumps a snapshot of the current register state at the beginning of a capture. (Any other registers are assumed initialised to zero.) This means that even an OPL2 only song will appear to have some data sent to the second OPL chip, because of this initial snapshot. To really know whether the second OPL chip is in use, you can find out if it is actually making any sound, like so:
** Examine bit 5 (0x20) on registers 0xB0 to 0xB8. If this bit is set, a note is playing and the chip is being used.
** Check whether bitmask 0x1F on register 0xBD is greater than 0x10 (i.e. <code>if (reg[0xBD] & 0x1F > 0x10) ...</code>). If so, the chip is in percussive mode and a rhythm instrument is being played, so the chip is being used.

===== Codemap table =====
The codemap table maps index numbers to OPL registers. As there are 256 possible OPL registers but only a subset of these actually used, the mapping table allows up to 128 OPL registers to be used in a song. The other 128 (with the high bit set) are used for the second OPL2 chip in a dual-OPL2 capture.

The table is a list of ''iCodemapLength'' bytes, with the index used later in the file. For example this code table:

01 04 05 08 BD

Means that when the song references register #0 the data should be sent to OPL register 0x01, when the song references register #4 the data should go to OPL register 0xBD. If the song references register #128 (i.e. register 128+0), data should be sent to OPL register 0x01 on the '''second''' chip (in dual OPL2 mode) or the second set of registers (OPL3 mode). Likewise register #132 (128+4) is OPL register 0xBD on the '''second''' chip.

==== Song data ====

Directly following the header is the song data in register index and value pairs.

{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT8||iRegisterIndex||Register to write to. This is an index into the codemap table.
|-
|UINT8||iValue||Value to write to the OPL register
|}

This structure is repeated ''iLengthPairs'' times. Note that while ''iRegisterIndex'' is normally an index into the codemap table, it can also match ''iShortDelayCode'' or ''iLongDelayCode'' if ''iValue'' is to be treated as a delay length (see above.) If the high bit is set (<code>iRegisterIndex & 0x80</code>) then it is a register on the second OPL chip in a dual-OPL2 song (so the high bit should be removed and the value looked up as normal, but then sent to the second OPL chip instead.)

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[AdPlug]]
| Platform = Windows/Linux/DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = v1/v2
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = Yes
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = N/A
| editMetadata = N/A
| notes = v1/v2
}}
{{FileFormatTool
| Name = [http://www.dosbox.com/ DOSBox]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = v2-only since 0.73. Produces .dro files as a result of capturing Adlib data from DOS games and applications
}}
{{FileFormatTool
| Name = [http://www.jestarjokin.net/apps/drotrimmer DRO Trimmer]
| Platform = Any (Python)
| canPlay = Yes
| canCreate = No
| canModify = Yes
| canExport = No
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Edits .dro files to remove unwanted notes from the start and end
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/dro2imf DRO2IMF]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[IMF Format|.imf]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Converts v1/v2 .dro to .imf
}}
{{FileFormatTool
| Name = [[DRO2MIDI]]
| Platform = Windows/Mac/Linux
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[MID Format|.mid]]
| canImport = No
| editHidden = N/A
| editMetadata = N/A
| notes = Converts v1/v2 .dro and .imf to .mid
}}
{{FileFormatTool
| Name = [[OpenMPT]]
| Platform = Windows
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = No
| canImport = Yes; many
| editHidden = N/A
| editMetadata = N/A
| notes = OpenMPT 1.30 and newer can export a DRO v1 register dump for songs that use OPL instruments.
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = No
| editHidden = No
| editMetadata = No
| notes = OPL3 Bank Editor can import FM instruments from DRO files
}}
{{EndFileFormatTools}}

== Similar formats ==
* [[RAW Format (Adlib)|Rdos' RAW format]] serves the same purpose, only these files were originally created through the RAC (Rdos Adlib Capture) TSR running under native DOS.
* The [[IMF Format|id Software Music Format (IMF)]] stores Adlib data in a similar manner in order to provide background music in many Apogee games.

== References ==
<references/>

OPL3 Bank Editor

2023-08-03T01:52:58Z

Wohlstand: Slightly tweaked the list of features.

{{Tool Infobox
| Platform = GNU/Linux, Windows, macOS
| Release = 2016-06-09
| Homepage = [https://github.com/Wohlstand/OPL3BankEditor/blob/master/README.md OPL3 Bank Editor]
| Download = [https://github.com/Wohlstand/OPL3BankEditor github.com]
| Edit1 = Instrument
}}

'''OPL3 Bank Editor''' is a free and open-source utility to create and edit various music instrument bank formats, developed by [[User:Wohlstand|Wohlstand]]. Various bank formats are had no own bank editor (For example, [[TMB Format]] which is a result of a generating by merging and chopping of two IBK files by official MAKETMB utility, or [[Junglevision Patch File Format]] which has proprietary bank editor that wasn't available in public), or had them be inconvenient. This bank editor allows working with all those formats by having same and friendly UI.

== Features ==
* Support for 2-operator, pseudo-4-operator, and 4-operator instruments and banks.
* Instrument testing through Nuked OPL3, DosBox OPL3, Opal, Java OPL3, and YMFM emulators.
* Instrument testing on hardware using various Serial Port protocols, C-Media chips, and through the Windows 98 version to test on real Sound Blaster or compatible sound cards.
* Playing single notes and various chords.
* Mouse-clickable piano claves to test various notes.
* Keyboard can be used to test instruments like on a piano.
* "Shut-up" button which allows to quickly mute all chip's channels.
* Tool-tips are describing purposes of every field.
* Import/Export of single instrument files.
* Instrument import from music files such as from [[IMF Format|IMF]] and [[CMF Format|CMF]].
* Ability to toggle global Deep Tremolo and Deep Vibrato flags.
* Support for both melodic and rhythm mode percussions.
* Performance benchmark of supported emulators.

== Links ==
* [http://www.vogons.org/viewtopic.php?f=9&t=48513 Support thread on VOGONS forum]

File:OPL3 Bank Editor.png

2023-08-03T01:50:02Z

Wohlstand: Wohlstand uploaded a new version of File:OPL3 Bank Editor.png

OPL3 Bank Editor

2021-08-16T14:54:43Z

Wohlstand: Minor fixes

{{Tool Infobox
| Platform = GNU/Linux, Windows, macOS
| Release = 2016-06-09
| Homepage = [https://github.com/Wohlstand/OPL3BankEditor/blob/master/README.md OPL3 Bank Editor]
| Download = [https://github.com/Wohlstand/OPL3BankEditor github.com]
| Edit1 = Instrument
}}

'''OPL3 Bank Editor''' is a free and open-source utility to create and edit various music instrument bank formats, developed by [[User:Wohlstand|Wohlstand]]. Various bank formats are had no own bank editor (For example, [[TMB Format]] which is a result of a generating by merging and chopping of two IBK files by official MAKETMB utility, or [[Junglevision Patch File Format]] which has proprietary bank editor that wasn't available in public), or had them be inconvenient. This bank editor allows working with all those formats by having same and friendly UI.

== Features ==
* Support for 2-operator, pseudo-4-operator, and 4-operator instruments and banks
* Instrument testing through Nuked OPL3 emulator
* Playing single notes and various chords
* Mouse-clickable piano claves to test various notes
* Keyboard can be used to test instruments like on a piano
* "Shut-up" button which allows to quickly mute all chip's channels
* Tool-tips are describing purposes of every field
* Import/Export of single instrument files
* Instrument import from music files such as from [[IMF Format|IMF]] and [[CMF Format|CMF]]
* Ability to toggle global Deep Tremolo and Deep Vibrato flags
* Support for both melodic and rhythm mode percussions

== Links ==
* [http://www.vogons.org/viewtopic.php?f=9&t=48513 Support thread on VOGONS forum]

OP2 Bank Format

2020-08-16T14:33:12Z

Wohlstand:

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 175
| Names = Yes, 31 char
| Games =
{{Game|Chex Quest}}
{{Game|Chex Quest 2}}
{{Game|Doom}}
{{Game|Doom 2}}
{{Game|Heretic}}
{{Game|Hexen}}
{{Game|Raptor}}
{{Game|Strife}}
}}

The '''OP2 Bank Format''' is an instrument bank format used by the DMX sound library developed by Paul Radek of Digital Expressions, Inc. The 128 melodic and 47 percussion instrument limit was most likely chosen so that a single OP2 file could store all the instruments for a General MIDI song. This bank has support for two-voice instruments to provide support for pseudo four-operator instruments. File of this format usually has <tt>GENMIDI</tt> name without extension as embedded WAD resource, but also can have <tt>.OP2</tt> extension.

==File format==

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][8] || magic || <tt>#OPL_II#</tt> signature, doesn't null terminated
|-
| [[BYTE]][175][36] || instrument || Set of 175 instrument entry
|-
| [[char]][175][32] || names || Instrument names per every instrument entry, must be null terminated
|}

===Instrument===

Each bank contains 128 melodic and 47 percussion instruments.

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT16LE]] || flags || N/A || Instrument flags: 0x01 - fixed pitch, 0x02 - delayed vibrato (unused), 0x04 - Double-voice mode
|-
| [[UINT8]] || fineTune || N/A || Second voice detune level
|-
| [[UINT8]] || noteNum || N/A || Percussion note number (between 0 and 128)
|-
!colspan=4|First voice
|-
| [[UINT8]] || iModChar1 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack1 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain1 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel1 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale1 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel1 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback1 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar1 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack1 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain1 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel1 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale1 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel1 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved1 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset1 || N/A || MIDI note offset for a first voice
|-
!colspan=4|Second voice
|-
| [[UINT8]] || iModChar2 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack2 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain2 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel2 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale2 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel2 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback2 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar2 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack2 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain2 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel2 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale2 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel2 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved2 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset2 || N/A || MIDI note offset for a second voice
|}

===Instrument names===
After 175'th instrument is folowing an array of 32-byte null-terminated instrument names

=== Fine tune ===
Fine tune value is an index offset of frequencies table. 128 is a center, i.e. don't detune. Formula of index offset is: <tt>(fine_tune / 2) - 64</tt>. Each unit of fine tune field is approximately equal to 1/0.015625 of tone.

=== Percussion instruments ===
Percussion instruments are in range between 35 (Bass drum 1) and 81 (Open Triangle) MIDI indeces.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://www.vgmpf.com/Wiki/index.php/IMF_Creator IMF Creator]
| Platform = Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; .op2
| canImport = Yes; many
| editHidden = Yes; delayed vibrato
| editMetadata = Yes
| notes = Utility by Adam Biser to create IMF music. Also includes OP2 bank editor.
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

OP2 Bank Format

2020-08-16T14:27:32Z

Wohlstand: The true sense of 0x02 instrument flag is "DELAYED_VIB" (Delayed vibrato), however, it's unused.

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 175
| Names = Yes, 31 char
| Games =
{{Game|Chex Quest}}
{{Game|Chex Quest 2}}
{{Game|Doom}}
{{Game|Doom 2}}
{{Game|Heretic}}
{{Game|Hexen}}
{{Game|Raptor}}
{{Game|Strife}}
}}

The '''OP2 Bank Format''' is an instrument bank format used by the DMX sound library developed by Paul Radek of Digital Expressions, Inc. The 128 melodic and 47 percussion instrument limit was most likely chosen so that a single OP2 file could store all the instruments for a General MIDI song. This bank has support for two-voice instruments to provide support for pseudo four-operator instruments. File of this format usually has <tt>GENMIDI</tt> name without extension as embedded WAD resource, but also can have <tt>.OP2</tt> extension.

==File format==

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][8] || magic || <tt>#OPL_II#</tt> signature, doesn't null terminated
|-
| [[BYTE]][175][36] || instrument || Set of 175 instrument entry
|-
| [[char]][175][32] || names || Instrument names per every instrument entry, must be null terminated
|}

===Instrument===

Each bank contains 128 melodic and 47 percussion instruments.

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT16LE]] || flags || N/A || Instrument flags: 0x01 - fixed pitch, 0x02 - delayed vibrato (unused), 0x04 - Double-voice mode
|-
| [[UINT8]] || fineTune || N/A || Second voice detune level
|-
| [[UINT8]] || noteNum || N/A || Percussion note number (between 0 and 128)
|-
!colspan=4|First voice
|-
| [[UINT8]] || iModChar1 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack1 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain1 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel1 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale1 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel1 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback1 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar1 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack1 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain1 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel1 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale1 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel1 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved1 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset1 || N/A || MIDI note offset for a first voice
|-
!colspan=4|Second voice
|-
| [[UINT8]] || iModChar2 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack2 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain2 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel2 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale2 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel2 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback2 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar2 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack2 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain2 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel2 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale2 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel2 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved2 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset2 || N/A || MIDI note offset for a second voice
|}

===Instrument names===
After 175'th instrument is folowing an array of 32-byte null-terminated instrument names

=== Fine tune ===
Fine tune value is an index offset of frequencies table. 128 is a center, i.e. don't detune. Formula of index offset is: <tt>(fine_tune / 2) - 64</tt>. Each unit of fine tune field is approximately equal to 1/0.015625 of tone.

=== Percussion instruments ===
Percussion instruments are in range between 35 (Bass drum 1) and 81 (Open Triangle) MIDI indeces.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://www.vgmpf.com/Wiki/index.php/IMF_Creator IMF Creator]
| Platform = Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; .op2
| canImport = Yes; many
| editHidden = Yes; Unknown flag
| editMetadata = Yes
| notes = Utility by Adam Biser to create IMF music. Also includes OP2 bank editor.
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

Apogee Sound System Timbre Format

2018-09-12T12:03:00Z

Wohlstand: Added "Rise of the Triad" game

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 256
| Names = No
| Games =
{{Game|Duke Nukem 3D}}
{{Game|Blood}}
{{Game|Shadow Warrior}}
{{Game|NAM}}
{{Game|Rise of the Triad}}
}}

The '''Apogee Sound System Timbre Format''' is an instrument bank format used by the Apogee Sound System library developed by 3D Realms. The 128 melodic and 128 percussion instrument limit was most likely chosen so that a single TMB file could store all the instruments for a General MIDI song. Files of this format are has <tt>.tmb</tt> extension.

==File format==

TMB files have no header and signature. The file contains 256 13-byte instrument entries (first 128 are melodic, and next 128 are percussion).

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT8]] || SAVEK[0] || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || SAVEK[1] || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || Level[0] || 0x40 || Modulator key scaling/output level
|-
| [[UINT8]] || Level[1] || 0x43 || Carrier key scaling/output level
|-
| [[UINT8]] || Env1[0] || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || Env1[1] || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || Env2[0] || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || Env2[1] || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || Wave[0] || 0xE0 || Modulator wave select
|-
| [[UINT8]] || Wave[1] || 0xE3 || Carrier wave select
|-
| [[UINT8]] || Feedback || 0xC0 || Feedback/connection
|-
| [[INT8]] || Transpose || N/A || Note offset for melodic instruments, and key number for percussion
|-
| [[INT8]] || Velocity || N/A || Velocity offset
|}

The TMB format is directly based on [[IBK Format]], and has first 12 bytes be same as in the IBK Format. Official <tt>MAKETMB.EXE</tt> utility (can be found with the source code of 3D Realms games in the Audio Library public folder) generates TMB files from the set of IBK files.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = <tt>MAKETMB.EXE</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = Yes; .tmb
| canImport = Yes; [[IBK Format|.ibk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''Apogee Sound System'' SDK
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

IMF Format

2017-08-06T12:47:18Z

Wohlstand: /* Timing */ Major Stryker has 560 Hz

{{Music Infobox
| Type = OPL
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 1
| Tags = Unofficial: Title, Composer, Remarks, Program name
| Games =
{{Game|Bio Menace}}
{{Game|Blake Stone}}
{{Game|Catacomb 3-D}}
{{Game|Commander Keen 4-6}}
{{Game|Corridor 7 Alien Invasion}}
{{Game|Cosmo's Cosmic Adventures}}
{{Game|Duke Nukem II}}
{{Game|Hocus Pocus}}
{{Game|Major Stryker}}
{{Game|Monster Bash}}
{{Game|Operation Body Count}}
{{Game|Realms of Chaos}}
{{Game|Wolfenstein 3-D}}
}}

The id Software Music Format (IMF) is a raw music format that stores the actual bytes sent to the Adlib's [[OPL2]] chip. For this reason it is a very simple format to process.

== File format ==

There are two versions of the IMF format: Type-0 format and Type-1 format. In a Type-0 file, the whole file is Adlib data that is played until the end of the file is reached. Type-1 files are actually ripped chunks from an [[AudioT Format]] file. No game ever actually used Type-1 IMFs that were not stored inside an AudioT file. The two initial bytes contain the size of the Adlib data (not including the two bytes themselves), so only this much data is played. This means it's possible to store arbitrary data in a Type-1 IMF file after the song data (see [[#Tag Data]] below.)

As a matter of luck, the first two data bytes in a Type-0 files are almost always 0x00 0x00, so this can be used to detect the file format version. If the first two bytes match the length of the file it is likely Type-1, but be aware that trailing data will mean this is not always true. Otherwise the only other way is to parse all the register/value pairs in the file and ensure the register is [[OPL chip#Register Map|within range]] (e.g. registers 0xA0 to 0xA9 are valid, but 0xAA to 0xAF should never be used.) Note that 0x00 is actually an invalid register, but must be treated as valid since the files usually begin by writing 0x00 to register 0x00.

Another way to detect the type of an IMF file is to examine the first few instructions in the IMF file. The idea is that the first few IMF commands set up the AdLib registers and therefore should have no delay. Even if there is a delay, it would normally be relatively low compared to the combined 16-bit value of the (register, value) pair.

<source lang="c">
UINT16 ReadInt16LE(FILE* in)
{
UINT8 buf[2];
fread(buf, 1, 2, in);
return (buf[0] | (buf[1] << 8));
}

int IMF_IsChunk(FILE* in)
{
UINT16 chunksize, buff, i=42;
UINT32 sum1=0, sum2=0;

if(!in)
return 0;

if (!feof(in))
{
chunksize = ReadInt16LE(in);
if ((chunksize == 0) || (chunksize & 3))
return 0;

while(!feof(in) && i)
{
buff = ReadInt16LE(in);
sum1 += buff;
buff = ReadInt16LE(in);
sum2 += buff;
i--;
}
fseek(in, 0, SEEK_SET);
return (sum1 > sum2);
}
return 0;
}
</source>

In the code given above, if the file is a chunk (Type-1), then <tt>sum1</tt> contains the sum of all (register, value) pairs and <tt>sum2</tt> contains the sum of all delays. If it's a plain IMF file (Type-0), the sums are swapped.

The only case in which this detection would fail is IMF data that writes a bunch of zeroes to register zero (which would be pointless since that register is undefined) and/or has very large delays (which would be pointless because it would lead to delays of up to a minute before the next IMF command would be processed, resulting in multiple minutes of silence before the song actually starts playing notes).

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[UINT16LE]]||iLength||Song data length in bytes (Type-1 format only)
|-
|[[BYTE]][iLength]||cAdlibData||Song data (see below) - <code>iLength</code> bytes long if Type-1, or until EOF if Type-0
|-
|[[BYTE]][]||cExtraData||Arbitrary data/tags (Type-1 format only, see [[#Tag Data]] below)
|}

The earliest version of the IMF data in the [[AudioT Format]] actually starts with a [[UINT32LE]] length value. The Commander Keen 4 Demo uses that early version. Just extracting the IMF chunk from the <tt>AUDIOT.CK4</tt> file will most likely confuse programs, since the file does not start with two 0's. Programs that only check the first two bytes will assume that the file is a ripped chunk, but will swap the delays and register/data pairs because of the length value being stored in the first four bytes instead of just the first two. That means the song will not play the intended notes. Programs that use the detection code given above will identify the file as plain IMF data and treat the length value as an IMF command. That means the song will play correctly at first, but any trailing data present in the file will also be interpreted as IMF data, most likely leading to long delays at the end of the song.

Note that for Type-1 files, the initial two bytes (the "song data length") are likely to be the filesize minus two, as the two initial bytes aren't counted. The obvious exception to this is if there is trailing data at the end of the OPL data, such as an info tag.

The song data is composed of four-byte "units":

{|class="wikitable"
!Data type!!Description
|-
|[[BYTE]]||Adlib register
|-
|[[BYTE]]||Adlib data
|-
|[[UINT16LE]]||Delay
|}

The data byte is sent to the specified register on the Adlib card, followed by a delay for the specified number of cycles. For a 560Hz IMF file, there are 560 cycles in one second (see [[#Timing]] below), so a delay of 560 would result in one second of silence (and likewise in a 700Hz IMF the delay value would need to be 700 to produce one second of silence.) A delay of 1 would wait for a single cycle, and a delay of zero means the next register/data pair should be sent immediately (so in a single 'cycle', data would be sent continuously until the next non-zero delay value is reached.)

=== Timing ===

IMF files exist at three known speeds. Unfortunately this is determined by the game, not the IMF file, so tempo cannot be determined from the music files alone. Extracted IMFs can be compared to discern their speeds. The known speeds are:

{|class="wikitable"
!Speed!!Game
|-
|280Hz||[[Duke Nukem II]]
|-
|560Hz||[[Bio Menace]], [[Commander Keen]], [[Cosmo's Cosmic Adventures]], [[Monster Bash]], [[Major Stryker]]
|-
|700Hz||[[Blake Stone]], [[Operation Body Count]], [[Wolfenstein 3-D]], [[Corridor 7]]
|}

The easiest method to tell the files apart is to treat all files with a .WLF extension as 700Hz and all .IMF files as 560Hz. Since Duke II is the odd one out, it is usually ignored since doubling the value of all the delay bytes conveniently turns it into a 560Hz .IMF.

=== Restrictions ===

As IMF files contain Adlib music for games that may also have Adlib sound effects, care must be taken to ensure that IMF music and any sound effects can share the OPL chip without conflict. This is done by reserving the OPL's first channel for sound effects, leaving eight remaining channels available for use in IMF files. This has been confirmed by automated inspection of the IMF files from the following games, all of which have no data on OPL channel #0 beyond 2-3 initialisation commands: [[Bio Menace]], [[Blake Stone]], [[Commander Keen 4-6]], [[Cosmo's Cosmic Adventures]], [[Duke Nukem II]], [[Major Stryker]], [[Monster Bash]], [[Operation Body Count]], [[Wolfenstein 3-D]].

In situations where channel #0 is not reserved and is used by the IMF file, when it is placed back into the game it interferes with the sound effects causing distortion, transposition, and otherwise resulting in broken sound effects. This can happen when an IMF file is created using a utility that does not take into account the fact that channel #0 must be left unused. See the end of this page for a list of utilities that can create IMF files and whether they treat channel #0 correctly.

It is worth noting that channel #0 is unused even in games such as Cosmo and Monster Bash, which do not use Adlib sound effects (Cosmo has PC speaker effects only and Monster Bash has PC speaker and digitised PCM audio.) It is also worth mentioning that some IMF songs from [[Monster Bash]] make use of the OPL's rhythm-mode, which trades three note-producing channels for five percussion channels. The IMF songs from the Keen 4 Demo also use rhythm-mode.

=== Tag Data ===

In a Type-1 IMF file it's possible to store data after the end of a song (as per the length given in the first two bytes of the file.) There are a few uses for this - some games store additional (unused) data there generated when the files were added to the game's group file, and others have repurposed this area to store information about the song itself (title, artist, etc.)

The tag data was originally written to the AudioT files by Id Software's tool [[Muse]] and was probably only processed by that tool. The [[Wolfenstein 3-D]] source code reads the entire chunk from the [[AudioT Format|AudioT]] file (including any tag data), but it only ever uses the song length and the song data.

==== Official data ====
For those files which were distributed with additional data in this area, it is not entirely clear what the purpose of this data is. It was apparently added when the source IMF files were compiled into a group audio file by [[Muse]]. (They appear not to be part of the source IMF files as there are occurrences where a file consists solely of tag data.) The format appears to be the same in all games that use it (such as Bio Menace or Wolfenstein 3-D) but it is not supported by any IMF players.

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[UINT16LE]]||Unknown||
|-
|[[char]][16]||strTitle||Song title
|-
|[[char]][64]||strRemarks||Song comment/message, usually source file name.
|-
|[[char]][6]||cProg||Data from the compiler?
|}

==== Unofficial uses ====
It is also possible to store tags there, and this simple format is supported by most IMF players:

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[BYTE]]||cSignature||0x1A
|-
|[[char]][256]||strTitle||Song title
|-
|[[char]][256]||strComposer||Song composer
|-
|[[char]][256]||strRemarks||Song comment/message
|-
|[[char]][9]||cProg||Name of the first program that added these tags (eight bytes + terminating NULL, pad out with NULLs if necessary.)
|}

Note that the char[256] strings are variable-length NULL-terminated strings. Their maximum length is 256 bytes *including* the terminating NULL, meaning the string will only ever contain 255 characters or less, plus the terminating-NULL. Of course the string will normally be much shorter, and an empty string will consist of a single 0x00 byte.

This tag format is supported by AdPlug when playing IMFs. The tag format can also be used with .raw files, but no players officially support it yet.

Note that the tags should begin directly after the IMF data, so in other words reading in the first two bytes of the file (the "song length") and then seeking forward that many bytes, should put the file pointer at the start of the tag block (so the next byte that will be read in should be 0x1A, if the tags are present.)

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://adplug.sourceforge.net AdPlug]
| Platform = All
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[RAW Format (Adlib)|.raw]]
| canImport = No
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/cmf2imf CMF2IMF]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[CMF Format|.cmf]]
| editHidden = No
| editMetadata = No
| notes = Doesn't leave channel 0 clear for SFX
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/dro2imf DRO2IMF]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[DRO Format|.dro]]
| editHidden = No
| editMetadata = No
| notes = Doesn't leave channel 0 clear for SFX
}}
{{FileFormatTool
| Name = [[DRO2MIDI]]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[MID Format|.mid]]
| canImport = No
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = [http://winwolf3d.dugtrio17.com/download/IMFCreator IMFCreator]
| Platform = Windows
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[MID Format|.mid]]
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = MUS2IMF
| Platform = DOS?
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[MUS Format|.mus]]
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = No
| editHidden = No
| editMetadata = No
| notes = OPL3 Bank Editor can import FM instruments from IMF files
}}
{{EndFileFormatTools}}

Raptor

2017-07-26T15:33:07Z

Wohlstand: Mark GENMIDI as known format

{{NeedMoreInfo}}
{{Game Infobox
| Levels = No
| Tiles = No
| Sprites = No
| Fullscreen = Edit
| Sound = No
| Music = Edit
| Text = Edit
| Story = No
| Interface = No
}}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Windows
| grp = Edit
| map = No
| gfx = Some
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

== Related links ==

* Raptor's creators have [http://mking.com/raptor_game.html ported it to other platforms] including iPhone and Windows

{{BeginGameFileList}}
{{GameFile
| Name = *.glb
| Format = [[GLB Format (Raptor)]]
| KnownFormat = Yes
| Desc = Archive file storing most of the game data files
}}
{{GameFile
| Name = *.ini
| Format = ASCII text
| KnownFormat = Yes
| Desc = Configuration file storing game settings
}}
{{GameFile
| Name = *_agx
| Format = ?
| KnownFormat = No
| Desc = Unknown
}}
{{GameFile
| Name = genmidi_op2
| Format = [[OP2 Bank Format]]
| KnownFormat = Yes
| Desc = [[OPL]] FM patches for MIDI instruments
}}
{{GameFile
| Name = lastscr?_txt
| Format = [[B800 Text]]
| KnownFormat = Yes
| Desc = Text-mode exit screens
}}
{{GameFile
| Name = *_dat
| Format = [[VGA Palette]]
| KnownFormat = Yes
| Desc = 6-bit VGA palette
}}
{{GameFile
| Name = *_fx
| Format = 8-bit PCM, unknown header
| KnownFormat = Partial
| Desc = Sound effects
}}
{{GameFile
| Name = *_itm
| Format = ?
| KnownFormat = No
| Desc = Unknown
}}
{{GameFile
| Name = *_map
| Format = [[Raptor Level Format]]
| KnownFormat = No
| Desc = Game levels
}}
{{GameFile
| Name = *_mus
| Format = [[MUS Format]]
| KnownFormat = Yes
| Desc = Background music
}}
{{GameFile
| Name = *_pic
| Format = [[Raptor PIC Format]]
| KnownFormat = Yes
| Desc = Various images and full-screen graphics
}}
{{GameFile
| Name = *_rec
| Format = [[Raptor Demo Format]]
| KnownFormat = No
| Desc = Pre-recorded demo macros
}}
{{GameFile
| Name = startg?tiles .. endg?tiles
| Format = [[Raptor Tileset Format]]
| KnownFormat = No
| Desc = Tiles used to draw game levels
}}
{{GameFile
| Name = *_txt
| Format = ASCII text
| KnownFormat = Yes
| Desc = Text for various game screens
}}
{{EndGameFileList}}

[[Category:Apogee]]
[[Category:Overhead]]
[[Category:Space Invaders]]

Doom

2017-07-26T15:31:54Z

Wohlstand: Added GENMIDI file

{{Stub}}

{{Game Infobox
| Levels = Edit
| Tiles = Edit
| Sprites = Edit
| Fullscreen = Edit
| Sound = Edit
| Music = Edit
| Text = Edit
| Story = Edit
| Interface = Edit
}}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Windows/Linux
| grp = Edit
| map = No
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://eureka-editor.sourceforge.net/ Eureka]
| Platform = Windows/Mac/Linux
| grp = No
| map = Edit
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [http://slade.mancubus.net SLADE]
| Platform = Windows/Mac
| grp = Edit
| map = Edit
| gfx = Edit
| mus = Edit
| sfx = Edit
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = DeHackEd
| Platform = DOS
| grp = No
| map = No
| gfx = No
| mus = No
| sfx = No
| txt = Edit
| sav = No
| exe = Edit
}}
{{EndFileFormatTools}}

== More detail ==

There is extensive information already on the [http://doom.wikia.com/wiki/ Doom wiki]

{{BeginGameFileList}}
{{GameFile
| Name = N/A
| Format = [[B800 Text]]
| KnownFormat = Yes
| Desc = Exit text screens
}}
{{GameFile
| Name = N/A
| Format = [[MUS Format]]
| KnownFormat = Yes
| Desc = Background music
}}
{{GameFile
| Name = GENMIDI
| Format = [[OP2 Bank Format]]
| KnownFormat = Yes
| Desc = FM patches for MUS/MIDI music
}}
{{GameFile
| Name = N/A
| Format = [[VOC Format]]
| KnownFormat = Yes
| Desc = Sound effects
}}
{{GameFile
| Name = *.wad
| Format = [[WAD Format]]
| KnownFormat = Yes
| Desc = Archive storing most of the game's data files
}}
{{EndGameFileList}}

[[Category:id Software]]
[[Category:3D]]
[[Category:First-Person Shooter]]

OP2 Bank Format

2017-07-24T20:55:26Z

Wohlstand: /* Instrument names */

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 175
| Names = Yes, 31 char
| Games =
{{Game|Chex Quest}}
{{Game|Chex Quest 2}}
{{Game|Doom}}
{{Game|Doom 2}}
{{Game|Heretic}}
{{Game|Hexen}}
{{Game|Raptor}}
{{Game|Strife}}
}}

The '''OP2 Bank Format''' is an instrument bank format used by the DMX sound library developed by Paul Radek of Digital Expressions, Inc. The 128 melodic and 47 percussion instrument limit was most likely chosen so that a single OP2 file could store all the instruments for a General MIDI song. This bank has support for two-voice instruments to provide support for pseudo four-operator instruments. File of this format usually has <tt>GENMIDI</tt> name without extension as embedded WAD resource, but also can have <tt>.OP2</tt> extension.

==File format==

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][8] || magic || <tt>#OPL_II#</tt> signature, doesn't null terminated
|-
| [[BYTE]][175][36] || instrument || Set of 175 instrument entry
|-
| [[char]][175][32] || names || Instrument names per every instrument entry, must be null terminated
|}

===Instrument===

Each bank contains 128 melodic and 47 percussion instruments.

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT16LE]] || flags || N/A || Instrument flags: 0x01 - fixed pitch, 0x02 - Unknown flag, 0x04 - Double-voice mode
|-
| [[UINT8]] || fineTune || N/A || Second voice detune level
|-
| [[UINT8]] || noteNum || N/A || Percussion note number (between 0 and 128)
|-
!colspan=4|First voice
|-
| [[UINT8]] || iModChar1 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack1 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain1 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel1 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale1 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel1 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback1 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar1 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack1 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain1 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel1 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale1 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel1 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved1 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset1 || N/A || MIDI note offset for a first voice
|-
!colspan=4|Second voice
|-
| [[UINT8]] || iModChar2 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack2 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain2 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel2 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale2 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel2 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback2 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar2 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack2 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain2 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel2 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale2 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel2 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved2 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset2 || N/A || MIDI note offset for a second voice
|}

===Instrument names===
After 175'th instrument is folowing an array of 32-byte null-terminated instrument names

=== Fine tune ===
Fine tune value is an index offset of frequencies table. 128 is a center, i.e. don't detune. Formula of index offset is: <tt>(fine_tune / 2) - 64</tt>. Each unit of fine tune field is approximately equal to 1/0.015625 of tone.

=== Percussion instruments ===
Percussion instruments are in range between 35 (Bass drum 1) and 81 (Open Triangle) MIDI indeces.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://www.vgmpf.com/Wiki/index.php/IMF_Creator IMF Creator]
| Platform = Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; .op2
| canImport = Yes; many
| editHidden = Yes; Unknown flag
| editMetadata = Yes
| notes = Utility by Adam Biser to create IMF music. Also includes OP2 bank editor.
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

OP2 Bank Format

2017-07-24T07:47:23Z

Wohlstand:

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 175
| Names = Yes, 31 char
| Games =
{{Game|Chex Quest}}
{{Game|Chex Quest 2}}
{{Game|Doom}}
{{Game|Doom 2}}
{{Game|Heretic}}
{{Game|Hexen}}
{{Game|Raptor}}
{{Game|Strife}}
}}

The '''OP2 Bank Format''' is an instrument bank format used by the DMX sound library developed by Paul Radek of Digital Expressions, Inc. The 128 melodic and 47 percussion instrument limit was most likely chosen so that a single OP2 file could store all the instruments for a General MIDI song. This bank has support for two-voice instruments to provide support for pseudo four-operator instruments. File of this format usually has <tt>GENMIDI</tt> name without extension as embedded WAD resource, but also can have <tt>.OP2</tt> extension.

==File format==

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][8] || magic || <tt>#OPL_II#</tt> signature, doesn't null terminated
|-
| [[BYTE]][175][36] || instrument || Set of 175 instrument entry
|-
| [[char]][175][32] || names || Instrument names per every instrument entry, must be null terminated
|}

===Instrument===

Each bank contains 128 melodic and 47 percussion instruments.

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT16LE]] || flags || N/A || Instrument flags: 0x01 - fixed pitch, 0x02 - Unknown flag, 0x04 - Double-voice mode
|-
| [[UINT8]] || fineTune || N/A || Second voice detune level
|-
| [[UINT8]] || noteNum || N/A || Percussion note number (between 0 and 128)
|-
!colspan=4|First voice
|-
| [[UINT8]] || iModChar1 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack1 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain1 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel1 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale1 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel1 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback1 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar1 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack1 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain1 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel1 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale1 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel1 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved1 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset1 || N/A || MIDI note offset for a first voice
|-
!colspan=4|Second voice
|-
| [[UINT8]] || iModChar2 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack2 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain2 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel2 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale2 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel2 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback2 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar2 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack2 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain2 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel2 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale2 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel2 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved2 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset2 || N/A || MIDI note offset for a second voice
|}

===Instrument names===

=== Fine tune ===
Fine tune value is an index offset of frequencies table. 128 is a center, i.e. don't detune. Formula of index offset is: <tt>(fine_tune / 2) - 64</tt>. Each unit of fine tune field is approximately equal to 1/0.015625 of tone.

=== Percussion instruments ===
Percussion instruments are in range between 35 (Bass drum 1) and 81 (Open Triangle) MIDI indeces.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://www.vgmpf.com/Wiki/index.php/IMF_Creator IMF Creator]
| Platform = Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; .op2
| canImport = Yes; many
| editHidden = Yes; Unknown flag
| editMetadata = Yes
| notes = Utility by Adam Biser to create IMF music. Also includes OP2 bank editor.
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

Apogee Sound System Timbre Format

2017-07-24T07:44:18Z

Wohlstand:

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 256
| Names = No
| Games =
{{Game|Duke Nukem 3D}}
{{Game|Blood}}
{{Game|Shadow Warrior}}
{{Game|NAM}}
}}

The '''Apogee Sound System Timbre Format''' is an instrument bank format used by the Apogee Sound System library developed by 3D Realms. The 128 melodic and 128 percussion instrument limit was most likely chosen so that a single TMB file could store all the instruments for a General MIDI song. Files of this format are has <tt>.tmb</tt> extension.

==File format==

TMB files have no header and signature. The file contains 256 13-byte instrument entries (first 128 are melodic, and next 128 are percussion).

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT8]] || SAVEK[0] || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || SAVEK[1] || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || Level[0] || 0x40 || Modulator key scaling/output level
|-
| [[UINT8]] || Level[1] || 0x43 || Carrier key scaling/output level
|-
| [[UINT8]] || Env1[0] || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || Env1[1] || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || Env2[0] || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || Env2[1] || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || Wave[0] || 0xE0 || Modulator wave select
|-
| [[UINT8]] || Wave[1] || 0xE3 || Carrier wave select
|-
| [[UINT8]] || Feedback || 0xC0 || Feedback/connection
|-
| [[INT8]] || Transpose || N/A || Note offset for melodic instruments, and key number for percussion
|-
| [[INT8]] || Velocity || N/A || Velocity offset
|}

The TMB format is directly based on [[IBK Format]], and has first 12 bytes be same as in the IBK Format. Official <tt>MAKETMB.EXE</tt> utility (Can be found with the source code of 3D Realms games in the Audio Library public folder) generates TMB files from the set of IBK files.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = <tt>MAKETMB.EXE</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = Yes; .tmb
| canImport = Yes; [[IBK Format|.ibk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''Apogee Sound System'' SDK
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

AdLib Timbre Bank Format

2017-07-23T22:36:27Z

Wohlstand: Added OPL3 Bank Editor into tools

{{Instrument Infobox
| Type = OPL
| Count = 65535
| Names = Yes, 8 chars
| Games =
{{Game|Vinyl Goddess From Mars}}
}}
The '''AdLib Timbre Bank Format''' is used to store the FM instruments used when playing songs in [[AdLib MIDI Format]]. The official documentation uses both the <tt>.snd</tt> and <tt>.tim</tt> extensions for files in this format.

This format is an early (1988) method of combining individual instrument files into one "bank" file. As this format was only designed to include the instruments needed to play a single song, in 1989 AdLib created the [[BNK Format (Ad Lib)|BNK Format]], giving it the <tt>.bnk</tt> extension. The differences are minor - compared to the Timbre format, the later Bank format includes a signature in the header, indicators for percussive vs melodic patches, and halves the capacity used for storing instruments by placing them in bytes instead of 16-bit integers.

== File format ==

The file begins with a header:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT8 || majorVersion || Always 1
|-
| UINT8 || minorVersion || Always 0
|-
| UINT16LE || nrTimbre || Number of instruments in the file
|-
| UINT16LE || offsetDef || Offset where instrument data begins
|}

This is followed by a list of instrument names, repeated <tt>nrTimbre</tt> times:

{|class="wikitable"
! Data type !! Name !! Description
|-
| char[9] || timbreName || Instrument name - must be null terminated
|}

At this point, the current position should be the same as <tt>offsetDef</tt>. 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]].

{|class="wikitable"
!Data type!!Name!!Description
|-
| OPLREGS || oplModulator || Register values for the Modulator (0) operator
|-
| OPLREGS || oplCarrier || Register values for the Carrier (1) operator
|-
| UINT16LE || iModWaveSel || Modulator wave select (only bits 0-1 recognised, OPL register 0xE0)
|-
| UINT16LE || iCarWaveSel || Carrier wave select (only bits 0-1 recognised, OPL register 0xE0)
|}

The ''OPLREGS'' structure is defined as:

{|class="wikitable"
! Data type !! Name !! Description !! OPL base register !! Value range
|-
| UINT16LE || iKSL || Key scaling level || 0x40 (bits 6-7) ||
|-
| UINT16LE || iMultiple || Frequency multiplier || 0x20 (bits 0-3) || iMultiple & 0x0F is sent to OPL register [verify this]
|-
| UINT16LE || iFeedback || Feedback || 0xC0 (bits 1-3) || Although only bits 1-3 are valid, Vinyl doesn't limit the output to three bits wide.
|-
| UINT16LE || iAttack || Attack rate || 0x60 (upper four bits) || [verify this]
|-
| UINT16LE || iSustain || Sustain level || 0x80 (upper four bits) || [verify this]
|-
| UINT16LE || iEG || Envelope gain (nonzero value is on) || 0x20 (bit 5) || [verify this]
|-
| UINT16LE || iDecay || Decay rate || 0x60 (lower four bits) || [verify this]
|-
| UINT16LE || iReleaseRate || Release rate || 0x80 (lower four bits) || [verify this]
|-
| UINT16LE || iTotalLevel || Total output level || 0x40 (bit 0-5) || [verify this]
|-
| UINT16LE || iAM || Amplitude modulation (Tremolo) || 0x20 (bit 7) || [verify this]
|-
| UINT16LE || iVIB || Frequency Vibrato || 0x20 (bit 6) || [verify this]
|-
| UINT16LE || iKSR || Key scaling/envelope rate || 0x20 (bit 4) || [verify this]
|-
| UINT16LE || iCONoff || Connector [OP0 only] || 0xC0 (bit 0, inverted) || 0: OPL bit set to 1 other: OPL bit set to 0
|}

=== Percussive instruments ===

There is no distinction between percussive and melodic instruments. This is controlled at playback time, depending on which channel the instrument is loaded into. This rules for this are described in [[AdLib MIDI Format]].

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>play.exe</tt>
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Only with an associated .mus file. Part of AdLib Programmer's Guide.
}}
{{FileFormatTool
| Name = AdLib <tt>convert.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[AdLib Instrument Format|.ins]]
| editHidden = No
| editMetadata = No
| notes = Loads .ins specified in .rol when producing .mus + .tim. Part of AdLib Programmer's Guide.
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Only with an associated .mus file
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes =
}}
{{EndFileFormatTools}}

== Credits ==

This file format was originally reverse engineered by [[User:Malvineous|Malvineous]] as the [[Vinyl Goddess From Mars]] instrument format, until [[User:binarymaster|binarymaster]] discovered it was the same as an early AdLib music format, and supplied the documentation on which this article is now based. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

SBI Format

2017-07-23T21:05:35Z

Wohlstand: /* Tools */ Improve table

{{Music Infobox
| Type = Instrument-only
| Instruments = OPL
| NumChannels = 1
| NumTracks = 0
| Tags = Title
}}
The '''SBI (Sound Blaster Instrument) Format''' stores a single instrument suitable for playback on a sound card with an OPL2 or OPL3 chip.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "SBI" followed by 0x1A
|-
| [[char]][32] || name || Instrument title (must be NULL-terminated)
|-
| [[BYTE]][16] || inst || Instrument settings (see below)
|}

=== Instrument settings ===

The instrument is in the following format. This is identical to the format used for each instrument in [[CMF Format]] songs and [[IBK Format]] instrument banks.

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[BYTE]][5]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

==== Percussive instruments ====

There is no indication as to whether a given instrument should be played in melodic or percussive mode. Playing an instrument destined for one mode in the other usually sounds quite bad.

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[SBI Format|.sbi]]
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Can import or export instruments in SBI format
}}
{{FileFormatTool
| Name = [[SBANK]]
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Сan convert SBI between [[AdLib Instrument Format|AdLib INS]] format
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = No
| notes = Can import or export instruments in SBI format
}}
{{EndFileFormatTools}}

CMF Format

2017-07-23T20:59:13Z

Wohlstand: /* Tools */ Using new table style

{{Music Infobox
| Type = MIDI
| Instruments = OPL
| NumChannels = 16
| NumTracks = 1
| NumPatterns = 1
| NumOrders = 0
| Tags = Title, Artist, Remarks
| Games =
{{Game|Jill of the Jungle}}
{{Game|Kiloblaster}}
{{Game|Scud Atak}}
{{Game|Solar Winds}}
{{Game|Traffic Department 2192}}
{{Game|Math Rescue}}
{{Game|Word Rescue}}
{{Game|Xargon}}
}}
The Creative Music Format (CMF) was created by Creative Labs for use with their SoundBlaster series of sound cards. It is a cut-down version of the [[MID Format|MIDI format]] (only one track) but unlike MIDI it allows custom instruments to be stored in the file itself (and unlike the Module formats that preceeded it, the instruments were not sampled but were synthesised using the Adlib/SoundBlaster OPL chips.)

== File format ==

The file begins with a header:

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[4]||cSignature||"CTMF" (not NULL-terminated)
|-
|UINT8||iVersionMinor||Minor version number (normally 0x01)
|-
|UINT8||iVersionMajor||Major version number (normally 0x01)
|-
|UINT16LE||iOffsetInstruments||Offset of the instrument block, from the start of the file
|-
|UINT16LE||iOffsetMusic||Offset of the music block, from the start of the file
|-
|UINT16LE||iTicksPerQuarter||Clock ticks per quarter note (one beat)
|-
|UINT16LE||iTicksPerSecond||Clock ticks per second
|-
|UINT16LE||iOffsetTitle||Offset of the song title string, zero if no title
|-
|UINT16LE||iOffsetComposer||Offset of the composer's name, zero if not listed
|-
|UINT16LE||iOffsetRemarks||Offset of the "remarks" string, zero if no remarks
|-
|UINT8[16]||iChannelInUse||Channel in use table (0x00 == channel not used, 0x01 == channel used in song)
|}

The rest of the header depends on the version:

==== Version 1.0 ====
{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT8||iInstrumentCount||Number of instruments used
|}

==== Version 1.1 ====
{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT16LE||iInstrumentCount||Number of instruments used
|-
|UINT16LE||iTempo||Basic tempo (BPM?)
|}

The song title, composer and remarks (if present) should follow this header and the instrument block should follow that (although there is no requirement for them to be located here, as long as the offsets in the header point to the correct location.) These three strings are NULL-terminated ASCII.

It is worth noting that the header stores both a tempo value and a "ticks per quarter note" value, however the only field that seems to be used for timing during playback is the "ticks per second" field. The tempo field doesn't even exist in version 1.0 files. It is assumed "basic tempo" means BPM (beats per minute) as this is the meaning of the "basic tempo" field in the earlier [[AdLib MIDI Format]].

It is also worth noting that between v1.0 and v1.1, the number of possible instruments expanded from a maximum of 256 (UINT8) to 65536 (UINT16.) However the MIDI data itself is only capable of addressing up to 128 instruments, so any extras cannot be used. Perhaps there was originally an intention to make these available through instrument banks like MIDI does.

Be aware that the title/composer/remarks fields are supposed to be zero if there is no metadata, but [[Highway Hunter]] sets them to invalid values (past EOF), so you may wish to check that these fields are within range and ignore them otherwise.

=== Instrument block ===

The instrument block contains all the instruments used in the song. The first instrument is referred to in the song data as instrument zero (MIDI patch #0.) The following table lists the fields used to define one instrument - it is repeated ''iInstrumentCount'' times.

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|UINT8||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|UINT8||iModScale||0x40||Modulator key scaling/output level
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level
|-
|UINT8||iModAttack||0x60||Modulator attack/decay level
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level
|-
|UINT8||iModSustain||0x80||Modulator sustain/release level
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level
|-
|UINT8||iModWaveSel||0xE0||Modulator wave select
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select
|-
|UINT8||iFeedback||0xC0||Feedback/connection
|-
|BYTE[5]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

There are 16 default instruments, repeated into the 128 available MIDI instruments (so instrument 0, 16, 32, etc. all refer to this first default instrument. See [[#Default instruments]] below) The instrument block then overrides these defaults. [[Word Rescue]] is notable for having CMFs that rely on these default instruments being present and correct.

==== Percussive instruments ====
Since each CMF instrument contains both OPL modulator and OPL carrier settings, when an instrument is selected in a CMF file, both the modulator and carrier settings are loaded into the OPL chip for that channel.

When the CMF is in percussive mode however (see [[#Controller 0x67: Rhythm mode]] below), most of the percussive instruments only occupy either a modulator or a carrier (i.e. half an instrument.) This means that loading these instruments must be treated slightly differently, as a whole instrument is supplied but only half of it will be loaded into the OPL chip, and not necessarily the expected half.

When percussive mode is active and an instrument change event (MIDI event 0xC0) is received on a percussive channel (12-16 inclusive), the instruments should be loaded as follows:

{|class="wikitable"
!CMF channel!!Instrument!!Instrument source!!OPL cell
|-
|<center>12</center>||Bass drum||Modulator Carrier||13 - Channel 7 Modulator 16 - Channel 7 Carrier
|-
|<center>13</center>||Snare drum||Modulator||17 - Channel 8 Carrier
|-
|<center>14</center>||Tom tom||Modulator||15 - Channel 9 Modulator
|-
|<center>15</center>||Top cymbal||Modulator||18 - Channel 9 Carrier
|-
|<center>16</center>||Hi-hat||Modulator||14 - Channel 8 Modulator
|}

Despite some documentation suggesting that certain instruments cannot have their pitch set, the Creative Labs SBFMDRV will play all percussive instruments at the requested pitch. Note however that as only one pitch can be set per channel, playing both a snare and hi-hat, or both a tom tom and top cymbal, at the same time, will cause a conflict, potentially changing the pitch of an already-playing note. The Creative Labs SBFMDRV simply writes the pitch as each note is played, changing the pitch of any currently playing note on the shared channel.

Be aware that some songs (e.g. [[Kiloblaster]]'s <tt>song_2</tt>) play two different percussive instruments simultaneously, when those two instruments share the same OPL channel (e.g. hi-hat and snare drum.) The notes are actually played at different pitches, which introduces a conflict, as only one note frequency is available for the channel and it must be shared by both instruments. In this case the order of events is important, as the pitch of the last event at that instant is the one that gets set for the channel. Normally with MIDI, if notes are played at the same instant in time it does not matter which order they are issued in, however in this case the song is quite different if the order is not maintained.

Essentially SBFMDRV writes the pitch to the OPL channel as the events are encountered, so whichever note is played last is the frequency the channel will be set to.

=== Song data ===

The song data itself is in standard MIDI format - identical to the ''data'' stored in a MIDI MTrk block (but without the "MTrk" header of course.) For details on this, see the [[MID Format#MIDI data|MIDI data description]].

One difference worth noting is that the official Creative Labs CMF player does not support pitch bends (code 0xE0) and those events are simply ignored. Simple sysex data appears to be ignored also, however its use in a CMF file can cause problems with other players.

==== MIDI controllers ====

In addition to the standard MIDI controllers (which are actually rarely used in CMF files), the following controllers have special meaning in a CMF file. Each controller has one data byte (the "controller value", 0-127), and the meaning of this byte will of course depend on which controller was selected.

{|class="wikitable"
!Controller!!Purpose
|-
|0x63||Non-standard extension: AM+VIB depth control (see below)
|-
|0x66||Set marker byte (used as a status flag readable by a music player)
|-
|0x67||Switch OPL between melody and rhythm mode (see below)
|-
|0x68||Transpose up by given number of 1/128 semitones
|-
|0x69||Transpose down by given number of 1/128 semitones
|}

===== Controller 0x63: Depth control =====
MIDI controller 0x63 is a nonstandard extension to allow the OPL's AM+VIB depth control to be adjusted (normal CMF playback has both the AM and VIB depth control fixed in the on state.) When this controller is set to zero, the depth control is switched off (i.e. amplitude depth is 1 dB, vibrato depth is 7 cents.) Setting the controller to a value of one increases the vibrato to a depth of 14 cents (OPL port 0xBD has bit 6 set), and setting the control to a value of two increases the amplitude depth to 4.8 dB (OPL port 0xBD has bit 7 set). Setting the control to a value of three increases both depth controllers, which is the CMF default setting (OPL port 0xBD has bits 6 and 7 set.)

Since this setting is global and affects the entire OPL chip, it does not matter which channel the controller change is issued on.

===== Controller 0x66: Song markers =====
Controller 0x66 is used to set a marker byte in the song. This can be used to notify the music player that a certain point in a song has been reached, or to trigger some kind of action in time with the music.

===== Controller 0x67: Rhythm mode =====
MIDI controller 0x67 is used to switch between "melody mode" and OPL "rhythm mode." In melody mode, nine-channel FM music is possible. In rhythm-mode, six-channel FM music is possible, with an additional five channels used for percussion (allowing 11 sounds to be played simultaneously.) In this mode, the last five MIDI channels are reserved for the percussive instruments as shown below.

Since this setting is global and affects the entire OPL chip, it does not matter which channel the controller change is issued on.

{|class="wikitable"
!Hex channel!!MIDI channel!!Use in melody mode!!Use in rhythm mode
|-
|0x00||1||Normal instrument||Normal instrument
|-
|0x01||2||Normal instrument||Normal instrument
|-
|0x02||3||Normal instrument||Normal instrument
|-
|0x03||4||Normal instrument||Normal instrument
|-
|0x04||5||Normal instrument||Normal instrument
|-
|0x05||6||Normal instrument||Normal instrument
|-
|0x06||7||Normal instrument||Normal instrument
|-
|0x07||8||Normal instrument||Normal instrument
|-
|0x08||9||Normal instrument||Normal instrument
|-
|0x09||10||Normal instrument||Normal instrument
|-
|0x0A||11||Normal instrument||Normal instrument
|-
|0x0B||12||Normal instrument||Bass drum
|-
|0x0C||13||Normal instrument||Snare drum
|-
|0x0D||14||Normal instrument||Tom-tom
|-
|0x0E||15||Normal instrument||Top cymbal
|-
|0x0F||16||Normal instrument||Hi-hat cymbal
|}

See [[#CMF/MIDI vs Adlib channels]] below for more details.

===== Controller 0x68: Transpose up =====
This controller transposes all following notes on the channel up by the given number of 1/128 semitones. Since the controller value must be between 0 and 127, it will allow a song to be transposed up anywhere between zero and almost a full semitone. The value is absolute, so a controller requesting a transpose up by 127 followed by a transpose up by 64, will initially be transposed up by almost a full semitone (127) but will then be transposed back by a half semitone (to 64).

A value of zero resets back to "not transposed."

===== Controller 0x69: Transpose down =====
Identical to controller 0x68 (Transpose up) only of course in the opposite direction, and again only affecting the channel the controller is issued on.

=== Notes ===

==== Keyon/off handling ====
Some songs don't always send keyoffs after a keyon, or they send them out of order (e.g. note 1 on, delay, note 2 on, note 1 off, delay, note 2 off.) If you don't check this you'll end up switching a note off too early (in the above example the "note 1 off" should *not* switch off "note 2" that was switched on just before it.) <tt>song_9.xr1</tt> from the first episode of Xargon is an excellent example of this, right at the start of the song.

The best way of handling this when playing through an OPL chip seems to be to remember the last note played on a channel, and upon receiving a keyoff, only process it if the keyoff is for the note currently playing on the channel (otherwise it can be discarded.) If a keyon is received and a note is already being played on a channel, the old note should be switched off just before playing the new note.

==== Keyon/off timing ====
Some songs play a note-on, then immediately (with no delay) have a corresponding note-off. If this is played faithfully, then the note will not be heard, however the Creative Labs player still plays these notes. The correct solution is {{TODO|currently unknown - wait for one tick or use the emulator callback between events?}}. A good example of this is the first few notes in <tt>song_32.xr1</tt>. ([https://github.com/adplug/adplug/issues/41 Discussion])

==== Default instruments ====
Although no documentation exists about this, it seems that the Creative Labs player sets the 128 available instruments based on 16 defaults looped/repeated to fill the 128 slots. They do not appear to be based on any MIDI instrument specification. Any instruments included in the CMF file then override these defaults. Some songs (e.g. the [[Word Rescue]] background music) rely on these default instruments and don't play properly if only their custom instruments are set.

There appear to be a different set of default instruments used for the percussion channels when rhythm mode is active. More investigation needs to be done to determine what these are and if they are related to the 16 default melody instruments.

{{TODO|Post a set of OPL settings here (perhaps in [[IBK Format]]) that provides these default parameters.}}

{{TODO|Confirm whether it's possible to set more than 16 custom instruments, without them looping and overwriting the earlier ones.}}

==== CMF/MIDI vs Adlib channels ====
MIDI (and consequently CMF) supports up to 16 channels. The OPL2 synth on the Adlib only supports a maximum of nine channels in normal mode, or six channels plus five percussion instruments in rhythm mode.

This means that any CMF player must correctly map up to 16 MIDI channels to only nine OPL channels. Many songs from games work correctly with a 1:1 mapping (i.e. the game music doesn't go beyond MIDI channel 9), however there are some songs that use channels beyond this (e.g. [[Word Rescue]] again, which, given the Voyetra credit, has probably been minimally converted from MIDI.)

At the time of writing, there are no known songs that use more than nine MIDI channels simultaneously, however [[Word Rescue]]'s E1L1 song appears to sound more than nine notes simultaneously across a smaller number of channels, so if all these notes should be heard, the extended OPL3 channels probably need to be used. [[Xargon]] <tt>song9</tt> also sounds multiple notes simultaneously in a single channel. Either of these will result in lost notes unless the available channels are cleverly managed.

As an aside, it would be interesting to test this with Creative's driver to see how it behaves.

==== Note velocity ====
The velocity values are loaded more or less directly into the OPL chip. This means unlike MIDI, the velocity is not a linear scale from 0 to 127, but logarithmic. A value of 1 is almost silent, and rapidly increase in volume so that values 2 and 3 are much louder. At the other end of the scale, 127 is full volume, but 126 and 125 are barely any quieter.

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://www.hitsquad.com/smm/programs/cmf2mid/ CMF2MID]
| Platform = DOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; .mid
| canImport = Yes; [[CMF Format|.cmf]]
| editHidden = No
| editMetadata = No
| notes = Convert CMF files into MIDI
}}
{{FileFormatTool
| Name = [http://adplug.sourceforge.net AdPlug/AdPlay]
| Platform = DOS, Linux, Windows
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Plugins for various audio players (plus a command line player) that mostly supports CMF files
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/xmms.html Malvineous' Adlib plugin]
| Platform = Linux
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Plugin for XMMS and Audacious that plays most CMF files more accurately than AdPlug
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Import instruments from CMF files to use them in banks
}}
{{EndFileFormatTools}}

== Similar formats ==
* The CMF song data is stored in the same format as used by [[MID Format|MIDI files]]
* The [[SBI Format]] (SoundBlaster Instrument) is the same as used in the CMF instrument block, with a header on the front.
* The [[IBK Format]] (Instrument Bank) is a group of SBI instruments, similar to the whole CMF instrument block.

OP2 Bank Format

2017-07-23T19:37:22Z

Wohlstand: small fix of categories

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 175
| Names = Yes, 31 char
| Games =
{{Game|Chex Quest}}
{{Game|Chex Quest 2}}
{{Game|Doom}}
{{Game|Doom 2}}
{{Game|Heretic}}
{{Game|Hexen}}
{{Game|Raptor}}
{{Game|Strife}}
}}

The '''OP2 Bank Format''' is an instrument bank format used by the DMX sound library developed by Paul Radek of Digital Expressions, Inc. The 128 melodic and 47 percussion instrument limit was most likely chosen so that a single OP2 file could store all the instruments for a General MIDI song. This bank has support for two-voice instruments to provide support for pseudo four-operator instruments.

==File format==

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][8] || magic || <tt>#OPL_II#</tt> signature, doesn't null terminated
|-
| [[BYTE]][175][36] || instrument || Set of 175 instrument entry
|-
| [[char]][175][32] || names || Instrument names per every instrument entry, must be null terminated
|}

===Instrument===

Each bank contains 128 melodic and 47 percussion instruments.

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT16LE]] || flags || N/A || Instrument flags: 0x01 - fixed pitch, 0x02 - Unknown flag, 0x04 - Double-voice mode
|-
| [[UINT8]] || fineTune || N/A || Second voice detune level
|-
| [[UINT8]] || noteNum || N/A || Percussion note number (between 0 and 128)
|-
!colspan=4|First voice
|-
| [[UINT8]] || iModChar1 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack1 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain1 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel1 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale1 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel1 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback1 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar1 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack1 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain1 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel1 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale1 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel1 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved1 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset1 || N/A || MIDI note offset for a first voice
|-
!colspan=4|Second voice
|-
| [[UINT8]] || iModChar2 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack2 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain2 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel2 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale2 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel2 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback2 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar2 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack2 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain2 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel2 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale2 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel2 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved2 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset2 || N/A || MIDI note offset for a second voice
|}

===Instrument names===

=== Fine tune ===
Fine tune value is an index offset of frequencies table. 128 is a center, i.e. don't detune. Formula of index offset is: <tt>(fine_tune / 2) - 64</tt>. Each unit of fine tune field is approximately equal to 1/0.015625 of tone.

=== Percussion instruments ===
Percussion instruments are in range between 35 (Bass drum 1) and 81 (Open Triangle) MIDI indeces.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://www.vgmpf.com/Wiki/index.php/IMF_Creator IMF Creator]
| Platform = Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; .op2
| canImport = Yes; many
| editHidden = Yes; Unknown flag
| editMetadata = Yes
| notes = Utility by Adam Biser to create IMF music. Also includes OP2 bank editor.
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

Apogee Sound System Timbre Format

2017-07-23T19:36:43Z

Wohlstand: small fix of categories

{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 256
| Names = No
| Games =
{{Game|Duke Nukem 3D}}
{{Game|Blood}}
{{Game|Shadow Warrior}}
{{Game|NAM}}
}}

The '''Apogee Sound System Timbre Format''' is an instrument bank format used by the Apogee Sound System library developed by 3D Realms. The 128 melodic and 128 percussion instrument limit was most likely chosen so that a single TMB file could store all the instruments for a General MIDI song.

==File format==

TMB files have no header and signature. The file contains 256 13-byte instrument entries (first 128 are melodic, and next 128 are percussion).

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT8]] || SAVEK[0] || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || SAVEK[1] || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || Level[0] || 0x40 || Modulator key scaling/output level
|-
| [[UINT8]] || Level[1] || 0x43 || Carrier key scaling/output level
|-
| [[UINT8]] || Env1[0] || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || Env1[1] || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || Env2[0] || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || Env2[1] || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || Wave[0] || 0xE0 || Modulator wave select
|-
| [[UINT8]] || Wave[1] || 0xE3 || Carrier wave select
|-
| [[UINT8]] || Feedback || 0xC0 || Feedback/connection
|-
| [[INT8]] || Transpose || N/A || Note offset for melodic instruments, and key number for percussion
|-
| [[INT8]] || Velocity || N/A || Velocity offset
|}

The TMB format is directly based on [[IBK Format]], and has first 12 bytes be same as in the IBK Format. Official <tt>MAKETMB.EXE</tt> utility (Can be found with the source code of 3D Realms games in the Audio Library public folder) generates TMB files from the set of IBK files.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = <tt>MAKETMB.EXE</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = Yes; .tmb
| canImport = Yes; [[IBK Format|.ibk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''Apogee Sound System'' SDK
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

Category:Instrument tools

2017-07-23T19:34:50Z

Wohlstand: Added "Modding tools" category

[[Category:Modding Tools]]
This category holds all tools that able to work with instrument banks and files.

Category:Instrument tools

2017-07-23T19:33:40Z

Wohlstand: Created page with "This category holds all tools that able to work with instrument banks and files."

This category holds all tools that able to work with instrument banks and files.

OPL3 Bank Editor

2017-07-23T19:31:01Z

Wohlstand: Change category into "Instrument"

{{Tool Infobox
| Platform = GNU/Linux, Windows, macOS
| Release = 2016-06-09
| Homepage = [https://github.com/Wohlstand/OPL3BankEditor/blob/master/README.md OPL3 Bank Editor]
| Download = [https://github.com/Wohlstand/OPL3BankEditor github.com]
| Edit1 = Instrument
}}

'''OPL3 Bank Editor''' is a free and open source utility to create and edit various music instrument bank formats, developed by [[User:Wohlstand|Wohlstand]]. Various bank formats are had no own bank editor (For example, [[TMB Format]] which is originally is generating by merging and chopping of two IBK files by official MAKETMB utility, or [[Junglevision Patch File Format]] which has proprietary bank editor that wasn't available in public), or had them be inconvenient. This bank editor allows working with all those formats by having same and friendly UI.

== Features ==
* Support for 2-operator, pseudo-4-operator, and 4-operator instruments and banks
* Instrument testing through Nuked OPL3 emulator
* Playing single note and various chords
* Mouse-clickable piano claves to test various notes
* Keyboard can be used to test instrument like on piano
* "Shut-up" button which allows to quickly mute all chip's channels
* Tool-tips are describing purposes of every field
* Import/Export of single instrument files
* Instrument import from music files such as from [[IMF Format|IMF]] and [[CMF Format|CMF]]
* Ability to toggle global Deep Tremolo and Deep Vibrato flags
* Support for both melodic and rhythm mode percussions

== Links ==
* [http://www.vogons.org/viewtopic.php?f=9&t=48513 Support thread on VOGONS forum]

Global Timbre Library

2017-07-23T19:25:33Z

Wohlstand: Added "Tools"

{{NeedMoreInfo}}
{{Instrument Infobox
| Type = OPL
| Type2 = MIDI
| Count = 65535
| Names = No
| Games =
{{Game|Syndicate}}
}}

The Global Timbre Library is an instrument bank format used by the Miles Sound System developed by John Miles.

The file defines a number of "timbres" (instruments) in the form of OPL register values. The instruments are indexed by MIDI bank and patch numbers, and are intended to be used for the playback of [[XMI Format]] MIDI tracks.

== File format ==

The file consists of two arrays:

# The header array
# The timbre (instrument) data array

=== Header array ===

The header array is a packed array of 6-octet header structs. There is one header per timbre (patch). Each header contains the following data:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[INT8]] || patch || MIDI Patch number
|-
| [[INT8]] || bank || MIDI Bank number
|-
| [[UINT32LE][offset] || offset || The offset of the data for this instrument, relative to the start of the file.
|}

The array is terminated by a 2-octet marker, 0xFFFF.

=== Timbre data ===

Immediately following the header array is the timbre data array. It has the same number of entries as the header array. Each timbre has the following structure (OPL2 format):

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT16LE]] || length || - || Struct length, including the length field itself. Value is always 14 for OPL2 instruments, and 25(?) for OPL3.
|-
| [[U(?)INT8]] || transpose || - || {{TODO|Precise meaning unknown}}
|-
| [[UINT8]] || mod_AVEKM || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || mod_KSLTL || 0x40|| Modulator key scaling/output level
|-
| [[UINT8]] || mod_AD || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || mod_SR || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || mod_WS || 0xE0 || Modulator wave select
|-
| [[UINT8]] || fb_c || 0xC0 || Feedback/connection
|-
| [[UINT8]] || car_AVEKM || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || car_KSLTL || 0x43 || Carrier key scaling/output level
|-
| [[UINT8]] || car_AD || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || car_SR || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || car_WS || 0xE4 || Carrier wave select
|}

== References ==

* [http://www.thegleam.com/ke5fx/misc/AIL2.ZIP Open Source release of Miles Sound System version 2 for DOS] by John Miles. See XPLAY.C and YAMAHA.INC.

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = XPLAY
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = No
| canImport = No
| editHidden = No
| editMetadata = No
| notes = Official example utility to play XMI files by using of GTL banks
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

SBI Format

2017-07-23T19:21:19Z

Wohlstand: Added "Tools"

{{Music Infobox
| Type = Instrument-only
| Instruments = OPL
| NumChannels = 1
| NumTracks = 0
| Tags = Title
}}
The '''SBI (Sound Blaster Instrument) Format''' stores a single instrument suitable for playback on a sound card with an OPL2 or OPL3 chip.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "SBI" followed by 0x1A
|-
| [[char]][32] || name || Instrument title (must be NULL-terminated)
|-
| [[BYTE]][16] || inst || Instrument settings (see below)
|}

=== Instrument settings ===

The instrument is in the following format. This is identical to the format used for each instrument in [[CMF Format]] songs and [[IBK Format]] instrument banks.

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[BYTE]][5]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

==== Percussive instruments ====

There is no indication as to whether a given instrument should be played in melodic or percussive mode. Playing an instrument destined for one mode in the other usually sounds quite bad.

== Tools ==
* [[SBTimbre]] - can import or export instruments in SBI format
* [[SBANK]] - can convert SBI between [[AdLib Instrument Format|AdLib INS]] format
* [[OPL3 Bank Editor]] - can import or export instruments in SBI format

CMF Format

2017-07-23T19:19:20Z

Wohlstand: Added OPL3 Bank Editor into tools

{{Music Infobox
| Type = MIDI
| Instruments = OPL
| NumChannels = 16
| NumTracks = 1
| NumPatterns = 1
| NumOrders = 0
| Tags = Title, Artist, Remarks
| Games =
{{Game|Jill of the Jungle}}
{{Game|Kiloblaster}}
{{Game|Scud Atak}}
{{Game|Solar Winds}}
{{Game|Traffic Department 2192}}
{{Game|Math Rescue}}
{{Game|Word Rescue}}
{{Game|Xargon}}
}}
The Creative Music Format (CMF) was created by Creative Labs for use with their SoundBlaster series of sound cards. It is a cut-down version of the [[MID Format|MIDI format]] (only one track) but unlike MIDI it allows custom instruments to be stored in the file itself (and unlike the Module formats that preceeded it, the instruments were not sampled but were synthesised using the Adlib/SoundBlaster OPL chips.)

== File format ==

The file begins with a header:

{|class="wikitable"
!Data type!!Name!!Description
|-
|BYTE[4]||cSignature||"CTMF" (not NULL-terminated)
|-
|UINT8||iVersionMinor||Minor version number (normally 0x01)
|-
|UINT8||iVersionMajor||Major version number (normally 0x01)
|-
|UINT16LE||iOffsetInstruments||Offset of the instrument block, from the start of the file
|-
|UINT16LE||iOffsetMusic||Offset of the music block, from the start of the file
|-
|UINT16LE||iTicksPerQuarter||Clock ticks per quarter note (one beat)
|-
|UINT16LE||iTicksPerSecond||Clock ticks per second
|-
|UINT16LE||iOffsetTitle||Offset of the song title string, zero if no title
|-
|UINT16LE||iOffsetComposer||Offset of the composer's name, zero if not listed
|-
|UINT16LE||iOffsetRemarks||Offset of the "remarks" string, zero if no remarks
|-
|UINT8[16]||iChannelInUse||Channel in use table (0x00 == channel not used, 0x01 == channel used in song)
|}

The rest of the header depends on the version:

==== Version 1.0 ====
{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT8||iInstrumentCount||Number of instruments used
|}

==== Version 1.1 ====
{|class="wikitable"
!Data type!!Name!!Description
|-
|UINT16LE||iInstrumentCount||Number of instruments used
|-
|UINT16LE||iTempo||Basic tempo (BPM?)
|}

The song title, composer and remarks (if present) should follow this header and the instrument block should follow that (although there is no requirement for them to be located here, as long as the offsets in the header point to the correct location.) These three strings are NULL-terminated ASCII.

It is worth noting that the header stores both a tempo value and a "ticks per quarter note" value, however the only field that seems to be used for timing during playback is the "ticks per second" field. The tempo field doesn't even exist in version 1.0 files. It is assumed "basic tempo" means BPM (beats per minute) as this is the meaning of the "basic tempo" field in the earlier [[AdLib MIDI Format]].

It is also worth noting that between v1.0 and v1.1, the number of possible instruments expanded from a maximum of 256 (UINT8) to 65536 (UINT16.) However the MIDI data itself is only capable of addressing up to 128 instruments, so any extras cannot be used. Perhaps there was originally an intention to make these available through instrument banks like MIDI does.

Be aware that the title/composer/remarks fields are supposed to be zero if there is no metadata, but [[Highway Hunter]] sets them to invalid values (past EOF), so you may wish to check that these fields are within range and ignore them otherwise.

=== Instrument block ===

The instrument block contains all the instruments used in the song. The first instrument is referred to in the song data as instrument zero (MIDI patch #0.) The following table lists the fields used to define one instrument - it is repeated ''iInstrumentCount'' times.

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|UINT8||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|UINT8||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|UINT8||iModScale||0x40||Modulator key scaling/output level
|-
|UINT8||iCarScale||0x43||Carrier key scaling/output level
|-
|UINT8||iModAttack||0x60||Modulator attack/decay level
|-
|UINT8||iCarAttack||0x63||Carrier attack/decay level
|-
|UINT8||iModSustain||0x80||Modulator sustain/release level
|-
|UINT8||iCarSustain||0x83||Carrier sustain/release level
|-
|UINT8||iModWaveSel||0xE0||Modulator wave select
|-
|UINT8||iCarWaveSel||0xE3||Carrier wave select
|-
|UINT8||iFeedback||0xC0||Feedback/connection
|-
|BYTE[5]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

There are 16 default instruments, repeated into the 128 available MIDI instruments (so instrument 0, 16, 32, etc. all refer to this first default instrument. See [[#Default instruments]] below) The instrument block then overrides these defaults. [[Word Rescue]] is notable for having CMFs that rely on these default instruments being present and correct.

==== Percussive instruments ====
Since each CMF instrument contains both OPL modulator and OPL carrier settings, when an instrument is selected in a CMF file, both the modulator and carrier settings are loaded into the OPL chip for that channel.

When the CMF is in percussive mode however (see [[#Controller 0x67: Rhythm mode]] below), most of the percussive instruments only occupy either a modulator or a carrier (i.e. half an instrument.) This means that loading these instruments must be treated slightly differently, as a whole instrument is supplied but only half of it will be loaded into the OPL chip, and not necessarily the expected half.

When percussive mode is active and an instrument change event (MIDI event 0xC0) is received on a percussive channel (12-16 inclusive), the instruments should be loaded as follows:

{|class="wikitable"
!CMF channel!!Instrument!!Instrument source!!OPL cell
|-
|<center>12</center>||Bass drum||Modulator Carrier||13 - Channel 7 Modulator 16 - Channel 7 Carrier
|-
|<center>13</center>||Snare drum||Modulator||17 - Channel 8 Carrier
|-
|<center>14</center>||Tom tom||Modulator||15 - Channel 9 Modulator
|-
|<center>15</center>||Top cymbal||Modulator||18 - Channel 9 Carrier
|-
|<center>16</center>||Hi-hat||Modulator||14 - Channel 8 Modulator
|}

Despite some documentation suggesting that certain instruments cannot have their pitch set, the Creative Labs SBFMDRV will play all percussive instruments at the requested pitch. Note however that as only one pitch can be set per channel, playing both a snare and hi-hat, or both a tom tom and top cymbal, at the same time, will cause a conflict, potentially changing the pitch of an already-playing note. The Creative Labs SBFMDRV simply writes the pitch as each note is played, changing the pitch of any currently playing note on the shared channel.

Be aware that some songs (e.g. [[Kiloblaster]]'s <tt>song_2</tt>) play two different percussive instruments simultaneously, when those two instruments share the same OPL channel (e.g. hi-hat and snare drum.) The notes are actually played at different pitches, which introduces a conflict, as only one note frequency is available for the channel and it must be shared by both instruments. In this case the order of events is important, as the pitch of the last event at that instant is the one that gets set for the channel. Normally with MIDI, if notes are played at the same instant in time it does not matter which order they are issued in, however in this case the song is quite different if the order is not maintained.

Essentially SBFMDRV writes the pitch to the OPL channel as the events are encountered, so whichever note is played last is the frequency the channel will be set to.

=== Song data ===

The song data itself is in standard MIDI format - identical to the ''data'' stored in a MIDI MTrk block (but without the "MTrk" header of course.) For details on this, see the [[MID Format#MIDI data|MIDI data description]].

One difference worth noting is that the official Creative Labs CMF player does not support pitch bends (code 0xE0) and those events are simply ignored. Simple sysex data appears to be ignored also, however its use in a CMF file can cause problems with other players.

==== MIDI controllers ====

In addition to the standard MIDI controllers (which are actually rarely used in CMF files), the following controllers have special meaning in a CMF file. Each controller has one data byte (the "controller value", 0-127), and the meaning of this byte will of course depend on which controller was selected.

{|class="wikitable"
!Controller!!Purpose
|-
|0x63||Non-standard extension: AM+VIB depth control (see below)
|-
|0x66||Set marker byte (used as a status flag readable by a music player)
|-
|0x67||Switch OPL between melody and rhythm mode (see below)
|-
|0x68||Transpose up by given number of 1/128 semitones
|-
|0x69||Transpose down by given number of 1/128 semitones
|}

===== Controller 0x63: Depth control =====
MIDI controller 0x63 is a nonstandard extension to allow the OPL's AM+VIB depth control to be adjusted (normal CMF playback has both the AM and VIB depth control fixed in the on state.) When this controller is set to zero, the depth control is switched off (i.e. amplitude depth is 1 dB, vibrato depth is 7 cents.) Setting the controller to a value of one increases the vibrato to a depth of 14 cents (OPL port 0xBD has bit 6 set), and setting the control to a value of two increases the amplitude depth to 4.8 dB (OPL port 0xBD has bit 7 set). Setting the control to a value of three increases both depth controllers, which is the CMF default setting (OPL port 0xBD has bits 6 and 7 set.)

Since this setting is global and affects the entire OPL chip, it does not matter which channel the controller change is issued on.

===== Controller 0x66: Song markers =====
Controller 0x66 is used to set a marker byte in the song. This can be used to notify the music player that a certain point in a song has been reached, or to trigger some kind of action in time with the music.

===== Controller 0x67: Rhythm mode =====
MIDI controller 0x67 is used to switch between "melody mode" and OPL "rhythm mode." In melody mode, nine-channel FM music is possible. In rhythm-mode, six-channel FM music is possible, with an additional five channels used for percussion (allowing 11 sounds to be played simultaneously.) In this mode, the last five MIDI channels are reserved for the percussive instruments as shown below.

Since this setting is global and affects the entire OPL chip, it does not matter which channel the controller change is issued on.

{|class="wikitable"
!Hex channel!!MIDI channel!!Use in melody mode!!Use in rhythm mode
|-
|0x00||1||Normal instrument||Normal instrument
|-
|0x01||2||Normal instrument||Normal instrument
|-
|0x02||3||Normal instrument||Normal instrument
|-
|0x03||4||Normal instrument||Normal instrument
|-
|0x04||5||Normal instrument||Normal instrument
|-
|0x05||6||Normal instrument||Normal instrument
|-
|0x06||7||Normal instrument||Normal instrument
|-
|0x07||8||Normal instrument||Normal instrument
|-
|0x08||9||Normal instrument||Normal instrument
|-
|0x09||10||Normal instrument||Normal instrument
|-
|0x0A||11||Normal instrument||Normal instrument
|-
|0x0B||12||Normal instrument||Bass drum
|-
|0x0C||13||Normal instrument||Snare drum
|-
|0x0D||14||Normal instrument||Tom-tom
|-
|0x0E||15||Normal instrument||Top cymbal
|-
|0x0F||16||Normal instrument||Hi-hat cymbal
|}

See [[#CMF/MIDI vs Adlib channels]] below for more details.

===== Controller 0x68: Transpose up =====
This controller transposes all following notes on the channel up by the given number of 1/128 semitones. Since the controller value must be between 0 and 127, it will allow a song to be transposed up anywhere between zero and almost a full semitone. The value is absolute, so a controller requesting a transpose up by 127 followed by a transpose up by 64, will initially be transposed up by almost a full semitone (127) but will then be transposed back by a half semitone (to 64).

A value of zero resets back to "not transposed."

===== Controller 0x69: Transpose down =====
Identical to controller 0x68 (Transpose up) only of course in the opposite direction, and again only affecting the channel the controller is issued on.

=== Notes ===

==== Keyon/off handling ====
Some songs don't always send keyoffs after a keyon, or they send them out of order (e.g. note 1 on, delay, note 2 on, note 1 off, delay, note 2 off.) If you don't check this you'll end up switching a note off too early (in the above example the "note 1 off" should *not* switch off "note 2" that was switched on just before it.) <tt>song_9.xr1</tt> from the first episode of Xargon is an excellent example of this, right at the start of the song.

The best way of handling this when playing through an OPL chip seems to be to remember the last note played on a channel, and upon receiving a keyoff, only process it if the keyoff is for the note currently playing on the channel (otherwise it can be discarded.) If a keyon is received and a note is already being played on a channel, the old note should be switched off just before playing the new note.

==== Keyon/off timing ====
Some songs play a note-on, then immediately (with no delay) have a corresponding note-off. If this is played faithfully, then the note will not be heard, however the Creative Labs player still plays these notes. The correct solution is {{TODO|currently unknown - wait for one tick or use the emulator callback between events?}}. A good example of this is the first few notes in <tt>song_32.xr1</tt>. ([https://github.com/adplug/adplug/issues/41 Discussion])

==== Default instruments ====
Although no documentation exists about this, it seems that the Creative Labs player sets the 128 available instruments based on 16 defaults looped/repeated to fill the 128 slots. They do not appear to be based on any MIDI instrument specification. Any instruments included in the CMF file then override these defaults. Some songs (e.g. the [[Word Rescue]] background music) rely on these default instruments and don't play properly if only their custom instruments are set.

There appear to be a different set of default instruments used for the percussion channels when rhythm mode is active. More investigation needs to be done to determine what these are and if they are related to the 16 default melody instruments.

{{TODO|Post a set of OPL settings here (perhaps in [[IBK Format]]) that provides these default parameters.}}

{{TODO|Confirm whether it's possible to set more than 16 custom instruments, without them looping and overwriting the earlier ones.}}

==== CMF/MIDI vs Adlib channels ====
MIDI (and consequently CMF) supports up to 16 channels. The OPL2 synth on the Adlib only supports a maximum of nine channels in normal mode, or six channels plus five percussion instruments in rhythm mode.

This means that any CMF player must correctly map up to 16 MIDI channels to only nine OPL channels. Many songs from games work correctly with a 1:1 mapping (i.e. the game music doesn't go beyond MIDI channel 9), however there are some songs that use channels beyond this (e.g. [[Word Rescue]] again, which, given the Voyetra credit, has probably been minimally converted from MIDI.)

At the time of writing, there are no known songs that use more than nine MIDI channels simultaneously, however [[Word Rescue]]'s E1L1 song appears to sound more than nine notes simultaneously across a smaller number of channels, so if all these notes should be heard, the extended OPL3 channels probably need to be used. [[Xargon]] <tt>song9</tt> also sounds multiple notes simultaneously in a single channel. Either of these will result in lost notes unless the available channels are cleverly managed.

As an aside, it would be interesting to test this with Creative's driver to see how it behaves.

==== Note velocity ====
The velocity values are loaded more or less directly into the OPL chip. This means unlike MIDI, the velocity is not a linear scale from 0 to 127, but logarithmic. A value of 1 is almost silent, and rapidly increase in volume so that values 2 and 3 are much louder. At the other end of the scale, 127 is full volume, but 126 and 125 are barely any quieter.

== Tools ==
* CMF2MID - convert CMF files into MIDI ([http://www.hitsquad.com/smm/programs/cmf2mid/ Link 1])
* [http://adplug.sourceforge.net AdPlug/AdPlay] - Plugins for various audio players (plus a command line player) that mostly supports CMF files
* [http://www.shikadi.net/utils/xmms.html Malvineous' Adlib plugin] - Plugin for XMMS and Audacious that plays most CMF files more accurately than AdPlug
* [[OPL3 Bank Editor]] - import instruments from CMF files to use them in banks

== Similar formats ==
* The CMF song data is stored in the same format as used by [[MID Format|MIDI files]]
* The [[SBI Format]] (SoundBlaster Instrument) is the same as used in the CMF instrument block, with a header on the front.
* The [[IBK Format]] (Instrument Bank) is a group of SBI instruments, similar to the whole CMF instrument block.

IMF Format

2017-07-23T19:17:56Z

Wohlstand: /* Tools */

{{Music Infobox
| Type = OPL
| Instruments = OPL
| NumChannels = 9 or 11
| NumTracks = 1
| Tags = Unofficial: Title, Composer, Remarks, Program name
| Games =
{{Game|Bio Menace}}
{{Game|Blake Stone}}
{{Game|Catacomb 3-D}}
{{Game|Commander Keen 4-6}}
{{Game|Corridor 7 Alien Invasion}}
{{Game|Cosmo's Cosmic Adventures}}
{{Game|Duke Nukem II}}
{{Game|Hocus Pocus}}
{{Game|Major Stryker}}
{{Game|Monster Bash}}
{{Game|Operation Body Count}}
{{Game|Realms of Chaos}}
{{Game|Wolfenstein 3-D}}
}}

The id Software Music Format (IMF) is a raw music format that stores the actual bytes sent to the Adlib's [[OPL2]] chip. For this reason it is a very simple format to process.

== File format ==

There are two versions of the IMF format: Type-0 format and Type-1 format. In a Type-0 file, the whole file is Adlib data that is played until the end of the file is reached. Type-1 files are actually ripped chunks from an [[AudioT Format]] file. No game ever actually used Type-1 IMFs that were not stored inside an AudioT file. The two initial bytes contain the size of the Adlib data (not including the two bytes themselves), so only this much data is played. This means it's possible to store arbitrary data in a Type-1 IMF file after the song data (see [[#Tag Data]] below.)

As a matter of luck, the first two data bytes in a Type-0 files are almost always 0x00 0x00, so this can be used to detect the file format version. If the first two bytes match the length of the file it is likely Type-1, but be aware that trailing data will mean this is not always true. Otherwise the only other way is to parse all the register/value pairs in the file and ensure the register is [[OPL chip#Register Map|within range]] (e.g. registers 0xA0 to 0xA9 are valid, but 0xAA to 0xAF should never be used.) Note that 0x00 is actually an invalid register, but must be treated as valid since the files usually begin by writing 0x00 to register 0x00.

Another way to detect the type of an IMF file is to examine the first few instructions in the IMF file. The idea is that the first few IMF commands set up the AdLib registers and therefore should have no delay. Even if there is a delay, it would normally be relatively low compared to the combined 16-bit value of the (register, value) pair.

<source lang="c">
UINT16 ReadInt16LE(FILE* in)
{
UINT8 buf[2];
fread(buf, 1, 2, in);
return (buf[0] | (buf[1] << 8));
}

int IMF_IsChunk(FILE* in)
{
UINT16 chunksize, buff, i=42;
UINT32 sum1=0, sum2=0;

if(!in)
return 0;

if (!feof(in))
{
chunksize = ReadInt16LE(in);
if ((chunksize == 0) || (chunksize & 3))
return 0;

while(!feof(in) && i)
{
buff = ReadInt16LE(in);
sum1 += buff;
buff = ReadInt16LE(in);
sum2 += buff;
i--;
}
fseek(in, 0, SEEK_SET);
return (sum1 > sum2);
}
return 0;
}
</source>

In the code given above, if the file is a chunk (Type-1), then <tt>sum1</tt> contains the sum of all (register, value) pairs and <tt>sum2</tt> contains the sum of all delays. If it's a plain IMF file (Type-0), the sums are swapped.

The only case in which this detection would fail is IMF data that writes a bunch of zeroes to register zero (which would be pointless since that register is undefined) and/or has very large delays (which would be pointless because it would lead to delays of up to a minute before the next IMF command would be processed, resulting in multiple minutes of silence before the song actually starts playing notes).

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[UINT16LE]]||iLength||Song data length in bytes (Type-1 format only)
|-
|[[BYTE]][iLength]||cAdlibData||Song data (see below) - <code>iLength</code> bytes long if Type-1, or until EOF if Type-0
|-
|[[BYTE]][]||cExtraData||Arbitrary data/tags (Type-1 format only, see [[#Tag Data]] below)
|}

The earliest version of the IMF data in the [[AudioT Format]] actually starts with a [[UINT32LE]] length value. The Commander Keen 4 Demo uses that early version. Just extracting the IMF chunk from the <tt>AUDIOT.CK4</tt> file will most likely confuse programs, since the file does not start with two 0's. Programs that only check the first two bytes will assume that the file is a ripped chunk, but will swap the delays and register/data pairs because of the length value being stored in the first four bytes instead of just the first two. That means the song will not play the intended notes. Programs that use the detection code given above will identify the file as plain IMF data and treat the length value as an IMF command. That means the song will play correctly at first, but any trailing data present in the file will also be interpreted as IMF data, most likely leading to long delays at the end of the song.

Note that for Type-1 files, the initial two bytes (the "song data length") are likely to be the filesize minus two, as the two initial bytes aren't counted. The obvious exception to this is if there is trailing data at the end of the OPL data, such as an info tag.

The song data is composed of four-byte "units":

{|class="wikitable"
!Data type!!Description
|-
|[[BYTE]]||Adlib register
|-
|[[BYTE]]||Adlib data
|-
|[[UINT16LE]]||Delay
|}

The data byte is sent to the specified register on the Adlib card, followed by a delay for the specified number of cycles. For a 560Hz IMF file, there are 560 cycles in one second (see [[#Timing]] below), so a delay of 560 would result in one second of silence (and likewise in a 700Hz IMF the delay value would need to be 700 to produce one second of silence.) A delay of 1 would wait for a single cycle, and a delay of zero means the next register/data pair should be sent immediately (so in a single 'cycle', data would be sent continuously until the next non-zero delay value is reached.)

=== Timing ===

IMF files exist at three known speeds. Unfortunately this is determined by the game, not the IMF file, so tempo cannot be determined from the music files alone. Extracted IMFs can be compared to discern their speeds. The known speeds are:

{|class="wikitable"
!Speed!!Game
|-
|280Hz||[[Duke Nukem II]]
|-
|560Hz||[[Bio Menace]], [[Commander Keen]], [[Cosmo's Cosmic Adventures]], [[Monster Bash]]
|-
|700Hz||[[Blake Stone]], [[Major Stryker]], [[Operation Body Count]], [[Wolfenstein 3-D]]
|}

The easiest method to tell the files apart is to treat all files with a .WLF extension as 700Hz and all .IMF files as 560Hz. Since Duke II is the odd one out, it is usually ignored since doubling the value of all the delay bytes conveniently turns it into a 560Hz .IMF.

=== Restrictions ===

As IMF files contain Adlib music for games that may also have Adlib sound effects, care must be taken to ensure that IMF music and any sound effects can share the OPL chip without conflict. This is done by reserving the OPL's first channel for sound effects, leaving eight remaining channels available for use in IMF files. This has been confirmed by automated inspection of the IMF files from the following games, all of which have no data on OPL channel #0 beyond 2-3 initialisation commands: [[Bio Menace]], [[Blake Stone]], [[Commander Keen 4-6]], [[Cosmo's Cosmic Adventures]], [[Duke Nukem II]], [[Major Stryker]], [[Monster Bash]], [[Operation Body Count]], [[Wolfenstein 3-D]].

In situations where channel #0 is not reserved and is used by the IMF file, when it is placed back into the game it interferes with the sound effects causing distortion, transposition, and otherwise resulting in broken sound effects. This can happen when an IMF file is created using a utility that does not take into account the fact that channel #0 must be left unused. See the end of this page for a list of utilities that can create IMF files and whether they treat channel #0 correctly.

It is worth noting that channel #0 is unused even in games such as Cosmo and Monster Bash, which do not use Adlib sound effects (Cosmo has PC speaker effects only and Monster Bash has PC speaker and digitised PCM audio.) It is also worth mentioning that some IMF songs from [[Monster Bash]] make use of the OPL's rhythm-mode, which trades three note-producing channels for five percussion channels. The IMF songs from the Keen 4 Demo also use rhythm-mode.

=== Tag Data ===

In a Type-1 IMF file it's possible to store data after the end of a song (as per the length given in the first two bytes of the file.) There are a few uses for this - some games store additional (unused) data there generated when the files were added to the game's group file, and others have repurposed this area to store information about the song itself (title, artist, etc.)

The tag data was originally written to the AudioT files by Id Software's tool [[Muse]] and was probably only processed by that tool. The [[Wolfenstein 3-D]] source code reads the entire chunk from the [[AudioT Format|AudioT]] file (including any tag data), but it only ever uses the song length and the song data.

==== Official data ====
For those files which were distributed with additional data in this area, it is not entirely clear what the purpose of this data is. It was apparently added when the source IMF files were compiled into a group audio file by [[Muse]]. (They appear not to be part of the source IMF files as there are occurrences where a file consists solely of tag data.) The format appears to be the same in all games that use it (such as Bio Menace or Wolfenstein 3-D) but it is not supported by any IMF players.

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[UINT16LE]]||Unknown||
|-
|[[char]][16]||strTitle||Song title
|-
|[[char]][64]||strRemarks||Song comment/message, usually source file name.
|-
|[[char]][6]||cProg||Data from the compiler?
|}

==== Unofficial uses ====
It is also possible to store tags there, and this simple format is supported by most IMF players:

{|class="wikitable"
!Data type!!Name!!Description
|-
|[[BYTE]]||cSignature||0x1A
|-
|[[char]][256]||strTitle||Song title
|-
|[[char]][256]||strComposer||Song composer
|-
|[[char]][256]||strRemarks||Song comment/message
|-
|[[char]][9]||cProg||Name of the first program that added these tags (eight bytes + terminating NULL, pad out with NULLs if necessary.)
|}

Note that the char[256] strings are variable-length NULL-terminated strings. Their maximum length is 256 bytes *including* the terminating NULL, meaning the string will only ever contain 255 characters or less, plus the terminating-NULL. Of course the string will normally be much shorter, and an empty string will consist of a single 0x00 byte.

This tag format is supported by AdPlug when playing IMFs. The tag format can also be used with .raw files, but no players officially support it yet.

Note that the tags should begin directly after the IMF data, so in other words reading in the first two bytes of the file (the "song length") and then seeking forward that many bytes, should put the file pointer at the start of the tag block (so the next byte that will be read in should be 0x1A, if the tags are present.)

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://adplug.sourceforge.net AdPlug]
| Platform = All
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[RAW Format (Adlib)|.raw]]
| canImport = No
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/cmf2imf CMF2IMF]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[CMF Format|.cmf]]
| editHidden = No
| editMetadata = No
| notes = Doesn't leave channel 0 clear for SFX
}}
{{FileFormatTool
| Name = [http://www.shikadi.net/utils/dro2imf DRO2IMF]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[DRO Format|.dro]]
| editHidden = No
| editMetadata = No
| notes = Doesn't leave channel 0 clear for SFX
}}
{{FileFormatTool
| Name = [[DRO2MIDI]]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; [[MID Format|.mid]]
| canImport = No
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = [http://winwolf3d.dugtrio17.com/download/IMFCreator IMFCreator]
| Platform = Windows
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[MID Format|.mid]]
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = MUS2IMF
| Platform = DOS?
| canPlay = No
| canCreate = No
| canModify = No
| canExport = No
| canImport = Yes; [[MUS Format|.mus]]
| editHidden = No
| editMetadata = No
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = No
| editHidden = No
| editMetadata = No
| notes = OPL3 Bank Editor can import FM instruments from IMF files
}}
{{EndFileFormatTools}}

OP2 Bank Format

2017-07-23T19:14:22Z

Wohlstand: Added OPL3 Bank Editor into tools

{{Instrument Infobox
| Type = OPL, MIDI
| Count = 175
| Names = Yes, 31 char
| Games =
{{Game|Chex Quest}}
{{Game|Chex Quest 2}}
{{Game|Doom}}
{{Game|Doom 2}}
{{Game|Heretic}}
{{Game|Hexen}}
{{Game|Raptor}}
{{Game|Strife}}
}}

The '''OP2 Bank Format''' is an instrument bank format used by the DMX sound library developed by Paul Radek of Digital Expressions, Inc. The 128 melodic and 47 percussion instrument limit was most likely chosen so that a single OP2 file could store all the instruments for a General MIDI song. This bank has support for two-voice instruments to provide support for pseudo four-operator instruments.

==File format==

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][8] || magic || <tt>#OPL_II#</tt> signature, doesn't null terminated
|-
| [[BYTE]][175][36] || instrument || Set of 175 instrument entry
|-
| [[char]][175][32] || names || Instrument names per every instrument entry, must be null terminated
|}

===Instrument===

Each bank contains 128 melodic and 47 percussion instruments.

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT16LE]] || flags || N/A || Instrument flags: 0x01 - fixed pitch, 0x02 - Unknown flag, 0x04 - Double-voice mode
|-
| [[UINT8]] || fineTune || N/A || Second voice detune level
|-
| [[UINT8]] || noteNum || N/A || Percussion note number (between 0 and 128)
|-
!colspan=4|First voice
|-
| [[UINT8]] || iModChar1 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack1 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain1 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel1 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale1 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel1 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback1 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar1 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack1 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain1 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel1 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale1 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel1 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved1 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset1 || N/A || MIDI note offset for a first voice
|-
!colspan=4|Second voice
|-
| [[UINT8]] || iModChar2 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack2 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain2 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel2 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale2 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel2 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback2 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar2 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack2 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain2 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel2 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale2 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel2 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved2 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset2 || N/A || MIDI note offset for a second voice
|}

===Instrument names===

=== Fine tune ===
Fine tune value is an index offset of frequencies table. 128 is a center, i.e. don't detune. Formula of index offset is: <tt>(fine_tune / 2) - 64</tt>. Each unit of fine tune field is approximately equal to 1/0.015625 of tone.

=== Percussion instruments ===
Percussion instruments are in range between 35 (Bass drum 1) and 81 (Open Triangle) MIDI indeces.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://www.vgmpf.com/Wiki/index.php/IMF_Creator IMF Creator]
| Platform = Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; .op2
| canImport = Yes; many
| editHidden = Yes; Unknown flag
| editMetadata = Yes
| notes = Utility by Adam Biser to create IMF music. Also includes OP2 bank editor.
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

Apogee Sound System Timbre Format

2017-07-23T19:13:01Z

Wohlstand: Added OPL3 Bank Editor into tools

{{Instrument Infobox
| Type = OPL, MIDI
| Count = 256
| Names = No
| Games =
{{Game|Duke Nukem 3D}}
{{Game|Blood}}
{{Game|Shadow Warrior}}
{{Game|NAM}}
}}

The '''Apogee Sound System Timbre Format''' is an instrument bank format used by the Apogee Sound System library developed by 3D Realms. The 128 melodic and 128 percussion instrument limit was most likely chosen so that a single TMB file could store all the instruments for a General MIDI song.

==File format==

TMB files have no header and signature. The file contains 256 13-byte instrument entries (first 128 are melodic, and next 128 are percussion).

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT8]] || SAVEK[0] || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || SAVEK[1] || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || Level[0] || 0x40 || Modulator key scaling/output level
|-
| [[UINT8]] || Level[1] || 0x43 || Carrier key scaling/output level
|-
| [[UINT8]] || Env1[0] || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || Env1[1] || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || Env2[0] || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || Env2[1] || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || Wave[0] || 0xE0 || Modulator wave select
|-
| [[UINT8]] || Wave[1] || 0xE3 || Carrier wave select
|-
| [[UINT8]] || Feedback || 0xC0 || Feedback/connection
|-
| [[INT8]] || Transpose || N/A || Note offset for melodic instruments, and key number for percussion
|-
| [[INT8]] || Velocity || N/A || Velocity offset
|}

The TMB format is directly based on [[IBK Format]], and has first 12 bytes be same as in the IBK Format. Official <tt>MAKETMB.EXE</tt> utility (Can be found with the source code of 3D Realms games in the Audio Library public folder) generates TMB files from the set of IBK files.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = <tt>MAKETMB.EXE</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = Yes; .tmb
| canImport = Yes; [[IBK Format|.ibk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''Apogee Sound System'' SDK
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

AdLib Instrument Format

2017-07-23T19:11:45Z

Wohlstand: Added OPL3 Bank Editor into tools

{{Instrument Infobox
| Type = OPL
| Count = 1
| Names = No
}}
The '''AdLib Instrument Format''' was the original format developed by Ad Lib, Inc. in 1987 to store OPL instruments in individual files with the <tt>.ins</tt> extension. It went through a number of revisions as hardware capabilities were added to the OPL chip, but ultimately it was replaced by the [[AdLib Instrument Bank Format]], which combined multiple instruments into a single file with a <tt>.bnk</tt> extension.

For a short time before the BNK format was introduced, there was an early bank format called [[AdLib Timbre Bank Format]] which used a <tt>.snd</tt> or <tt>.tim</tt> extension. Each instrument in this bank format is stored in a structure almost identical to the structure used in the individual <tt>.ins</tt> instrument files.

== File format ==

The file is in the following structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || unknown || {{TODO|Unknown purpose, always 0x0000}}
|-
| OPLREGS || oplModulator || Register values for the Modulator (0) operator
|-
| OPLREGS || oplCarrier || Register values for the Carrier (1) operator
|-
| UINT16LE || iModWaveSel || Modulator wave select (only bits 0-1 recognised, OPL register 0xE0)
|-
| UINT16LE || iCarWaveSel || Carrier wave select (only bits 0-1 recognised, OPL register 0xE0)
|-
| char[22] || unknown2 || {{TODO|Unknown purpose reserved space. Second to last byte usually always 0x01 or 0x00}}
|}

The last three fields (<tt>iModWaveSel</tt>, <tt>iCarWaveSel</tt>, <tt>unknown2</tt>) are not present in early 54-byte files in this format. Some files are also missing <tt>oplCarrier</tt> entirely - presumably these are patches for single-operator percussive instruments. Possibly <tt>unknown2</tt> is an instrument name, but the existing software doesn't use it and uses the base filename instead.

The ''OPLREGS'' structure is defined as:

{|class="wikitable"
! Data type !! Name !! Description !! OPL base register !! Value range
|-
| UINT16LE || iKSL || Key scaling level || 0x40 (bits 6-7) ||
|-
| UINT16LE || iMultiple || Frequency multiplier || 0x20 (bits 0-3) || iMultiple & 0x0F is sent to OPL register [verify this]
|-
| UINT16LE || iFeedback || Feedback || 0xC0 (bits 1-3) || Although only bits 1-3 are valid, Vinyl doesn't limit the output to three bits wide.
|-
| UINT16LE || iAttack || Attack rate || 0x60 (upper four bits) || [verify this]
|-
| UINT16LE || iSustain || Sustain level || 0x80 (upper four bits) || [verify this]
|-
| UINT16LE || iEG || Envelope gain (nonzero value is on) || 0x20 (bit 5) || [verify this]
|-
| UINT16LE || iDecay || Decay rate || 0x60 (lower four bits) || [verify this]
|-
| UINT16LE || iReleaseRate || Release rate || 0x80 (lower four bits) || [verify this]
|-
| UINT16LE || iTotalLevel || Total output level || 0x40 (bit 0-5) || [verify this]
|-
| UINT16LE || iAM || Amplitude modulation (Tremolo) || 0x20 (bit 7) || [verify this]
|-
| UINT16LE || iVIB || Frequency Vibrato || 0x20 (bit 6) || [verify this]
|-
| UINT16LE || iKSR || Key scaling/envelope rate || 0x20 (bit 4) || [verify this]
|-
| UINT16LE || iCONoff || Connector [OP0 only] || 0xC0 (bit 0, inverted) || 0: OPL bit set to 1 other: OPL bit set to 0
|}

=== Percussive instruments ===

There is apparently no distinction between percussive and melodic instruments. This is controlled at playback time, depending on which channel the instrument is loaded into.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>bankmng.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = Yes
| canExport = Yes; [[AdLib Instrument Bank Format|.bnk]]
| canImport = Yes; [[AdLib Instrument Bank Format|.bnk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''AdLib Programmer's Manual''
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

== Credits ==

This file format was documented by [[User:Malvineous|Malvineous]] from reading code included with the ''AdLib Programmer's Manual''. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

IBK Format

2017-07-23T19:10:44Z

Wohlstand: /* Tools */ Small fix

{{Instrument Infobox
| Type = OPL, MIDI
| Count = 128
| Names = Yes, 8 chars
| Games =
{{Game|Drum Blaster}}
}}
The '''IBK (Instrument Bank) Format''' was created to store up to 128 instruments suitable for playback on a sound card with an OPL2 or OPL3 chip. The 128 instrument limit was most likely chosen so that a single IBK file could store all the instruments for a General MIDI song.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "IBK" followed by 0x1A
|-
| [[BYTE]][16][128] || inst || 128 instrument settings, 16 bytes each (see below)
|-
| [[char]][9][128] || names || 128 instrument titles (each must be NULL-terminated, giving 8 visible chars max)
|}

=== Instruments ===

Each instrument is in the following format. This is identical to the format used for the instrument block in [[CMF Format]] files. Each individual instrument is the same as in the [[SBI Format]].

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iPercVoc||N/A||Percussion voice mode: 0 is melodic, 6 - bass drum, 7 - Snare, 8 - Tom-Tom, 9 - Cymbell, 10 - HiHat
|-
|[[INT8]]||iTranspos||N/A||Number of notes to transpose timbre, signed
|-
|[[INT8]]||iDPitch||N/A||Percussion pitch: MIDI Note 0 - 127
|-
|[[BYTE]][2]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

==== Percussive instruments ====

Percussive instruments are indicated by <tt>iPercvoc</tt> field. Percussive instruments are using rhythm mode of the OPL2/OPL3 chip.

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; [[IBK Format|.ibk]]
| canImport = Yes; [[AdLib Instrument Bank Format|.bnk]]
| editHidden = No
| editMetadata = Yes
| notes = Instrument editor using IBK as its primary format
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

IBK Format

2017-07-23T19:10:11Z

Wohlstand: Added OPL3 Bank Editor into tools

{{Instrument Infobox
| Type = OPL, MIDI
| Count = 128
| Names = Yes, 8 chars
| Games =
{{Game|Drum Blaster}}
}}
The '''IBK (Instrument Bank) Format''' was created to store up to 128 instruments suitable for playback on a sound card with an OPL2 or OPL3 chip. The 128 instrument limit was most likely chosen so that a single IBK file could store all the instruments for a General MIDI song.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "IBK" followed by 0x1A
|-
| [[BYTE]][16][128] || inst || 128 instrument settings, 16 bytes each (see below)
|-
| [[char]][9][128] || names || 128 instrument titles (each must be NULL-terminated, giving 8 visible chars max)
|}

=== Instruments ===

Each instrument is in the following format. This is identical to the format used for the instrument block in [[CMF Format]] files. Each individual instrument is the same as in the [[SBI Format]].

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iPercVoc||N/A||Percussion voice mode: 0 is melodic, 6 - bass drum, 7 - Snare, 8 - Tom-Tom, 9 - Cymbell, 10 - HiHat
|-
|[[INT8]]||iTranspos||N/A||Number of notes to transpose timbre, signed
|-
|[[INT8]]||iDPitch||N/A||Percussion pitch: MIDI Note 0 - 127
|-
|[[BYTE]][2]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

==== Percussive instruments ====

Percussive instruments are indicated by <tt>iPercvoc</tt> field. Percussive instruments are using rhythm mode of the OPL2/OPL3 chip.

== Tools ==
{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; [[IBK Format|.ibk]]
| canImport = Yes; [[AdLib Instrument Bank Format|.bnk]]
| editHidden = No
| editMetadata = No
| notes = Instrument editor using IBK as its primary format
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

AdLib Instrument Bank Format

2017-07-23T19:07:57Z

Wohlstand: Added OPL3 Bank Editor into tools

{{NeedMoreInfo}}
{{Instrument Infobox
| Type = OPL
| Count = 65535
| Names = Yes, 8 chars
| Games =
{{Game|SkyRoads}}
{{Game|Super Tetris}}
{{Game|Wordtris}}
{{Game|Witchaven}}
{{Game|Witchaven II}}
{{Game|Dark Legions}}
}}
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 [[AdLib Instrument Format|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 <tt>.bnk</tt> 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 [[:Category:id Software|id Software]] titles, the two files were converted into [[IMF Format]] during game development. Also this format used by [[Human Machine Interfaces MIDI Format|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:

{|class="wikitable"
! 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 <tt>numInstruments</tt> times:

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[UINT16LE]] || index || Index into data section Calculation: <tt>offsetInstr = offsetData + (index * sizeof(PackedTimbre))</tt>
|-
| [[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 <tt>offsetData</tt>. 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.

{|class="wikitable"
! 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:

{|class="wikitable"
! 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")==

{{TODO|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 ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>bankmng.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = Yes
| canExport = Yes; [[AdLib Instrument Format|.ins]]
| canImport = Yes; [[AdLib Instrument Format|.ins]]
| editHidden = No
| editMetadata = No
| notes = Part of ''AdLib Visual Composer'' and ''AdLib Programmer's Manual''
}}
{{FileFormatTool
| Name = [[SBTimbre]]
| Platform = DOS
| canPlay = Yes
| canCreate = No
| canModify = No
| canExport = Yes; [[IBK Format|.ibk]]
| canImport = No
| editHidden = No
| editMetadata = No
| notes =
}}
{{FileFormatTool
| Name = [[OPL3 Bank Editor]]
| Platform = Linux, Windows, macOS
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
| notes =
}}
{{EndFileFormatTools}}

OPL3 Bank Editor

2017-07-23T18:34:28Z

Wohlstand: Created page with "{{Tool Infobox | Platform = GNU/Linux, Windows, macOS | Release = 2016-06-09 | Homepage = [https://github.com/Wohlstand/OPL3BankEditor/blob/master/README.md OPL3 Bank Edito..."

{{Tool Infobox
| Platform = GNU/Linux, Windows, macOS
| Release = 2016-06-09
| Homepage = [https://github.com/Wohlstand/OPL3BankEditor/blob/master/README.md OPL3 Bank Editor]
| Download = [https://github.com/Wohlstand/OPL3BankEditor github.com]
| Edit1 = Music
}}

'''OPL3 Bank Editor''' is a free and open source utility to create and edit various music instrument bank formats, developed by [[User:Wohlstand|Wohlstand]]. Various bank formats are had no own bank editor (For example, [[TMB Format]] which is originally is generating by merging and chopping of two IBK files by official MAKETMB utility, or [[Junglevision Patch File Format]] which has proprietary bank editor that wasn't available in public), or had them be inconvenient. This bank editor allows working with all those formats by having same and friendly UI.

== Features ==
* Support for 2-operator, pseudo-4-operator, and 4-operator instruments and banks
* Instrument testing through Nuked OPL3 emulator
* Playing single note and various chords
* Mouse-clickable piano claves to test various notes
* Keyboard can be used to test instrument like on piano
* "Shut-up" button which allows to quickly mute all chip's channels
* Tool-tips are describing purposes of every field
* Import/Export of single instrument files
* Instrument import from music files such as from [[IMF Format|IMF]] and [[CMF Format|CMF]]
* Ability to toggle global Deep Tremolo and Deep Vibrato flags
* Support for both melodic and rhythm mode percussions

== Links ==
* [http://www.vogons.org/viewtopic.php?f=9&t=48513 Support thread on VOGONS forum]

File:OPL3 Bank Editor.png

2017-07-23T14:02:42Z

Wohlstand:

OP2 Bank Format

2017-07-23T13:48:09Z

Wohlstand: Created page with "{{Instrument Infobox | Type = OPL, MIDI | Count = 175 | Names = Yes, 31 char | Games = {{Game|Chex Quest}} {{Game|Chex Quest 2}} {{Game|Doom}} {{Game|Doom 2}}..."

{{Instrument Infobox
| Type = OPL, MIDI
| Count = 175
| Names = Yes, 31 char
| Games =
{{Game|Chex Quest}}
{{Game|Chex Quest 2}}
{{Game|Doom}}
{{Game|Doom 2}}
{{Game|Heretic}}
{{Game|Hexen}}
{{Game|Raptor}}
{{Game|Strife}}
}}

The '''OP2 Bank Format''' is an instrument bank format used by the DMX sound library developed by Paul Radek of Digital Expressions, Inc. The 128 melodic and 47 percussion instrument limit was most likely chosen so that a single OP2 file could store all the instruments for a General MIDI song. This bank has support for two-voice instruments to provide support for pseudo four-operator instruments.

==File format==

{|class="wikitable"
! Data type !! Name !! Description
|-
| [[char]][8] || magic || <tt>#OPL_II#</tt> signature, doesn't null terminated
|-
| [[BYTE]][175][36] || instrument || Set of 175 instrument entry
|-
| [[char]][175][32] || names || Instrument names per every instrument entry, must be null terminated
|}

===Instrument===

Each bank contains 128 melodic and 47 percussion instruments.

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT16LE]] || flags || N/A || Instrument flags: 0x01 - fixed pitch, 0x02 - Unknown flag, 0x04 - Double-voice mode
|-
| [[UINT8]] || fineTune || N/A || Second voice detune level
|-
| [[UINT8]] || noteNum || N/A || Percussion note number (between 0 and 128)
|-
!colspan=4|First voice
|-
| [[UINT8]] || iModChar1 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack1 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain1 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel1 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale1 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel1 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback1 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar1 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack1 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain1 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel1 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale1 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel1 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved1 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset1 || N/A || MIDI note offset for a first voice
|-
!colspan=4|Second voice
|-
| [[UINT8]] || iModChar2 || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iModAttack2 || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || iModSustain2 || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || iModWaveSel2 || 0xE0 || Modulator wave select
|-
| [[UINT8]] || iModScale2 || 0x40 || Modulator key scaling (first two bits)
|-
| [[UINT8]] || iModLevel2 || 0x40 || Modulator output level (last six bits)
|-
| [[UINT8]] || iFeedback2 || 0xC0 || Feedback/connection
|-
| [[UINT8]] || iCarChar2 || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || iCarAttack2 || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || iCarSustain2 || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || iCarWaveSel2 || 0xE3 || Carrier wave select
|-
| [[UINT8]] || iCarScale2 || 0x43 || Carrier key scaling (first two bits)
|-
| [[UINT8]] || iCarLevel2 || 0x43 || Carrier output level (last six bits)
|-
| [[UINT8]] || reserved2 || N/A || Unused byte
|-
| [[INT16LE]] || noteOffset2 || N/A || MIDI note offset for a second voice
|}

===Instrument names===

=== Fine tune ===
Fine tune value is an index offset of frequencies table. 128 is a center, i.e. don't detune. Formula of index offset is: <tt>(fine_tune / 2) - 64</tt>. Each unit of fine tune field is approximately equal to 1/0.015625 of tone.

=== Percussion instruments ===
Percussion instruments are in range between 35 (Bass drum 1) and 81 (Open Triangle) MIDI indeces.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = [http://www.vgmpf.com/Wiki/index.php/IMF_Creator IMF Creator]
| Platform = Windows
| canPlay = Yes
| canCreate = Yes
| canModify = Yes
| canExport = Yes; .op2
| canImport = Yes; many
| editHidden = Yes
| editMetadata = Yes
| notes = Utility by Adam Biser to create IMF music. Also includes OP2 bank editor.
}}
{{EndFileFormatTools}}

AdLib Instrument Format

2017-07-23T12:19:53Z

Wohlstand: /* File format */

{{Instrument Infobox
| Type = OPL
| Count = 1
| Names = No
}}
The '''AdLib Instrument Format''' was the original format developed by Ad Lib, Inc. in 1987 to store OPL instruments in individual files with the <tt>.ins</tt> extension. It went through a number of revisions as hardware capabilities were added to the OPL chip, but ultimately it was replaced by the [[AdLib Instrument Bank Format]], which combined multiple instruments into a single file with a <tt>.bnk</tt> extension.

For a short time before the BNK format was introduced, there was an early bank format called [[AdLib Timbre Bank Format]] which used a <tt>.snd</tt> or <tt>.tim</tt> extension. Each instrument in this bank format is stored in a structure almost identical to the structure used in the individual <tt>.ins</tt> instrument files.

== File format ==

The file is in the following structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || unknown || {{TODO|Unknown purpose, always 0x0000}}
|-
| OPLREGS || oplModulator || Register values for the Modulator (0) operator
|-
| OPLREGS || oplCarrier || Register values for the Carrier (1) operator
|-
| UINT16LE || iModWaveSel || Modulator wave select (only bits 0-1 recognised, OPL register 0xE0)
|-
| UINT16LE || iCarWaveSel || Carrier wave select (only bits 0-1 recognised, OPL register 0xE0)
|-
| char[22] || unknown2 || {{TODO|Unknown purpose reserved space. Second to last byte usually always 0x01 or 0x00}}
|}

The last three fields (<tt>iModWaveSel</tt>, <tt>iCarWaveSel</tt>, <tt>unknown2</tt>) are not present in early 54-byte files in this format. Some files are also missing <tt>oplCarrier</tt> entirely - presumably these are patches for single-operator percussive instruments. Possibly <tt>unknown2</tt> is an instrument name, but the existing software doesn't use it and uses the base filename instead.

The ''OPLREGS'' structure is defined as:

{|class="wikitable"
! Data type !! Name !! Description !! OPL base register !! Value range
|-
| UINT16LE || iKSL || Key scaling level || 0x40 (bits 6-7) ||
|-
| UINT16LE || iMultiple || Frequency multiplier || 0x20 (bits 0-3) || iMultiple & 0x0F is sent to OPL register [verify this]
|-
| UINT16LE || iFeedback || Feedback || 0xC0 (bits 1-3) || Although only bits 1-3 are valid, Vinyl doesn't limit the output to three bits wide.
|-
| UINT16LE || iAttack || Attack rate || 0x60 (upper four bits) || [verify this]
|-
| UINT16LE || iSustain || Sustain level || 0x80 (upper four bits) || [verify this]
|-
| UINT16LE || iEG || Envelope gain (nonzero value is on) || 0x20 (bit 5) || [verify this]
|-
| UINT16LE || iDecay || Decay rate || 0x60 (lower four bits) || [verify this]
|-
| UINT16LE || iReleaseRate || Release rate || 0x80 (lower four bits) || [verify this]
|-
| UINT16LE || iTotalLevel || Total output level || 0x40 (bit 0-5) || [verify this]
|-
| UINT16LE || iAM || Amplitude modulation (Tremolo) || 0x20 (bit 7) || [verify this]
|-
| UINT16LE || iVIB || Frequency Vibrato || 0x20 (bit 6) || [verify this]
|-
| UINT16LE || iKSR || Key scaling/envelope rate || 0x20 (bit 4) || [verify this]
|-
| UINT16LE || iCONoff || Connector [OP0 only] || 0xC0 (bit 0, inverted) || 0: OPL bit set to 1 other: OPL bit set to 0
|}

=== Percussive instruments ===

There is apparently no distinction between percussive and melodic instruments. This is controlled at playback time, depending on which channel the instrument is loaded into.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>bankmng.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = Yes
| canExport = Yes; [[AdLib Instrument Bank Format|.bnk]]
| canImport = Yes; [[AdLib Instrument Bank Format|.bnk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''AdLib Programmer's Manual''
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
}}
{{EndFileFormatTools}}

== Credits ==

This file format was documented by [[User:Malvineous|Malvineous]] from reading code included with the ''AdLib Programmer's Manual''. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)

IBK Format

2017-07-23T12:16:33Z

Wohlstand: Fix the infobox

{{Instrument Infobox
| Type = OPL, MIDI
| Count = 128
| Names = Yes, 8 chars
| Games =
{{Game|Drum Blaster}}
}}
The '''IBK (Instrument Bank) Format''' was created to store up to 128 instruments suitable for playback on a sound card with an OPL2 or OPL3 chip. The 128 instrument limit was most likely chosen so that a single IBK file could store all the instruments for a General MIDI song.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "IBK" followed by 0x1A
|-
| [[BYTE]][16][128] || inst || 128 instrument settings, 16 bytes each (see below)
|-
| [[char]][9][128] || names || 128 instrument titles (each must be NULL-terminated, giving 8 visible chars max)
|}

=== Instruments ===

Each instrument is in the following format. This is identical to the format used for the instrument block in [[CMF Format]] files. Each individual instrument is the same as in the [[SBI Format]].

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iPercVoc||N/A||Percussion voice mode: 0 is melodic, 6 - bass drum, 7 - Snare, 8 - Tom-Tom, 9 - Cymbell, 10 - HiHat
|-
|[[INT8]]||iTranspos||N/A||Number of notes to transpose timbre, signed
|-
|[[INT8]]||iDPitch||N/A||Percussion pitch: MIDI Note 0 - 127
|-
|[[BYTE]][2]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

==== Percussive instruments ====

Percussive instruments are indicated by <tt>iPercvoc</tt> field. Percussive instruments are using rhythm mode of the OPL2/OPL3 chip.

== Tools ==
* [[SBTimbre]] - instrument editor using IBK as its primary format

Apogee Sound System Timbre Format

2017-07-23T12:14:26Z

Wohlstand:

Apogee Sound System Timbre Format

2017-07-23T12:12:22Z

Wohlstand: /* Tools */ Small fix

{{NeedMoreInfo}}
{{Instrument Infobox
| Type = OPL, MIDI
| Count = 256
| Names = No
| Games =
{{Game|Duke Nukem 3D}}
{{Game|Blood}}
{{Game|Shadow Warrior}}
{{Game|NAM}}
}}

The '''Apogee Sound System Timbre Format''' is an instrument bank format used by the Apogee Sound System library developed by 3D Realms. The 128 melodic and 128 percussion instrument limit was most likely chosen so that a single TMB file could store all the instruments for a General MIDI song.

==File format==

TMB files have no header and signature. The file contains 256 13-byte instrument entries (first 128 are melodic, and next 128 are percussion).

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT8]] || SAVEK[0] || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || SAVEK[1] || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || Level[0] || 0x40 || Modulator key scaling/output level
|-
| [[UINT8]] || Level[1] || 0x43 || Carrier key scaling/output level
|-
| [[UINT8]] || Env1[0] || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || Env1[1] || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || Env2[0] || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || Env2[1] || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || Wave[0] || 0xE0 || Modulator wave select
|-
| [[UINT8]] || Wave[1] || 0xE3 || Carrier wave select
|-
| [[UINT8]] || Feedback || 0xC0 || Feedback/connection
|-
| [[INT8]] || Transpose || N/A || Note offset for melodic instruments, and key number for percussion
|-
| [[INT8]] || Velocity || N/A || Velocity offset
|}

The TMB format is directly based on [[IBK Format]], and has first 12 bytes be same as in the IBK Format. Official <tt>MAKETMB.EXE</tt> utility (Can be found with the source code of 3D Realms games in the Audio Library public folder) generates TMB files from the set of IBK files.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = <tt>MAKETMB.EXE</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = Yes; .tmb
| canImport = Yes; [[IBK Format|.ibk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''Apogee Sound System'' SDK
}}
{{EndFileFormatTools}}

Shadow Warrior

2017-07-23T12:10:23Z

Wohlstand: Add missing TMB format

{{Game Infobox
| Levels = Edit
| Tiles = Edit
| Sprites = Edit
| Fullscreen = Edit
| Sound = Edit
| Music = Edit
| Text = Edit
| Story = Edit
| Interface = No
}}

'''Shadow Warrior''' is an oriental-themed first-person shooter using the [[:Category:Build engine|Build engine]]. It is one of the final games to use this engine, and compared with the earlier [[Duke Nukem 3D]], has many improvements including 3D sprites, sector-over-sector, drivable vehicles and dozens of new interactive effects. It also uses an updated version of the Build map editor, which can now modify many additional properties of map elements, beyond simply the lotag and hitag. Many of these additional values are used for advanced interactive effects, such as deformable walls, used to design cars that crumple when hit by explosions.

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [[Build]]
| Platform = DOS
| grp = No
| map = Edit
| gfx = View
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Windows
| grp = Edit
| map = No
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = EditART
| Platform = DOS
| grp = No
| map = No
| gfx = Yes
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = Kextract/Kgroup
| Platform = DOS
| grp = Edit
| map = No
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

== Links ==

* [http://dukenukem.wikia.com/wiki/Shadow_Warrior Shadow Warrior on the Duke Nukem wiki]

{{BeginGameFileList}}
{{GameFile
| Name = *.anm
| Format = [[ANM Format (Duke Nukem 3D)]]
| KnownFormat = Yes
| Desc = Intro and story cutscenes
}}
{{GameFile
| Name = *.art
| Format = [[ART Format (Build)]]
| KnownFormat = Yes
| Desc = Level textures
}}
{{GameFile
| Name = *.bin
| Format = [[B800 Text]]
| KnownFormat = Yes
| Desc = Exit text screens
}}
{{GameFile
| Name = *.dmo
| Format = [[DMO Format (Build)]]
| KnownFormat = No
| Desc = Demo macros
}}
{{GameFile
| Name = *.grp
| Format = [[GRP Format]]
| KnownFormat = Yes
| Desc = Archive storing most of the game's data files
}}
{{GameFile
| Name = *.kvx
| Format = [[KVX Format (Build)]]
| KnownFormat = Yes
| Desc = Voxel (3D) sprites
}}
{{GameFile
| Name = *.map
| Format = [[MAP Format (Build)]]
| KnownFormat = Yes
| Desc = Game levels
}}
{{GameFile
| Name = *.mid
| Format = [[MID Format]]
| KnownFormat = Yes
| Desc = Background music
}}
{{GameFile
| Name = *.rts
| Format = [[RTS Format]]
| KnownFormat = Yes
| Desc = ''RemoteRidicule'' multiplayer audio taunts
}}
{{GameFile
| Name = gmtimbre.tmb
| Format = [[TMB Format]]
| KnownFormat = Yes
| Desc = FM patches for MIDI music (Shareware version only)
}}
{{GameFile
| Name = *.voc
| Format = [[VOC Format]]
| KnownFormat = Yes
| Desc = Sound effects
}}
{{EndGameFileList}}

[[Category:3DRealms]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Build engine]]

Duke Nukem 3D

2017-07-23T12:09:19Z

Wohlstand: Add missing TMB format

{{Stub}}

{{Game Infobox
| Levels = Edit
| Tiles = Edit
| Sprites = Edit
| Fullscreen = Edit
| Sound = Edit
| Music = Edit
| Text = Edit
| Story = Edit
| Interface = No
}}

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [[Build]]
| Platform = DOS
| grp = No
| map = Edit
| gfx = View
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Windows
| grp = Edit
| map = No
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = EditART
| Platform = DOS
| grp = No
| map = No
| gfx = Yes
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [https://gist.github.com/jasonsperske/31324a0cdffd8edf9683 GRPParser.py]
| Platform = Python
| grp = Read
| map = Convert to .svg
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = Kextract/Kgroup
| Platform = DOS
| grp = Edit
| map = No
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

== Links ==

* [http://dukenukem.wikia.com/wiki/Portal:Duke_Nukem_3D Duke Nukem 3D portal] on the Duke Nukem wiki

{{BeginGameFileList}}
{{GameFile
| Name = *.anm
| Format = [[ANM Format (Duke Nukem 3D)]]
| KnownFormat = Yes
| Desc = Intro and story cutscenes
}}
{{GameFile
| Name = *.art
| Format = [[ART Format (Build)]]
| KnownFormat = Yes
| Desc = Level textures
}}
{{GameFile
| Name = *.bin
| Format = [[B800 Text]]
| KnownFormat = Yes
| Desc = Exit text screens
}}
{{GameFile
| Name = *.con
| Format = ASCII text in [[CON Format]]
| KnownFormat = Yes
| Desc = Game parameters and scripting
}}
{{GameFile
| Name = *.dmo
| Format = [[DMO Format (Build)]]
| KnownFormat = No
| Desc = Demo macros
}}
{{GameFile
| Name = *.grp
| Format = [[GRP Format]]
| KnownFormat = Yes
| Desc = Archive storing most of the game's data files
}}
{{GameFile
| Name = *.map
| Format = [[MAP Format (Build)]]
| KnownFormat = Yes
| Desc = Game levels
}}
{{GameFile
| Name = *.mid
| Format = [[MID Format]]
| KnownFormat = Yes
| Desc = Background music
}}
{{GameFile
| Name = *.rts
| Format = [[RTS Format]]
| KnownFormat = Yes
| Desc = ''RemoteRidicule'' multiplayer audio taunts
}}
{{GameFile
| Name = gmtimbre.tmb
| Format = [[TMB Format]]
| KnownFormat = Yes
| Desc = FM patches for MIDI music
}}
{{GameFile
| Name = *.voc
| Format = [[VOC Format]]
| KnownFormat = Yes
| Desc = Sound effects
}}
{{EndGameFileList}}

== Modding tips ==
* The game directory is searched for files before looking inside DUKE3D.GRP. This means when you replace a file you don't need to copy it inside DUKE3D.GRP to test it.
* The game has a command-line option to load custom .GRP files. This means you can package your mod into a single GRP file and distribute it easily. Any game files not in your .GRP file will be loaded from the main DUKE3D.GRP.

[[Category:3DRealms]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Build engine]]

Blood

2017-07-23T12:08:11Z

Wohlstand: Mark TMB as known format

{{Game Infobox
| Levels = Edit
| Tiles = Edit
| Sprites = Edit
| Fullscreen = Edit
| Sound = Edit
| Music = Edit
| Text = Edit
| Story = Edit
| Interface = No
}}

'''Blood''' is a first-person shooter using the [[:Category:Build engine|Build engine]]. It uses a later version of the engine than that used for [[Duke Nukem 3D]], and includes new features such as 3D sprites and sector-over-sector. These new features are somewhat early in development however, and lack the refinement later found in [[Shadow Warrior]]. This can be seen by the somewhat jerky transition between sector-over-sector rooms, with similar transitions being seamless in Shadow Warrior.

== Tools ==

{{BeginFileFormatTools|Type=game}}
{{FileFormatTool
| Name = [[Build]]
| Platform = DOS
| grp = No
| map = Edit
| gfx = View
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Windows
| grp = Edit
| map = No
| gfx = No
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{FileFormatTool
| Name = EditART
| Platform = DOS
| grp = No
| map = No
| gfx = Yes
| mus = No
| sfx = No
| txt = No
| sav = No
| exe = No
}}
{{EndFileFormatTools}}

== Links ==

* [http://www.blood-wiki.org/index.php/Main_Page Blood wiki]

{{BeginGameFileList}}
{{GameFile
| Name = *.art
| Format = [[ART Format (Build)]]
| KnownFormat = Yes
| Desc = Level textures
}}
{{GameFile
| Name = *.dmo
| Format = [[DMO Format (Build)]]
| KnownFormat = No
| Desc = Demo macros
}}
{{GameFile
| Name = *.kvx
| Format = [[KVX Format (Build)]]
| KnownFormat = Yes
| Desc = Voxel (3D) sprites
}}
{{GameFile
| Name = *.map
| Format = [[MAP Format (Build)]]
| KnownFormat = Yes
| Desc = Game levels
}}
{{GameFile
| Name = *.mid
| Format = [[MID Format]]
| KnownFormat = Yes
| Desc = Background music
}}
{{GameFile
| Name = *.qav
| Format = [[QAV Format (Blood)]]
| KnownFormat = No
| Desc = Some kind of animation scripts
}}
{{GameFile
| Name = *.qfn
| Format = [[QFN Format (Blood)]]
| KnownFormat = Yes
| Desc = Fonts
}}
{{GameFile
| Name = *.rff
| Format = [[RFF Format]]
| KnownFormat = Yes
| Desc = Archive storing most of the game's data files
}}
{{GameFile
| Name = *.seq
| Format = [[SEQ Format (Blood)]]
| KnownFormat = No
| Desc = ?
}}
{{GameFile
| Name = *.smk
| Format = [[SMK Format]]
| KnownFormat = Yes
| Desc = Cutscenes/intro movies
}}
{{GameFile
| Name = gmtimbre.tmb
| Format = [[TMB Format]]
| KnownFormat = Yes
| Desc = FM patches for MIDI music
}}
{{GameFile
| Name = *.wav
| Format = [[WAV Format]]
| KnownFormat = Yes
| Desc = Intro sounds
}}
{{EndGameFileList}}

[[Category:Monolith]]
[[Category:3D]]
[[Category:First-Person Shooter]]
[[Category:Build engine]]

Apogee Sound System Timbre Format

2017-07-23T12:07:23Z

Wohlstand: Created page with "{{NeedMoreInfo}} {{Instrument Infobox | Type = OPL, MIDI | Count = 256 | Names = No | Games = {{Game|Duke Nukem 3D}} {{Game|Blood}} {{Game|Shadow Warrior}} {{..."

{{NeedMoreInfo}}
{{Instrument Infobox
| Type = OPL, MIDI
| Count = 256
| Names = No
| Games =
{{Game|Duke Nukem 3D}}
{{Game|Blood}}
{{Game|Shadow Warrior}}
{{Game|NAM}}
}}

The '''Apogee Sound System Timbre Format''' is an instrument bank format used by the Apogee Sound System library developed by 3D Realms. The 128 melodic and 128 percussion instrument limit was most likely chosen so that a single TMB file could store all the instruments for a General MIDI song.

==File format==

TMB files have no header and signature. The file contains 256 13-byte instrument entries (first 128 are melodic, and next 128 are percussion).

{|class="wikitable"
! Data type !! Name !! OPL base register !! Description
|-
| [[UINT8]] || SAVEK[0] || 0x20 || Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || SAVEK[1] || 0x23 || Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
| [[UINT8]] || Level[0] || 0x40 || Modulator key scaling/output level
|-
| [[UINT8]] || Level[1] || 0x43 || Carrier key scaling/output level
|-
| [[UINT8]] || Env1[0] || 0x60 || Modulator attack/decay level
|-
| [[UINT8]] || Env1[1] || 0x63 || Carrier attack/decay level
|-
| [[UINT8]] || Env2[0] || 0x80 || Modulator sustain/release level
|-
| [[UINT8]] || Env2[1] || 0x83 || Carrier sustain/release level
|-
| [[UINT8]] || Wave[0] || 0xE0 || Modulator wave select
|-
| [[UINT8]] || Wave[1] || 0xE3 || Carrier wave select
|-
| [[UINT8]] || Feedback || 0xC0 || Feedback/connection
|-
| [[INT8]] || Transpose || N/A || Note offset for melodic instruments, and key number for percussion
|-
| [[INT8]] || Velocity || N/A || Velocity offset
|}

The TMB format is directly based on [[IBK Format]], and has first 12 bytes be same as in the IBK Format. Official <tt>MAKETMB.EXE</tt> utility (Can be found with the source code of 3D Realms games in the Audio Library public folder) generates TMB files from the set of IBK files.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = <tt>MAKETIM.EXE</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = No
| canExport = Yes; .tmb
| canImport = Yes; [[IBK Format|.ibk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''Apogee Sound System'' SDK
}}
{{EndFileFormatTools}}

IBK Format

2017-07-23T11:52:49Z

Wohlstand: /* Instruments */ Tiny fix

{{Music Infobox
| Type = Instrument-only
| Instruments = OPL
| NumChannels = 9
| NumTracks = 0
| Tags = None
| Games =
{{Game|Drum Blaster}}
}}
The '''IBK (Instrument Bank) Format''' was created to store up to 128 instruments suitable for playback on a sound card with an OPL2 or OPL3 chip. The 128 instrument limit was most likely chosen so that a single IBK file could store all the instruments for a General MIDI song.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "IBK" followed by 0x1A
|-
| [[BYTE]][16][128] || inst || 128 instrument settings, 16 bytes each (see below)
|-
| [[char]][9][128] || names || 128 instrument titles (each must be NULL-terminated, giving 8 visible chars max)
|}

=== Instruments ===

Each instrument is in the following format. This is identical to the format used for the instrument block in [[CMF Format]] files. Each individual instrument is the same as in the [[SBI Format]].

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iPercVoc||N/A||Percussion voice mode: 0 is melodic, 6 - bass drum, 7 - Snare, 8 - Tom-Tom, 9 - Cymbell, 10 - HiHat
|-
|[[INT8]]||iTranspos||N/A||Number of notes to transpose timbre, signed
|-
|[[INT8]]||iDPitch||N/A||Percussion pitch: MIDI Note 0 - 127
|-
|[[BYTE]][2]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

==== Percussive instruments ====

Percussive instruments are indicated by <tt>iPercvoc</tt> field. Percussive instruments are using rhythm mode of the OPL2/OPL3 chip.

== Tools ==
* [[SBTimbre]] - instrument editor using IBK as its primary format

IBK Format

2017-07-23T11:52:05Z

Wohlstand: /* Instruments */ Fixed IBK specification, now it is more complete

{{Music Infobox
| Type = Instrument-only
| Instruments = OPL
| NumChannels = 9
| NumTracks = 0
| Tags = None
| Games =
{{Game|Drum Blaster}}
}}
The '''IBK (Instrument Bank) Format''' was created to store up to 128 instruments suitable for playback on a sound card with an OPL2 or OPL3 chip. The 128 instrument limit was most likely chosen so that a single IBK file could store all the instruments for a General MIDI song.

== File format ==

The file is structured as follows:

{|class="wikitable"
! Data type !! Name!! Description
|-
| [[char]][4] || signature || "IBK" followed by 0x1A
|-
| [[BYTE]][16][128] || inst || 128 instrument settings, 16 bytes each (see below)
|-
| [[char]][9][128] || names || 128 instrument titles (each must be NULL-terminated, giving 8 visible chars max)
|}

=== Instruments ===

Each instrument is in the following format. This is identical to the format used for the instrument block in [[CMF Format]] files. Each individual instrument is the same as in the [[SBI Format]].

{|class="wikitable"
!Data type!!Name!!OPL base register!!Description
|-
|[[UINT8]]||iModChar||0x20||Modulator characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iCarChar||0x23||Carrier characteristic (Mult, KSR, EG, VIB and AM flags)
|-
|[[UINT8]]||iModScale||0x40||Modulator key scaling/output level
|-
|[[UINT8]]||iCarScale||0x43||Carrier key scaling/output level
|-
|[[UINT8]]||iModAttack||0x60||Modulator attack/decay level
|-
|[[UINT8]]||iCarAttack||0x63||Carrier attack/decay level
|-
|[[UINT8]]||iModSustain||0x80||Modulator sustain/release level
|-
|[[UINT8]]||iCarSustain||0x83||Carrier sustain/release level
|-
|[[UINT8]]||iModWaveSel||0xE0||Modulator wave select
|-
|[[UINT8]]||iCarWaveSel||0xE3||Carrier wave select
|-
|[[UINT8]]||iFeedback||0xC0||Feedback/connection
|-
|[[UINT8]]||iPercvoc||N/A||Percussion voice mode: 0 is melodic, 6 - bass drum, 7 - Snare, 8 - Tom-Tom, 9 - Cymbell, 10 - HiHat
|-
|[[INT8]]||transpos||N/A||Number of notes to transpose timbre, signed
|-
|[[INT8]]||dpitch||N/A||Percussion pitch: MIDI Note 0 - 127
|-
|[[BYTE]][2]
|colspan=3|Padding to bring instrument definition up to 16 bytes
|}

==== Percussive instruments ====

Percussive instruments are indicated by <tt>iPercvoc</tt> field. Percussive instruments are using rhythm mode of the OPL2/OPL3 chip.

== Tools ==
* [[SBTimbre]] - instrument editor using IBK as its primary format

TMB Format

2017-07-23T10:48:42Z

Wohlstand: Redirected page to Apogee Sound System Timbre Format

#REDIRECT [[Apogee Sound System Timbre Format]]

AdLib Instrument Format

2017-07-23T10:40:01Z

Wohlstand: Fixed incorrectness in the specification, researched by me from SBANK utility and old INS files are came with AdLib SDK

{{Instrument Infobox
| Type = OPL
| Count = 1
| Names = No
}}
The '''AdLib Instrument Format''' was the original format developed by Ad Lib, Inc. in 1987 to store OPL instruments in individual files with the <tt>.ins</tt> extension. It went through a number of revisions as hardware capabilities were added to the OPL chip, but ultimately it was replaced by the [[AdLib Instrument Bank Format]], which combined multiple instruments into a single file with a <tt>.bnk</tt> extension.

For a short time before the BNK format was introduced, there was an early bank format called [[AdLib Timbre Bank Format]] which used a <tt>.snd</tt> or <tt>.tim</tt> extension. Each instrument in this bank format is stored in a structure almost identical to the structure used in the individual <tt>.ins</tt> instrument files.

== File format ==

The file is in the following structure:

{|class="wikitable"
! Data type !! Name !! Description
|-
| UINT16LE || unknown || {{TODO|Unknown purpose, always 0x0000}}
|-
| OPLREGS || oplModulator || Register values for the Modulator (0) operator
|-
| OPLREGS || oplCarrier || Register values for the Carrier (1) operator
|-
| UINT16LE || iModWaveSel || Modulator wave select (only bits 0-1 recognised, OPL register 0xE0)
|-
| UINT16LE || iCarWaveSel || Carrier wave select (only bits 0-1 recognised, OPL register 0xE0)
|-
| char[22] || unknown2 || {{TODO|Unknown purpose reserved space. Second to last byte usually always 0x01 or 0x00}}
|}

The last four fields (<tt>iModWaveSel</tt>, <tt>iCarWaveSel</tt>, <tt>unknown2</tt>) are not present in early 54-byte files in this format. Some files are also missing <tt>oplCarrier</tt> entirely - presumably these are patches for single-operator percussive instruments. Possibly <tt>unknown2</tt> is an instrument name, but the existing software doesn't use it and uses the base filename instead.

The ''OPLREGS'' structure is defined as:

{|class="wikitable"
! Data type !! Name !! Description !! OPL base register !! Value range
|-
| UINT16LE || iKSL || Key scaling level || 0x40 (bits 6-7) ||
|-
| UINT16LE || iMultiple || Frequency multiplier || 0x20 (bits 0-3) || iMultiple & 0x0F is sent to OPL register [verify this]
|-
| UINT16LE || iFeedback || Feedback || 0xC0 (bits 1-3) || Although only bits 1-3 are valid, Vinyl doesn't limit the output to three bits wide.
|-
| UINT16LE || iAttack || Attack rate || 0x60 (upper four bits) || [verify this]
|-
| UINT16LE || iSustain || Sustain level || 0x80 (upper four bits) || [verify this]
|-
| UINT16LE || iEG || Envelope gain (nonzero value is on) || 0x20 (bit 5) || [verify this]
|-
| UINT16LE || iDecay || Decay rate || 0x60 (lower four bits) || [verify this]
|-
| UINT16LE || iReleaseRate || Release rate || 0x80 (lower four bits) || [verify this]
|-
| UINT16LE || iTotalLevel || Total output level || 0x40 (bit 0-5) || [verify this]
|-
| UINT16LE || iAM || Amplitude modulation (Tremolo) || 0x20 (bit 7) || [verify this]
|-
| UINT16LE || iVIB || Frequency Vibrato || 0x20 (bit 6) || [verify this]
|-
| UINT16LE || iKSR || Key scaling/envelope rate || 0x20 (bit 4) || [verify this]
|-
| UINT16LE || iCONoff || Connector [OP0 only] || 0xC0 (bit 0, inverted) || 0: OPL bit set to 1 other: OPL bit set to 0
|}

=== Percussive instruments ===

There is apparently no distinction between percussive and melodic instruments. This is controlled at playback time, depending on which channel the instrument is loaded into.

== Tools ==

{{BeginFileFormatTools|Type=audio}}
{{FileFormatTool
| Name = AdLib <tt>bankmng.exe</tt>
| Platform = DOS
| canPlay = No
| canCreate = Yes
| canModify = Yes
| canExport = Yes; [[AdLib Instrument Bank Format|.bnk]]
| canImport = Yes; [[AdLib Instrument Bank Format|.bnk]]
| editHidden = No
| editMetadata = No
| notes = Part of ''AdLib Programmer's Manual''
}}
{{FileFormatTool
| Name = [[Camoto]]
| Platform = Linux/Win
| canPlay = No
| canCreate = No
| canModify = No
| canExport = Yes; many
| canImport = Yes; many
| editHidden = No
| editMetadata = Yes
}}
{{EndFileFormatTools}}

== Credits ==

This file format was documented by [[User:Malvineous|Malvineous]] from reading code included with the ''AdLib Programmer's Manual''. If you find this information helpful in a project you're working on, please give credit where credit is due. (A link back to this wiki would be nice too!)