Here are examples of how to access data in a Humdrum score using the humlib classes:

[Close all] [Open all]

Reading/Writing

Read Humdrum data from a file, string or istream.

HumdrumFile infile;
infile.read(char* filename);
infile.read(string filename);

To read content from a char* or string:

infile.parse(stringstream content);
infile.parse(istream content);
infile.read(std::cin);
infile.parse(char* content);
infile.parse(string content);

See also the tutorial and the reference manual for more details about reading Humdrum data.

Data access

Access a particular token.

Access the token in the second field of the fourth line (12e in the above example). This can be done in two ways: either address the HumdrumLine by the [] operator of HumdrumFile and then the data files with HumdrumLine::token, or access the HumdrumToken directly from the HumdrumFile::token function directly from the HumdrumFile class, giving the line and field index as arguments.

infile[3].token(1);    // 12e
infile.token(3, 1);    // 12e

example data

Get token string contents.

HumdrumTokens inherit from std::string, so the text of the token can be accessed in several ways:

(std::string)infile.token(3, 1);   // "12e"
infile.token(3, 1).c_str();        // "12e"

example data

Get starting token in track/spine.

Get the first token in the second spine/track (second **kern token on the first line):

infile.getTrackStart(2);

example data

Note that this will return a pointer rather than a reference to the token.

Structural information

Total number of HumdrumLines in a HumdrumFile.

infile.getLineCount();    // 12

example data

Total number of token fields on a HumdrumLine.

infile[3].getTokenCount();  // 2
infile[3].getFieldCount();  // 2

example data

Get the track number for a token

infile[3].getTrack(1);   // 2 = second track in file.

example data

The "1" is the field number for the second token on the 4th line, which is in the second track of the file.

Get the sub-track number for a token.

infile[3].getSubtrack(1);  // 0

In this case the spine has not split, so the sub-track assignment is 0. If there were a spine split, then the sub-track count would start at 1 for the first token on the line in a track, the next token in the spine would be sub-track 2, and so on.

example data

Get the number of tokens which following next in track/spine.

Ask the starting token how many tokens precede/follow the starting token in the second spine:

HumdrumToken* tok = infile.getTrackStart(2);
tok->getNextTokenCount();           // 1 token following in the spine
tok->getPreviousTokenCount();       // 0 tokens preceding in the spine
tok->getNextToken();                // returns pointer to `*M3/4`, using default value of 0 for argument.
tok->getPreviousToken();            // returns NULL

example data

The HumdrumToken::getNextTokenCount() function will return 0 for the last token in a spine/track (which always must be the characters *- (start-minus) which is the data terminator token.

Timing information

Token durations

To access the parsed duration of the token, use the HumdrumToken::getDuration function. The return value of getDuration() is a "HumNum" which is a rational number, or fraction, consisting of an integer numerator and denominator. The HumNum::getFloat() function will return the duration as a double:

infile.token(3, 1).getDuration();              // 1/3    for "12e"
infile.token(3, 1).getDuration().getFloat();   // 0.3333 for "12e"

example data

HumdrumLines also possess duration

infile[4].getDuration();             // 1/6 (1/6th of a quarter note)
infile[4].getDuration().getFloat();  // 0.166667

example data

HumdrumFiles also possess duration.

infile.getDuration();    // 3 (one measure of 3/4)

example data

Ticks per quarter note

When converting Humdrum files into MIDI, MuseData, MusicXML or SKINI, the function HumdrumFileBase::tpq (ticks per quarter note) will return the minimum number of fractional time units necessary to describe all rhythms in the file as integer durations.

infile.tpq();           // 6 = minimum time unit is a triplet 16th note

example data

In the case of the musical example further above, the smallest duration is a triplet eighth note, but the minimum time unit between both parts is a triplet sixteenth note when considering the polyrhythmic interaction between the parts.

Token/line/score durations in ticks per quarter note.

Durations can be expressed in ticks by giving the tpq value as an argument to the duration functions:

int tpq = infile.tpq();                           // 6 ticks per quarter note
infile.token(3, 1).getDuration(tpq).toInteger();  // 2 ticks for a triplet 8th note
infile[3].getDuration(tpq).toInteger();           // 1 tick for a triplet 16th note
infile.getDuration(tpq).toInteger();              // 18 ticks for 3 quarter notes

example data