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

    Class Instrument

    An immutable instrument: what it physically is — an open-string tuning and a fret count, or the voices each limb reaches — with the range, the positions and the playability checks of the instrument module bound to it. A thin convenience wrapper over a plain InstrumentProfile.

    import { Instrument } from '@libraz/libcantus';
    Instrument.guitar().fingerings(64).length; // 6
    Instrument.bass4().canSound(27); // false
    Index
    name kind polyphony articulations data
    of guitar guitarDropD bass4 bass5 fromData fromJSON range canSound fingerings foldIntoRange soundingPitch playability equals toJSON toString
    • get kind(): "stringed" | "percussion"

      Which family the instrument belongs to.

      Returns "stringed" | "percussion"

    • get articulations(): (
          | "accent"
          | "ghost"
          | "staccato"
          | "legato"
          | "slide"
          | "hammer"
          | "mute"
          | "flam"
          | "drag"
          | "roll"
          | "choke"
          | "open"
      )[]

      A copy of the techniques the instrument can produce.

      Returns (
          | "accent"
          | "ghost"
          | "staccato"
          | "legato"
          | "slide"
          | "hammer"
          | "mute"
          | "flam"
          | "drag"
          | "roll"
          | "choke"
          | "open"
      )[]

    • Wrap a plain instrument profile, whether a built-in one or a caller's own.

      An Instrument is accepted too, and comes back as an equal one: the factory is the boundary a profile crosses everywhere in the library, so it takes the same InstrumentProfileLike every other entry point does rather than making a caller unwrap what it already holds.

      Parameters

      Returns Instrument

      The wrapped instrument.

      If the profile describes no instrument: a neck with no strings, a fret count that is not a whole number, a kit no limb reaches, or a tuning, stretch or voice count that is not finite.

      import { GUITAR_DROP_D } from '@libraz/libcantus/core';
      import { Instrument } from '@libraz/libcantus';
      Instrument.of(GUITAR_DROP_D).range().low; // 38

    • Five-string bass with the low B: B0 E1 A1 D2 G2.

      Returns Instrument

      The instrument.

      import { Instrument } from '@libraz/libcantus';
      Instrument.bass5().range().low; // 23

    • The lowest and highest pitch the instrument sounds.

      Derived from the tuning and the fret count, or from the voices the player's limbs reach, rather than stored — and not necessarily gapless, so Instrument.canSound answers for one pitch.

      Returns { low: number; high: number }

      The extreme sounding pitches as MIDI numbers, inclusive.

      import { Instrument } from '@libraz/libcantus';
      Instrument.guitar().range(); // { low: 40, high: 88 }

    • Whether the instrument has this pitch at all.

      Parameters

      • pitch: number

        MIDI pitch.

      Returns boolean

      True when some string and fret, or some limb the player has, produces it.

    • Every position on the neck that sounds a pitch, lowest string first.

      Parameters

      • pitch: number

        MIDI pitch.

      Returns StringFingering[]

      One entry per string that reaches the pitch; empty when none does.

      If the instrument is a kit, which has no neck to place a pitch on.

    • Move a pitch by whole octaves until the instrument can sound it, which is what a player does with a line written below the instrument.

      Parameters

      • pitch: number

        MIDI pitch to place.

      Returns number

      The nearest octave transposition the instrument sounds, taking the upper one when two are equally near; the pitch unchanged when no transposition is available.

      import { Instrument } from '@libraz/libcantus';
      Instrument.bass4().foldIntoRange(27); // 39

    • The pitch this instrument sounds for a note written in its part.

      Most parts are written at the pitch they sound, but some are not: a guitar part is printed an octave above concert pitch, and a part for an instrument in B flat or in A is printed in a different key altogether. The instrument is looked up by its own name, so an instrument the transposition table carries needs nothing said; name a transposition to read a part for one it does not, which is every instrument whose profile is the caller's own.

      The interval decides the letter, so the spelling of the part survives: on a clarinet in A a written D sharp sounds B sharp, where a semitone count alone would answer C natural and lose the letter the part is written on.

      Parameters

      • note: NoteLike

        A note name, a MIDI number, plain note data, or a Note, as the player reads it.

      • transposition: TransposingInstrument = ...

        The written-to-sounding transposition to read the part under; the instrument's own name by default.

      Returns Note

      The sounding note, at concert pitch.

      If the note is malformed, or the transposition is neither a known instrument name nor a spelled interval — which is what an instrument the table does not carry reports when none is named.

      import { Instrument } from '@libraz/libcantus';
      Instrument.guitar().soundingPitch('C4').name; // 'C3'
      Instrument.bass4().soundingPitch('C4', '-P8').name; // 'C3'

    • Judge whether a passage can be played on this instrument, and how hard it is.

      Nothing is rewritten or rejected: the report names what stands in the way, and only the tempo-dependent layer consults bpm, so omitting the tempo reports what the instrument alone decides.

      Parameters

      • notes: readonly NoteEvent[]

        The passage, in any order. Drum hits qualify as note events.

      • Optionalbpm: number

        Tempo in quarter-note beats per minute; enables the layer that asks whether there is time for the movement.

      Returns PlayabilityReport

      Difficulty, the issues found, and each note's string/fret or limb.

      If the notes are not note events, or the tempo is not a finite positive number of beats per minute.

      import { Instrument } from '@libraz/libcantus';
      const report = Instrument.bass4().playability([
        { pitch: 27, startBeat: 0, durationBeat: 1 },
      ]);
      report.issues[0]?.type; // 'noteOutOfRange'

    • Whether another instrument is described identically.

      Parameters

      • other: Instrument

        The instrument to compare with.

      Returns boolean

      True when both profiles name the same instrument, string for string or voice for voice.

    • The plain profile, for JSON serialization.

      Private class fields do not serialize, so an explicit toJSON keeps JSON.stringify(instrument) from collapsing to {}.

      Returns InstrumentProfile

      A copy of the underlying profile, its lists included.

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

      Returns string

      The name, e.g. 'guitar'.

      import { Instrument } from '@libraz/libcantus';
      Instrument.guitar().toString(); // 'guitar'

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods