tonal
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.
Example
import { Chord, Interval, Note, Scale } from "tonal";
Note.midi("C4"); // => 60
Note.freq("a4"); // => 440
Note.accidentals("c#2"); // => '#'
Note.transpose("C4", "5P"); // => "G4"
Interval.semitones("5P"); // => 7
Interval.distance("C4", "G4"); // => "5P"
// Scales
Scale.get("C major").notes; // => ["C", "D", "E", "F", "G", "A", "B"];
[1, 3, 5, 7].map(Scale.degrees("C major")); // => ["C", "E", "G", "B"]
Chord.get("Cmaj7").name; // => "C major seventh"
// Chord inversions
const triad = Chord.degrees("Cm");
[1, 2, 3].map(triad); // => ["C", "Eb", "G"];
[2, 3, 1].map(triad); // => ["Eb", "G", "C"];
[3, 1, 2].map(triad); // => ["G", "C", "Eb"];Install
Install all packages at once:
npm install --save tonalYou can read CHANGELOG here.
Usage
Tonal is compatible with both ES5 and ES6 modules, and browser.
ES6 import:
import { Note, Scale } from "tonal";ES5 require:
const { Note, Scale } = require("tonal");Browser
You can use the browser version from jsdelivr CDN directly in your html:
<script src="https://cdn.jsdelivr.net/npm/tonal/browser/tonal.min.js"></script>
<script>
console.log(Tonal.Key.minorKey("Ab"));
</script>Or if you prefer, grab the minified browser ready version from the repository.
Bundle size
tonal includes all published modules.
Although the final bundle it is small, you can reduce bundle sizes even more by installing the modules individually, and importing only the functions you need.
Note that individual modules are prefixed with @tonaljs/. For example:
npm i @tonaljs/noteimport { transpose } from "@tonaljs/note";
transpose("A4", "P5");Documentation
Generally, you just need to install tonal package (before it was called @tonaljs/tonal).
The API documentation is inside README.md of each module 👇
Notes and intervals
- @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
Scales and chords
- @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.
Voicings
- @tonaljs/voicing: Voicings and voice leadings for chords
- @tonaljs/voice-leading: Voice leading logic for transitions between voicings
- @tonaljs/voicing-dictionary: Collections of chord voicings
Keys, chord progressions
- @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
Time, rhythm
- @tonaljs/time-signature: Parse time signatures
- @tonaljs/duration-value: Note duration values
Utilities
- @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
Contributing
Read contributing document. To contribute open a PR and ensure:
- If is a music theory change (like the name of a scale) link to reliable references.
- If is a new feature, add documentation: changes to README of the affected module(s) are expected.
- Ad tests: changes to the test.ts file of the affected module(s) are expected.
- All tests are green
Inspiration
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
Projects using tonal
Showcase of projects that are using Tonal:
- Solfej by Shayan Javadi
- EarBeater by Morten Vestergaard
- Sonid (play store, apple store) by martijnmichel
- Songcraft by Gabe G'Sell
- React Guitar by 4lejandrito
- Fretty.app by tfeldmann
- Chordify by ashleymays
- Chordal by kad1kad
- muted.io by thisisseb
- Midi Sandbox by jdlee022
- music, eternal by kousun12
- Chromatone.center by davay42
- Super Oscillator by lukehorvat
Thank you all!
Add your project here by editing this file