---------------------------------------------------------------
 DRO2MIDI - version 1.3 (2007-09-02)
 Written by malvineous()shikadi.net
 Heavily based upon IMF2MIDI written by Guenter Nagler in 1996
 http://www.shikadi.net/utils/
---------------------------------------------------------------

// What is it?
////////////////

DRO2MIDI converts Adlib music (in .dro, .imf or .raw format) into standard MIDI
files, so that it can be played or edited in most audio applications, or so the
notes can be extracted to be played on a real instrument.

// Features
/////////////

 * Converts DOSBox .dro captures, id Software .imf songs and Rdos .raw captures

 * Supports MIDI pitchbends

 * Tries to map Adlib instruments to MIDI instruments as best it can, but these
   mappings can be easily changed

 * Instruments can also be mapped to MIDI percussion

 * OPL rhythm-mode percussion is converted (to fixed instruments at the moment,
   but these can be changed by recompiling)

// Usage
//////////

  Linux:      $ dro2midi file.dro file.mid
 
  Windows:  C:\>dro2midi file.dro file.mid

  For a list of the command line options run dro2midi with no parameters.

For best results, all the .txt data files should be in the current directory.

Instrument mappings between Adlib registers and MIDI instruments are stored in
inst.txt.  This file contains a number of existing mappings, but additional
mappings can easily be added.  During conversion, if an exact match cannot
be found the mapping with the closest Adlib parameters will be used instead.
A message will be printed when this happens, along with a line that can be
copied into inst.txt to provide an exact match.  This approximation can have
the unfortunate side effect of providing some odd conversions, such as
converting a bass-line into a monotonic drum.

To get a perfect conversion you may wish to delete all but the first "all-zero"
instrument in inst.txt, which will cause all instruments to be converted as
a piano.  You can then copy the definitions printed during conversion one by
one into inst.txt, to assign the best-sounding instrument without worring about
any default mappings taking over.  Alternatively the -i option can be used
which will disable the closest-match algorithm, and only exact matches will be
used (again, anything that can't be exactly matched will be mapped as a piano.)

// inst.txt
/////////////

The instrument mappings are stored in inst.txt, in a format like this:

  07-12/4F-00/F2-F2/60-72/08/00-00: patch=15  # Tubular bells

The numbers at the start are hexidecimal values of the Adlib registers for that
instrument.  "patch=15" assigns MIDI instrument #15 for this Adlib instrument.
For percussion, "drum=35" could be used instead.  Anything after a # symbol is
treated as a comment.

The instrument names (and values to supply to the patch= parameter) are stored
in patch.txt, and the drum names (and numbers) in drum.txt.  You may find these
files helpful to reference when selecting instruments for conversion.

Note that the parser for this file is quick and dirty, so it's easy to get a
syntax error - for example, an otherwise blank line with a single space on it
will cause an error (so if you get an error about a blank line, make sure it
really is blank!)

// License
////////////

DRO2MIDI was based on IMF2MIDI by Guenter Nagler.  DRO2MIDI is released under
the GPL license, except where it is incompatible with IMF2MIDI's original
license, in which case IMF2MIDI's license takes precedence.

---- Begin IMF2MIDI license ----

IMF2MIDI (c) 1996 was created by Guenter Nagler.

IMF2MIDI is free and may be used as you wish with this one exception:

    You may NOT charge any fee or derive any profit for distribution
    of IMF2MIDI.  Thus, you may NOT sell or bundle IMF2MIDI with any
    product in a retail environment (shareware disk distribution, CD-ROM,
    etc.) without permission of the author.

You may give IMF2MIDI to your friends, upload it to a BBS, or ftp it to
another internet site, as long as you don't charge anything for it.

---- End IMF2MIDI license ----

// Contact
////////////

Source code is available at http://www.shikadi.net/utils/

You can e-mail me at malvineous()shikadi.net