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:
- An include file humlib.h
- 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
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.