MIDIMOD Documentation

MIDIMOD - Amiga Noise/Sound/Protracker to MIDI file converter (ver 0.2)

MIDIMOD - What it does
MIDIMOD is a program which converts music modules generated by Amiga
tracker programs (MOD files) to general MIDI format 1 (MID files). It is
menu-driven and if not "user-friendly", at least "user-polite". No
temporary files are created at any stage, so it is ok to be run on a
floppy drive (though a disk-cache utility or a fast drive are
preferred.. in fact, the faster the computer the better). Some editting
of the output MID file might be necessary, but next time there will be
less editting to do as MIDIMOD can remember previous settings.

Why convert MOD files to MID files?
Even though MOD files contain some music-instructions that cannot be
represented in MID format, there are many reasons why it is desirable to
have music in MID form rather than MOD form:
    * Some sound cards cannot play MOD files, only MID files (eg. Ad
    * Top-of-the-range music editting programs do not handle MOD files,
     but almost always handle MID files, or at least allow you to
     convert from MID files.
    * There exist programs to print out MID files as musical score. I
     don't know of any which do the same for MOD files
    * MID files tend to be much smaller than MOD files
    * On some sound cards, MID files sound better than MOD files
     (although on many others the converse is true)
    * MID files are more portable, having a well-known format, and have
     utilities on many different computers. MID files _ARE_ the industry
    * MID files can be played on professional keyboards, allowing expert
     recording/presentation of music
    * Umm.. Microsoft Windows comes with a MID player but not a MOD
     player, so you can play MID files as a background task (and insert
     MID files into documents etc. etc.)
Ok.. have I sold you on MOD->MID conversion yet?

How to use MIDIMOD
After starting up MIDIMOD (I assume you know how to do that), you can
select menus and commands by simply pressing a key. There are 3 menus:
    * File menu (press "F"): commands to do with files
    * Samples menu (press "S"): commands to do with samples
    * Options menu (press "O"): commands to set simple configurations
    * Help menu (press "H"): commands to do with help
You can also use the cursor keys to select menus and commands, and then
press  to select that command.

The File Menu
The file menu consists of 4 commands:
    * Destination MIDI file (press "D"): A dialogue box will appear and
     ask you to enter the name of a MID file. After entering the full
     name (including extension eg. TECHNO.MID) press . If the
     file you entered already exists then you will be asked if it can be
     overwritten.. press "Y" for yes or "N" for no.
    * Source MOD file (press "S"): A dialogue box will appear similar to
     the "Destination MIDI" one. Enter a filename then press .
    * Convert (press "C"): This will convert the MOD file you entered to
     the MID file you entered. I suggest before you do this step, use
     the Sample menu to set samples to appropriate instruments.
     Sometimes conversion takes a while - please be patient. If you get
     an error message which says that you have too many different
     instruments, then use the "Map samples" command to reduce the
    * Quit (press "Q"): Yep.. you quit MIDIMOD if you choose this

The Samples Menu
The samples menu consists of 2 commands:
    * Map samples (press "M"): There are many, many MOD samples on
     computers around the world, so it is impossible to automatically
     know which instrument is equivalent to which sample. You must tell
     MIDIMOD which instrument to use. Use the cursor keys and 
     to select a sample from the list that appears on the screen. It is
     possible that the list will be longer than the screen and so you
     will need to move off the bottom of the list (don't worry.. the
     list will scroll upwards if it can). If you can't move off the
     top/bottom of the list, you will hear a beep. Each sample may have
     an asterisk "*" before it - this means that there is actual sample
     data that corresponds to this sample - ignore any other samples..
     they won't be converted (except in name only). Each sample will
     have an instrument code to its right. If the code is prefixed by a
     "D" then it is a percussion code. Anyway.. after selecting a
     sample, a list of all of the available instruments will appear on
     the screen (it is another scrolling menu). Select one and the
     appropriate code will appear to the right of the chosen sample. If
     you don't want to select anything from a menu, just press .
     So when all samples have been given instruments (sometimes they
     will already have an instrument code.. it is best to leave these
     codes as they already have been matched with a sample's name) press
    * Transposing (press "T"): Even if you have matched a MOD sample
     with a MIDI instrument there is no guarantee that each will play at
     the same pitch. MOD samples tend to sound high, low, very low, or
     slightly off pitch when both MOD and MIDI instruments play the same
     note. The trick is to map MOD samples to a different note during
     the conversion, so that there won't be any horrible musical
     clashes. A good way to do this is to find a sample that maps
     exactly to a MIDI instrument, and then get a MOD-editor and play
     other samples, and compare those samples to the "true" sample. This
     way you can find the number of semitones difference there are
     between a MOD sample and its instrument equivalent. For example,
     bass guitar samples are usually an octave lower (sometimes two)
     than their actual note. As an octave is 12 semitones, if the guitar
     sample is transposed down 12 semitones, it sounds ok. Another
     example, chords are usually made up of 3 notes which are played
     simulateously (major chords have part of them transposed up 4
     semitones, and another part 7 semitones where minor chords have 3
     and 7 semitone transposed parts). After selecting a MOD-sample from
     the menu (the numbers on the right are the transpose values), you
     can enter in its transposition. For a bass sample you might enter:
     then press , whereas for a major chord you might enter
          0, 4, 7
     then press , and for a bass major chord you might enter
          -12, -8, -5
     then press  (note than -12+4=-8 etc.). During conversion,
     these transpositions are applied and hopefully the MID-file won't
     sound as if many musicians are playing using different scales. A
     couple of things you need to watch out for: if one of the
     transposition values is 0 then it must be the first value, also
     don't transpose percussion instruments - it's not a good idea.
    * Volume shift (press "V"): This is similar to transposing, but it
     affects volume rather than pitch. MIDIMOD alters volumes by
     applying a formula to each volume in the MOD file. The formula is
     simple: it takes the volume, then adds a number, then multiplies by
     a number, then divides by a number. So all you have to do is supply
     3 numbers, though when you come to change a volume formula you will
     notice that MIDIMOD has already given each sample a formula.
     MIDIMOD analyses each sample of the MOD file when you it reads in
     the MOD file and based on this analysis allocates a formula to the
     samples. Note that these formulae are not necessarily correct, they
     are just MIDIMOD's best guess, but most of the time they will
     suffice. To set the formula yourself, choose a sample then enter
     the three numbers for the formula respectively (as you do for
     transposition amounts), eg. if you want to "add 1, multiply by 2,
     then divide by 3" every volume for a particular sample, you would
          1, 2, 3
     the press . The last two numbers cannot be negative, and
     last number cannot be 0.
    * Save info (press "S"): Because it is nicer to have the computer
     select instruments, transpositions and volume shifts for you than
     having to look them up each time, MIDIMOD keeps a list of "known"
     mappings/transposes/volume-shifts from MOD-samples to MID-
     instruments. Once you have selected a mapping using the "Map
     samples", a transposition using "Transposing", or a volume shift
     using "Volume shift" you can use this command to save a sample's
     info to the info file. Just select the sample with the cursor keys
     and  and it is done. Press  to leave this command.

The Options Menu
There are 2 commands which allow you to set options:
    * Drum channel (press "D"): As different software/soundcard/hardware
     is by definition different, I decided that setting the drum channel
     to 10 permanently (as I did in version 0.1) is a bit impolite. So
     you can choose this option and enter the drum channel that you want
     (though if you don't enter any drum channel, it will assume you
     meant channel 10).
    * Tempo type (press "T"): Hmmm.. the MOD format caught me out with
     this one in version 0.1, and I didn't know what to do to fix it, so
     hence this option. Some MOD-files use an old tempo convention and
     the rest use a newer one. Some MOD-files don't convert at all well
     if the wrong convention is used. Anyway, after selecting this
     option press either "0" or "1" to select new or old conventions
     respectively. Initially, the convention will be the old one. If
     the MID file produced sounds like the timing is out of whack, try
     changing the tempo type and then doing the conversion again.

The Help Menu
There is only 1 command in the help menu:
    * About (press "A"): This displays some information about MIDIMOD.
     Press any key to make it go away.
If you really wanted help.. print out this document and use it as a
reference while you use MIDIMOD. If you are still stuck, call up a
friend who knows a bit about computers and ask them what to do (but you
were going to do that anyway weren't you?).. it may help if they know
something about music too. Maybe get in contact with a hacker-friend and
a muso-friend. On the other hand, maybe it would be best to throw a
party and invite all your friends around.

Command Line Parameters
When executing MIDIMOD, you can put the two filenames on the command-
line, eg.
          midimod headbang.mod techno.mid
The first filename (you guessed it) is the MOD file, and the second is
the MID file. If the MID-file already exists, then you will be asked if
you really want to overwrite it.

Example Session
Ok.. just incase everything I have said so far has gone over your head,
here is the way that I use the program (and it works for me.. honest!):
    * Run MIDIMOD by typing "MIDIMOD" at the command-line and press
    * Press "F" followed by "S" to choose the "Source MOD file" command.
    * Enter the MOD file name (eg. headbang.mod) and press .
    * Press "D" to choose the "Destination MIDI file" command.
    * Enter the MID file name (eg. techno.mid) and press 
    * Press either: the right cursor key
                or:  followed by "S"
    * Press "M" to choose the "Map Samples" command.
    * Now use the up cursor key and the down cursor key to highlight a
     sample, then press  to select it. Remember, only the
     samples with a "*" on the left-hand side are actually samples, the
     rest are probably just advertising.
    * Now use the up cursor key and the down cursor key to highlight an
     instrument (you should be getting quite good at this now) then
     press  to select it. If the sample was percussion, you
     should've selected a percussion instrument (the ones with a "D" on
     the left).
    * Go back to <<1>> and do these steps until you get sick of them, or
     all of the proper samples have been allocated an instrument
    * Press  to quit from this command
    * Press either: the left cursor key, or
                     followed by "F"
    * Press "C" to choose the "Convert" command.
    * Wait for the disk to stop writing, and the cursor to reappear.
    * Press "Q" to choose the "Quit" command.
There should now be a file lying around called "techno.mid" or whatever
you typed in. This is the MIDI equivalent of the MOD file.

The Instruments
The list of MIDI instruments is kept in the text file "midimod.ins".
Each instrument on a separate line. The first 128 lines must hold the
instruments 0 to 127. The lines after this hold the percussion
instruments (no more than 128). All instruments should have a code as
the first thing on the line. The code must consist of the letter "D"
(only if it is a percussion instrument) followed by a number from 0 to
127. This file can be editted with a text editor to put in the
instruments for your particular soundcard/computer/keyboard/software
etc. The supplied instrument file contains the Soundblaster MIDI
patches, if you are using a synth or a different sound card, then edit
this file and insert the correct instruments for you.

The Info File
A list of default mappings and transpositions is kept in the text file
"midimod.map". This is maintained with the "Save info" command in the
"Samples" menu, but it can also be editted with a text-editor. Each
sample is on a separate line, and consists of the first word in the
sample's name followed by 7 numbers, all separated by spaces. The first
word is the sample's name (which comes right after any header (st-xx: or
leading spaces) and has any intermediate spaces replaced by underbar
characters. The first number is a mapping number, the next three numbers
are transposition values (normally 0 0 0), and the last three are the
volume-shift values (eg. 1 0 0). The mapping numbers range from 0 to
255. The numbers 0-127 correspond to the MIDI instruments 0-127, and the
other mapping numbers are the percussion instrument codes plus 128
(without the "D" infront of course). The transposition values hold
either a set amount to transpose the instrument by (first transposition
value) or a mapping to a chord (two or more non-zero numbers). Any 0
transposition value must occur in the first position. The transposition
values range -128 to 127, 0 to 127, and 1 to 127 respectively in the
formula (volume + x) * y / z. Each line in the info file is in
alphabetical order, and it would be a bad idea to put a sample in the
wrong place.

All of the mapping/transpositions in the supplied "midimod.map" file are
for the soundblaster card (preferrably running windows). If none of the
info applies to you, you can delete the file and replacing it with the
"blank.map" file provided. It is probably better to note down some of
the info in the given "midimod.map", as even if mappings are wrong,
transpose and volume-shift values will still apply.

What is this .mm file?
Because there are some times when you don't want to store information
about a MOD file in the info file, a file with the same name as the MOD-
file except with a .mm extension is created. This .mm file holds all of
the information that you have entered about the MOD-file. It is
automatically read in when you load the MOD file, and automatically
saved when you quit. It is read in just before checking the info file
(above), and so if you have added any new sample info that applies to
that particular MOD-file it will be included. You can safely delete
the .mm file, but it will come back next time you using that MOD-file. 

Notes on Conversion
Firstly, the way the algorithm works, each different instrument is
allocated a different channel (this makes later editting of the MID file
_MUCH_ easier). As there are only 16 different channels this causes a
bit of a problem when you have a MOD file with 31 different samples. All
is not lost due to the nature of MOD files. Each percussion instrument
can be put on the same channel (10), giving you unlimited percussion
instruments but 15 channels for the other instruments. If the MOD file
you are using has more than 15 completely different non-percussion
samples then it is an unusual MOD file indeed, and you will need to give
some of the non-percussion samples the same instrument.

There is also some ambiguity with regard to multiple notes of the same
pitch on the same channel in the MIDI format. The MOD format can handle
it if the notes are on different channels, but if they are the same
sample then MIDIMOD will map them to the same channel in MIDI format.
Some MIDI players allow "overlapping" notes, some don't - I was going to
automatically remove "overlapped" notes, but no MIDI-player that I have
look at chucks a fit if they are in, so they are still there. Cross your
fingers and everything should sound fine.

It seems that there is also ambiguity with the MOD format, and tempo can
be interpretted two ways (I hope there aren't any more!). If your MID
file sounds like it should be in a different tempo in places, try
changing the "Tempo Type" Option (from the Options menu.. see above).

Even with automatic volume-shift allocation and checking of the info-
file for previous samples you will occasionally meet a converted MID
file that doesn't sound right (well.. with all of the different hardware
and software around, what can you expect?). Also, some samples may not
be recognised by MIDIMOD and may need transposing otherwise the tune
might sound horrible.. but as soon as you find correct details about any
new sample, feed them back into MIDIMOD so it can recognise them
correctly next time.

Not all MOD effects can be reproduced in a MID file. Things that I have
been able to reproduce include:
    * Tempo (given that your MID player can handle a tempo-track)
    * Note length (calculated from frequency, tempo, and # bytes in sample)
    * Pattern Break
    * Position Jump (well.. not really.. pretend its Pattern Break)
    * Set Volume
    * Note slides (slide up, slide down, slide to, fine-up, fine-down)
     all implemented, but permanently in glissando mode (ie. not a
     smooth slide).
    * Arpeggio
    * Volume Slides (and finevolume slides), but only if they occur at
     the start of a note
    * Set Sample Offset (actually retriggers the sample)
    * Retrigger sample
    * Cut sample
    * Delay sample
    * Pattern delay
Effects that I have not been able to reproduce, or have ignored on the
grounds that they are silly in a MID file are:
    * Vibrato and Tremolo (not really possible to do nicely in a MID file)
    * Position Jump (I have sort-of included it)
    * Pattern Loop (dangerous.. can cause infinite loops.. MIDI doesn't
     support loops so left it out)
    * Set filter (an Amiga-only hardware effect)
    * Set glissando (permanently on)
    * Set vibrato/tremolo waveforms (no MIDI equivalent)
    * Invert loop (*sigh* MIDI can't even come close to implementing
     this one)
Hmm.. looking back at what I have included, it seems that MIDIMOD has
more features than some MOD-file players I have seen! (Some MOD-file
players are really bad.. but this might be because not many programmers
know the MOD-format specification.)

Source Code
I am distributing the source code - in fact, so must you! If MIDIMOD is
placed on a publicly accessible medium (eg. BBS, FTP-site, Shareware
vendor, etc.), then the source code must be there too. It must always be
possible for the user to be able to modify this program. This allows
multiple-platform distribution, allows everyone to add their little
tweaks or use their favourite optimiser, and is even educational (if you
can stand my code). It is legal to only possess the executable-code, but
not to distribute only the executable. It is legal to distribute only
the source code. For more information on the license, see the textfile
also distributed with this package. Oh.. by the way.. if your computer
crashes when running this program and you lose 3 years of hard work and
gain a stomach ulser, don't blame me.. blame the power station, or the
computer store, or your nextdoor neighbor. Details of who not to blame
are also in the license.

The source code consists of three .c files and and two header files:
    * midimod.c - main program
    * midimod.h - header file for midimod.c
    * textwin.c - text-windowing system I notched up because I didn't
     have one, and because I wanted one for midimod. Hence it's rather
    * textwinc.c - same text-windowing system as textwin.c, but runs
     with the "curses" system. As curses is rather machine-independent,
     this allows MIDIMOD to be recompiled for just about any computer.
    * textwin.h - header file for textwin.c
If you are creating an executable, make sure you link textwin with
midimod. MIDIMOD was compiled on Turbo C 2.0, though it should work on
any ANSI C compiler (if it's not an MSDOS gizmo, use textwinc.c instead
of textwin.c)

How to get in touch
You can email me on the Internet at:
  andrewREMOVE@CAPSaes.id.au (just remove the CAPS before sending)