Humdrum Extras

rscale manpage


    rscale -- Scale the rhythms in **kern and **recip representations.


    rscale [-f # | -a | -o[input[> output]


-a Scan input data for the first reference record starting with !!!rscale-alt: and use the scaling factor found in that record to scale the rhythms in the file. This reference record is intended to allow for generating backwards-compatible rhythms for analysis with standard Humdrum Toolkit programs.
-f # Scale note durations in **kern and **recip representations by the given factor. The factor to scale rhythm durations can be either an integer or a rational number, such as "1/2" for one-half.
-l Adjust note layout visual rhythms in local comments.
-o Return the rhythms in the data to their original states by applying the inverse scaling found in the first "!!!rscale: reference record in the data.
-t Also adjust rscale tandem interpretations.
-r Use rational values instead of 0 codes for breves, longs and maximas.
-M Do not alter time signature denominator rhythm values.


    The rscale program scales the duration of rhythmic values in **kern and **recip data. For example, if the durations in the data are scaled by a factor of 2, quarter notes will become half notes, eighth notes will become quarter notes, etc. Using a duration scaling factor of "1/2" will shorten durations by half, such that half notes become quarter notes, and quarter notes become eighth notes. The basic usage of rscale involves specifying a rhythmic factor with the -f option. The rhythmic factor can be either an integer or a rational number (fraction) consisting of two integers separated by a slash, such as "1/2" for one-half, or "1/4" for one-quarter.

    rscale -f 2
    rscale -f 1/2

    When rscale adjusts the rhythmic durations in a file, it also stores the scaling factor in a reference record which start with "!!!rscale:". If this reference exists in the data file already, it will be updated by multiplying the rational number found in the reference record by the current scaling factor being applied. If no !!!rscale: reference record is found in the data, one will be appended to the end of the output data. Examples of these !!!rscale: reference records can be seen in the above output from rscale, and here is an example of applying successive scaling factors:

    cat input
    | rscale -f 1/2
    | rscale -f 1/2
    | rscale -f 1/2
    | rscale -f 8

    Note that if the scaling factor returns to "1", the !!!rscale: reference record is dropped automatically from the data.

    When an !!!rscale: record is present in the input data, the -o option can be used to apply the inverse rhythmic scaling factor which returns the rhythmic values to their original state.

    cat input
    | rscale -f 1/2
    | rscale -f 8
    | rscale -o

    Rational rhythms

    The rscale program can handle rhythm values which are more generalized than standard Humdrum Toolkit programs. In the conventional rhythmic representation of **kern and **recip data, only rhythms which can be represented by an integer number of divisions of the whole note can be encoded (plus augmentation dots for a limited class of non-integer divisions of the whole note). For example, quarter notes are represented by "4" since four of them occur within a whole note.

    One way to conceptualize rhythm values in Humdrum is as durations. For example, a quarter note is 1/4th of a whole note. Therefore, durations are the reciprocal of Humdrum rhythm values. Note, however, that Humdrum-derived durations must have a "1" in the numerator, since the rhythm representations are integers. In Humdrum **recip and **kern representations, only the augmentation dots can alter the denominator of the rhythm, or the numerator of the duration: "4." is a dotted quarter note which has a duration that is equal to the duration of a quarter note plus the duration of half of a quarter note: 1/4 + 1/2 * 1/4 = 3/8. Thus, if the augmentation dot did not exist in the Humdrum representations, the rhythm would have to be encoded as 8/3 (the inverse of the duration, since a whole note can contain 2 and 2/3 dotted quarter notes). However, since the rhythm "8/3" contains a denominator, it cannot be represented in **recip or **kern data.

    Triplet whole notes are one example of a rhythm which cannot be represented in conventional **recip rhythm encodings. A triplet whole note is equivalent to 2/3rds of a whole note, so its **recip rhythm would have to be 3/2 (the inverse of the duration of whole notes the rhythm represents). Since there is a "2" in the denominator of the rhythm, it is not expressible as a **recip rhythm.

    A generalized rational-number rhythmic representation extension is understood by the rscale program which encodes both a numerator and denominator for rhythmic values. The representation uses a "%" character to separate the numerator from the denominator. Therefore the rhythmic value for triplet whole notes is "3%2". Here is an example of 3 triplet whole notes playing against two regular whole notes:

    Since some programs which process **kern data may not recognize this rational extension to rhythm encoding, a reference record starting with "!!!rscale-alt:" can be placed somewhere in the data. This reference record is intended for specifying a rhythmic scaling factor by which the rhythmic data can be converted into the condition where the denominator of all rhythms is "1" which is required for the basic rhythmic representation model. In this case applying a factor of 1/2 will convert whole notes from "1" rhythms to "2" rhythms (half notes), and will convert triplet whole notes from "3%2" notes into "3" notes (triplet half notes). Both "3" and "2" rhythms now parsable by the basic rhythm model.

    Giving the -a option to rscale will cause the program to search for the !!!rscale-alt: reference record and scale the rhythms by the factor which it finds (or scale the values by 1 if no reference record is found).

    rscale -a

    Notice in the above example that the result of applying the 1/2 scaling factor to the rhythm durations allowed the rhythms to be expressed purely as integers, allowing the data to be processed by any program which does not understand the rational rhythm encoding method. For example, the data can be sent through timebase using the rscale -a and rscale -o pair to convert out and back into rational rhythm data:

    rscale -a
    timebase -t 6
    rscale -o
    In this case, the timebase command is used to timebase the data by triplet quarter notes, then the data is converted back to the original rhythmic encoding method, where each line of data represents a triplet half note ("3").

    The scaling factor can be any rational number besides the more common usage of powers of two. The following example goes through exotic rational rhythms before the original rhythms are recovered with the -o option. Notice that the bottom number in the time signature changes in order to match the rhythm scaling (this can be turned off with the -M option).

    rscale -f 1/2
    rscale -f 7/5
    rscale -o

    Encoding **kern music in a mensural-like style

    Modern musical notation is derived from the mensural notation of the Renaissance. In mensural notation, the beat is typically found on the whole note level, and sometime on the breve (double-whole note) level (similar to the half note being the beat in cut time). Modern notation, on the other hand, prefers to use the quarter note as the rhythmic level of the beat.

    Therefore, there are two style for encoding mensural notation: (1) encode the rhythms using the original rhythmic levels in the notation, or (2) divide the duration of each original rhythmic level by 4, such that beats on the whole-note level are moved to the quarter note level. The rscale program allows for switching conveniently between these two methods of rhythm encoding by using the "!!!rscale-alt:" option. For example, the original rhythmic levels can be used to encode the music, and the reference record:

        !!!rscale-alt: 1/4
    can be used to convert to the modern beat convention with rscale -a, and the original rhythm values can be recovered with rscale -o.
    rscale -a

    From the viewpoint of mensural notation, the modern rhythmic convention uses imperfect subdivision (division by 2) of each rhythmic level to generate the smaller duration level from it.

    Longs and maxima notes do not exist in modern rhythmic notation (and breves are relatively rare). Therefore they are somewhat proleptic, but useful for notating mensural notation within modern notation while keeping the original rhythmic values of the notes closer to their original values (mensural notation typically places the beat on the whole-note or breve level, while modern notation typically uses the quarter note or half note as the beat).

    Suppressing 0-codes for breves, longs and maximas

    By default, the rscale program will use "0" codes for rhythms larger than a whole note:

    code rhythm name rational representation
    0 breve (two whole notes) 1%2
    00 long (four whole notes) 1%4
    000 maxima (eight whole notes) 1%8

    The 0-codes are for backwards compatibility with the Humdrum Toolkit, although only 0 (breve or double wholenote) is fully understood by the standard Humdrum Toolkit programs. If the -r option is used with rscale, the full rational rhythmic representations for breves/longs/maximas will be used instead of the zero codes:

    rscale -r

    The zero codes can be recovered by passing the data through rscale without any options:

    rscale input

    Note that in the modern conception of rhythm (as used in **kern and **recip data) starting in the Baroque era, the relative durations of breves/longs/maximas is always related by fixed factors of two, with dots of prolongation used to indicate subdivisions by three. In mensural notation, rhythmic subdivisions can be either 2 (imperfect) or three (perfect), depending on context, "color" or mensural signs.

    Parsed tandem interpretations

    The rscale program is aware of time signature and timebase tandem interpretations. To prevent the program from altering time signatures, use the -M option.

    rscale tandem interpretations

    Visual rhythmic adjustments for groups of notes (separate from their logically encoded durations in **kern data) can be controlled within a spine with the *rscale tandem interpretation:

    By default, the rscale program will not modify this tandem interpretation unless the -t option is given. Without -t option, the visual shapes of the notes will be scaled by the given factor. However with the -t option, the note shapes will remain constant since the *rscale value will be divided by the scaling factor.

    local comment layout note shapes

    The visual display for individual notes can be controlled separately from the logically encoded durations by using a !LO:TX:vis= layout parmeter.

    Using the -l option will cause these visual rhythmic displays to changes according to the rhythm scaling factor as well.




    The compiled rscale program can be downloaded for the following platforms:
    • Linux (i386 processors) (dynamically linked) compiled on 13 Dec 2012.
    • Windows compiled on 29 Jun 2012.
    • Mac OS X/i386 compiled on 13 Nov 2013.

    The source code for the program was last modified on 7 Jan 2011. Click here to go to the full source-code download page.