IMF Format
From ModdingWiki
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.
Contents |
File format
There are two versions of the IMF format. The first two bytes in the file will be zero if it's in Type-0 format, otherwise it will be Type-1 format. In a Type-0 file the two initial zero bytes are skipped, then the rest of the file is Adlib data that is played until the end of the file is reached. In a Type-1 file the two initial bytes contain the size of the Adlib data (not including the two bytes themselves [TODO: Check this]), 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.)
| Data type | Name | Description |
|---|---|---|
| UINT16LE | iLength | Type-1: Song data length (in bytes), Type-0: 0x0000 |
| BYTE[iLength] | cAdlibData | Song data (see below) - iLength bytes long if Type-1, or until EOF if Type-0
|
| BYTE[] | cExtraData | Arbitrary data/tags (Type-1 format only, see #Tag Data below) |
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":
| 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.
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:
| Speed | Game |
|---|---|
| 560Hz | Bio Menace, Commander Keen, Monster Bash |
| 700Hz | Blake Stone, Wolfenstein 3-D, Cosmo's Cosmic Adventures |
| 280Hz | Duke Nukem II |
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.
Tag Data
In a Type-1 IMF file it's possible to store data after the end of a song. Some games (such as Wolfenstein 3-D) have extra data stored there, but its purpose is unknown. It is also possible to store tags there, and this simple format is supported by most IMF players:
| Data type | Name | Description |
|---|---|---|
| BYTE | cSignature | 0x1A |
| ASCIIZ[256] | strTitle | Song title |
| ASCIIZ[256] | strComposer | Song composer |
| ASCIIZ[256] | strRemarks | Song comment/message |
| BYTE[9] | cProg | Name of the first program that added these tags (eight bytes + terminating NULL, pad out with NULLs if necessary.) |
Note that the ASCIIZ[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.)
Use
This format has been used in the following games:
- Bio Menace
- Blake Stone
- Commander Keen 4-6
- Catacomb 3D
- Corridor 7
- Cosmo's Cosmic Adventures
- Duke Nukem II
- Hocus Pocus
- Major Stryker
- Monster Bash
- Operation Body Count
- Wolfenstein 3-D
Utilities
The following utilities work with this file format.
Convert other formats to IMF
- IMFCreator - creates IMF files from MIDI files in one step and also includes a preview feature, from the WinWolf3D website
- MIDI2MUS then MUS2IMF can be used together to make IMF files
- DRO2IMF can convert DOSBox OPL captures into IMF files
Convert IMF to other formats
- DRO2MIDI converts IMF to MIDI files
