tonal.notation
is a collection of javascript functions to parse notes, intervals and other musical elements to numerical pitch representations and convert them back to strings:
var notation = require('tonal.notation')
notation.note.parse('C2') // => [0, 2, null]
notation.interval.parse('5P') // => [1, 0]
notation.roman.parse('IV') // => [-1, 0]
notation.note.split('Bb3 dorian') // => ['Bb3', 'B', 'b', '3', '', 'dorian']
This is a low level library and part of tonal
One of the central ideas of tonal
is that, from the user persepective, notes and intervals are just strings (as opposite of objects, in most of the libraries). Internally they are converted to numerical formats to perform operations, and thats the library that performs that conversions. Aditionally, it allows to use different string notations (using the operation
function) so tonal
can deal with diferent note and interval formats.
This library it's for music library builders, not music library users.
Via npm only: npm i --save tonal.notation
and then require the whole library:
var notation = require('tonal.notation')
notation.roman.split(...)
or the individual functions (recommended):
var note = require('tonal.notation/note')
note(...)
This library represent pitches in three different formats:
- Strings literals: just it.
- Array notation: a numerical fifths/octave pitch representation
- Properties: pitch properties expressed with numbers
You can read more about them here
You can read the generated API documentation here
The implemented functions are:
interval
: return an interval string from a source.null
if not valid intervalinterval.parse
: convert an interval string into array notationinterval.str
: convert an interval in array notation to stringnote
: return an note string from a source.null
if not valid notenote.split
: divides a note string into its componentsnote.parse
: convert a note string into array notationnote.str
: convert a note in array notation to stringpitch
: return an pitch string from a source.null
if not valid pitchpitch.parse
: convert a pitch string into array notationpitch.str
: convert a pitch in array notation to stringroman.split
: divides a roman string into its componentsroman.parse
: convert a roman string into array notationoperation
: decorates a function to parse params and convert to string the resultparser
: decorates a parser function to ensure correct params and cache resultsprops
: convert from array notation to propertiesprops.parse
: convert from properties to array notation
Require the function and use it:
var parse = require('tonal.notation/note.parse')
parse('C2') // => [0, 2, null]
It's fast, since all results are memoized by default.
Although you can require the while library, it's recommended to require the individual functions.
There are four type of entities implemented at this moment:
- Notes: include pitch classes (notes without octaves), notes without durations and notes with duration. Examples:
Db
(pitch class),G#4
(notes),Ebb5/4
(note with duration) - Intervals: two different shorthand interval format: with accidentals and with qualifiers. Examples:
3M
or3
(major third),3m
or3b
(minor third) - Pitches: an abstraction that includes notes and intervals. Used when you want to manipulate both in a uniform way.
- Roman numerals: They are used to express pitches in relation with a scale. Examples:
VI
,bIV
,iii
You can:
- Split: divide the string into its parts (implemented using regexp)
- Parse: convert a string to array notation
- Str: convert from array notation back to string
- Props: convert from array notation to properties (and the opposite)
Examples:
notation.note.split('Gb4Maj7') // => ['Gb4Maj9', 'G', 'b', '4', '', 'Maj7']
notation.roman.split('bVIIMaj7') // => ['bVIIMaj7', 'b', 'VII', 'Maj7' ]
notation.note.parse('D4') // => [1, 0, 3, null]
notation.interval.parse('P5') // => [1, 0]
notation.note.str([3]) // => 'A'
The operation
function decorates another function that manipulates pitches in array notation without worry about parsing and convert back to string:
var operation = require('tonal.notation/operation')
var parse = require('tonal.notation/interval.parse')
var str = require('tonal.notation/interval.str')
// The function adds two intervals and the operation takes care of the conversion
var add = operation(parse, str, function(a, b) {
return [a[0] + b[0], a[1] + b[1]]
})
add('3m', '3M') // => '5P'
tonal.notation
provides a helper function to create your own parsers:
notation.parser(function (str) {
// the parameter is always an string
// the result of the parse process is cached
})
Read the generated documentation to learn more. Or take a look to tonal
MIT License