2.2.2 • Public • Published

    tonal npm

    Build Status license codecov

    tonal is a small (20kb minified, 6kb gzipped) javascript modular music theory library. It provides functions to manipulate tonal elements of music (pitches, chords, scales, keys). It deals with abstractions (not actual music).

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


    API documentation


    Basic usage:

    import { midi, transpose, scale } from "tonal";
    midi("c4"); // => 60
    transpose("d4", "3M"); // => 'F#4'
    scale("major").map(transpose("C2")); // => ['C2', 'D2', 'E2', 'F2', 'G2', 'A2', 'B2']

    Tonal modules:

    import { Note, Interval, Distance, Scale, Chord } from "tonal";
    // note properties
    Note.chroma("Cb"); // => 11
    Note.pc("Db5"); // => 'Db'
    Note.freq("C#3"); // => 138.59
    Note.midi("A4"); // => 69
    Note.fromMidi(69); // => 'A4'
    Note.from({ alt: 2 }, "C4"); // => 'C##4'
    Note.from({ oct: 2 }, "C4"); // => 'C2'
    // interval properties
    Interval.semitones("5P"); // => 7
    Interval.invert("3m"); // => '6M'
    Interval.fromSemitones(7); // => '5P'
    // distances
    Distance.transpose("D4", "2M"); // => 'E#4'
    Distance.interval("C", "G"); // => '5P'
    Distance.semitones("C", "G"); // => 7
    // scales
    Scale.notes("Bb lydian"); // => [ 'Bb', 'C', 'D', 'E', 'F', 'G', 'A']
    Scale.notes("Eb bebop"); // => [ 'Eb', 'F', 'G', 'Ab', 'Bb', 'C', 'Db', 'D' ]
    Scale.names(); // => ["major", "minor", "bebop", ... and 90 more]
    // chords
    Chord.notes("Fm7b5"); // => [ 'F', 'Ab', 'Cb', 'Eb' ]
    Chord.names(); // => ['M', 'm', 'm7b5', ... and 100 more]

    Extensions modules:

    import * as Key from "tonal-key";
    Key.chord("Bb major"); // => ["BbMaj7", "Cm7", "Dm7", "EbMaj7", "F7", "Gm7", "Am7b5W]


    tonal is still a work in progress, but currently has implemented:

    • Note, intervals, transposition, distances, enharmonics, midi, frecuency tonal-note
    • Scales and chords, dictionaries tonal-dictionary
    • Utilities to work arrays of notes: sort, filter, rotate, shuffle tonal-array
    • Pitch sets comparations, chord and scale detection tonal-pcset

    In extensions:

    • Keys, keys signatures, key scales tonal-key
    • Complex note range generation tonal-range
    • Chord progressions
    • Enharmonics


    This library is evolving with this ideas in mind:

    • Functional: no classes, no side effects, no mutations. Just functions, data-in data-out. Most of the functions has the data to operate on as last argument and lot of functions are currified.
    • Notes and intervals are represented with strings, instead of objects.
    • Carefully written: small, fast and modular.
    • Documented: all public functions are fully documented inside the code. Read the generated API documentation here
    • Learneable: since all the modules share the same philosophy is easy to work with them.
    • Tested: every public method is tested with coverage support.
    • Advanced features: chord and scale detection, binary sets, chord progressions, key signatures...


    Using yarn: yarn add tonal (or a single module: yarn add tonal-scale)

    Using npm: npm install --save tonal (or: npm install --save tonal-scale)

    Browser: grab the minified file here (20kb) and include it in your html page (use a Tonal global object)

    <script src="tonal.min.js"></script>



    import { transpose, Scale } from "tonal";
    transpose("C4", "3M");
    Scale.notes("Db major");


    var Tonal = require("tonal");
    Tonal.transpose("C4", "2m");
    Tonal.Scale.notes("Bb minor");

    Browser (use the Tonal global object):

      console.log(Tonal.transpose('C4', '8P'))


    Mostly, because I want to learn:

    Reinventing the wheel is bad for business, but it’s great for learning *

    I want to learn about music theory and I want to express the concepts I learn using functional programming style.

    Also, I want a complete library, where I can model some (for me) esoteric features like interval classes, pitch sets, dft to pitch class sets, and so on.


    Tonal itself is built from a collection of packages.

    Please read the generated API documentation here to get an overview.

    Build, test and documentation

    It's a multipackage module that uses lerna to manage.

    To build the library from the first time use npm run init or yarn

    To run the tests: npm run test or just jest if you have jest globally installed.

    The distributable tonal.min.js file is generated with npm run dist

    The documentation can be generated with: npm run docs


    This library takes inspiration from other music theory libraries:


    MIT License


    npm i tonal

    DownloadsWeekly Downloads






    Unpacked Size

    53.8 kB

    Total Files


    Last publish


    • danigb