music-gamut API

October 21, 2015 · View on GitHub

All functions are pure (no side effects, no mutations).

binarySet(source) → {String}

Get the binary set number from a collection of notes.

A binary set number is a 12 digit binary numbers, each digit represent a note in the chromatic scale. For example '10101100000' means ['C', 'D', 'E', 'F']

The binary set representation is very useful to compare different sets (scales, for example)

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 282

Returns:

the binary number

Type: String

Example

gamut.binarySet('C D E F G A B C') // => '101011010101'

distances(tonic, source) → {Array.<String>}

Get the distances (in intervals) of the notes from a tonic

If the tonic is null, the first note of the gamut is asumed to be the tonic

Important: al pitch classes are converted to octave 0 before calculating the distances.

Parameters:

Name	Type	Description
`tonic`	String \| Array	(Optional) the note to calculate the interval from. If its null, the first note of the gamut is the tonic
`source`	String \| Array \| Array.<Array>	the notes

Source:

gamut.js , lineno 178

Returns:

the intervals

Type: Array.<String>

Example

gamut.distance('D2', 'D2 E2 F2') // => ['1P', '2M', '3m']
// pitch classes are octave 0
gamut.distance('C', 'C2') // => ['15P']
gamut.distance('C2', 'C') // => ['-15P']

fromBinarySet(source, tonic) → {Array.<String>}

Get a note set from a binary set number and a (optionally) a tonic.

This function accepts binary numbers (as strings) or integers. For example, 2773 identify the major scale.

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut
`tonic`	String	(Optional) the first note of the set ('C' by default)

Source:

gamut.js , lineno 303

See:

`binarySet`

Returns:

the set pitch classes (note names without octaves)

Type: Array.<String>

Example

gamut.fromBinarySet('101011010101') // => ['C', 'D', 'E', 'F', 'G', 'A', 'B']
gamut.fromBinarySet(2773, 'Bb') // => ['Bb', 'C', 'D', 'Eb', 'F', 'G', 'A']

gamut(source) → {Array}

Get a gamut: create an array from a source. The source can be a string with items separated by spaces, commas or bars (|), an array or an object.

If the source is an array, it's returned as it. If its an object you get an array with the object as the only element.

This function does not perform any transformation to the items of the array. This function always return an array, even if its empty

Parameters:

Name	Type	Description
`source`	String \| Array \| Object	the source

Source:

gamut.js , lineno 10

Returns:

the source converted to an array (never null)

Type: Array

Example

gamut('c d e') // => [ 'c', 'd', 'e' ]
gamut('CMaj7 | Dm7 G7') // => [ 'CMaj7', 'Dm7', 'G7' ]
gamut('1, 2, 3') // => ['1', '2', '3']
gamut([1, 'a', 3]) // => [1, 'a', 3]
gamut(object) // => [ object ]
gamut(null) // => [ ]

heights(source) → {Array.<Integer>}

Get the heights of the notes or intervals. The height of a note is the distance in semitones from 'C0' to the note. Applied to intervals, is the number of semitones

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 123

Returns:

the heights

Type: Array.<Integer>

Example

gamut.heights('C0 D0 C1') // => [0, 2, 12]

intervals(source) → {Array.<String>}

Get the intervals of the gamut. Everything is not an interval will be null.

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 76

Returns:

the gamut intervals

Type: Array.<String>

Example

gamut.intervals('1 C#4 3m') // => ['1P', null, '3m']

intervalSet(source) → {Array.<String>}

Get the interval set of the gamut. An interval set is a group of ascending simple intervals with no repetitions.

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 250

Returns:

the intervals

Type: Array.<String>

Example

gamut.intervalSet('1P 2M 3m 8P 9M 10M') // => ['1P', '2M', '3m', '3M']

notes(source) → {Array.<String>}

Get the note names of the gamut. Everything is not a note will be null.

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 59

Returns:

the gamut note names

Type: Array.<String>

Example

gamut.notes('C blah D') // => ['C', null, 'D']

parse(source) → {Array|Array.<Array>}

Parses a string or a collection of strings into pitch-array notation

Parameters:

Name	Type	Description
`source`	String \| Array.<String>	the item or items to be parsed

Source:

gamut.js , lineno 42

Returns:

the value or values in pitch array notation. Items can be null but an array will be always be returned.

Type: Array | Array.<Array>

Example

gamut.parse('C D') // => [ [0, 0, null], [1, 0, null]]
gamut.parse('1P 2M 3m') // => [ [0, 0, 0], [1, 0, 0], [2, -1, 0] ]

pitchClasses(source) → {Array.<String>}

Remove the octaves from the notes

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 93

Returns:

the pitch classes

Type: Array.<String>

Example

gamut.pitchClasses('C2 D4 E') // => ['C', 'D', 'E']

pitchSet(source) → {Array.<String>}

Get the pitch set of the gamut. A pitch set is a group of note names without octave and no repretition in ascending order (starting from the first note)

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 266

Returns:

the pitch classes (note names without octaves)

Type: Array.<String>

Example

gamut.pitchSet('D4 D5 E6 Eb5 C2') // => ['D', 'Eb', 'E', 'C']

simplify(source) → {Array.<String>}

Convert all compound intervals to simple intervals

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 108

Returns:

the simplified intervals

Type: Array.<String>

Example

gamut.simplify('1P 2M 9m') // => ['1P', '2M', '2m']

sortByFreq(source) → {Array.<String>}

Sort notes in ascending frequency (pitch) order

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 220

Returns:

the sorted notes

Type: Array.<String>

Example

gamut.sortByFreq('D E F G C') // => ['C', 'D', E', F', 'G']

sortBySize(source) → {Array.<String>}

Sort intervals by size

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 235

Returns:

the sorted intervals

Type: Array.<String>

Example

gamut.sortBySize('5 4 3 2 1') // => ['1P', '2M', '3M', '4P', '5P']

transpose(interval, source) → {Array.<Array>}

Add an interval to a gamut of intervals

Parameters:

Name	Type	Description
`interval`	String \| Array	the interval to add
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 161

Returns:

the gamut added by the interval

Type: Array.<Array>

Example

gamut.add('M2', '1P 2M 3M') // => ['2M', '3M', '4A']

transpose(interval, source) → {Array.<Array>}

Transpose a list of notes by an interval

If the pitch to tranpose is a pitch class (note name without octave), the transposed pitch will be a pitch class.

Parameters:

Name	Type	Description
`interval`	String \| Array	the interval to transpose
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 140

Returns:

the transposed notes

Type: Array.<Array>

Example

gamut.transpose('M2', 'C D E') // => ['D', 'E', 'F#']
gamut.transpose('M2', 'C2 D3 E2') // => ['D2', 'E3', 'F#2']

uniq(source) → {Array.<String>}

Remove duplicates and nulls

Parameters:

Name	Type	Description
`source`	String \| Array \| Array.<Array>	the gamut

Source:

gamut.js , lineno 205

Returns:

the notes

Type: Array.<String>

Example

gamut.uniq('C D blah E2 E3') // => ['C', 'D', 'E2', 'E3']

generated with docme