Humdrum Extras

mkeyscape manpage


    mkeyscape -- Generate keyscapes from MIDI files or Humdrum **kern data.


    mkeyscape [options[input[> output]


-b Post-process the initial key analyses so that key regions which are not are touching the bottom of the plot are blanked out. (see -f option to try to fill blank regions).
-c file Key to color mapping file which controls the colors in the output plot. See below for color file format.
-C Print the color map which will be used and then exit without doing anything. Useful for generating your own color map by editing the default settings.
-D Suppress the drum track (Channel 10) from being analyzed in General MIDI files.
-f Post-process the key analyses to fill in spots blanked out when using the -b option. Blanked spots will be filled in with the second-best key, provided that it is found in an adjoining region. If -f is used, then the -b option will automatically be set.
-l Display a key to color mapping legend beneath the keyscape plot. One octave of a keyboard is displayed with the color of the tonic for that key display. Two colors are displayed on each key: the higher color (typically darker) is the color for the minor mode, and the lower (typically brighter) color is for the major mode.
-m string User the following pre-defined color-map set rather than the default color mapping. Possible string values include: castel.
-n Display a measure-number line below the keyscape plot. Measure numbers divisible by 100 are marked with 10-pixel high markers with a cross-bar at the bottom. Measure numbers divisible by 50 are 8 pixels high; divisible by 10 are 6 pixels, divisible by 5 are 4, and other measures measures are 2 pixels. Repeated measures will be displayed in different colors. By default, barline ticks are colored black. The second repeat of measures are red, third repeats are blue, fourth repeats are green, and more repetitions are colored orange.
-r Output the raw key analysis results before converting into an image. The major keys are the numbers 1 through 12 starting on C. The minor keys are the negative numbers -1 through -12 starting on C at -1. Silence in the input file is represented by the number 0. The first line of output is the top-level analysis which contains only one number. The bottom line contains the key analysis for each evenly spaced segment of the music.
-s size Specifies the number of equal segments to chop the music up for analysis. Equivalent to the height in pixels of the output graphic image. The default size is 300. The width of the image is twice the height (600 pixels is the default).
-t # Transpose the music by the specified number of half-steps in the range from +/- 12.
-w file Set the key profile weights from an input file. There are several related options which use pre-defined weightings:
--aarden or --aa Weightings derived by Bret Aarden from the Essen folksong collection
--bellman or --bb Weightings derived by Hector Bellman from the classical music chord frequencies collected by Helen Budge
--krumhansl or --kk Original weightings derived from perceptual experiments by Krumhansl and Kessler
--kostkapayne or --kp Weightings derived by David Temperley from musical examples found in the Kostka-Payne textbook, Harmony
--simple or --ss Simple weightings useful as a control set.
-W Print the key weights which will be used and then exit without doing anything. Useful for generating your own key profile weightings by editing the default settings.
-x string Suppress specified MIDI channels from being analyzed. The option string consists of a list of channels to be excluded, with the channels being specified as hexadecimal digits. MIDI channel 1 is the character "0", MIDI channel 10 is the character "9", MIDI channel 11 is "A", and MIDI channel 16 is "F". Specifying the option -D is equivalent to the option -x "9".
--aa Use Aarden-Essen key-profile weights for correlation measurements.
--bb Use Bellman-Budge key-profile weights for correlation measurements.
--ss Use simple key-profile weights for correlation measurements.
--kk Use Krumhansl-Kessler key-profile weights for correlation measurements.
--kp Use Kostka-Payne key-profile weights for correlation measurements.
--khist Outputs a histogram of the key analyses found in the keyscape. Measures the area coverage for each key.
--hist Outputs the base twelve-tone pitch-class histograms used to construct the plots.
--no-outline Suppress the black borders in the key-to-color mapping legend displayed with the -l option.
--trim Post-procesing of the key analyses which is used to trim key region which are bounded on the bottom of the key plot by a larger key region. See also the -f and -b options. If --trim is used, then -b and -f options will be set.


    mkeyscape produces a visual summary of key analysis results for various segmentations of the musical data. The "m" stands for MIDI-enabled. Input data can be either a standard MIDI file, or a Humdrum file containing one or more spines of **kern data. The program recognizes MIDI files by the file extension ".mid". Any other file extension will be treated as a Humdrum file. Humdrum data may be piped to the program on the command-line, although MIDI data cannot be piped into the program and must be specified with a filename as a command-line argument. Here are some basic example usages:
          # **kern data processing:
          mkeyscape file.krn > file.ppm
          mkeyscape file.krn | pnmtopng > file.png
          cat file.krn | mkeyscape > file.ppm
          cat file.krn | mkeyscape | pnmtopng > file.png
          # MIDI data processing:
          mkeyscape file.mid > file.ppm
          mkeyscape file.mid | pnmtopng > file.png

    Graphical output from the program is a format called PPM 3 which is a text-based image format. Here is a sample of raw output data from mkeyscape which is 3 pixels high and 6 pixels wide:

    mkeyscape prelude28-03.krn -s 3

    The first column contains the string "P3" which indicates the data format for a text-based PPM image file. The second line contains two numbers: The width of the image in pixels, and the height of the image in pixels. The third line contains the maximum color value in the list of numbers which follow. In this case each color value represents one byte of data and the maximum value is 255. Following the header information is a serial list of the pixels in the image.

    Each pixel is represented by three numbers. The first number represents the amount of red in the pixel, the second number is for green, and the last number is for blue. White is represented by maximum brightness for all pixels: "255 255 255" and black by minimum brightness for all colors: "0 0 0".

    In this case are a total of 18 pixels and therefore 54 numbers are expected after the header. The formatting of the lines is arbitrary, but in this case the numbers map how the final image is to be displayed. The pixel list starts at the top left of the image, going left to right, then through successive rows to the bottom of the picture. Thus in this case, you can see that there are 18 pixels on each row, representing the 6 pixels on each row of the image, and there are three rows of pixels which represent the 3 pixels height of the image. Here is the PPM image converted to a visual graphic: .

    Graphic File Conversion and Processing

    PPM images can be enormous and take a lot of space to store, so you will probably want to store the output images in another format. If you want to store the PPM images (for later processing with text-based programs, for example), you might want to consider compressing them:

          bzip2 prelude28-03.ppm
    will create a file called prelude28-03.ppm.bz2 which is even smaller than other graphics types you could convert the image to. To uncompress the file, type "bunzip2 prelude28-03.ppm.bz2 or you can pipe a temporary output to another program with "bzcat prelude28-03.ppm.bz2 | less, where less is an example program you can send the uncompressed data to.

    Most of the time, however, you will probably prefer to store the resulting images in a more convenient image format, such as PNG. Here are two ways of converting the PPM 3 data into PNG data:

    (1) From the command-line the output PPM data can be piped to another unix command called pnmtopng which is often pre-installed on linux computers. The following command-line:

          mkeyscape -s 150 prelude28-03.krn | pnmtopng > prelude28-03.png
    will generate the following PNG image which is 150 pixels high, and 300 pixels wide:

    (2) Another program which can convert PPM images on the command-line is called convert. This program is more widely distributed, and has more features since it can convert almost any image format to any other image format. To accomplish the same task with convert, you would type two commands:

           mkeyscape -s 150 prelude28-03.krn > prelude28-03.ppm
           convert prelude28-03.ppm prelude28-03.png
    With convert you can also resize the image at the same time. For example if you want to make a thumbnail image when you convert, you can try this command:
           convert prelude28-03.ppm -resize 50 prelude28-03-tn.png
    which generates the 50x25 pixel thumbnail image shown to the right.

    Another useful feature of convert is the ability to add text on top of the image:

           convert prelude28-03.ppm -font NewCenturySchlbk-Roman -pointsize 12 \
                -draw "text 5,20 'Chopin prelude 28/3' prelude28-03-text.png
    which produces text starting at pixel (5,20) from the top left corner of the image:

    A list of fonts recognized by convert can be found in configuration files which are found on my computer in the directory /usr/lib/ImageMagick-6.2.4/config. Here is a list of fonts which might work for you based on the files in that configuration directory: fontlist.txt.

    Another use of the convert program is to generate a transparent background. Here is a rather painful way of making the white background of the image transparent:

          convert prelude28-03.png -bordercolor white -border 1x1 -matte \
                  -fill none -fuzz 5% -draw 'matte 0,0 floodfill' -shave 1x1 \
    which generates this image:

    A command-line program called transparency may also be use to create transparent backgrounds. You will probably have to install this program, since it does not come with OS installations by default. Also, you could save this bash script to a file:

    For example, save the above text to a file called maketransparent. Then make sure that it is executable by typing "chmod 0755 maketransparent", and then run by giving the original file name first, followed by the filename of the image with the transparent background:

          maketransparent oldfile.png newfile.png
    If your program search path does not include the current directory, you will have to type:
          ./maketransparent oldfile.png newfile.png

    Key to Color Mapping

    Key color representation is ultimately arbitrary, but the convention in the mkeyscape program is to assign the seven colors of the rainbow to the seven diatonic-pitch classes, arrange by circle of fifths with the C pitch-class centered at green: red=E, orange=B, yellow=F, green=C, blue=G, indigo (dark blue) = D, purple=A. By adding the -l, a key-to-color mapping legend will be displayed underneath the plot. Here is the default mapping:

    Minor keys are shown in a darker hue of the parallel major key. Chromatic alterations of the diatonic pitches are displayed in intermediate colors along the circle-of-fifths. For example F is yellow, and F-sharp is a greenish-yellow, and F-flat is an orangish-yellow.

    By using the -m option, you can use other key-to-color mappings. Pre-defined color mappings available include:

    castel Derived from Louis Bertrand Castel's ocular harpsichord colors with colors of the rainbow progressinging diatonically from G downwards.
    newton Derived from Isaac Newton's mapping of seven diatonic pitches to the seven main colors of the rainbow.

    Barline number axis

    In order to coordinate between a musical score and a keyscape plot, you can use the -n option to display a number line underneath the plot which indicates the location of barlines in the music. Barlines will not be displayed in the plot when MIDI files are used as input data, only Humdrum input files will be parsed or barline information.

    Barlines which are multiples of 100 generate tick marks which are 10 pixels tall, and also contain a short horizontal bar at the bottom of the tick so that it is easier to differentiation 100's from other numbers. Multiples of 50 create 8-pixel high ticks; multiples of 10 create 6-pixel high ticks; multiples of 5 create 4-pixel high ticks; and other measure tick marks are 2-pixel high. If 2-pixel barline ticks would crowed too closely together under the plot, they will be suppressed.

    In the following example for the first movement of Beethoven's fifth symphony, there are about 500 measures which can be seen by couting the 100's tick marks. Since the image is 600 pixels wide, single-measure ticks are not displayed. Instead the smallest division is a 5-measure interval.

    With the barline markers below the plot, it is easy to locate modulation boundaries in the score.

    measure     1 Exposition, first theme in C minor (dark green)
    measure   60 Exposition, second theme in E-flat major (pinkish-red)
    measure 125 Development, starting with F minor (dark yellow)
    measure 250 Recapitulation, first theme in C minor (dark green)
    measure 303 Recapitulation, second theme in C major (light green)
    measure 375 Coda, starting with F minor, but mostly in C minor (dark yellow/dark green)

    The barline ticks are control by measure numbers in the data, not by their sequence. Barline numbers must be present in the input data file in order for them to be displayed under the plot. You can use the barnum command to automatically number music which does not contain barline numbers.

    If music is repeated, the barline ticks will change color to indicate which repeat is being done in the music. First occurences of a barline number will cause the ticks to be colored black (or the color which indicates "silence" in the keyscape plots). Other repeats will be given in different colors. The default color for the second repeat of barline numbers is red, as shown in the following example where the expostion section of the previous example is repeated. Third repeats are blue by default. 4th repeats are green by default, and additional repetitions are orange.

    In this case the 100's markers represent 100, 100, 200, 300, 400, and 500; with the second 100 found in red on the numberline.

    Post-processing options


    Notice that the key-regions boundaries in the Chopin G major prelude are localized in the score at the bottom of the plot, but the dominant and subdominant regions expand outwards from their actual positions in the score at higher levels in the plot. However this outward expansion is only due to limits in the measuring process. This sort of measurement artifact can be somewhat compensated for by using the --trim option. The result of using -trim is shown on the right.

    The basic rule for trimming is: if a key region can encompass another then limit the encompased key region borders withing the encompassing limits. In the above case, the light blue region encompasses both the blue and green regions. First, some preprocessing (called tonal-biasing) is done which connects the light-blue region on the left-hand side of the plot to the larger light-blue region.


    Using the -b option, blanking is applied to the raw key analyses in the plot. Blanking removes any key region which does not touch the bottom of the plot (the lowest-level key regions approximately equivalent to chord roots). The rationale being that if a key region does not contain any chords within that key, the region is more likely to be noise which might as well be removed. In the pair of plots below, the plot on the left contains all of the raw key analyses. The plot on the right removes all color regions which do not touch the bottom of the plot.


    A secondary step in post-processing is to try and fill in the blank spots with the second-best key measurements for each pixel. To do this, use the -f option. If -f option is given but the -b option is not, then the -b option will be turned on automatically.

    All black regions will be examined when this option is specified. If a neighboring colored/key region matches to the second-best key in the blanked area, then the second-best key is displayed instead of the blank. Notice that filling of this example cleans up the image, and nearly all of the initial blank pixels have been filled.

    The --trim option automatically blanks and fills the plot before attempting to trim key regions.

    Absolute Key vs. Functional Key

    When comparing the key structure of large numbers of compositions in different keys, it is useful to color the keys functionally rather than with the absolute pitch color. For example, if green (usually representing the pitch class C) is defined as the tonic key, then the dominant key is in light blue, the subdominant color is yellow, and so on.

    In a Humdrum file, if the start of a composition contains a key specification, then you can transpose the music to C major, and interpret the key colors functionally rather than as absolute pitch-class colors. For example, using the transpose command, you can easily convert prelude28-03.krn to C major before sending it to mkeyscape to be converted into an image:

          transpose -k c prelude28-03.krn | mkeyscape -s 150
    The file prelude28-03.krn contains a marker for G major, *G:, which is used to instruct the transpose program how to convert the music into C major. If there is more than one primary key in the music, all other subsequent key-regions are ignored during the transposition. In other words, the dominant key of the dominant key will be displayed in dark blue, just as the supertonic key will be (there will be a brightness difference though, since the first is a major key and the second in a minor chord/key). Here is the resulting image when transposing to C major.

    Now, the tonic color is green, the dominant is blue and the subdominant key region is yellow.

    MIDI input can be transposed using the -t option to transpose the music before key analysis is done. For example to transpose the music up by a perfect fifth, you can type either of the two commands:

          mkeyscape -t 7 file.mid
          mkeyscape -t -5 file.mid
    Which will transpose the music up 7 steps, or equivalently, down 5 steps.

    Humdrum file data can also be transpose in this manner, but there is no automatic method to transpose the key to C major/minor with the -t option. Also, transposition in twelve-tone space will involve enharmonic errors which might disrupt the functional color display. But since the color display in this version of the keyscape program only displays 12 colors per octave, this shouldn't be a problem.

    Underlying Key Analysis Method

    Key analysis is accomplished by comparing a histogram of the pitch-classes to what would be expected in each major and minor key. The key which fits best is then assigned a color in the keyscape plot. The algorithm used in mkeyscape is the Krumhansl-Schmuckler algorithm which does a Pearson correlation between the measured histogram of pitch classes and the pre-determined profiles for major and minor keys. Pearson correlation generates a value between -1.0 and +1.0 for the comparsion between the histogram and a particular key profile with better matches being given higher values. The key-profile which generates the highest Pearson correlation to the measured histogram of pitch classes is decided to be the key of the musical region.

    When modulation occurs inside of the region of music being analyzed, the algorithm may prefer one key over the other, or it may even decide on a third key, generating noise in the keyscape plot. If the analysis results of this algorithm were ideal, the following picture would be generated for Chopin's prelude Op. 28, No. 3.

    The music start in G major (the tonic), then goes into the dominant key area, returns to the tonic, then goes into the subdominant key region for a longer period than when in the dominant, and finally returns to the tonic at the end of the piece.

    Analysis Data

    Using the --hist option will output a histogram of the pitch-classes for every segment. Here is the output from the command keyscape --hist prelude28-03.krn -s 10:

    The values in the histogram are relative to the duration of the frame. If you want the values in the histogram to represent the number of quarter notes of each pitch-class in each segment, use the scordur program to find the duration of the music in beats. For prelude28-03.krn, the duration is 132 beats, so the command: "mkeyscape -s 132 --hist prelude28-03.krn" will give this result:

    The --hist output data is similar to Chromograms extracted from audio data (but there is no interference from harmonics).

    Color File Format

    Using the -c option allows you to specify any color for the 24 major / minor twelve-tone keys as well as the color for silence (default is black) and the background image color (default is white). The color file is a text file in the Humdrum file format as shown in this example:

    There must be a spine called **index and a spine called **pixel. There can be any number of other spines, such as **comment in the example file, and the index and pixel spines can occur in any position. If there are more than one index or pixel spine, the ones furthest to the right will be used.

    The above example color file is also the default color scheme for mapping keys to color. If you only want to change specific colors and keep the rest as in the default, you only have to specify the colors you want to change. For example, if you only want to change the background color from white to black, you could use this color file:

    Key Profile Weights



    Input arguments or piped data which are expected to be Humdrum files can also be web addresses. For example, if a program can process files like this:
           program file.krn
    It can also read the data over the web:
    Piped data works in a somewhat similar manner:
           cat file.krn | program
    is equivalent to a web file using ths form:
           echo | program

    Besides the http:// protocol, there is another special resource indicator prefix called humdrum:// which downloads data from the kernscores website. For example, using the URI humdrum://brandenburg/bwv1046a.krn:

          program humdrum://brandenburg/bwv1046a.krn
    will download the URL:
    Which is found in the Musedata Bach Brandenburg Concerto collection.

    This online-access of Humdrum data can also interface with the classical Humdrum Toolkit commands by using humcat to download the data from the kernscores website. For example, try the command pipeline:

          humcat humdrum://brandenburg/bwv1046a.krn | census -k



    The compiled mkeyscape program can be downloaded for the following platforms:
    • Linux (i386 processors) (dynamically linked) compiled on 28 Jun 2012.
    • Windows compiled on 29 Jun 2012.
    • Mac OS X/i386 compiled on 13 Nov 2013.
    • Mac OS X/PowerPC (version 10.2 and higher) compiled on 13 May 2009.

    The source code for the program was last modified on 21 Oct 2012. Click here to go to the full source-code download page.