Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tonaljs/tonal
A functional music theory library for Javascript
https://github.com/tonaljs/tonal
chord-progression chords functional interval javascript key-signatures music music-theory scale transpose typescript
Last synced: about 2 months ago
JSON representation
A functional music theory library for Javascript
- Host: GitHub
- URL: https://github.com/tonaljs/tonal
- Owner: tonaljs
- Created: 2015-07-17T18:55:18.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2024-04-23T20:36:54.000Z (5 months ago)
- Last Synced: 2024-05-28T13:21:42.724Z (4 months ago)
- Topics: chord-progression, chords, functional, interval, javascript, key-signatures, music, music-theory, scale, transpose, typescript
- Language: TypeScript
- Homepage: https://tonaljs.github.io/tonal/docs
- Size: 9.61 MB
- Stars: 3,723
- Watchers: 61
- Forks: 207
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- Contributing: docs/CONTRIBUTING.md
- Code of conduct: docs/CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-list - tonal
README
# tonal
[](https://www.npmjs.com/package/tonal)
`tonal` is a music theory library. Contains functions to manipulate tonal
elements of music (note, intervals, chords, scales, modes, keys). It deals with
abstractions (not actual music or sound).
`tonal` is implemented in Typescript and published as a collection of Javascript
npm packages.
It uses a functional programing style: all functions are pure, there is no data
mutation, and entities are represented by data structures instead of objects.
## Example
```js
import { Chord, Interval, Note, Scale } from "tonal";
Note.midi("C4"); // => 60
Note.freq("a4"); // => 440
Note.accidentals("c#2"); // => '#'
Note.transpose("C4", "5P"); // => "G4"
Interval.semitones("5P"); // => 7
Interval.distance("C4", "G4"); // => "5P"
// Scales
Scale.get("C major").notes; // => ["C", "D", "E", "F", "G", "A", "B"];
[1, 3, 5, 7].map(Scale.degrees("C major")); // => ["C", "E", "G", "B"]
Chord.get("Cmaj7").name; // => "C major seventh"
// Chord inversions
const triad = Chord.degrees("Cm");
[1, 2, 3].map(triad); // => ["C", "Eb", "G"];
[2, 3, 1].map(triad); // => ["Eb", "G", "C"];
[3, 1, 2].map(triad); // => ["G", "C", "Eb"];
```
## Install
Install all packages at once:
```bash
npm install --save tonal
```
You can read [CHANGELOG here](https://github.com/tonaljs/tonal/blob/main/docs/CHANGELOG.md).
## Usage
Tonal is compatible with both ES5 and ES6 modules, and browser.
#### ES6 `import`:
```js
import { Note, Scale } from "tonal";
```
#### ES5 `require`:
```js
const { Note, Scale } = require("tonal");
```
#### Browser
You can use the browser version from jsdelivr CDN directly in your html:
```html
console.log(Tonal.Key.minorKey("Ab"));
```
Or if you prefer, grab the
[minified browser ready version](https://raw.githubusercontent.com/tonaljs/tonal/master/packages/tonal/browser/tonal.min.js)
from the repository.
#### Bundle size
`tonal` includes all published modules.
Although the final bundle it is small, you can
reduce bundle sizes even more by installing the modules individually, and
importing only the functions you need.
Note that individual modules are prefixed with `@tonaljs/`. For example:
```bash
npm i @tonaljs/note
```
```js
import { transpose } from "@tonaljs/note";
transpose("A4", "P5");
```
## Documentation
Generally, you just need to install `tonal` package (before it was called `@tonaljs/tonal`).
The API documentation is inside README.md of each module 👇
#### Notes and intervals
- [@tonaljs/note](/packages/note): Note operations (simplify, transposeBy )
- [@tonaljs/midi](/packages/midi): Midi number conversions
- [@tonaljs/interval](/packages/interval): Interval operations (add, simplify,
invert)
- [@tonaljs/abc-notation](/packages/abc-notation): Parse ABC
notation notes
#### Scales and chords
- [@tonaljs/scale](/packages/scale): Scales
- [@tonaljs/scale-type](/packages/scale-type): A dictionary of scales
- [@tonaljs/chord](/packages/chord): Chords
- [@tonaljs/chord-type](/packages/chord-type): A dictionary of chords
- [@tonaljs/chord-detect](/packages/chord-detect): Detect chords from notes
- [@tonaljs/pcset](/packages/pcset): Pitch class sets. Compare note groups.
#### Voicings
- [@tonaljs/voicing](/packages/voicing/): Voicings and voice leadings for chords
- [@tonaljs/voice-leading](/packages/voice-leading/): Voice leading logic for transitions between voicings
- [@tonaljs/voicing-dictionary](/packages/voicing-dictionary/): Collections of chord voicings
#### Keys, chord progressions
- [@tonaljs/key](/packages/key): Major and minor keys, it's scales and chords
- [@tonaljs/mode](/packages/mode): A dictionary of Greek modes (ionian,
dorian...)
- [@tonaljs/progression](/packages/progression): Chord progressions
- [@tonaljs/roman-numeral](/packages/roman-numeral): Parse roman numeral symbols
#### Time, rhythm
- [@tonaljs/rhythm-pattern](/packages/rhythm-pattern): Generate and manipulate rhythmic patterns
- [@tonaljs/time-signature](/packages/time-signature): Parse time signatures
- [@tonaljs/duration-value](/packages/duration-value): Note duration values
#### Utilities
- [@tonaljs/core](/packages/core): Core functions (note, interval, transpose and
distance)
- [@tonaljs/collection](/packages/collection): Utility functions to work with
collections (range, shuffle, permutations)
- [@tonaljs/range](/packages/range): Create note ranges
## Contributing
Read [contributing document](/docs/CONTRIBUTING.md). To contribute open a PR and ensure:
- If is a music theory change (like the name of a scale) link to reliable references.
- If is a new feature, add documentation: changes to README of the affected module(s) are expected.
- Ad tests: changes to the test.ts file of the affected module(s) are expected.
- All tests are green
## Inspiration
This library takes inspiration from other music theory libraries:
- 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
- Sharp11: https://github.com/jsrmath/sharp11
- python-mingus: https://github.com/bspaans/python-mingus
## Projects using tonal
Showcase of projects that are using Tonal:
- [Solfej](https://www.solfej.io/) by
[Shayan Javadi](https://github.com/ShayanJavadi)
- [EarBeater](https://www.earbeater.com/online-ear-training/) by
[Morten Vestergaard](https://github.com/vellebelle)
- [Sonid](https://sonid.app/)
([play store](https://play.google.com/store/apps/details?id=org.stroopwafel.music.app),
[apple store](https://apps.apple.com/us/app/sonid/id1490221762?ls=1)) by
[martijnmichel](https://github.com/martijnmichel)
- [Songcraft](https://songcraft.io/) by
[Gabe G'Sell](https://github.com/gabergg)
- [React Guitar](https://react-guitar.com/) by
[4lejandrito](https://github.com/4lejandrito)
- [Fretty.app](https://fretty.app/) by [tfeldmann](https://github.com/tfeldmann)
- [Chordify](https://ashleymays.github.io/Chordify) by [ashleymays](https://github.com/ashleymays)
- [Chordal](https://chordal.vercel.app) by [kad1kad](https://github.com/kad1kad)
- [muted.io](https://muted.io/) by [thisisseb](https://github.com/thisisseb)
- [Midi Sandbox](https://midisandbox.com/) by [jdlee022](https://github.com/jdlee022)
- [music, eternal](https://eternal.rob.computer) by [kousun12](https://github.com/kousun12)
- [Chromatone.center](https://chromatone.center) by [davay42](https://github.com/davay42)
- [Super Oscillator](https://github.com/lukehorvat/super-oscillator) by [lukehorvat](https://github.com/lukehorvat)
Thank you all!
Add your project here by
[editing this file](https://github.com/tonaljs/tonal/edit/main/README.md)
## License
[MIT License](docs/LICENSE)