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

    Class Motif

    A short melodic cell, and the transformations that make a piece out of one.

    A motif is the smallest thing a composer works with: a handful of notes that come back inverted, in retrograde, a step higher, twice as slow. The library generates one and transforms one, but every step hands back a bare cell that has to be named again on the way into the next, and the key travels beside it by hand. A Motif carries the cell, so a subject and its answer are two expressions rather than two variables.

    The cell holds notes and nothing else: the key it was written in is not part of it, since the same figure is worth restating in another key, and the members that need one are given it.

    import { Motif } from '@libraz/libcantus';
    const subject = Motif.generate({ key: 'C major', bars: 1 });
    subject.transform('invert').relateTo(subject)?.kind; // 'inversion'
    Index
    constructor
    notes totalBeats data
    generate fromNotes fromData fromJSON transform develop relateTo similarityTo toScore equals toJSON
    • get totalBeats(): number

      Where the cell stops sounding, measured from its own first onset.

      Returns number

    • Generate a seed motif.

      The line follows the requested contour in diatonic steps from the tonic, snapped to the key; with a chord in hand, the notes landing on bar downbeats are pulled to the nearest chord tone.

      Parameters

      Returns Motif

      The generated motif.

      If the key or the chord names none, or a dial is outside [0, 1].

      import { Motif } from '@libraz/libcantus';
      const motif = Motif.generate({ key: 'C major', bars: 2, contour: 'ascending' });
      motif.notes.length; // 4

    • Read a run of notes as a motif.

      This is how a caller names a cell it already has — a subject lifted out of a score, a phrase a player typed in. Only the fields a motif note carries are kept, so notes that arrived from a score leave their dynamics behind.

      Parameters

      • notes: readonly NoteEvent[]

        The cell, in the order the transforms should read it.

      Returns Motif

      The motif.

      If a note carries a value the transforms cannot hold.

    • The cell put through one of the classical transformations.

      invert reflects the pitches about the earliest note and retrograde mirrors the onsets about the cell's span, both self-inverse; augment and diminish scale the note values by amount and its reciprocal; transposeChromatic moves by semitones; transposeDiatonic and sequence move by scale degrees with a key in hand, and by semitones without one.

      The result's notes run in time order whichever way the source cell was written, so an inversion of a retrograde reflects about the note that now sounds first.

      Parameters

      • kind:
            | "retrograde"
            | "transposeDiatonic"
            | "transposeChromatic"
            | "invert"
            | "augment"
            | "diminish"
            | "sequence"

        The transformation.

      • Optionalamount: number

        Semitones, scale degrees, or the time factor, as the transformation reads it.

      • Optionalkey: KeyLike

        Key context for the diatonic transformations: a name, plain key data, or a Key.

      Returns Motif

      The transformed motif.

      If a transformed pitch would leave the MIDI range.

      import { Motif } from '@libraz/libcantus';
      const motif = Motif.fromNotes([
        { pitch: 60, startBeat: 0, durationBeat: 1 },
        { pitch: 62, startBeat: 1, durationBeat: 1 },
      ]);
      motif.transform('transposeDiatonic', 1, 'C major').notes[0]?.pitch; // 62

    • The cell laid across a span and snapped to the harmony under it.

      The cell is tiled back to back to fill the bars asked for; the notes carrying structural weight are pulled to the nearest chord tone of the segment sounding there, and the ones between them are kept in the key.

      Parameters

      • timeline: ChordTimeline | Timeline

        The harmony to snap against, as a Timeline or the plain chord timeline the analysis layer hands out.

      • key: KeyLike

        The key the passing notes are kept in.

      • bars: number

        How many bars to fill.

      • ts: MeterLike

        Meter the bars are counted in, in any form that names one. A motif carries no meter of its own — it is a run of notes — so there is nothing to fall back on, and a development laid on the wrong bar length drifts off the part it plays under.

      Returns Motif

      The developed motif.

      If the bar count is not a positive integer.

    • How this motif stands to another: the transformation that turns one into the other, named.

      Parameters

      • other: Motif

        The statement to name against this one.

      • Optionalkey: SpelledKeyLike

        Key context for the tonal reading. Without one an answer holding only diatonically is left unnamed unless its interval pattern also fits the retrograde family, in which case it is named there; a motif carries no key of its own, so this is the only way to have the tonal reading offered.

      Returns MotifRelation | null

      The relation, or null when the two stand in none.

    • How alike two lines are, in [0, 1].

      What Motif.relateTo answers null for still scores here: this is the measure for a variant that adds a passing note or drops one, rather than for the exact transformations.

      Parameters

      • other: Motif

        The line to compare with.

      Returns number

      The likeness: 1 for the same line, a transposition of it included.

    • Whether another motif holds the same notes in the same order.

      The comparison is made through the other motif's public data, so two motifs built by different copies of the module still compare. The order is part of it: the transformations read the first note of the cell as its pivot, so two cells sounding alike but read from different ends are not the same motif.

      Parameters

      • other: Motif

        The motif to compare.

      Returns boolean

      True when the cells hold the same notes in the same order.

    Settings
    Member Visibility

    On This Page
    Constructors
    Accessors
    Methods