/v2

tonal v2

Primary LanguageJavaScriptMIT LicenseMIT

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.

Demo

API documentation

Examples

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]

Features

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

Philosophy

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...

Install

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>

Usage

ES6:

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

ES5:

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

Browser (use the Tonal global object):

<script>
  console.log(Tonal.transpose('C4', '8P'))
</script>

Why

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.

What

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

Inspiration

This library takes inspiration from other music theory libraries:

License

MIT License