Humdrum Extras

xml2hum manpage


    xml2hum -- Convert MusicXML files into Humdrum files.


    xml2hum [input[> output]


-s # Convert only the specified staff.
-i Display MusicXML information (mostly for debugging).
-x Try to fix note spellings of data originating from MIDI files.
-S Do not print stem information in output **kern data.
-B Do not beaming information in output **kern data.
-D Do not dynamics information in output **kern data.
-N Do not notation information in output **kern data. Equivalent to -SB
-T Do not convert any text from lyrics.
-M Do not automatically fix measure numbers in MusicXML input.


    xml2hum converts MusicXML files into Humdrum files. MusicXML data is output from many music applications. A list of many of these programs is available at The main input sources of MusicXML data tested with xml2hum has been Finale which is a music typesetting program, and SharpEye which is a music scanning program. Japanese users may want to use Score Maker from Kawai for converting scanned music into MusicXML data.

    Generating MusicXML data from SharpEye

    After you have converted a scanned image of a piece of music in the SharpEye editor, you can save a MusicXML file by going to the "File" menu and then the "MusicXML" submenu as in the following illustration:

    SharpEye MusicXML Export

    Generating MusicXML data from Finale

    To export MusicXML data from Finale, you will first need to purchase the Dolet MusicXML plugin from Then start with an open file in the Finale editor, such as:

    Example melody in Finale editor

    Next, go to the "Plug-ins" menu and select "MusicXML Export..." as shown in the following illustration and save the music in MusicXML format:

    Extracting MusicXML data

    You should end up with a MusicXML file like the following example:

    To convert this file into a Humdrum file, run the command:

        xml2hum melody.xml > melody.krn
    melody.krn should contain the file contents:


    Converting a single staff of music

    To extract a single staff of **kern music from a MusicXML file, use the -s # option, where # is a number from 1 to the number of system staves present in the MusicXML file.

    If you do not know what the maximum number of staves in the MusicXML file, then use the -i option:

        xml2hum -i file.xml | head
           There is 1 part in the MusicXml File:
                   Part 1: id=P1   name=Part_1     staves=2
           PART DATA ================================
           Staff 1 ---------------------------------
           i=0     j=0     tick=0  tdur=6  voice=0 serial=1        name=measure (-1)
           i=0     j=1     tick=0  tdur=0  voice=0 serial=2        name=divisions
           i=0     j=2     tick=0  tdur=0  voice=0 serial=6        name=clef
           i=0     j=3     tick=0  tdur=0  voice=0 serial=3        name=key
           i=0     j=4     tick=0  tdur=0  voice=0 serial=4        name=time
           i=0     j=5     tick=0  tdur=0  voice=0 serial=5        name=time
           i=0     j=6     tick=0  tdur=6  voice=1 serial=8        name=note (d)

    For the example file, there were two staves of music found in the MusicXML file.

    To extract these two staves into separate files, you can do these commands:

        xml2hum -s1 file.xml > staff1.krn
        xml2hum -s2 file.xml > staff2.krn
    staff1.krn will contain the highest staff in the system, and staff2.krn will contain the lowest staff in the system.

    Assembling a score from individual parts

    Sometimes the xml2hum program does not generate correct humdrum files either due to errors in the input data or, more likely, bugs in its own converter to Humdrum data. When an error converting the MusicXML score occurs, then you should extract the individual parts separately and combine them with assemble after making any corrections to the individual parts.

    First review the previous section on extracting individual staves from a MusicMXL file. If your MusicXML file has two parts, for example, then extract each part to a separate file:

        xml2hum -s1 file.xml > staff1.krn
        xml2hum -s2 file.xml > staff2.krn

    Now you should determine why the xml2hum program failed to assemble the final score. Firstly you can look at the files and make sure that the contents look like Humdrum files rather than error messages. After that basic check, you can verify that the number of beats in each file is identical. If the number of beats does not match, then xml2hum was confused because it could not align the two parts. To check if the number of beats is equal for both files, use the scoredur program or the rcheck program:

        rcheck staff1.krn | grep = | tail -5
           235     0       3       ::      =79     =79
           238     0       3       ::      =80     =80
           241     0       3       ::      =81     =81
           244     0       3       ::      =82     =82
           247     0       0       ::      ==      ==
    The file staff1.krn contains 247 beats. Do the same with staff2.krn. Usually the two files with report a different beat length if xml2hum failed to combine them, so next you will have to edit the files to correct the problem. If the rcheck program cannot even parse the file, it will complain about a particular line, which is a good starting point in locating the problem.

    If the two files do not have the same number of beats but they are processed correctly by rcheck, then the next step is to view the numbers of beats in each measure using the rcheck program.

        rcheck staff1.krn | grep = | less
    Then look at the numbers in the third column. This number counts the number of beats in the measure. Look for measures where there is an incorrect number of beats in the measure and fix the problem by edting the file and correcting the rhythm error in that measure.

    Once the two files report the same duration according to scoredur and rcheck, you can combine the two files with assemble. To do that, first you must determine the minimum rhythmic unit which is common to both files with the minrhy program:

        minrhy staff1.krn staff2.krn
           staff1.krn:   48
           staff2.krn:   4
           all:          48
    In this case the minimum time unit for both files in 48 (triplet 32nd note). Next you need to match the timebases of both files using the 48 rhymic unit:
        timebase -t 48 staff1.krn > x1.krn
        timebase -t 48 staff2.krn > x2.krn
        assemble x2.krn x1.krn | rid -d > score.krn

    More example usages of the xml2hum program are available on the xml2hum examples page


    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 MusicXML parser is complete and is working without any known bugs. The converter that takes the MusicXML data and converts it into Humdrum data has several limitations due to the simple conversion model. In particular, only valid data is only expected to be generated when there are two or fewer voices on a staff. If there are three or more voices on a staff, the program may convert correctly, but possibly it will generate invalid Humdrum syntax or may even crash. To convert files in these cases, you should try to extract the individual staves to separate files and combine with the assemble command.
    • Sometimes **dynam data is added incorrectly in the middle of notes by not adding a null token to the **kern spine. This generates incorrect Humdrum syntax. This error will prevent an assembled score from being generated, but will not prevent a single staff from being extracted.


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

    The source code for the program was last modified on 26 Jun 2010. Click here to go to the full source-code download page.