Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


AppVeyor Build Status

The humlib repository consists of a set of C++ classes for parsing Humdrum data files, used for digital encodings of musical scores. In addition, Humlib includes command-line tools that also can be used via JavaScript in web applications. This is easiest done through the notation renderer verovio, and in particular with Humdrum Notation Plugin. Online use of most tools can be done when editing Humdrum files in Verovio Humdrum Viewer.

Using humlib as a C++ library

The library is designed to be portable with only two source-code files to copy into your project:

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

Plus three Pugixml files used for parsing/writing data in the XML format:

  1. The pugixml include file pugixml.hpp
  2. The pugixml configuration file pugiconfig.hpp
  3. The pugixml source file pugixml.cpp

All of these files can be copied from the min directory into your project. For example, verovio include the humlib.cpp and humlib.h and independently uses the pugixml library for processing XML data (MusicXML and MEI).


Documentation for humlib source code can be found at

Documentation for the tools can be found at

Download and compiling

To download humlib with git in a directory where you want to store humlib:

git clone

To compile, run the command:

cd humlib

This will compile both the library and command-line tools found in cli. To compile only the library:

cd humlib
make library

To download updates of the humdrum repository, use the command:

make update

after which you can recompile the library and programs:


Minimal downloading

For minimal use of the library with your own project, you can download just the composite header and source files (and pugixml library). In a terminal you can download with wget (on linux):


Or with curl (most common method downloading on the comnmand line in MacOS):

curl -o humlib.h
curl -o humlib.cpp
curl -o pugixml.hpp
curl -o pugixml.hpp
curl -o pugiconfig.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. (See the humlib Makefile). In particular, 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 the command-line tools.


Here is a short example 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(HTp token, int tpq) {
   int duration  = token->getTiedDuration(tpq).getInteger();
   int starttime = token->getDurationFromStart(tpq).getInteger();
   vector<string> chordnotes = token->getSubtokens();
   for (size_t i=0; i<chordnotes.size(); i++) {
      cout << Convert::kernToSciPitch(chordnotes[i])
         << '\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].getFieldCount(); j++) {
         HTp token = infile.token(i, j);
         if (!token->isKern()) {
         if (token->isNull() || token->isRest()) {
         printNoteInformation(token, 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

Writing your own command-line tools with Humlib:

If you are using the humlib project directory to compile your own programs (or this test program), place them into the cli (Command-Line Interface) subdirectory.

Then to compile, go to the base directory of the humlib repository and type make myprogram if the program is called humlib/cli/myprogram.cpp. The compiled program will be created as bin/myprogram.

To run from the humlib directory type bin/myprogram file.krn, for example. You can also either copy your program to /usr/local/bin or set the $PATH variable to include humlib/bin in the executable search path.

See the Coding-examples documentation for more programming examples.


No releases published


No packages published