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

    Class Note

    An immutable spelled note: a diatonic letter plus a chromatic alteration and an optional octave. Wraps the plain note object and delegates to the pitch module; every transformation returns a new instance.

    import { Note } from '@libraz/libcantus';
    Note.parse('C4').transpose(7).name; // 'G4'
    Index
    constructor
    name pitchClass midi letter alter octave data
    of parse tryParse fromMidi fromData format frequency transpose intervalTo transposeBy withOctave forInstrument enharmonic degreeIn fromJSON compareTo equals toJSON toString

    • Wrap a plain note object.

      Parameters

      • data: NoteData

        The spelled note; it is copied, never retained or mutated.

      Returns Note

      If letter is not an integer in 0..6.

    • get name(): string

      The note rendered as scientific pitch notation in English, e.g. 'G4' or 'Bb'. Use Note.format to write it in another notation system.

      Returns string

    • get pitchClass(): number

      The pitch class (0..11), ignoring octave.

      Returns number

    • get midi(): number

      The MIDI number (middle C = C4 = 60).

      Returns number

      If the note has no octave and therefore no fixed pitch.

    • get letter(): number

      The diatonic letter number: 0..6 for C..B.

      Returns number

    • get alter(): number

      The chromatic alteration in semitones: -1 flat, 0 natural, +1 sharp, ...

      Returns number

    • get octave(): number | undefined

      The octave (scientific pitch notation), or undefined for a bare pitch class.

      Returns number | undefined

    • Build a note from its parts, without reading any text.

      The parts are the fields a note holds, so nothing here is interpreted: Note.parse is what reads 'Bb' or 'C#4', and a letter name given here may carry neither an accidental nor an octave.

      Parameters

      • letter: string | number

        The diatonic letter, as a number 0..6 (C..B) or a bare natural letter name 'C'..'B'.

      • alter: number = 0

        The chromatic alteration in semitones; defaults to natural.

      • Optionaloctave: number

        The octave (scientific pitch notation); omit it for a bare pitch class.

      Returns Note

      The note.

      If the letter is out of range, if a letter name carries an accidental or an octave, or if the alteration or octave is out of range.

      import { Note } from '@libraz/libcantus';
      Note.of(1, -1, 4).name; // 'Db4'
      Note.parse('G').name; // 'G'

    • Parse a note name (e.g. 'C#4', 'Bb', 'F##3'), in any of the supported note-name systems.

      The system is detected from the name itself unless one is given, exactly as Key.parse reads a key name: 'gis' is a G sharp, while a bare 'B' is the English B natural until 'german' says otherwise.

      Parameters

      • text: string

        The note text.

      • Optionalopts: NoteNameOptions

        system reads the name in that notation system instead of detecting it.

      Returns Note

      The parsed note.

      If the text is not a valid note. Use Note.tryParse where failure is ordinary, such as a note field read on every keystroke.

      import { Note } from '@libraz/libcantus';
      Note.parse('gis').name; // 'G#'
      Note.parse('B', { system: 'german' }).name; // 'Bb'

    • Parse a note name, reporting failure instead of throwing it.

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

      Parameters

      • name: string

        The note text.

      • Optionalopts: NoteNameOptions

        system reads the name in that notation system instead of detecting it.

      Returns ParseResult<Note>

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

      import { Note } from '@libraz/libcantus';
      const result = Note.tryParse('C#4');
      result.ok ? result.value.midi : result.error.message; // 61

    • Name a MIDI number (middle C = C4 = 60) as a note.

      Parameters

      • midi: number

        The MIDI number.

      • spelling: "flat" | "sharp" = 'sharp'

        Whether to prefer sharps or flats for black keys.

      Returns Note

      The spelled note, with octave.

    • The note name written in a notation system.

      The counterpart of Note.parse: a getter cannot take an argument, so the system is named here instead of on Function.name.

      Parameters

      • Optionalopts: NoteNameOptions

        system writes the name in that notation system instead of English.

      Returns string

      The note name, including the octave when the note has one.

      import { Note } from '@libraz/libcantus';
      Note.parse('G#').format({ system: 'german' }); // 'gis'
      Note.parse('G#').format({ system: 'japanese' }); // '嬰ト'

    • The note's frequency in Hz.

      The note's MIDI number is read as a step index, which is how the tuning module numbers steps: under twelve divisions the two coincide, and under any other the step index keeps counting from the same reference. A Tuning carries the three fields this takes, so an instance of it can be passed here directly.

      Parameters

      • Optionaltuning: TuningTable

        The temperament to read the note under; twelve-tone equal temperament with A4 = 440 Hz by default.

      Returns number

      The frequency in Hz.

      If the note has no octave and therefore no fixed pitch, if the temperament describes no tuning, or if the frequency falls outside the range a number holds.

      import { Note, Tuning } from '@libraz/libcantus';
      Note.parse('A4').frequency(); // 440
      Math.round(Note.parse('C4').frequency()); // 262
      Note.parse('A4').frequency(Tuning.edo(19)); // 440, the reference step of any EDO

    • Transpose by a signed number of semitones, keeping the spelling.

      The letter moves by the diatonic distance of the conventional interval for that many semitones, so Ab4 up a major second is Bb4 rather than A#4 and a flat key stays on the flat side. An octave-less note stays octave-less: only its pitch class is moved. Transposing by zero is the identity: the original spelling is preserved (no enharmonic respelling).

      Parameters

      • semitones: number

        The signed semitone offset.

      • Optionalopts: { spelling?: "flat" | "sharp" }

        spelling forces the result onto the sharp or flat side instead of following this note's letter.

      Returns Note

      The transposed note.

      import { Note } from '@libraz/libcantus';
      Note.parse('Ab4').transpose(2).name; // 'Bb4'
      Note.parse('Ab4').transpose(2, { spelling: 'sharp' }).name; // 'A#4'

    • Transpose by a spelled interval, keeping the spelling the interval names.

      Unlike Note.transpose, which picks a letter from the semitone count, the interval's diatonic number decides the letter: C up an augmented second is D#, not Eb.

      Parameters

      • interval: IntervalLike

        An interval name (e.g. 'A2', '-m3'), plain interval data, or an Interval; a descending interval moves down.

      Returns Note

      The transposed note.

      import { Interval, Note } from '@libraz/libcantus';
      Note.parse('C4').transposeBy('A2').name; // 'D#4'
      Note.parse('C4').transposeBy(Interval.parse('A2')).name; // 'D#4'
      Note.parse('C4').transposeBy('A4').name; // 'F#4', not 'Gb4'

    • The same spelled note in another octave.

      The letter and the alteration are untouched, so this places a note in a register rather than moving it by an interval: Cb4 given octave 3 is Cb3, not the B3 it sounds as.

      Parameters

      • octave: number

        The octave (scientific pitch notation), where middle C is C4.

      Returns Note

      The note in that octave.

      If the octave is not an integer in -100..100.

      import { Note } from '@libraz/libcantus';
      Note.parse('C#').withOctave(4).name; // 'C#4'
      Note.parse('Eb5').withOctave(3).name; // 'Eb3'

    • The note a transposing instrument must read to sound this one.

      The direction is written-side, as Key.forInstrument is for a key: the part is transposed away from what the instrument sounds, so a B flat instrument — which sounds a major second lower than it reads — has a concert C4 written as D4. The interval decides the letter, so a concert E flat 3 reads as C4 on an alto saxophone rather than as B sharp 3.

      The opposite reading, a written note back to the pitch it sounds, is Note.transposeBy applied to instrumentTransposition — the instrument's own written-to-sounding interval.

      Parameters

      • instrument: TransposingInstrument

        A built-in instrument name, or an interval naming a transposition the table does not carry.

      Returns Note

      The note the player reads.

      If the instrument is neither a known name nor a spelled interval.

      import { instrumentTransposition, Note } from '@libraz/libcantus';
      Note.parse('C4').forInstrument('clarinetBb').name; // 'D4'
      Note.parse('Eb3').forInstrument('altoSax').name; // 'C4'
      // And back: what a written C4 on a clarinet in A sounds as.
      Note.parse('C4').transposeBy(instrumentTransposition('clarinetA')).name; // 'A3'

    • The other ways this note can be spelled: the same sounding pitch written on the letter above and on the letter below.

      A list rather than a single answer, because a note has no one enharmonic partner the way a key has: C#4 is both Db4 and B##3. Only spellings within a double accidental are offered — the letters two steps away would need a triple one — so a note whose neighbours are unwritable gets a shorter list, and an octave-less note stays octave-less.

      Returns Note[]

      The alternative spellings, the letter above first.

      import { Note } from '@libraz/libcantus';
      Note.parse('C#4').enharmonic().map((note) => note.name); // ['Db4', 'B##3']
      Note.parse('Cb4').enharmonic().map((note) => note.name); // ['B3']

    • The scale degree this note occupies in a key, counted from 1 at the tonic.

      The degree is read from the sounding pitch, so an enharmonic spelling answers for the pitch it sounds: in C major both F# and Gb are outside the scale, and both B# and C are the tonic.

      Parameters

      • key: KeyLike

        The key to measure against; a key name, a plain key/scale, or a Key.

      Returns number | null

      The 1-based degree, or null when the note is not in the scale.

      If the value names no key.

      import { Note } from '@libraz/libcantus';
      Note.parse('E4').degreeIn('C major'); // 3
      Note.parse('F#4').degreeIn('C major'); // null

    • Order two notes by the pitch they sound, for Array.prototype.sort.

      Sounding pitch, not spelling: an enharmonic pair compares equal, so C#4 and Db4 keep the order they were given in while every note that sounds lower comes before them. Note.equals is the spelling comparison, and the two deliberately disagree about enharmonics.

      A note carrying an octave is ordered by its MIDI number and an octave-less one by its pitch class, so the octave-less notes of a mixed list gather at the bottom rather than being placed in a register they do not name.

      Parameters

      • other: Note

        The note to compare with.

      Returns number

      Negative when this note sounds lower, zero when the two sound the same pitch, positive when it sounds higher.

      import { Note } from '@libraz/libcantus';
      const notes = [Note.parse('G4'), Note.parse('C4'), Note.parse('E4')];
      notes.sort((a, b) => a.compareTo(b)).map((note) => note.name); // ['C4', 'E4', 'G4']
      Note.parse('C#4').compareTo(Note.parse('Db4')); // 0

    • Whether another note has the same letter, alteration, and octave.

      Parameters

      • other: Note

        The note to compare.

      Returns boolean

      True if the spellings are identical.

    • The plain note data, for JSON serialization.

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

      Returns NoteData

      A copy of the underlying plain note object.

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

      Parameters

      Returns string

      The spelled name, e.g. 'Bb3'.

      import { Note } from '@libraz/libcantus';
      Note.parse('G#4').toString({ system: 'japanese' }); // '嬰ト4'

    Settings
    Member Visibility

    On This Page
    Constructors
    Accessors
    Methods