Notice that the first beat in the score occurs on a pickup beat to the
first measure, so the metrical position of the first data line starts
on beat 4 of the metric cycle.
In addition, an integer form of the beat location is available
if you use the -t to display values as ticks
which represent the beat offset from the start of the measure in
minimum-duration units. The timebase of ticks is dependent on the
rhythms found in the file. You can use the --tpw to extract
the number of ticks per whole note for the data in the file, or --tpq
for the number of ticks per quarter note.
In the following example, the first column contains the metric beat position
in terms of ticks, generated
by the -t option. The second column contains the fractional
values for the beat positions, created by using the -f option.
And the third column contains the default display for beat positions
as floating-point values.
Here is a summary and graphical musical example of the three different
data output positions for metrical position analysis from
the beat program:
- no additional option: display analysis data as numbers with
decimal places for the fractional part of the numbers between integers.
- -f: display analysis data as rational numbers.
- -t: display analysis data as ticks (integer multiples
of the minimum durational unit for the shortest line of data in the score).
Beat offsets from zero
By using the -z option, metrical locations start at 0 for the
downbeat instead of 1. Tick-based beat values are more useful when
offset from zero; otherwise they are start at the value of ticks in
a quarter note (see the example above). In particular, tick values are
easier to work with when using a zero offset.
Minimum attack triggering
By default, the beat program will only output beat/duration
information for a line in the score if there is at least one note attack
occurring on the line. For example, if the data line in the score contains
only rests, no analysis output will be generated. Likewise, a single tied
note will not be considered a note attack, and no analysis will be generated.
To override this behavior, use the -A option, followed by the
minimum number of notes attacks occurring on the line which will trigger
an analysis output:
- -A 0: calculate a duration/beat for every data line in the
- -A 1: calculate a duration/beat for every data line in the
score which has at least one note attack.
- -A 2: calculate a duration/beat for every data line in the
score which has at least two note attacks.
The first column in the above example contains the analysis for -A0; the second column contains data for -A1; -A2 in
the third column; and -A3 in the fourth column.
Beat widths for compound/cut-time meters
By default, the beat program will assume that quarter notes
are the definition of a beat. Specifying the -u option allows for
other beat widths to be applied in the analysis of metrical beat positions.
Currently, only one beat width is allowed per analysis of a Humdrum file.
The -u option can also affect duration options.
For compound meters such as 3/8, 6/8, 9/8 or 12/8, etc., use the option setting
-u 4. to indicate that the duration of a beat is equivalent to a
dotted quarter note. For non-compound meters which use the same time signature,
use -u 8 to indicate that a beat is equivalent to an
eighth note. For cut-time, use -u 2. By default, 6/4 is
treated as a simple meter with the beat set to a quarter note. Use -u 2. to treat 6/4 as a compound meter with 2 beats per measure.
beat -afu 4. input |
beat -afu 8 input |
beat -af input
Calculating the duration of each line in a Humdrum file is particularly
useful for real-time applications (such as humplay),
and standard MIDI file generation (see hum2mid).
The duration of each line in a Humdrum **kern file
can be extracted by using the -d option.
program will analyze the rhythmic duration of each line which is the
reciprocal of the smallest rhythmic value on the line.
For example a **recip
rhythm of 16 is a sixteenth note, and its rhythmic duration is: 1/16.
When duration values are given as floating-point numbers, the values
are multiplied by 4 to produces quarter-note durations units: 16 rhythm = 1/16 * 4 = 0.25. The first column in the example below shows the duration
of each line in terms of fractions of whole notes. The second column
shows the duration of the line as floating point values, where 1.0 is
equivalent to a quarter note duration.
beat -pd humdrum://371chorales/chor227.krn | beat -pdf > output.krn
Notice that the -f option displays the duration values as fractions
(rational numbers) in a similar manner to beat values. Likewise, the
-t option can be used to specify durations of lines as tick values.
Using the -t option with -d
(or -c option described further below)
will force the beat program to work with integer values which are the
least common multiple (LCM) of all rhythmic values
found in the input data. In the following example there are two voices: one in
triplet eighth notes and one in sixteenth notes. The LCM rhythmic value
for triplet eighths and sixteenths is a triplet 32nd note [LCM(12,16)=48].
Where **dtick stands for delta ticks: the duration
of the current line in ticks before the next line is to be played.
Note that the minimum tick value is based on the minimum composite
rhythm of all rhythm values found in the score, not on the minimum
rhythm of a particular note/rest: LCM(rhythms)=48, not Max(rhythms)=16.
The number of ticks per whole note can be
determined by using the --tpw option, which is equivalent to
using the minrhy command:
The --tpq option will display the number of ticks in
a quarter-note duration (one fourth of the -tpw value).
A cumulative form of duration can be extracted with the -c
option. Cumulative duration is a summation of the duration of all
lines in the file prior to the current one.
When the -t option is used in combination with -c (used
to generate first spine in the file above), the maximum absolute tick value cannot
exceed 4 billion
in the duration of the piece, or there will be a overflow error in the
tick value (likewise tick durations of individual notes cannot exceed
4 billion). This is not very likely to occur outside of degenerate cases.
Here is one of the worst cases, where the tpw value is 89760:
Duration base rhythmic unit
Similar to the metric beat position analyses, line duration analyses
can be refined by using the -u option to adjust the
rhythmic value which is equivalent to a duration of 1.
By default in floating-point style output,
the rhythmic value equivalent to a duration of 1 is "1",
meaning that a whole-note rhythm has a duration of 1.
For the rational style option -f, there is a
built-in factor of 4 for duration and cumulative duration outputs.
In this case to set a whole-note equal to a duration of would is the
option setting -u 4, since 4 * 1 = 4.
This behavior will probably be automatically adjusted in the future
so that -u 4 when displaying in the fractional style gives
the same duration base as with floating-point output.
Beat count by measure
Using the -s option, a summation of the beats within a measure
will be output. The total number of beats in a measure is displayed as the
first item after the measure line when appended/prepended to the original
score, or it is the only data line output between barlines when the input data is not included
in the output. For this example, each measure contains four beats except
for the first and last measures (which are two partial measures which
sum to four beats).
beat -ps humdrum://chopin/preludes/prelude28-18.krn > output.krn
A practical use of the -s option is to verify the number of beats
in each measure with the following command:
beat -s h://chopin/preludes/prelude28-18.krn | context -n 2 | grep ^= > output.txt
The results can easily be scanned for missing beats due to data entry
errors. Also, the command:
beat -s h://chopin/preludes/prelude28-18.krn | ridx -GLIMd | sort | uniq -c
is useful for checking the durations of the measures in a score. In this case,
the output is "21 4" which means that there were 21 measure segments in the file, and all of then had 4 quarter-note durations worth of music in them.
By default, output from the beat program does not include
null tokens when outputting certain data types such as the sum of beats
in a measure -- unless the -a or -p option is used to
incorporate the analysis data with the input data. If you need to include
null-tokens to space with the original music,
or for a similar purpose, use the -n option:
Rhythm and Duration searching
Specific composite rhythmic or duration patterns can be found in
the input by using the -B and/or -D options. Both options
require a sequence of floating point numbers separated by spaces. For the -B option, the sequence is a list of the metric beats where
note onsets occur. For the -D option, the sequence is a list
of the rhythmic durations between successive data lines in the input.
When both the -B and -D options are specified at the
same time, returned matches will satisfy both beat and duration queries
(which do not have to be the same length).
For example, if you want to locate places in
Chorale 227 where two quarter-note durations form a sequence in the
composite rhythm, then do the following search:
The output will be a list of the locations in the input data where the
matches start. The first column is the line number in the input data
for the start of the match. The second column is the measure number
in which the match starts. Measure numbers are extracted directly
from the data, so pre-process the input data with barnum
if there are no measure numbers present in the input data. The third
column lists the beat location of the start of the match within the measure.
The fourth column lists the absolute beat location, or the beat duration
of the start of the match since the first event in the music.
As an example of metric beat searching, the following two searches
look for the metric patterns "4 1" and "4.5 1" in the chorale. The first
search looks for a quarter note starting the sequence, followed by a
note of any duration occurring on the downbeat. The second search
looks for an eighth note on the offbeat of beat 4, followed by
an event of any duration on the following downbeat.
For this particular chorale, the downbeat is more likely to be
preceded by an eighth note than a quarter note (occurring 11 times as compared to 4 times).
If the -a or -p option are used when doing a
-B and/or -D search, the output will contains a
spine of data called **match which enumerates the
match results by placing a number at the start of the match sequence.
For -B and -D searches, an asterisk (*)
can be used to represent a match to any value. Here is an example
metric beat search where the first event is on the 4th beat, the second
event can occur on any beat, and the third event must occur on the downbeat.
Notice that when a search contains a wild card, the match results
list the individual matching patterns. For the search -B "4 * 1",
the wildcard matched to both 4.5 and 4.75.
In order to guarantee that multiple metric cycles are not included
unintentionally in a -B match, you can use the -R
option to force an exact durational relation between the first and last
element in the search pattern. For example, here is a search for a
metric beat pattern starting on beat 1, followed by exactly seven events
of any metrical position, and ending on beat 1. The -R 4
option specifies that the duration between the first search position
(1) and the last search position (1) is exactly 4 beats.
In other words, search for a pattern which starts on a downbeat and ends
on the next downbeat, with seven events occurring between them: