README
MusicTheoryJS v2
Music Theory Abstractions for analysis, synthesis, and real-time music composition. Designed for use with MIDI.
Includes nearly 70 pre-defined scale templates and over 40 pre-defined chords templates.
Designed to be an enterprise grade library that's easy to use and extend.
Examples:
import { Scale, Chord, Note, Instrument, buildTables } from "musictheoryjs";
// build the string tables
buildTables();
// create a note
const note = new Note("D4");
// create a scale
const scale = new Scale("C5(major)");
console.log(scale.getNoteNames()); // --> ["C5", "D5", "E5", "F5", "G5", "A5", "B5"]
// create a chord
const chord = new Chord("(Ab3)maj7");
console.log(chord.notes); // --> array of notes in the chord
// get the frequency of the scales 3rd degree
const instrument = new Instrument();
const freq = instrument.getFrequency(scale.degree(3)); // --> 659.26
// get the midi key for the scales 3rd degree
const midiKey = instrument.getMidiKey(scale.degree(3)); // --> 76
A Note On Performance
The most performant and efficient way to create entities in MusicTheoryJS is to use Initializer objects e.g. {root: 5, octave: 3}. Using strings e.g. "C5(major)" is also fast when used the right way.
Each entity that accepts a string initializer uses an ideal format specified in the documentation. Using a format other what is prescribed will bypass the lookup table and the resulting performance will be much slower.
If you intend to use string initializers, you should probably use the buildTables
function to create the lookup tables. Probably soon after the library loads.
import { buildTables } from "musictheoryjs";
buildTables();
This can be great for client side if you run buildTables in an async function and you present a spinner and/or prevent the user from creating new entities until the tables are built. This way you have control over the performance of your application.
Note: buildTables should only(optionally) be called once soon after your app loads and only if you intend to use string initialization.
Installation
npm:
npm i musictheoryjs@latest
yarn:
yarn add musictheoryjs
Usage
import * as mt from "musictheoryjs";
// or
import {
Chord,
Scale,
Note,
Instrument,
Semitone,
Modifier,
} from "musictheoryjs";
Semitones
Semitones are simple numbers that represent notes
There are 12 in total ranging from 0(C) to 11(B)
0 -> C
1 -> C#
2 -> D
3 -> D#
4 -> E
5 -> F
6 -> F#
7 -> G
8 -> G#
9 -> A
10 -> A#
11 -> B
Modifiers
Modifiers are this library's way of representing alterations.
Think of modifiers as the mathematical form.
Flat is represented as -1,
Sharp is represented as 1,
Natural is represented as 0.
You can import the Modifier enum or just create your own constants when needed.
Instruments
Instruments encapsulate tuning and methods for calculating the frequency and midi key notes.
the tuning is specified as the A4 frequency in Hertz. The default tuning is 440Hz.
Notes
Notes encapsulate the semitone and octave of a musical note.
Chords
Chords are made from a root semitone, octave, template(containing ChordIntervals), and a base scale(default is the Major scale).
The following Pre-defined templates are available:
maj | maj4 | maj6 | maj69 |
maj7 | maj9 | maj11 | maj13 |
maj7s11 | majb5 | min | min4 |
min6 | min7 | minAdd9 | min69 |
min9 | min11 | min13 | min7b5 |
dom7 | dom9 | dom11 | dom13 |
dom7s5 | dom7b5 | dom7s9 | dom7b9 |
dom9b5 | dom9s5 | dom7s11 | dom7s5s9 |
dom7s5b9 | dim | dim7 | aug |
sus2 | sus4 | fifth | b5 |
s11 |
Scales
Scales are made from a key semitone, octave, template(a list of intervals).
The following Pre-defined templates are available:
major | minor | ionian | dorian |
phrygian | lydian | mixolydian | aeolian |
locrian | enigmaticMajor | enigmaticMinor | minor7b5 |
major7s4s5 | harmonicMajor | harmonicMinor | doubleHarmonic |
melodicMinorAscending | melodicMinorDescending | majorPentatonic | majorPentatonicBlues |
minorPentatonic | minorPentatonicBlues | b5Pentatonic | minor6Pentatonic |
dim8Tone | dom8Tone | neopolitanMajor | neopolitanMinor |
hungarianMajor | hungarianMinor | hungarianGypsy | spanish |
spanish8Tone | spanishGypsy | augmented | dominantSuspended |
bebopMajor | bebopDominant | mystic | overtone |
leadingTone | hirojoshi | japaneseA | japaneseB |
oriental | arabian | persian | balinese |
kumoi | pelog | algerian | chinese |
mongolian | egyptian | hindu | romanian |
hindu | insen | iwato | scottish |
yo | istrian | ukranianDorian | petrushka |
ahavaraba | halfDiminished | jewish | byzantine |
acoustic |
Development
Step 1:
Fork the project
Step 2:
Create a new branch - Name it based on the work/feature your working on
Step 3:
From the project root(after you checkout your branch), run:
npm install
or
yarn install
Step 4:
Submit a pull request
Scripts:
Build:
npm run build
or
yarn build
Test:
npm run test
or
yarn test
Lint:
npm run lint
or
yarn lint
Build Docs:
npm run build-docs
or
yarn build-docs