SYNOPSIS
OPTIONS
DESCRIPTION
# **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:
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 \
prelude28-03-trans.png
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:
Barline number axisIn 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.
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 optionsTrimNotice 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. Blank 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.
Fill 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.
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
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). 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
Keyscape of Tchaikovsky's Symphony No. 4 in F minor, Op. 36, Movement 4: Finale: Allegro con fuoco:       Keyscape of Schenker's Heimat, Op. 6, No. 1:  ONLINE DATA
program file.krnIt can also read the data over the web: program http://www.some-computer.com/some-directory/file.krnPiped data works in a somewhat similar manner: cat file.krn | programis equivalent to a web file using ths form: echo http://www.some-computer.com/some-directory/file.krn | 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.krnwill 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 SEE ALSODOWNLOAD
The source code for the program was last modified on 21 Oct 2012. Click here to go to the full source-code download page. |
