Humdrum Extras

beat manpage

COMMAND

    beat -- Extract composite rhythm information from musical scores.

SYNOPSIS

    beat [-d|-c|-s] [-f|-t] [-z] [-a|-p] [input(s)] [> output]  
    beat [[-B seq]|[-D seq]] [-R #] [-a|-p] [input(s)] [> output]

OPTIONS

ⓘ-a Append analysis spine to input data. (see -p option).
ⓘ-A # Note attack threshold. Only consider data lines with the minimum number of note attacks on the line. The default is 1 note. Setting the value to 0 will also include lines containing rests, null tokens, and ends of tied notes.
ⓘ-B seq Search for a sequence of beat positions in the composite rhythm of the score.
ⓘ-c Returns a cumulative rhythmic duration for each line in the score, giving the total number of beats between the start of the music and the current line.
ⓘ-d Calculate the rhythmic duration of each line rather than its beat position in the measure.
ⓘ-f Display duration values as fractions instead of numbers with decimal places. (compare to -t option).
ⓘ-D seq Search for a sequence of durations in the composite rhythm of the score.
ⓘ-n Keep null records for alignment with original data.
ⓘ-p Prepend analysis data to input lines.
ⓘ-R # Duration requirement between first and last beat in -B searches.
ⓘ-s Sum the rhythmic duration of music in each measure.
ⓘ-t Display duration information (-d) using Least Common Multiple (LCM) minimum-rhythm ticks. Dotted rhythms are expanded to their tied-note equivalents for the purpose of calculating the ticks per whole note (see --tpw, and compare to -f option).
ⓘ-u rhythm Use a **recip rhythm as the definition for a beat. The default value is "4". A compound meter of 6/8 would use the setting -u 4. to indicate that the dotted quarter note is the basis of a beat. To indicate that 6/8 contains 6 beats, use -u 8. Cut-time beats can be indicated with -u 2.
ⓘ-z Start downbeats of measures from 0 rather than 1.
ⓘ--tpw Display the number of Ticks Per Whole note which is useful to know when the -t option is used. The output value is the number of ticks per whole note.
ⓘ--tpq Similar to --tpw, but display as Ticks Per Quarter note.

DESCRIPTION
    The primary function of the beat program is for identifying the metrical beat on which a line in a Humdrum **kern score occurs. The beat program can also calculate the duration of each line in a score, sum the duration of notes in a measure, and perform basic rhythm and duration searches on the composite rhythm of the score (the rhythm of the union of parts in the score).

    A basic call to the beat program will calculate the beat positions of lines in the score, reporting values as floating-point numbers. Take, for example, the following Humdrum score for a Bach chorale which has been processed by the beat program, with the beat information found in the first column of the output data on the right. The -p option used in the example instructs the beat program to prepend the analysis to the input data. Alternatively, the -a option can be used to append the output data to the end of the line.

    beat -p humdrum://371chorales/chor227.krn > output.krn
    input
    		  
    output

    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.

    Three output formats for beat information

  • By default, the beat program will output a beat position of a data line as a floating-point number. When tuplets (such as triplets or quintuplets) are found in the music, these floating-point values are approximations of the exact value which can be more accurately be described as a rational number (a fraction with an integer numerator divided by an integer denominator). Adding these floating-point values together to calculate another rhythm or duration is prone to round-off error in these cases.

  • For more precise rhythmic calculations in music with complicated rhythms, you can display the calculated data as a rational value by using the -f option (for Fraction). When rational values are greater than one, the value is split into two parts: an integer plus a fractional value less than one. For example, the rational number 3/2 is displayed as 1+1/2.

  • 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.

    beat -p input.krn | beat -pf | beat -pt > output.krn

    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.

    beat -pz h://371chorales/chor227.krn | beat -pzf | beat -pzt > output.krn

    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 score.
    • -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.
    • etc.

    beat input.krn -pA3 | beat -pA2 | beat -pA1| beat -pA0 > output.krn

    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.

    compound
    beat -afu 4. input   
    simple
    beat -afu 8 input   
    default
    beat -af input

    Duration

    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.

    The beat 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].

    beat -dtp poly.krn
    		 beat -da poly.krn
    		 beat -dfp poly.krn

    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:

    beat --tpw poly.krn
    		 minrhy poly.krn

    The --tpq option will display the number of ticks in a quarter-note duration (one fourth of the -tpw value).

    Cumulative duration

    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.

    beat -pc input.krn | beat -pfc | beat -ptc > output.krn

    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:

    beat -cp input.krn | beat -cpf | beat -cpt > output.krn

    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.

    Null-token preservation

    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:

    beat -s chor227.krn         
    		 beat -sn chor227.krn

    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:

    beat -D "3 1" h://371chorales/chor227.krn

    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.

    beat -B "4 1" chor227.krn         
    		     beat -B "4.5 1" chor227.krn

    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.

    beat -p -B "4.5 1" h://371chorales/chor227.krn

    Search wildcards

    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.

    beat -B "4 * 1" h://371chorales/chor227.krn

    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:

    beat -B "1 * * * * * * * 1" -R 4 h://371chorales/chor227.krn

EXAMPLES

    As an example application, use beat to identify the most common rhythmic patterns in the example Bach chorale:

    beat -d h://371chorales/chor227.krn | grep -v = | context -n3 | rid -GLId \
         | sort | uniq -c | sort -nr
    In this chorale, the most common composite rhythmic duration pattern of three events is a sequence of eighth-notes (0.5, 0.5, 0.5) which occurs 47 times in the music. This set of rhythmic patterns can be compared to that of the entire Bach chorale set (excluding chorale 150):

    beat -d chor???.krn | grep -v = | context -n3 | rid -GLId \
         | sort | uniq -c | sort -nr

    In the case of all chorales, the rhythm sequence of three eighth-notes in a row is noticeably more common than any other rhythm-triplet:

    In a similar manner, the pattern of note attacks on sequences of beat locations can be examined:

    beat chor???.krn | grep -v = | context -n3 | rid -GLId \
         | sort | uniq -c | sort -nr

    The most common composite metric pattern in the Chorales is the sequence "2 2.5 3", but both "1 1.5 2" and "4 4.5 1" patterns are nearly as common (note that patterns starting on beat 4 only exist in quadruple meters). Interestingly, the pattern "3 3.5 4" is the least common pattern of "0.5 0.5" durations starting on a beat.

    The above results can also be sorted by the initial beat position of the sequence, which could be used in the generation of Markov chains for rhythm generation:

    beat chor???.krn | grep -v = | context -n3 | rid -GLId \
         | sort | uniq -c | sort -nr -k 2

    Example 2

    The following plot shows the rhythmic activity in Beethoven's Moonlight sonata, movement 2. The plot shows the duration of events in the left hand (blue), right hand (red), and both (black) which is a composite rhythmic pattern of the events in the two hands.

    The first 20 beats or so of the music is in a cyclic metric pattern of (2, 1) quarter-note durations. This pattern mostly occurs throughout the first part of the movement in both hands, and in the composite rhythm of both hands together. Note the change in rhythmic texture in the trio section starting at beat 108. The left and right hands mostly have rhythmic durations of 3 beats, but the two hands are offset in their attacks by one beat. Therefore, the composite rhythm of both hands (black) has the same (2, 1) rhythmic cycle as in the first half of the music.

    Data for the above plot was extracted from the movement with these three commands (click on the output file to view results): 

     beat -dp h://beethoven/sonatas/sonata14-2.krn | beat -cp \
      | extractx -f1,2 | rid -GLId | egrep -v '=|\.$' > BOTH.dat
 extractx -f2 h://beethoven/sonatas/sonata14-2.krn | beat -dp | beat -cp \
      | extractx -f1,2 | rid -GLId | egrep -v '=|\.$' > RH.dat
 extractx -f1 h://beethoven/sonatas/sonata14-2.krn | beat -dp | beat -cp \
      | extractx -f1,2 | rid -GLId | egrep -v '=|\.$' > LH.dat

    More example usages of the beat program are available on the beat examples page

ONLINE DATA
    Input arguments or piped data which are expected to be Humdrum files can also be web addresses. For example, if a program can process files like this: 
           program file.krn
    It can also read the data over the web: 
           program http://www.some-computer.com/some-directory/file.krn
    Piped data works in a somewhat similar manner: 
           cat file.krn | program
    is equivalent to a web file using ths form: 
           echo http://www.some-computer.com/some-directory/file.krn | program

    Besides the http:// protocol, there is another special resource indicator prefix called humdrum:// which downloads data from the kernscores website. For example, using the URI humdrum://brandenburg/bwv1046a.krn: 

          program humdrum://brandenburg/bwv1046a.krn
    will download the URL:
    Which is found in the Musedata Bach Brandenburg Concerto collection.

    This online-access of Humdrum data can also interface with the classical Humdrum Toolkit commands by using humcat to download the data from the kernscores website. For example, try the command pipeline: 

          humcat humdrum://brandenburg/bwv1046a.krn | census -k

SEE ALSO

BUGS
    When using tick values, individual tick durations cannot exceed 4 billion, and the total duration of the input should not exceed 4 billion.

    More work to be done to finalize beat labeling in compound meters. Possibly allowing for assymetric beat widths, and a compound meter option.

DOWNLOAD
    The compiled beat program can be downloaded for the following platforms:
    • Linux (i386 processors) (dynamically linked) compiled on 28 Jun 2012.
    • Windows compiled on 29 Jun 2012.
    • Mac OS X/i386 compiled on 13 Nov 2013.
    • Mac OS X/PowerPC (version 10.2 and higher) compiled on 13 May 2009.

    The source code for the program was last modified on 19 May 2010. Click here to go to the full source-code download page.