humlib

The humlib library consists of a set of C++ classes for parsing Humdrum data files, used for digital encodings of musical scores. 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

All other source-code files are irrelevant unless you are developing the library or need to create the command-line tools. For example verovio, a music notation rendering library, uses humlib as an internal sublibrary for importing Humdrum data, placing humlib.h here, and humlib.cpp here. (see the .download scripts in those directories for how updates are managed).

Most command-line tools are implemented as C++ classes, found in files that start with tool- in the src directory. For example, here is a use of the colortriads and satb2gs tools inside of verovio to create colorized version of Bach chorales on the Grand Staff.

Resources

Humlib website Documentation Class overview Code snippets Example programs Topics Tutorial

Downloading

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 console to download and allow easy updating:

git clone https://github.com/craigsapp/humlib

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

Minimal downloading

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

wget https://raw.githubusercontent.com/craigsapp/humlib/master/include/humlib.h
wget https://raw.githubusercontent.com/craigsapp/humlib/master/src/humlib.cpp

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

curl https://raw.githubusercontent.com/craigsapp/humlib/master/include/humlib.h -o humlib.h
curl https://raw.githubusercontent.com/craigsapp/humlib/master/src/humlib.cpp -o 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.

Compiling

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

make

This should compile the file lib/libhumlib.a as well as the command-line tools in cli into the humlib/bin directory..

make library

This is similar to make, but only compiles the library file and not the command-line tools.

make lib

Used for testing purposes only, this make target compiles the uncollated library files, making it easier to debug the source code.

Example

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 (!infile.read(argv[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()) {
         continue;
      }
      for (int j=0; j<infile[i].getFieldCount(); j++) {
         HTp token = infile.token(i, j);
         if (!token->isKern()) {
            continue;
         }
         if (token->isNull() || token->isRest()) {
            continue;
         }
         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 PITCH TRACK START DURATION 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 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.