For AI agents
How to write correct code with tonal. Written for coding agents, useful for people too.
This page is for coding agents (and people) writing code that uses tonal. Read
it before writing tonal code, then look up the functions you need in the
API list, which has every
function with its exact signature and return type. Don't guess function names:
tonal's API has changed over the years, so names you remember may be gone or
deprecated. Every page of these docs is also available as markdown: add .md
to its url, or start from llms.txt.
The API list is also in the npm package, at node_modules/tonal/llms-api.txt,
matching the version you have installed.
Import
import { Chord, Interval, Key, Note, Scale } from "tonal";tonal exports one namespace per module (Note, Interval, Chord,
ChordType, Scale, ScaleType, Key, Mode, Midi, Pcset,
Progression, RomanNumeral, Range, Collection, Voicing,
VoicingDictionary, VoiceLeading, TimeSignature, DurationValue,
RhythmPattern, AbcNotation) and a few top-level functions (note,
interval, transpose, distance). Each namespace is also its own npm package:
import * as Chord from "@tonaljs/chord". Use tonal unless bundle size
matters. In a browser without a bundler, tonal/browser/tonal.min.js defines a
Tonal global.
Don't use the deprecated namespaces Tonal, PcSet, ChordDictionary and
ScaleDictionary: use the top-level functions, Pcset, ChordType and
ScaleType.
How tonal works
Everything is a string or a plain object. Notes are strings ("C4",
"Eb5", "F#"), intervals are strings ("5P", "3m"), chords and scales are
named by strings ("Cmaj7", "D dorian"). Functions that parse a name return
a plain object with its properties. There are no classes and nothing mutates.
Invalid input never throws. It returns an empty value, so check it:
Note.get("H4").empty; // => true
Chord.get("Cxyz").empty; // => true
Note.transpose("C4", "X"); // => ""
Note.midi("C"); // => null (a pitch class has no midi number)
Key.majorKey("X").tonic; // => "" (Key objects have no `empty` field)
Interval.semitones("X"); // => NaN
Note.chroma("X"); // => NaNNumber results are null, undefined or NaN depending on the function: the
API list shows which. NaN passes typeof x === "number", so test with
Number.isFinite(x).
Notes and pitch classes. A note with an octave ("C4") is a note; without
one ("C") it's a pitch class. Most functions keep what they're given:
transposing a pitch class gives a pitch class, and a chord or scale with a
plain tonic has pitch-class notes. Octave 4 is the one with middle C ("C4" is
midi 60, "A4" is 440 Hz).
Note.transpose("C4", "5P"); // => "G4"
Note.transpose("C", "8P"); // => "C"
Scale.get("C4 major").notes; // => ["C4", "D4", "E4", "F4", "G4", "A4", "B4"]Intervals are written number first, quality second: "5P", "3M",
"3m", "4A", "5d", "-2M" (descending). Quality first ("P5", "M3") is
also accepted as input, but tonal always returns number first:
Interval.distance("C4", "G4"); // => "5P"
Interval.distance("G4", "C4"); // => "-5P"
Interval.distance("G", "C"); // => "4P" (between pitch classes, always upwards)
Interval.semitones("5P"); // => 7
Interval.fromSemitones(7); // => "5P"Spelling is kept. Transposition follows the interval, so the result can have
double accidentals or E#. Use Note.simplify or Note.enharmonic when you
want the simplest name:
Note.transpose("C#", "3M"); // => "E#"
Note.simplify("C##4"); // => "D4"
Note.enharmonic("C#4"); // => "Db4"MIDI numbers have no spelling, so converting them to names needs a choice.
Note.fromMidi uses flats, Note.fromMidiSharps uses sharps:
Note.midi("C4"); // => 60
Note.fromMidi(61); // => "Db4"
Note.fromMidiSharps(61); // => "C#4"Chords
Chord.get("Cmaj7").notes; // => ["C", "E", "G", "B"]
Chord.get("Cmaj7").intervals; // => ["1P", "3M", "5P", "7M"]
Chord.get("Cmaj7/E").notes; // => ["E", "G", "B", "C"] (the bass first)
Chord.notes("Cmaj7", "C4"); // => ["C4", "E4", "G4", "B4"]
Chord.transpose("Dm7", "4P"); // => "Gm7"-
Don't put an octave in a chord name.
Chord.get("C4maj7")is empty, andChord.get("C4")is not C at octave 4 but C quartal (["C", "F", "Bb", "Eb"],"4"is an alias of the quartal chord). For notes with octaves, pass the tonic separately:Chord.notes("Cmaj7", "C4")orChord.notes("maj7", "C4"). -
Chord names accept the usual symbols and aliases (
"CM7","CΔ","C^7","C-7","Cø","Cm7b5","C7(b9,#9)"). Check.emptyfor symbols you aren't sure of.ChordType.get("maj7").aliaseslists the aliases of a type. -
Chord.detectreturns names, best match first, and the lowest note is the bass. A major triad is named"CM", not"C":Chord.detect(["E4", "G4", "C5"]); // => ["CM/E", "Em#5"] Chord.detect(["C", "Eb", "G", "Bb"]); // => ["Cm7", "Eb6/C"] -
Chord degrees by name (counted from the major scale of the root, as in chord symbols):
Chord.formula,Chord.noteOf,Chord.degreeOf.Chord.degreesByImportancesorts them by how much they define the chord, to choose which notes to keep when there are fewer voices than chord tones:Chord.formula("Cm7"); // => ["1", "b3", "5", "b7"] Chord.noteOf("G13", "3"); // => "B" Chord.degreesByImportance("G13"); // => ["3", "b7", "9", "1", "5", "13"] -
Chord.degreesandChord.stepsare different: they count chord notes by position (1 or 0 is the root), not degrees by name.Chord.degrees("C")(3)is"G", the third note of the chord.
Scales, modes and keys
Scale.get("D dorian").notes; // => ["D", "E", "F", "G", "A", "B", "C"]
Scale.rangeOf("C major")("C4", "C5"); // => ["C4", "D4", ..., "B4", "C5"]
[1, 3, 5].map(Scale.degrees("C major")); // => ["C", "E", "G"]
Key.majorKey("F").chords; // => ["Fmaj7", "Gm7", "Am7", "Bbmaj7", "C7", "Dm7", "Em7b5"]
Key.majorKey("F").triads; // => ["F", "Gm", "Am", "Bb", "C", "Dm", "Edim"]
Key.minorKey("A").harmonic.chords; // => ["AmMaj7", "Bm7b5", "C+maj7", "Dm7", "E7", "Fmaj7", "G#o7"]- Scale names are full names:
"C major","A minor","C maj"is empty.Scale.names()lists all of them. A scale without a tonic ("major") has intervals but no notes. Key.majorKeyandKey.minorKeyreturn everything about a key at once (scale, triads, seventh chords, harmonic functions, chord scales, secondary and substitute dominants). A minor key has three scales:natural,harmonicandmelodic. InsecondaryDominantsand similar lists,""means the degree has none.Modeis about the seven Greek modes (Mode.names()); for other scales useScale.
Roman numerals and progressions
Progression.fromRomanNumerals("Bb", ["ii7", "V7", "Imaj7"]); // => ["Cm7", "F7", "Bbmaj7"]
Progression.toRomanNumerals("C", ["Dm7", "G7", "Cmaj7"]); // => ["IIm7", "V7", "Imaj7"]Lowercase numerals are minor ("ii7" is the same as "IIm7"). Applied
chords such as "V7/V" are supported. RomanNumeral.get parses one numeral
into its parts.
Voicings
Voicing.get("Dm7"); // => ["F3", "A3", "C4", "E4"]
Voicing.search("Cmaj7", ["E3", "D5"]); // every voicing in the range
Voicing.sequence(["Dm7", "G7", "Cmaj7"], ["E3", "G4"]); // one voicing per chord, smooth voice leadingVoicings come from a dictionary of voicings for common chord types
(VoicingDictionary), within a range of notes. This module is being
extended: check the API list for its current functions.
Time
tonal describes where things are in musical time, never when they play: there
is nothing in seconds, no tempo-based timing, no scheduling and no audio.
TimeSignature, DurationValue and RhythmPattern cover meters, note values
and rhythm patterns. Use an audio or scheduling library for playback.
Common mistakes
- Using functions that don't exist or are deprecated: check the
API list. Functions marked
[deprecated]there still work, but write new code with their replacement. - Not checking for empty results: an invalid name gives
"",[],nullor an object withempty: true, and the error shows up later. - Expecting octaves from chords and scales named with a pitch class, or putting the octave inside a chord name.
- Comparing notes as strings:
"C#4"and"Db4"are different strings for the same key on a piano. CompareNote.midi(a) === Note.midi(b)for the same pitch, orNote.chroma(a) === Note.chroma(b)for the same pitch class. - Writing
"C"for a C major chord when comparing withChord.detectresults, which name it"CM". Compare chords by their notes or withChord.get(name).symbolinstead of by name.