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
Lib)
* 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
standard.
* 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
number.
* Quit (press "Q"): Yep.. you quit MIDIMOD if you choose this
command.
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:
-12
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
enter:
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.
<<1>>
* 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
incomplete.
* 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)