Contents of the Download Site

This page describes the contents of the Melisma download site. The site contains a variety of things that may be useful to those who wish to experiment with, test, or use the Melisma system. You can also get a compressed version of the entire directory; download the file in melisma2003.tar.gz.

As of July 2003, a new version of the system is being released. This includes a new version of the key-finding program. It also includes a new system for testing meter-finding programs - the "note-address" system. Other components of the system are unchanged since the last (2001) release.

SOURCE CODE. The site contains all the source code necessary for running the five programs which constitute the analyzer. The programs are written in C, and run on a UNIX platform. For each program - meter, grouper, streamer, harmony and key - there is a directory containing the necessary source code for that program; a Makefile for compilation of the program; and a parameter file, currently containing the default parameters for the program. (To compile one of the programs, download the entire contents of the relevant directory; then enter the directory and type "make".)

UTILITIES. We also provide some simple utility programs for generating and manipulating notefiles. These simple C programs are in the directory utilities; they do not have Makefiles, and can be compiled just by typing, for example, "cc tempo-adjust.c -o tempo-adjust". (The exception is mftext, which is in its own directory "mftext" and has a Makefile.)

mftext. This program, which was written by Tim Thompson and modified by us, takes a standard midi file and outputs a "notefile" (a list of statements of the form "Note [ontime] [offtime] [pitch]", suitable for input to the Melisma meter program. Run it like this:

        mftext [input-file]

It is recommended to use the most recent release, mftext-release-07.

In some midifiles, "off" events are indicated by on-events with velocity of zero. The handling of such events by mftext is controlled by the variable zerov_noteoff in midifile.c: when set to 1 (the default), on-events with velocity 0 are treated as off-events; when set to 0, they are treated as on-events. (This is a new feature of mftext-release-07.)

tempo-adjust. This program takes a notefile (or a note-beat file) and adjusts the time points by a certain muliplicative factor, and outputs a new notelist (or note-and-beat list). Run it like this:

        tempo-adjust [-m or -t] [value] [input-file]
If the first flag is "-m", the program will multiply all time-points in the file by the value specified immediately following. If this value is 2.0, then, the program will take the line "Note 1000 2000 60" and output "Note 2000 4000 60". If the first flag is "-t", the program will assume the following value is a metronome mark; it will assume that the input has a tempo of quarter = 60, and scale all time values to the new tempo. If the value is 90, then, the program will take the line "Note 1000 2000 60" and output "Note 666 1333 60".

time-offset. This program ADDS a value to all time-points in the input file (either a notefile or note-beat file), and outputs the result. Run it like this:

        time-offset [time-offset value] [input-file] 

This program can be useful if one wants to concatenate two input files together. If the first file has a length of 30000 ms, simply add this value to all timepoints in the second file, then add the second file to the first.

concatenate. This program takes a file consisting of a series of notes and rests with duration and pitch, like this:

     Note 100 60
     Note 100 62
     Note 200 64
     Note 100 67
     Rest 100
     Note 300 67

("Rest" statements in the input file are rests; they have simply a duration, no pitch.) The program "concatenates" them, giving each note an ontime and offtime and adding it on to the previous note:

     Note 0 100 60
     Note 100 200 62
     Note 200 400 64
     Note 400 500 67
     Note 600 900 67

The former format can be convenient to use if one is constructing a notefile by hand (though it can only be used for monophonic pieces). Of course one can also use this in conjunction with "tempo-adjust.c"--for example, using small time values such as 1 and 2 to construct the original notefile, and then multiplying them by an appropriate large value.

gen-add. This program takes a "note-beat file" - a list of notes and beats, as generated by the meter program - and generates a list of note-addresses statements. Each note-address statement lists the ontime, offtime, and pitch of each note, along with an "address" indicating the location of that note in the metrical grid. See Temperley, "An Evaluation System for Metrical Models" (Computer Music Journal 28/3) for explanation.

compare-na and tally-na. The program compare-na takes two "note-address" files of the kind generated by gen-add and compares them, scoring the second file in terms of its similarity to the first. The program tally-na takes a series of outputs of compare-na and outputs an overall score. This system could be used for evaluating a set of "testfiles" outputted by a meter program in terms of their similarity to correct "goldfiles". See Temperley, "An Evaluation System for Metrical Models" (Computer Music Journal 28/3) for explanation.

tally-na. This program takes two "note-address" files of the kind generated by gen-add and compares them, scoring the second file in terms of its similarity to the first. See Temperley, "An Evaluation System for Metrical Models" (Computer Music Journal 28/3) for explanation.

INPUT FILES. We also provide a large number of input files which may be of use in exploring and testing the program (and also in comparing it with other programs). Many of the files relate specifically to tests and musical examples in Temperley's book The Cognition of Basic Musical Structures. The input files are of six kinds:

midifiles are standard midifiles.

notefiles consist of "note statements", of the form "Note [ontime] [offtime] [pitch]". (Ontime and offtime are assumed to be in milliseconds; pitches are specified in integer notation, with middle C = 60.) Notefiles can be used as input for the meter program.

nbfiles ("note-beat files") consist of note statments plus "beat statements", of the form "Beat [time] [level]". ("Level" indicates the metrical level at which that beat is present; see the meter program documentation for further explanation.) Such files can be produced by the meter program, and used as input to the grouper, streamer, harmony and key programs.

ncfiles ("note-chord files"). These are like notefiles, but they also contain "chord" statements indicating harmony. Each chord statement is of the form Chord [ontime] [offtime] [root]. Note-chord files are not usable as input files to any of the Melisma programs, but some are included here as they contain nformation that may be useful (see below).

nafiles ("note-address files"). This is essentially another way of encoding the information in note-beat files. An nafile consists of a list of Anote statements, of the form "Anote [ontime] [offtime] [pitch] [note address]". The note address of an event indicates its position in the metrical grid.

kfiles consist of TPCNote statements, beat statements, and chord statements. TPCNote statements are like note statements, except they also specify a TPC or "tonal-pitch-class": "TPCNote [ontime] [offtime] [pitch] [TPC]". Chord statements indicate a segmentation of a piece into "chord spans", each one having an ontime, an offtime, and a root: "Chord [ontime] [offtime] [root]". Such files can be produced by the harmony program, and can be used as input to the key program; see the documentation for further information.

These six kinds of input files are kept in directories of the same name. Each directory has several sub-directories. The directories called "wtc" contain the fugue subjects (opening themes) from the 48 fugues of Bach's Well-Tempered Clavier. Directories called "kp" contain musical excerpts from the textbook Harmony, by Stefan Kostka and Dorothy Payne; we call this the Kostka-Payne corpus. Directories called "kp-perf" contain performed, rather than quantized, files for the 19 excerpts from the Kostka-Payne corpus for solo piano. Directories called "essen" contain folk melodies from the Essen database, a collection of European folk music.

Finally, directories called "misc" contain a miscellanous assortment of files. For description of these files, see the text document "notefiles/misc/COMMENTS". This describes the notefiles in that directory; this can also be used to identify miscellaneous midifiles, nbfiles, and kfiles, which generally have corresponding names. For example, as indicated in "COMMENTS", the file cmainv.q.notes is a quantized file for Bach's Two-Part Invention in C major; the midifile midifiles/misc/bach.cmainv.q.mid is the midifile for this same piece. The miscellaneous files are of two kinds: "quantized" files (identified with ".q") generated artificially and thus containing completely regular timing; and "performed" files (identified with ".p"), generated from performances on a MIDI keyboard.

Notice that not all notefiles have corresponding midifiles, nbfiles, nafiles, and kfiles. Moreover, there is no guarantee that (for example) running a notefile through the meter program will produce an nbfile identical to the nbfile of the same name. In some cases we may have generated a file with special parameters, or modified a file after generating it.

We have tried to make sure that the information in these files is correct (with one exception described below). For example, the nafiles, nbfiles and kfiles should contain correct metrical information. In particular, the directories nafiles/kp-correct and nafiles/kp-perf-correct contain hand-corrected nafiles for the Kostka-Payne corpus; these are intended to be used as "goldfiles" for the testing of metrical models.

The directory ncfiles/kp contains chord information representing correct harmonic analyses of the excerpts in the Kostka-Payne corpus (as provided by the authors of the textbook); this information was encoded by Bryan Pardo. By contrast, the harmonic information in the files in kfiles/kp was generated by the Melisma harmony program and may not be correct.

SCRIPTS. We include a few "shell scripts" that may be useful. (Shell scripts are simple programs that allow one to run complex or multiple UNIX commands with a single simple command.) In order to use these scripts, you may have to type "chmod a+x [script]" to make it executable.

The scripts "wtc-script" and "kp-script" can be used to run the Well-Tempered Clavier and Kostka-Payne corpora through the key program, thus simulating tests reported in The Cognition of Basic Musical Structures. The script "essen-script" runs the Essen folksong corpus through the grouping program. (Run them simply by typing "wtc-script", etc.).

Scripts can also be used to "pipe" the output from one program into another. There are many ways that this might be useful. We have provided one simple example, a script called "met-harm-key". This takes a notefile as input (run it like this: "met-harm-key [input-file]"), runs it through the meter program, then pipes the outputted note-beat list into the harmony program, then pipes the outputted TPCNote-beat-chord list into the key program, and finally outputs a key analysis to the screen.

The script "met-harm-twopass" is an experimental script which essentially runs an input file through both the meter and harmony programs twice. This was motivated by the observation that the meter program sometimes functions better if it has access to harmonic information: namely, where the chord changes are. The "met-harm-twopass" script works as follows. First it runs a notefile into the meter program, but with the parameter "highest_level=2", so that no levels above the tactus are generated. Then this is run into the harmonic program, with the parameter "prechord_mode=1". This causes the harmonic program to output only the note list and a list of "Prechord" statements indicating the timepoints at which it found chord changes. This is then run back into the meter program. The meter program recognizes "Prechord" statements and gives a bonus for having strong beats at these timepoints. The output of the meter program is then piped into the harmonic program in the normal fashion.