OPL/dro2midi/README

---------------------------------------------------------------
 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