Humdrum Extras

humplay manpage


    humplay -- Play Humdrum files interactivly with MIDI.


    humplay [input(s)]


-e # Tempo scaling factor for all playback tempos.
-m ms Minimum duration of notes in milliseconds.
-s ms Shorten notes by given millisecond amount.
-p sec Pause between multiple files/movements by given time in seconds.
-q Quiet mode: don't display Humdrum data while playing.
-t # Set the default tempo (120=default, or read from **MM120 style records)..
-v # Set the default key velocity of played notes.
-Q Suppress main command window on startup.
--ports List the available MIDI I/O ports for playback.


    Real-time Commands

    b   Set the colorization style to a black background. See also w and c.
    c Toggle colorization / plain text display of the Humdrum data. See also b and w.
    e Display the exclusive interpretation for all spines currently being played.
    k Toggle hiding/showing of non-kern spines. This is useful if the spine count is too large to display in the width of the screen, and there are non-kern spines present in the data.
    #l (lower-case L) Transpose the performance up the specified number of half-steps from the written pitch. Typing l without a number will transpose to the original written pitches.
    #L Transpose the performance down the specified number of half-steps from the written pitch. Typing L without a number will transpose to the original written pitches.
    #m Mute/Unmute the MIDI output. You can mute particular **kern spines independently by typing a spine number before m. For example 1m will turn off MIDI output of the first (left-most) **kern spine (Other non-kern spines are ignored with the m command). Typying 1m a second time will unmute the first **kern spine so that it is audible again. In colorization modes the muted spines are displayed in a different color than the regular spines (dark blue for black mode, and yellow for white mode). To solo a particular spine, for example the third **kern spine, type m3m. The first m will mute all spines, and 3m will unmute only the third **kern spine.
    n Toggle display of notes only or full **kern data. When turned on, the option will suppress beaming and stemming information on notes which will make it easier to read the sounding information such as pitch, rhythm and accidentals.
    #o (lower-case O) Set the tempo in (quarter-notes per minute) to the given number typed before o. Valid tempo values are in the range from 21 to 600. If you need to play in a tempo outside of this range, use the ,, <, ., and > keys. If you press o without typing a tempo marking first, the computer will display the current tempo of the music.
    p Pause/unpause playback of music.
    q Quiet mode: do not display Humdrum data while playing it.
    #r Return to the specified mark which was created by pressing the space key. If no number is given, then the command will go back to the most recently created mark with the space bar.
    R Print a list of all marks created with the space bar.
    s Silence currently-playing notes. Holding down the s key will generate stacatto texture.
    t Increase the tab-size which controls spine width by one character.
    T Decrease the tab-size by one character.
    w Set the colorization style to a white background. See b and c
    x Clear the screen and start printing from the top of the screen.
    #space Mark the playback location in the file with the current line, the current absolute beat (number of quarter notes since the start of the file), the measure number (if explicitly given on barlines in the data), and the beat number in the measure. Useful for marking errors during prooflistening or for marking interesting points in the file for later examination. Try using this command after pressing the q key. Up to 1000 marks can be stored the space bar and recalled with g. If you type the space bar without typing a number first, the mark will be stored in the next memory location. If you type a number between 1 and 1000, then the mark will be stored at that position.
    , Slow down the tempo by 3%.
    < Slow down the tempo by 7%.
    . Speed up the tempo by 3%.
    > Speed up the tempo by 7%.
    #= Jump to specified measure number. A measure number is typed first, then = is pressed. If no number is given before =, then the music will be played starting at the first line of the input file. See also ^.
    #( Go back one measure in the score. If a number is typed before the parenthesis sign, then go back by that number of measures.
    #) Go forward one measure in the score. If a number is typed before the parenthesis sign, then go forward by that number of measures.
    _ (Underline character) Decrease the loudness of the MIDI output by one unit.
    + Increase the loudness of the MIDI output by one unit.
    ^ Start playing the file from the first line. See also =.

    Spine spacing

    If a spine cell exceeds the width of a tab, the last column in the tab-width for the spine will contain a '|' character. The width of the tab-character can be set during playback by typing t to increase the tab size, and T to decrease it.


    Colorization is turned on by default in humplay. It can be toggled on/off with the real-time command c. Two colorization styles are available: one with a black background which can be activated by typing the real-time command b, and another with a white background which can be activated by typing the real-time command w.

    Colorization is accomplished with ANSI escape codes, and in the future a configuration file can be used to use your own color scheme.

    Here is an example of a string quartet file being played using colorization. The first **kern spine (cello part) has been muted with the real-time command 1m, and the second violin part in the 5th spine (3rd **kern spine) has also been muted by using the real-time command 3m.

    Hiding/Showing non-kern spines

    Using the h real-time command, you can disable/enable the printing of non-kern spines to the screen. Here is an example screen shot where all spines are initially shown. Then the h key is pressed, and only **kern spines are shown. Next, the h key is pressed again, and all of the spines are displayed.

    Note the red highlighted line which was displayed by typing e immediately after typing h. The e real-time command displays the exclusive interpretation data for the currently playing spines. This is useful if you want to know what data type each spine represents after the initial exclusive interpretation line at the top of the file has scrolled off of the screen.

    Hiding/Showing print-only **kern data

    If you press the h key, only notes will be displayed in **kern data, with beaming and stemming information suppressed. This makes it easier to follow the sound data. Here is an example of using the h real-time command:


    Markers can be created by pressing the space bar. When a marker is created, a comment will display the line in the file, the absolute beat (number of quarter notes from the start of the file), the measure (if measures are encoded on barlines in the file), and the beat number inside the measure.

    Markers are stored in a buffer with 1000 locations. You can store a marker in a particular slot by typing the number of the marker before pressing the space bar. If you press the space bar multiple times to generate markers, the default storage of the marker is in the next higher slot.

    To return to a marker in the performace, use the r real-time command. If you type a number before the command, the specified marker will be recalled. If you type r without a preceeding number, the last marker generated by the space bar will be recalled.

    Using the R real-time command will print a list of all markers currently being stored. You can go to one of these markers in the list by using the r command.

    In the above example, r was pressed to generate the table highlighted in light blue which contains a list of the marks which had been generated while playing the file. In the exmaple, note that there is a gap between marks 3 an 77. This is due to mark 77 being explicitly created by typing 77 and then the space bar to store the mark in slot 77. Pressing the space bar after that created marks 78, 79, and 80. To return to mark 3, for example, type 3r.

    Performance Time/Tempo spine

    Future version will include **time or **tempo parsing to play non-score derived performance timing.


    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


    Humplay can be considered a semi-compatible replacement for the standard Humdrum Toolkit command perform (which is no longer maintained).


    Works with both software and hardware MIDI synthesizers in Microsoft Windows. Probably only works with external synthesizers on Apple OS X and Linux operating systems.


    The compiled humplay program can be downloaded for the following platforms:

    The source code for the program was last modified on 6 Mar 2013. Click here to go to the full source-code download page.