github

danigb / tonal

  • вторник, 15 марта 2016 г. в 02:13:42
https://github.com/danigb/tonal

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



tonal npm Build Status Code Climate js-standard-style license

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

Notes and intervals

Transposition and distances

Collection of notes

Keys

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

Work in progress...

 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:

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:

License

MIT License