@tonaljs/note
v4.11.0
Published
Parse and manipulate music notes in scientific notation
Downloads
10,308
Readme
@tonaljs/note
A collection of functions to manipulate musical notes
Usage
ES6:
import { Note } from "tonal";
nodejs:
const { Note } = require("tonal");
single module:
import { get } from "@tonaljs/note";
API
Note properties
Note.get(noteName: string) => Note
Given a note name, it returns an object with the following properties:
- name: the note name
- pc: the pitch class name
- letter: the note letter
- step: the letter number (0..6)
- acc: the note accidentals
- alt: the accidental number (..., -1 = 'b', 0 = '', 1 = '#', ...)
- oct: the octave (or null if not present)
- chroma: the note chroma (0..11)
- midi: the note midi or null if octave is not present
- freq: the note frequency in Hertzes, or null if the octave is not present
Note.get("C4"); // => { name: "C4", midi: 60, ... }
It has several shorthands to retrieve properties easily:
Note.name("fx4"); // => "F##4"
Note.pitchClass("Ab5"); // => "Ab"
Note.accidentals("Eb"); // => 'b'
Note.octave("C4"); // => 4
Note.midi("A4"); // => 69
Note.freq("A4"); // => 440
Note.chroma("D"); // => 2
["C", "D", "E"].map(Note.chroma); // => [0, 2, 4]
Note.fromMidi(midi: number) => string
Given a midi number, returns the note name. This function is the same as midiToNoteName
from @tonaljs/midi
Note.fromMidi(61); // => "Db4"
Note.fromMidi(61.7); // => "D4"
[60, 61, 62].map(Note.fromMidi); // => ["C4", "Db4", "D4"]
There's also a Note.fromMidiSharps
version:
Note.fromMidiSharps(61); // => "C#4"
Note.fromFreq(freq: number) => string
Given a frequency in Hz, returns the note name.
Note.fromFreq(440); // => "A4"
It rounds to the nearest name:
[440, 550, 660].map(t.Note.fromFreq); // => [ 'A4', 'Db5', 'E5' ]
There's also a Note.fromFreqSharps
version:
[440, 550, 660].map(t.Note.fromFreqSharps); // => [ 'A4', 'C#5', 'E5' ]
Transposition and distances
transpose(note: string, interval: string) => string
Transpose a note by an interval. It returns the note name or "" if not valid parameters.
Examples:
Note.transpose("d3", "3M"); // => "F#3"
Note.transpose("D", "3M"); // => "F#"
transposeBy
and transposeFrom
are currified versions of this function to make easy work with arrays:
["C", "D", "E"].map(Note.transposeBy("5P"));
// => ["G", "A", "B"]
["1P", "3M", "5P"].map(Note.transposeFrom("C"));
// => ["C", "E", "G"]
transposeFifths(noteName: string, fifths: number) => string
Transpose a note a given number of fifths:
Note.transposeFifths("G4", 3); // => "E6"
Note.transposeFifths("G", 3); // => "E"
[0, 1, 2, 3, 4, 5, 6].map((n) => transposeFifths("F#", n));
// => ["F#", "C#", "G#", "D#", "A#", "E#", "B#"]
[0, -1, -2, -3, -4, -5, -6].map((n) => transposeFifths("Bb", n));
// => ["Bb", "Eb", "Ab", "Db", "Gb", "Cb", "Fb"]
Note.distance(from: string, to: string) => string
Find the interval between two notes:
Note.distance("C", "D").toEqual("2M");
Note.distance("C3", "E3").toEqual("3M");
Note.distance("C3", "E4").toEqual("10M");
Named collections
names(array?: any[]) => string[]
Get note names of an array of anything. Notice that names are normalized:
Note.names(["fx", "bb", 12, "nothing", {}, null]); // => ["F##", "Bb"];
Without parameters, it returns a list of natural pitch classes:
Note.names(); // => ["C", "D", "E", "F", "G", "A", "B"]
You may be in a situation where you have note names with octaves, but don't want them, remove them like this:
Note.names(["C2", "C#3", "Db4", 12, "nothing", {}, null]).map(Note.pitchClass); // => ['C', 'C#', 'Db']
sortedNames(array?: any[], comparator?: NoteComparator) => string[]
Sort an array of note names in ascending order. Pitch classes are listed before notes. Anything that is not a note is removed:
Note.sortedNames(["c2", "c5", "c1", "c0", "c6", "c"]);
// => ['C', 'C0', 'C1', 'C2', 'C5', 'C6']
Note.sortedNames(["c", "F", "G", "a", "b", "h", "J"]);
// => ['C', 'F', 'G', 'A', 'B']
An optional comparator can be passed as a second argument:
Note.sortedNames(["c2", "c5", "c1", "c0", "c6", "c"], Note.descending);
// => ['C6', 'C5', 'C2', 'C3', 'C1', 'C0']
sortedUniqNames(array?: any[]) => string[]
Sort notes ascending and remove duplicates.
Enharmonics
simplify(noteName: string) => string
Given a note name, return the same note with less accidentals (or "" if not a valid note):
Note.simplify("C#"); // => "C#"
Note.simplify("C##"); // => "D"
Note.simplify("C###"); // => "D#"
enharmonic(noteName: string, pitchClass?: string) => string
Given a note name, returns its enharmonic (or "" if not valid note):
Note.enharmonic("C#"); // => "Db"
Note.enharmonic("C##"); // => "D"
Note.enharmonic("C###"); // => "Eb"
Note.eharmoinic("C##b"); // => ""
Using eharmonic on a natural will return the same value passed in:
Note.eharmonic("C"); // => "C"
Note.eharmonic("C4"); // => "C4"
The destination pitch class can be enforced to calculate the octave:
Note.enharmonic("F2", "E#"); // => "E#2"
Note.enharmonic("B2", "Cb"); // => "Cb3"
Note.enharmonic("C2", "B#"); // => "B#1"
Enforced pitch class must have the same chroma as the note, otherwise "" is returned:
Note.enharmonic("F2", "Eb"); // => ""