MIDI2IMF

Developer(s)	K1n9_Duk3
Initial release	2013-02-14
Latest update	2021-03-01
Development status	Experimental
Platform	CLI
Tool Type	Audio Editor
Engine(s)	None
Homepage	http://k1n9duk3.shikadi.net
Discussion(s)	PCKF Discussion Thread
Download	Version 1.3 newest; mirror

MIDI2IMF (aka MIDI to IMF converter) is a Win32 bit based tool to convert MIDI files to IMF format created by K1n9_Duk3. This tool tries to keep the size of the resulting IMF file as small as possible, although that depends on the complexity of the source MIDI file.

Note: This program is distributed without any warranty; without even the implied warranty of merchant-ability or fitness for a particular purpose.

Usage

MID2IMF <midifile>[.mid] [OPTIONS]

Recognized options are:

/help          shows this text and quits
/dumptimbre    dumps the included timbre file and quits
/info          lists the names of the MIDI tracks and quits
/imf=<file>    saves the converted data to <file> (default: <midifile>.imf)
/rate=<x>      sets the IMF rate to <x> (default: 560)
/volume=<x>    sets volume to <x> (default: 255)
/allvoices     don't reserve voice 0 for AdLib sound effects
/nosilence     removes silence at the beginning of the song
/chunk         saves an AUDIOT chunk instead of a plain IMF fileVersion 1.0
/truncate      truncates IMF data if it's too large
               (automatically set if /chunk or /maxsize used)
/maxsize=<x>   sets maximum IMF size (default: 65532)
/exclude=<x>   disables MIDI track <x>; can be set multiple times
/keepdummy     keep instructions that get overwritten in the same cycle
/keepredundant keep instructions that write the same value that's already in
               the AdLib register
/keepall       combination of /keepdummy and /keepredundant
/timbre=<file> uses timbres from <file> instead of included timbres

Note: Be careful when using the /exclude option! Most MIDI files set the tempo in track 0. Excluding track 0 might cause the converted IMF file to use the wrong tempo settings.

Note: The default volume setting is also the maximum volume.

MIDI formats

There are several different formats that store MIDI (or MIDI-like) data:

+ MIDI (file starts with ASCII characters "MThd")

- XMIDI (file starts with ASCII characters "FORM")

- HMI (file starts with ASCII characters "HMI-MIDISONG")

- HMP (file starts with ASCII characters "HMIMIDIP")

+ CMF (file starts with ASCII characters "CTMF")

- MUS (file starts with ASCII characters "MUS")

This program will only work properly on standard MIDI files. CMF files can be converted, too, but that feature is still experimental. The resulting IMF file will not sound exactly like the CMF file.

Technical Information

Most of the information on how to play MIDI music on an AdLib FM chip were taken from the source code of the Apogee Sound System, written by James R. Dosé.

Instead of writing instructions directly to the registers of the AdLib FM chip, this program produces a sequence of instructions in IMF format. The resulting data is processed twice to eliminate unnecessary instructions and thus reduce the size of the resulting IMF file. The first run removes all instructions that write data to registers that are overwritten in the same IMF cycle. The only exception are the registers 0xB0 to 0xB8. They must always be written, otherwise a sequence of short notes might get merged into a single, long note. The second run removes all instructions that try to write the same data to a register that is already stored in the register.

Note: There is no guarantee that these runs won't remove any important commands. You can use the /keepdummy and /keepredundant options to disable these runs.

Note: This program ignores the EMIDI loop commands of the Apogee Sound System. This is done because a) other MIDI files might use the EMIDI commands for different purposes and b) infinite loops in the MIDI

file would lead to an infinite number of IMF instructions.

Specific Instruments

To make an AdLib voice play a MIDI-specific instrument, the program needs a timbre file. The program comes with an included timbre file, but you can select a different one if you want the instruments to sound differently. The structure of the timbre file is declared as follows:

typedef struct
{
  unsigned char SAVEK[ 2 ];	// = {mChar, cChar}	//Sound Characteristic
  unsigned char Level[ 2 ];	// = {mScale, cScale}	//Scaling/Output Level
  unsigned char Env1[ 2 ];	// = {mAttack, cAttack}	//Attack/Decay
  unsigned char Env2[ 2 ];	// = {mSus, cSus}	//Sustain/Release
  unsigned char Wave[ 2 ];	// = {mWave, cWave}	//Wave Select
  unsigned char Feedback;	// = nConn		//Feedback/Connection
  signed   char Transpose;	//added to VOICE.key in SetVoicePitch()
  signed   char Velocity;	//added to VOICE.Velocity in SetVoiceVolume()
} TIMBRE;

extern TIMBRE ADLIB_TimbreBank[ 256 ];	//first 128 entries for instruments,
                                       //last 128 entries for percussion

IMF Restrictions

Reduced number of voices

The AdLib FM chip can only play up to 9 voices or 'notes' at the same time, while MIDI files can play notes on up to 16 channels. This means that it is impossible to convert just any MIDI file to IMF format without losing or ignoring some of the notes.

In addition, some games use the first AdLib voice to play AdLib sound effects. IMF files should not use that voice, or the music might interrupt or modify the sound effect and vice versa. The first voice should only be used if the game does not use AdLib sound effects at all (like Cosmo's Cosmic Adventures).

To make sure that your MIDI file can be converted without losing notes, you should not use more than 8 MIDI tracks and make sure that each track only plays one note at a time.

Restricted IMF size

The original code that is used to play IMF music uses only an unsigned 16-bit integer to store the size of the IMF data. This means that none of the original DOS games can play IMF data larger than 65532 bytes. Since each IMF instruction is 4 bytes in size and a note must at least be turned on and off, the maximum number of notes in an IMF song is 8191.

Furthermore, some games limit the size of IMF files due to the way they store them in memory. When these games load IMF files larger than the allocated buffer, some other data in memory might get overwritten, which may cause the game to crash or display random garbage.

 Cosmo's Cosmic Adventure: ~40000 bytes 
                           -> corrupts tileset graphics

            Duke Nukem II: ~56000 bytes (limit depends on number of actors)
                           -> game crashes

Implicit IMF rates

The rate at which the IMF music should be played is not stored in the IMF files. It is hard-coded into each game's playback routines. This means that games that use different IMF rates play the same IMF music at different speed.

Known IMF rates

280: Duke Nukem II

560: BioMenace
     Catacomb 3-D series
     Commander Keen 4-6
     Cosmo's Cosmic Adventure
     Major Stryker
     Monster Bash

700: Blake Stone
     Corridor 7
     Operation Bodycount
     Planet Strike
     Spear of Destiny
     Wolfenstein 3-D