@libraz/libcantus - v1.1.0
    Preparing search index...

    Class Meter

    An immutable time signature: a numerator over a note-value denominator, with the optional grouping that gives an additive metre its felt beats. A thin convenience wrapper over the meter module's plain time signature.

    One signature, not a piece's meter over time: a piece that changes meter is described by a meter map, which the meter module's own functions read.

    import { Meter } from '@libraz/libcantus';
    Meter.parse('6/8').isCompound; // true
    Index
    numerator denominator grouping data isCompound beatsPerBar pulsesPerBar pulseBeats
    of parse tryParse fromData fromJSON format weightAt isStrongBeat barPositionAt formatPosition tuplet equals toJSON toString
    • get numerator(): number

      Beats in a bar, counted in denominator units: the 6 of 6/8.

      Returns number

    • get denominator(): number

      The note value one unit is written as: the 8 of 6/8.

      Returns number

    • get grouping(): number[] | undefined

      A copy of the felt-beat grouping, or undefined when the bar is ungrouped.

      Returns number[] | undefined

    • get isCompound(): boolean

      Whether the meter is compound: its main pulses each divide into three, as in 6/8, 9/8, or 12/8. A simple triple such as 3/4 is not compound, and neither is a signature whose grouping selects the additive reading.

      Returns boolean

    • get beatsPerBar(): number

      Length of a bar in quarter-note beats.

      Returns number

    • get pulsesPerBar(): number

      Main pulses (felt beats) in a bar: 2 in 6/8, 4 in 4/4.

      Returns number

    • get pulseBeats(): number

      Length of one felt beat in quarter-note beats: a quarter note in simple meters, a dotted quarter in compound ones.

      Returns number

    • Build a meter from its parts.

      Parameters

      • numerator: number

        Beats in a bar, counted in denominator units.

      • denominator: number

        The note value one unit is written as, e.g. 8 for an eighth note.

      • Optionalgrouping: number[]

        Optional grouping of the bar into felt beats, as positive integers summing to the pulse count or to the numerator — [2, 2, 3] for a 2+2+3 reading of 7/8.

      Returns Meter

      The meter.

      If the numerator or denominator is not a positive integer, or the grouping sums to neither the pulse count nor the numerator.

    • Parse a time signature such as '4/4', '6/8', or the additive '2+2+3/8'.

      Parameters

      • text: string

        The signature text.

      Returns Meter

      The meter that text names.

      If the text is not n/d with positive integers, or names a signature the library rejects. Use Meter.tryParse where failure is ordinary, such as a meter field read on every keystroke.

    • Parse a time signature, reporting failure instead of throwing it.

      The same reading as Meter.parse — that method is this one with its error thrown — for the callers where text that does not parse yet is the normal state of the input rather than a fault.

      Parameters

      • text: string

        The signature text.

      Returns ParseResult<Meter>

      The meter, or the error explaining why the text is not one.

      import { Meter } from '@libraz/libcantus';
      const result = Meter.tryParse('7/8');
      result.ok ? result.value.pulsesPerBar : result.error.message; // 7

    • Render the signature as 'n/d', or as 'a+b+c/d' when it carries an additive grouping and one is asked for.

      Parameters

      • opts: { grouping?: boolean } = {}

        Set grouping: true to render an additive grouping. A grouping counted in main pulses has no additive spelling: one whose groups are all the same length states the division the bare signature already has and falls back to the plain form, and one whose groups differ is refused rather than printed as a bar that weighs its pulses otherwise.

      Returns string

      The formatted signature.

      If grouping: true is asked of a grouping that no signature text can spell: one counted in main pulses, on a compound numerator, whose groups are not all the same length — 12/8 as [1, 1, 2].

      import { Meter } from '@libraz/libcantus';
      Meter.of(7, 8, [2, 2, 3]).format({ grouping: true }); // '2+2+3/8'
      Meter.of(12, 8, [1, 1, 1, 1]).format({ grouping: true }); // '12/8'

    • Metric weight of a position within its bar, on a 0–3 scale: 3 the downbeat, 2 a secondary strong pulse, 1 any other main pulse, and 0 an off-pulse subdivision.

      Parameters

      • beatInQuarters: number

        Position in quarter-note beats; a position past the end of a bar is read in the bar it falls in.

      Returns number

      The metric weight (0–3).

      If the position is not finite.

    • Whether a position is metrically accented — a downbeat or a secondary strong pulse.

      Parameters

      • beatInQuarters: number

        Position in quarter-note beats.

      Returns boolean

      True on strong beats.

      If the position is not finite.

    • Convert a position in quarter-note beats to a bar index and in-bar offset.

      Parameters

      • beatInQuarters: number

        Position in quarter-note beats.

      Returns BarPosition

      The 0-based bar and the quarter-note offset within it.

      If the position is not finite.

    • Render a position as the bar.beat a DAW or a score shows: 1-based bar, 1-based felt beat.

      Parameters

      • beatInQuarters: number

        Position in quarter-note beats.

      • decimals: number = 2

        Digits of the fractional beat to keep.

      Returns string

      The formatted position in one of two forms: bar.beat on a felt beat, e.g. '3.2' for bar 3, felt beat 2; and bar.beat+fraction between felt beats, e.g. '3.2+0.5' halfway from the second felt beat to the third. A reader of these strings has to take both, since most onsets of an ordinary piece fall between pulses.

      If the position is not finite or decimals is not an integer in 0..100.

      import { Meter } from '@libraz/libcantus';
      Meter.parse('6/8').formatPosition(7.5); // '3.2'
      Meter.parse('6/8').formatPosition(8.25); // '3.2+0.5'

    • Subdivide a span into equal tuplet durations — an eighth-note triplet is tuplet(1, 3).

      Parameters

      • totalBeats: number

        Total span in quarter-note beats.

      • count: number

        Number of equal parts.

      Returns number[]

      count equal durations summing to totalBeats.

      If the span is negative or count is not a positive integer.

    • Whether another meter is the same signature, grouping included.

      6/8 and 3/4 fill a bar with the same six eighth notes and are not equal: they group them differently, and every weight this class reports follows the grouping.

      Parameters

      • other: Meter

        The meter to compare with.

      Returns boolean

      True when numerator, denominator, and grouping all match.

    • The plain time signature, for JSON serialization.

      Private class fields do not serialize, so an explicit toJSON keeps JSON.stringify(meter) from collapsing to {}. The grouping appears only on a meter that carries one, which is the shape the meter module's own parser produces.

      Returns TimeSignature

      A copy of the numerator, denominator, and grouping.

    • The signature, so a template literal or a log line reads as the meter.

      Returns string

      The plain form, e.g. '6/8'; ask Meter.format for the additive one.

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods