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

    Class Interval

    An immutable spelled interval value: a diatonic number, a quality label, and a signed semitone span. A thin convenience wrapper over the pitch module's plain interval result.

    import { Interval, Note } from '@libraz/libcantus';
    Interval.between(Note.parse('C4'), Note.parse('G4')).name; // 'P5'
    Index
    number quality semitones isDescending name data
    between of fromData fromJSON parse tryParse invert negate isConsonant equals toJSON toString
    • get number(): number

      Diatonic size: 1 = unison, 2 = second, ... 8 = octave, and beyond.

      Returns number

    • get isDescending(): boolean

      Whether the interval moves downward. A descending unison spans zero semitones, so this flag is the only record of its direction.

      Returns boolean

    • get name(): string

      A readable label composed of quality and number, e.g. 'P5' or 'M3', prefixed with '-' when the interval descends.

      The name is written in the grammar Interval.parse reads, so an interval that has been logged, written to a column, or interpolated into a template comes back as the same interval — direction included.

      Returns string

    • Build an interval from explicit components.

      Parameters

      • numberValue: number

        Diatonic size: 1 = unison, 2 = second, ... 8 = octave.

      • quality: IntervalQualityLabel

        Quality label: 'P', 'M', 'm', or repeated 'A'/'d'.

      • semitones: number

        Signed semitone span; its magnitude must be the span the number and quality describe.

      Returns Interval

      The interval.

      If the three components do not describe the same interval — a P5 spanning 8 semitones is not a value any other method can produce.

    • Wrap a plain spelled interval, as returned by the pitch module.

      The data is checked the way Interval.of checks its arguments: a deserialized interval enters through here, and an unchecked one would be a value no measurement produces — a P5 spanning eight semitones names itself a fifth while sounding a sixth.

      Parameters

      Returns Interval

      The wrapped interval.

      If the number, quality, and span do not describe the same interval.

    • Parse an interval name such as 'P5', 'm3', 'AA4', or '-m3'.

      Parameters

      • name: string

        The interval name; a leading '-' names the interval taken downward.

      Returns Interval

      The interval of that name, descending when the name is prefixed.

      If the name is not a quality label followed by a diatonic number. Use Interval.tryParse where failure is ordinary, such as an interval field read on every keystroke.

    • Parse an interval name, reporting failure instead of throwing it.

      The same reading as Interval.parse, for the callers where a name that does not parse yet is the normal state of the input rather than a fault.

      Parameters

      • name: string

        The interval name.

      Returns ParseResult<Interval>

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

      import { Interval } from '@libraz/libcantus';
      const result = Interval.tryParse('M5');
      result.ok ? result.value.name : result.error.message; // a major fifth does not exist

    • The interval's inversion: the complement that completes the octave.

      A compound interval is reduced to its simple form first, and the result is always ascending — an inversion answers "what is left of the octave", which has no direction of its own. The reduction keeps the octave and its multiples on the octave, so the answer depends on the relation between the two notes and not on how many octaves apart they happen to sit: a double octave inverts to a unison exactly as a single octave does.

      Returns Interval

      The inverted interval, e.g. M3 becomes m6.

      For an augmented octave, whose complement would be a diminished unison: the letters do not move in a unison, so the pitch module reads that relation as the descending '-A1' and refuses the name. Every other interval inverts.

    • The same interval taken in the opposite direction.

      The number and quality are untouched — only the direction changes, so an ascending major third becomes a descending major third rather than its inversion.

      Returns Interval

      The interval with its direction flipped.

      import { Interval } from '@libraz/libcantus';
      Interval.parse('M3').negate().toString(); // '-M3'

    • Whether the interval is consonant.

      Parameters

      • twoVoice: boolean = true

        When true, the perfect fourth counts as a dissonance, matching two-voice counterpoint.

      Returns boolean

      True if the interval is consonant in that context.

    • Whether another interval is spelled identically.

      Enharmonic equivalents are not equal: an augmented second and a minor third span the same distance but are different intervals.

      Parameters

      • other: Interval

        The interval to compare with.

      Returns boolean

      True when number, quality, and span all match.

    • The plain interval data, for JSON serialization.

      Private class fields do not serialize, so an explicit toJSON keeps JSON.stringify(interval) from collapsing to {}. The result is the canonical shape the pitch module produces: descending is always there, so a measured interval, a parsed name, and this method all serialize to the same object and none of them leaves the direction to be guessed.

      Returns SpelledInterval

      The diatonic number, quality, and semitone span, with descending telling which way the interval goes.

    • The interval's name, so a template literal or a log line reads as the interval.

      Returns string

      The name, e.g. 'M3' or '-M3' for the same third taken downward.

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods