eniuz/tonal

Music tonal elements —pitches, chords, scales, keys— in Javascript

tonal

tonal is a modular, functional music theory library. Built from a collection of modules, it's able to create and manipulate tonal elements of music (pitches, chords, scales, keys). It deals with abstractions (not actual music) and while is designed for algorithmic composition and music generation, can be used to develop any kind of midi or audio software.

Although this library is under active development, the modules more than 1.0.0 are considered more or less stable.

Features

Although tonal is a work in progress, currently is implemented (but not all released):

• Note, intervals, transposition, distances, enharmonics
• Midi and frequency conversion
• Scales, chords, dictionaries
• Work with collection of notes: gamut, harmonizer
• Pitch sets and binary representations
• Keys, keys signatures, key scales and chords, key detection

Philosophy

This library is evolving with this ideas in mind:

• Notes and intervals are represented with strings, instead of objects. Easy and concise code.
• 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.
• Small and fast
• Modular: lot of modules (all integrated in tonal). You can require exactly the functions you need, or get the whole thing.
• Different notations: scientific notation by default. Helmholtz coming. Change it easily.
• Documented: all public functions are documented inside the code. Aside the generated documentation (in API.md file) a 'usage' guides are provided for each module.
• Learneable: since all the modules share the same philosophy is easy to work with them.
• Tested: carefully tested with coverage support.
• Advanced features: chord and scale detection, binary sets, chord progressions, key signatures...

Why

First of all, because I want to learn:

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

Also, I want a complete library, where I can model all what I learn, with some (for me) esoteric features like interval classes, binary scales and other weird stuff.

What

tonal is a collection of modules. They all live in this multi package repository (monorepo). Take a look inside packages:

Notation

• music-notation: Parse notes, intervals, scale names, alterations...

Notes and intervals

• note-midi: Note name to midi
• midi-note: Midi to note name
• midi-freq: Given a midi note, get it's frequency
• enharmonics: Get note enharmonics
• semitones: Get the size in semitones of an interval
• interval-class: Get the interval-class of an interval

Transposition and distances

• note-transposer: Transpose notes
• note-harmonizer: Harmonize notes or create harmonizer functions
• note-interval: Find the interval between two notes

Collection of notes

• pitch-set: Create pitch sets
• music-scale: Create music scales
• music-chord: Create music chords
• scale-dictionary: A music scales dictionary
• chord-dictionary: A music chords dictionary
• note-range: Create ranges of notes
• music-gamut: Work with collection of notes
• music-dictionary: Create dictionaries of notes
• interval-density: Analyze the intervals of a collection of notes

Keys

• music-key: Get key accidentals, relative major and minor, key notes and key alterations

Work in progress...

• scale-triads: Create triads from scales
• note-filter: Filter notes
• binary-set: Binary pitch set manipulation
• chord-type: Get the type of a chord
• chord-progression: Create chord progressions

## Examples

var tonal = require('tonal')

// notes and intervals
tonal.note.fromMidi(60) // => 'C4'
tonal.note.midi('A4') // => 69
tonal.note.fromFreq(220) // => 'A3'
tonal.note.freq('C') // => ...

// transposition and distances
tonal.tranpose('D4', '2M') // => 'E#4'
tonal.distance('C', 'G') // => '5P'
['c', 'd', 'e'].map(tonal.transpose('3M')) // => ['E4', 'F#4', 'G#4']

// scales and chords
tonal.scale('A major') // => ['A', 'B', 'C#', 'D', 'E', 'F#', 'G#']
tonal.chord('Cmaj7') // => ['C', 'E', 'G', 'B']

// harmonizers
var major = tonal.harmonizer('1 3 5')
major('C#') // => ['C#', 'E#', 'G#']
major('E5') /// => ['E5', 'G#5', 'B5']
var V7 = tonal.harmonizer('1 3 5 7m')
var V7ofV = function(tonic) { V7(tonal.transpose(tonic, '5P')) }
var V7ofV('D') // => ['A4', 'C#5', 'E5', 'G7']

// keys
key('###') // => 'A major'
key.signature('A major') // => '###'
key.altNotes('A major') // => ['F#', 'C#']
key.relative('minor', 'A major') // => 'F minor'

Install

Install via npm: npm i --save tonal

Then you can load the whole library:

var tonal = require('tonal')
tonal.transpose(tonal.note.fromMidi(60), '2M') // => 'D4'

... or install and require individual modules:

var midiNote = require('midi-note')
var transpose = require('note-transposer')
transpose(midiNote(60), '2M') // => 'D4'

## Documentation and tests

The functions are extensively documented inside the code. The generated documentation can be read here

To run the tests, clone this repository and run:

make

Resources and inspiration

This library takes inspiration from lot of places:

• 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

While developing, I read/study part of this resources:

The binary representation of the scales are based on the awesome book Arpeggio & Scale Resources by Rich Cochrane. Additional scale stuff (like scale spaces) are inspired by the works of Walter Zettel and William Zeitler

Trying to get the correct name of the things: http://music.stackexchange.com/questions/17780/naming-pitch-and-interval-collections

Interval analysis stuff are based on the book Harmonic Materials of Modern Music of Howard Hanson.

Other things this library can be related to:

• A Corpus Study of Rock Music: http://theory.esm.rochester.edu/rock_corpus/index.html
• Musical futures: https://www.musicalfutures.org/
• Music JSON proposal: https://github.com/soundio/music-json
• Staff notation: http://opusmodus.com/omn.html

License

MIT License