The humlib library is of a set of C++ classes for parsing Humdrum data files. It is easy to incorporate into your project by adding these two files:

  1. An include file humlib.h
  2. and a source file humlib.cpp

The source code uses some C++11-specific features, so add the -stc=c++11 option when compiling with GNU g++ or the clang++ compiler. Also include the -stdlib=libc++ option when compiling with clang. See the Makefile for compiling the library and Makefile.examples for compiling and linking executables.


For minimal use of the library, you can download the composite header and source files. In a terminal, download with wget (most common method for linux) by typing:


Or with curl (most common method for OS X):

curl -o humlib.h
curl -o humlib.cpp

To compile humlib as a stand-alone library, you can download a ZIP or tarball from the buttons at the top of this page, or you can use git in the terminal to download and allow easy updating:

git clone

To update to the most recent version of humlib if git was used to download the library, type anywhere in the humlib directory structure:

git pull


When downloading the git repository or a zip/tarball of the repository, compile the library with the command:


This should create the file lib/libhumlib.a, which can be used to link to other program code. (But note that you can also simply copy the .h and .cpp files listed above into your own project files if you don’t want to link against a separately compiled library file). Primarily for testing purposes, another form of the library can be compiled from the individual source files for each class:

make lib

This will create the file lib/libhumdrum.a.


Here is a short program that uses the humlib library to convert a Humdrum file into a MIDI-like listing of notes:

#include "humlib.h"

using namespace std;
using namespace hum;

void printNoteInformation(HumdrumFile& infile, int line, int field, int tpq) {
	HTp token = infile.token(line, field);
   int starttime = infile[line].getDurationFromStart(tpq).getInteger();
   int duration  = token->getDuration(tpq).getInteger();
   cout << Convert::kernToSciPitch(*token)
        << '\t' << token->getTrackString()
        << '\t' << starttime << '\t' << duration << endl;

int main(int argc, char** argv) {
   if (argc != 2) {
      return 1;
   HumdrumFile infile;
   if (![1])) {
      return 1;
   int tpq = infile.tpq();
   cout << "TPQ: " << tpq << endl;
   cout << "PITCH\tTRACK\tSTART\tDURATION" << endl;

   for (int i=0; i<infile.getLineCount(); i++) {
      if (!infile[i].isData()) {
      for (int j=0; j<infile[i].getTokenCount(); j++) {
			HTp token = infile.token(i, j);
         if (token->isNull()) {
         if (token->isKern()) {
            printNoteInformation(infile, i, j, tpq);
   return 0;

Test data for use with the above program:

Example input:
**kern  **kern
*M3/4   *M3/4
8C      12d
.       12e
8B      .
.       12f
*       *^
4A      2g      4d
4G      .       4c
*       *v      *v
=       =
*-      *-
Example output:
TPQ: 6
C3      1       0       3
D4      2       0       2
E4      2       2       2
B3      1       3       3
F4      2       4       2
A3      1       6       6
G4      2.1     6       12
D4      2.2     6       6
G3      1       12      6
C4      2.2     12      6

If you are using the humlib project directory, place your own programs into a subdirectory called myprograms, and then to compile, go to the base directory of the humlib code and type make myprogram if the program is called myprograms/myprogram.cpp. The compiled program will be created as bin/myprogram.

For more information see: