---------------------------------------------------------------
DRO2MIDI - version 1.6 (2013-11-29)
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
* Converts OPL frequency changes into MIDI pitchbends
* Tries to map Adlib instruments to MIDI instruments as best it can, but
these mappings can be easily added to and changed
* Instruments can also be mapped to MIDI percussion
* OPL rhythm-mode percussion is converted (v1.4 adds support for user-defined
mapping via new syntax in the mapping file)
* The OPL conversion constant can be changed (see -c option) to more
accurately convert notes without excessive pitchbend events
// 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 or
see below for more details. 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.)
// Command-line options
/////////////////////////
-p disables generation of MIDI pitchbends. This results in a single note-on
when the instrument sounds, but no further pitch change results until the
note is switched off again. This can also be used to prevent the large number
of small pitchbends generated when the conversion constant is slightly off (but
see the -c option, which now provides a better way around this.)
-a will, if pitchbends are disabled with -p, approximate any pitchbend by
playing the nearest note to the new pitch at the time. This results in a
"hammering" of notes during a pitchbend, which while humourous, is probably
of limited use.
-r disables the conversion of OPL rhythm mode instruments. As OPL rhythm mode
conversion is now quite flexible, this option should rarely be needed.
-i will disable the approximation algorithm which selects similar instruments
when an exact match cannot be found in the mapping file (insts.txt). This is
useful when trying to create a perfect map for a single song, as it makes it
easier to pick out which instruments are being mapped. This option should not
be used for the final conversion however, as any instruments that haven't been
precisely mapped will come out (by default) as a grand piano. (This default
mapping is simply the first entry in insts.txt.)
-c changes the conversion constant used when converting OPL notes into their
MIDI equivalents. This is the heart of what DRO2MIDI does. Unfortunately
depending on which set of documents are available, those writing OPL *players*
are told the conversion constant is either 49716, or 50000. Thus half the
games out there use one, and half use the other. The result of using the wrong
constant in the DRO2MIDI conversion is a tiny difference in pitch when the song
is played (about 1/17th of a cent.) Most people will be unable to hear the
difference between these two values, however if the wrong constant is used by
DRO2MIDI during the conversion into MIDI, the resulting file will contain
thousands of small pitchbend events, as it tries to approximate the exact OPL
note played. Using -c to try a different constant should solve this problem.
The default constant is 49716, and "-c alt" will change the constant to 50000.
It is possible to specify an arbitrary constant like "-c 49999" however this
should be unnecessary unless the same nonstandard constant was used wherever
the song was originally played. Note that no error checking is performed here,
so out of range values could easily crash the program (not that that's a major
problem though...) After conversion the number of pitchbend events is
displayed at the end of the output, so it will be obvious when the correct
constant is in use as this number will be significantly smaller than with
any other constant.
-v disables the volume detection. Normally DRO2MIDI will take the OPL
carrier's "Level" amount and translate it to a MIDI note velocity. This will
result in the output MIDI file more accurately matching the loud and quiet
parts of the OPL song. Some songs (e.g. Stunts) somehow manage to work with
these volume levels set to zero, which results in very quiet MIDI files (there
is an internal limit as to how quiet a note can sound to prevent it being lost
entirely.) If your output MIDI file is much too quiet, this option will cause
all notes to be played at maximum velocity.
-s instructs dro2midi to write all detected instruments to a .sbi file. This
is a 52 byte binary instrument format for OPL chips created by Creative Labs.
It is supported by applications written to work with the OPL, such as Ad Lib
Tracker 2.
// inst.txt
/////////////
The instrument mappings are stored in inst.txt, in a format like this:
NO 07-12/4F-00/F2-F2/60-72/08/00-00: patch=15 # Tubular bells
These lines are printed automatically when an unknown instrument is encounted.
All you will need to do is copy and paste the line into insts.txt and choose
a MIDI instrument for it. The file itself is read in from the current
directory during conversion, so if you run DRO2MIDI in another folder remember
to copy the file across too or your mappings won't be used.
The first two characters indicate what type of instrument it is. The
hexadecimal numbers that follow are the Adlib register values 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. See the comments at the top of the file for more
detailed information.
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.
(These two files are read in from the current directory during conversion to
allow the display of instrument names in status messages instead of just
numbers.)
Note that the parser for insts.txt 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
