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

aaroncshearer / tonal