tonal is a music theory library. Contains functions to manipulate tonal elements of music (note, intervals, chords, scales, modes, keys). It deals with abstractions (not actual music or sound).

tonal is implemented in Typescript and published as a collection of Javascript npm packages.

It uses a functional programing style: all functions are pure, there is no data mutation, and entities are represented by data structures instead of objects.

import { Note, Interval, Scale } from "@tonaljs/tonal";

Note.midi("A4"); // => 60
Note.freq("a4").freq; // => 440
Note.accidentals("c#2"); // => '#'
Note.transpose("C4", "5P"); // => "G4"
Interval.semitones("5P"); // => 7
Interval.distance("C4", "G4"); // => "5P"
Scale.get("C major").notes; // =>["C", "D", "E", "F", "G", "A", "B"];

Install all packages at once:

npm install --save @tonaljs/tonal

Tonal is compatible with both ES5 and ES6 modules, and browser.

import { Note, Scale } from "@tonaljs/tonal";

const { Note, Scale } = require("@tonaljs/tonal");

Grab the minified browser ready version from the repository and include in the html file:

<script src="tonal.min.js"></script>
<script>
  console.log(Tonal.Key.minorKey("Ab"));
</script>

@tonaljs/tonal includes all published modules.

Although the final bundle it is small (less than 9kb minified and gzipped), you can reduce bundle sizes by installing the modules individually, and importing the functions you need:

npm i @tonaljs/note

import { transpose } from "@tonaljs/note";
transpose("A4", "P5");

Generally, you just need to install:

• @tonaljs/tonal: All modules bundled in one package

The API documentation lives inside README.md file of each module

• @tonaljs/note: Note operations (simplify, transposeBy )
• @tonaljs/midi: Midi number conversions
• @tonaljs/interval: Interval operations (add, simplify, invert)
• @tonaljs/abc-notation: Parse ABC notation notes

• @tonaljs/scale: Scales
• @tonaljs/scale-type: A dictionary of scales
• @tonaljs/chord: Chords
• @tonaljs/chord-type: A dictionary of chords
• @tonaljs/chord-detect: Detect chords from notes
• @tonaljs/pcset: Pitch class sets. Compare note groups.

• @tonaljs/key: Major and minor keys, it's scales and chords
• @tonaljs/mode: A dictionary of Greek modes (ionian, dorian...)
• @tonaljs/progression: Chord progressions
• @tonaljs/roman-numeral: Parse roman numeral symbols

• @tonaljs/core: Core functions (note, interval, transpose and distance)
• @tonaljs/collection: Utility functions to work with collections (range, shuffle, permutations)
• @tonaljs/range: Create note ranges

Read contributing document for instructions

This library takes inspiration from other music theory libraries:

• Teoria: https://github.com/saebekassebil/teoria
• Impro-Visor: https://www.cs.hmc.edu/~keller/jazz/improvisor/
• MusicKit: https://github.com/benzguo/MusicKit
• Music21: http://web.mit.edu/music21/doc/index.html
• Sharp11: https://github.com/jsrmath/sharp11
• python-mingus: https://github.com/bspaans/python-mingus

Showcase of projects that are using Tonal:

• Solfej by Shayan Javadi
• EarBeater by Morten Vestergaard
• sonid.app (play store, apple store) by martijnmichel

Thank you all!

Add your project here by editing this file

MIT License