MTM Documentation

Installation
Command Syntax and Options
Control File Specification
Problems and Tips
Midi File Structure

Installation

The following sequence assumes that you are using some dialect of Unix. MTM was developed under Linux, and my recent experience of other dialects is negligible, but, to the best of my understanding, MTM has no significant system dependencies and so should compile without problems.

Download the source archive. Unless you have good reasons to do otherwise, take the most up-to-date version from the Download section. The following refers to mtm2.4, but you should replace '2.4' by whatever is the current version number.
Unpack the downloaded archive:
```
              tar xvzf mtm2.4.tgz
    
```
Change directory into the MTM directory:
```
              cd mtm2.4
    
```
There is no specific configuration needed, though you may wish to 'tweak' the Makefile, particularly if you wish the compiled program to be installed in some specific system directory. If you are just compiling for personal use then you can probably skip this step.
Invoke the 'make' program which will build the executable:
```
              make
    
```
There should be a clean compilation. If you get any errors or warnings, then you need to investigate the cause. If these errors imply that the source needs to be modified, please let me know. I only have access to Linux as a development platform so be prepared to evaluate modifications needed to ensure portability over other systems.
Once the program is compiled, move into the 'test' directory and try running mtm on the test files provided:
```
              cd test
              make
    
```
Again, these should run without significant discrepancies. Please report any errors or differences to me by e-mail.
Finally, move the executable to some suitable directory which is included in your normal execution path. The Makefile comes with a rule to install the program in /usr/local/bin but you will need to be superuser (root) to do this on any normal system. I keep my program in a personal directory and would simply use the mv command:
```
              mv mtm ~/bin/x86/mtm
    
```

If all the above have been done, you should be able to invoke MTM from any directory. See the next section for details of command syntax and options.

Do let me know if you have problems with any of the above. I can't promise to come up with a fix, but I'd prefer to make MTM portable and easy to install.

Command Syntax and Options

The syntax for MTM is simple:

             mtm { options } filename

I will deal with the various options below. The filename may be the full filename, or if it conforms to the 'normal' conventions and has a .mid extension, this may be omitted. MTM first attempts to open the filename specified and if this fails, then it appends .mid and tries again. If this still fails, then MTM gives up with an error message.

By default, MTM will create an output file based on the input file name. The rules are:

Generate a 'base name' by removing any extension from the file name that was succesfully opened, as described above.
Append .mup to the base name.

This is the mode that I normally use, and I find to be simplest. It has one rather nasty drawback: If you start with a MUP file and use MUP to create a MIDI file, and then try to run MTM on the MIDI file, it will probably overwrite the original MUP file unless you have renamed the MIDI file. If I were doing this, I would always rename the MIDI file first before trying to run MTM on it. Alternatively, you can use the -o option (see below) to specify an alternative output file name.

Command-Line Options

The following options are currently supported:

`-h`	The usual Unix-style help information. MTM will display the command sytax and list the available options.
`-v`	MTM will display the current version number and exit without processing anything.
`-o filename`	Specify the output filename to be used in place of the MTM default. If you specify `-o -` then MTM will output the MUP text to stdout, thereby allowing you to pipe the output directly into MUP (or any other program).
`-f filename`	Specify a parameter file name to be used in place of the MTM default (see below).
`-a quantum`	Specify a quantization note length. By default, MTM will use the 'minimum' sensible note length for quantisation, but if you have a 'captured' MIDI file, or if the file was produced with shorter than standard lengths, it may be beneficial to specify a value with this option. The number given should be a power of 2, and follow the modern (i.e. US) convention: crochet=4, quaver=8, and so on.
`-s stretch`	During the development of MTM I have encountered some very odd MIDI files. One feature that some software packages adopt is to shorten notes by a fixed percentage of the 'standard' note length (NB: This is not done by MUP, which shortens notes by a fixed length, regardless of note length). In order to compensate for this I provide a stretch facility which extends all note lengths to compensate. The number specified should be an integer, and is the percentage to be applied. For example `-s 11` will add 11% to the note lengths. This will compensate for a 10% shortening which seems to be the default on the files that I encountered.
`-p pad`	This is used to specify a length of padding to be prefixed to the midifile. This is useful when there is a lead-in (short bar) at the start of a piece. The 'pad' value should be the number of crotchets (quarter-notes) to be added. This may include decimal fractions. As an example, a piece in 12/8 time, with a single quaver lead-in, needs a pad value of 5.5 (6 crotchets/bar - 1 quaver=0.5 crotchets).
`-k keysig`	This can be used to apply a key signature to a MIDI file that lacks this information. Most MIDI files include a key specification which MTM will use, but if a piece has been recorded by MIDI file capture from a live performance, the information may be lacking or incorrect. The key signature is expressed as a signed number in the range -7..7, with negative number being the number of flats in the key, and positive for sharps, e.g.:`-k -3` is E flat, while `-k3` is A.
`-t timesig`	This option allows you to provide a time signature. It was added because some midifiles contain erroneous time signatures: a piece in 3/4 time may have a 4/4 signature embedded. If you supply this option, then any time signatures from the midifile will be ignored and the whole piece will be interpreted with this time signature.
`-m`	[ New with 2.1.1 ] MIDI commands are no longer generated by default. If you want them, use the -m option which enables them.
`-n`	This options suppresses the comments which are normally included to indicate bar numbers.
`-c`	This option suppresses various other comments inserted into the output.
`-l number`	[ New with 2.3 ] This option requests MTM to produce MUP lyrics statements. If there are lyrics events in the MIDI file, then these are output as MUP lyrics statement. If lyrics events are missing then dummy lyrics statements are produced. These contain a dash '-' for each syllable and it is a fairly simple job to edit lyrics in by hand. Note that MTM assumes that the lyrics in the file match the notes. If this is not the case, then you will probably get MUP errors reported when you try to generate output with MUP. The number specified with this option determines which tracks should have lyrics generated. The number is formed by adding powers of two - 1 for track 1, 2 for track 2, 4 for track 3, 8 for track four, and so on. If you aren't sure how many tracks there are and want all tracks to be generated you can put -1. I always use macros rather than staff numbers, and I expect many other users do also. I've taken the liberty of assuming that you also define macros for lyrics. The lyrics output by MTM are of the form: L1: "lyric text"; where `L1` has been defined like: define L1 lyrics below 1 @ If you have use the #translate command in the control file (see below) then the '1' is replaced by the name defined there. I often use `S, A, T, B` for four-part voice pieces, so defining define LS lyrics below S @ define LA lyrics below A @ .... will be appropriate.
`-N filename`	This option allows you to specify a customised datafile to control selection of accidentals. The install process will place the standard file in `/usr/local/lib/mtm/notelist`. Users can copy this to `~/.mtm/notelist` where it can be edited. That version will take precedence over the installed version. Alternatively, you can override both by specifying this option. You can therefore have several files and select which one at will. The format of the file is essentially 15 strings each of 24 characters. Leading spaces and tabs are ignored. Lines beginning with '/' are ignored. See the comments at the start of the installed file for further explanations.

Control File Specification

In order to produce a MUP source file from a MIDI file, you have to provide extra information, as the MIDI file conveys less information than a MUP file. By default MTM will make lots of assumptions, which may or may not be appropriate. The output from MTM should always be acceptable to MUP (though occasionally it isn't), but the printed output from MUP is unlikely to be acceptable to you without further assistance. In order to provide this, MTM attempts to read a control file in which you can specify some of the information. If this file doesn't exist, MTM will simply adopt it's defaults. You won't get an error message. It's up to you to provide this if you wish to do so.

The control file name is normally based on the 'base name' described above in relation to the output file. The input file name is stripped of it's extension and the extension .mtm is added. If you wish to use a different file name you can use the -f opetion listed above to specify the name. The file consists of a number of directives, one per line (or group of lines), as follows:

#header This begins a group of lines which are copied verbatim into the MUP output, before any other output. You can include any valid MUP source here, including header titles, footers, macro definitions, staff specifications etc. These should be followed by:
#headend This terminates the above.
#secondaries As for #header,but these are inserted into the output after the main headings are done. Probably a better place to insert staff specifications. Ended by:
#secend This terminates secondaries.
#translate trk=staff {voice} By default, MTM outputs events to the staff which corresponds to the track number. This directive allows you to tailor this and group two or three tracks onto a single staff. If you use it, it's probably best if you specify a translation for all the tracks to avoid the possibility of sending two tracks to the same staff+voice combination. If you omit the voice number, MTM will do likewise. Mup treats this as voice 1 on the specified staff. You'll also need to include a vscheme directive if you put more than one tracks per staff.
#beamstyle The lines following this should consist of a series of beamstyle specifications, one per line. These should consist of <number>/<number>=<spec> where the two numbers indicate a time signature, and spec is a mup beamstyle specification. For example:
3/4=2,4
Whenever the time signature changes, MTM consults this list and if it finds a matching time signature, it inserts the appropriate beamstyle command into the output.
From Version 2.2 onwards, you can specify a track number along with the other information: [<track>] should precede the time signature described above.
The beamstyle specifications are terminated by:
#beamend Terminates #beamstyle specifications.
#key trk=number This is used to modify the key signature for a specified track. Since I have yet to find a need to use this, I can't say whether it works in a meaningful way. This is one of the bits from the original code. Feedback on it's usefulness and correctness would be welcomed.
#clef number=<clef> Specify either bass or treble for a given track number. At present you can't specify the other clefs here. Mtm will select either bass or treble automatically based on the range of notes in the track. If all notes are less that F above middle C, then it's bass otherwise treble.

There has been confusion about the directives which end groups in the control file, they were not consistent with each other. I have changed the specification so that they are all #*end, and recommend you to adopt this, but to avoid existing files from failing, mtm will accept either variation, at least for the present.

There are probably lots of other directives that could be added. Feel free to make suggestions and if they can be easily done I'll add them to the to-do list.

Problems and Tips

I'm sure that there are still bugs in the program. It certainly doesn't do everything that I want yet, so don't expect it to do everything you want (which is probably different from what I want). This section outlines existing problems and suggests work-arounds.

Accidentals. I'm never sure whether a note should be a sharp or flat. MTM makes very arbitrary decisions on this which are probably quite illogical. It often gets it wrong and this can cause MUP to reject the file. MUP insists that you can't have two notes of the same name in a chord, even if one of them is sharpened or flattened. As a result the following MUP segment is illegal: 4a;b&b;;c;d;. The B flat and the B have the same name and will produce a MUP error message. I have encountered MIDI files which manage to include two instances of the same nore (no accidentals) and I have managed to pursuade MTM to discard the duplicate note, but so far I haven't been able to figure out a way of avoiding the first problem. My approach to this is to edit the MTM output by hand when I get the message from MUP. You can usually change a B flat to an A sharp to get around it. What you do if there's a A natural in the chord as well I don't know.
New from V2.2: The code has been rewritten so that conflicts such as those above are now detected, and the program will attempt to make the enharmonic change needed to resolve the clash. If this cannot be done, a warning is issued and you can expect an error message from MUP. If anyone has any suggestions as to how this might be better resolved, I'd be glad to hear from them.
Triplets (and worse Quintuplets etc.) There is code in MTM which is supposed to handle triplets, and this works providing the basic timing is adequate - see below in the section on Midi File Structure for more details on what I mean here. I suspect that lots of MIDI files, which sound fine, will end up with triplets being 'rounded-off' into standard notes. This area needs more work.

Do let me have details of any other problems that you come across. If nothing else I can list them here so that people are aware of them. If I can fix them I will do so when time permits.

Midi File Structure

For those who just use MIDI files without wondering what they contain, this section gives a brief outline. It also describes what MTM tries to do with the various bits and why it doesn't always turn out the way you'd like it.

Some Basic Concepts

I'm only familiar with Format 1 MIDI Files. The standard also describes Format 0 and Format 2 files, but I've not come across these so I've never had to worry about them. In a Format 1 MIDI file, there a file header, followed by a number of tracks.

The header contains a couple of useful bits of information, the number of tracks, and a timing parameter, for which see below.

The tracks are just a sequence of events, each with a time interval which gives the time between this event and the preceding one.

Events are the basic units of a MIDI file. They specify things like start a note, at a given pitch and volume (referred to as velocity in MIDI parlance), end a note, change a parameter, change key, change time signature, and so on. These are all interpreted by your synth or software to produce the desired effects.

There is usually one track per instrument, plus a track 0 which contains things like time signature changes. For instruments like a piano there will normally be two tracks, one for each hand, but there may be even more; for instance in a 4-part fugue you might well have 4 tracks, one for each voice. It's all down to the way in which the composer decided to do things and we all know that composers never do anything in a straightforward way :-).

By default, MTM will take each of these tracks and convert them into a MUP staff. By fiddling with the control file, you can pursuade MTM to output two or three of these tracks as voices on a common staff if it is sensible to do so.

Pitch

The MIDI concept of pitch is pretty basic. It simply uses a number in the range 0-127 to identify the chromatic scale from a low C upwards. It turns out that middle C is MIDI pitch 60 so you can work everything out from there. If you want to do quarter tones you're in for a hard time, as you have to do these by 'bending' the pitch for the in-between notes. Alternatively there are synths which can handle scales like this, but then the MIDI pitch no longer corresponds to real pitch and you find that C's are no longer an octave apart. I'm not into that sort of music, so don't ask me for advice on how to do it!

One thing that is apparent when you look at a MIDI file is that there is no concept of Clefs. Notes are just spread across the scale and if you wan't to convert this to notation, you need some idea of which clef things are on. MTM can't do much about this and assumes everything is Treble Clef. If you know that some track should be Bass Clef, then you can insert the appropriate MUP directives using the #header, or better, the #secondaries directive in a control file. You have to also specify defoct=4 as MTM assumes that it will all be interpreted by MUP as Treble Clef. This may be something to go on the list for future enhancement.

Timing Structure

The timing of a piece of music is crucial and must be able to cope with fast runs and syncopation accurately if the beauty of a piece of music is not to be spoiled. MIDI files handle this by dividing the time scale into a series of very short time intervals, known as Ticks. The size of a tick is not standardised, but is specified in the track header. It is usually chosen by the person designing the software that is used to create the MIDI file. Some of the files I have seen used a value which is totally unsuitable for good quality of performance. This number is usually referred to as the division factor.

The number specified in the file header, mentioned above, is the number of Ticks per quarter note (crotchet). This must be large enough so that the different lengths of notes can all be expressed as numbers of Ticks. If the shortest note in a piece is a semiquaver (16th note) then 4 is adequate for this. However, if the piece contains quintuplets of 32nd notes, then the number should be 40 (8 times 5). If you wish to record live performances, then the number needs to be much larger still to for subtle variations in tempo and style. Most software uses much larger numbers. To be able to handle triplets well, the number should include a factor of three, quintuplets need a factor of 5 and 64th notes a factor of 16.

I have had files using 1024 as the division factor. This gives good resolution for live performances, but is awful for trying to sort out triplets, as it is not divisible by 3!

Most performers, when playing, will shorten notes to some extent. They have to make a transition to the next note anyway, so it's almost impossible to maintain each note to the full extent and it would sound odd if they did. Software which produces MIDI files do the same things, but in varying ways. MUP specifies a 'release' parameter which chops a fixed length off the end of a note, subject to never reducing the length below 75%. By specifying 'release=0' you get a very legato-sounding performance. Other programs determine how much to drop in other ways. I encountered one program that removes a fixed percentage from each note. This is fine for shorter notes but long sustained notes can lose a substantial amount!

As a result of all this, MTM has to do a fair bit of work to produce a score which matches the original. If it just produced the notes as they appear in the file, they would consist of lots of very short bits, tied together to get the exact length, which is not what you expect when you look at a score. MTM will round notes up in an attempt to make the notes what would be written by the composer. You can help MUP by specifying two parameters in the command line: -a notelen and -s percentage. See the command line options for details of these.

Page Created by Bill Purvis, Last Update 14 October, 2008

`#header`	This begins a group of lines which are copied verbatim into the MUP output, before any other output. You can include any valid MUP source here, including header titles, footers, macro definitions, staff specifications etc. These should be followed by:
`#headend`	This terminates the above.
`#secondaries`	As for #header,but these are inserted into the output after the main headings are done. Probably a better place to insert staff specifications. Ended by:
`#secend`	This terminates secondaries.
`#translate trk=staff {voice}`	By default, MTM outputs events to the staff which corresponds to the track number. This directive allows you to tailor this and group two or three tracks onto a single staff. If you use it, it's probably best if you specify a translation for all the tracks to avoid the possibility of sending two tracks to the same staff+voice combination. If you omit the voice number, MTM will do likewise. Mup treats this as voice 1 on the specified staff. You'll also need to include a vscheme directive if you put more than one tracks per staff.
`#beamstyle`	The lines following this should consist of a series of beamstyle specifications, one per line. These should consist of `<number>/<number>=<spec>` where the two numbers indicate a time signature, and `spec` is a mup beamstyle specification. For example: 3/4=2,4 Whenever the time signature changes, MTM consults this list and if it finds a matching time signature, it inserts the appropriate beamstyle command into the output. From Version 2.2 onwards, you can specify a track number along with the other information: [<track>] should precede the time signature described above. The beamstyle specifications are terminated by:
`#beamend`	Terminates #beamstyle specifications.
`#key trk=number`	This is used to modify the key signature for a specified track. Since I have yet to find a need to use this, I can't say whether it works in a meaningful way. This is one of the bits from the original code. Feedback on it's usefulness and correctness would be welcomed.
`#clef number=<clef>`	Specify either bass or treble for a given track number. At present you can't specify the other clefs here. Mtm will select either bass or treble automatically based on the range of notes in the track. If all notes are less that F above middle C, then it's bass otherwise treble.