- modeIntervals(modeName) ⇒
Array.<string>
returns the intervals that define the scale degrees of a given mode
- scaleSet(tonic, mode) ⇒
Array.<PitchString>
given a pitch string and scale mode, build a pitch class scale from that pitch
- scale(tonic, mode) ⇒
Array.<PitchString>
given a pitch string and scale mode, build a scale from that pitch
- intervalQuality(sciPitch1, sciPitch2) ⇒
String
the interval quality between two pitch strings
- intervalSize(sciPitch1, sciPitch2) ⇒
Number
the generic interval size between two pitch strings, disregarding accidentals
- interval(sciPitch1, sciPitch2) ⇒
String
the interval between two pitch strings
- isHigher(sciPitch1, sciPitch2) ⇒
boolean
does this pitch sound higher than that pitch?
- parseInterval(interval) ⇒
Object
|false
parses an interval string or number and return its properties in an object or return false if the string or number is not valid
- parsePitch(sciPitch) ⇒
object
|false
parses a pitch string and return its components in an object or false if the string is not valid
- plusInterval(sciPitch, interval) ⇒
PitchString
|function
given pitch string plus given interval string equals new pitch string
Optionally, give only one parameter and get back a function with that parameter set as the default.
- semitonesBetween(sciPitch1, sciPitch2) ⇒
Number
the number of semitones between these two pitch strings
- simplifyIntervalSize(intervalSize) ⇒
Number
simplify compound intervals to within the range of 1-7. Works for negative intervals as well.
- sortPitches(pitches) ⇒
Array.<PitchString>
helper function to sort an array of PitchStrings from lowest to highest
- toMidi(sciPitch) ⇒
Number
the midi number of this pitch string
- clone(obj) ⇒
object
|array
helper function to clone a simple object/array made up of primitives. Will not work if the object or array contains non-primitives.
- MusicLetter :
'A'
|'B'
|'C'
|'D'
|'E'
|'F'
|'G'
[A-G] representing a musical lettername
- AccidentalString :
'#'
|'b'
|'##'
|'bb'
'#' for sharp, 'b' for flat. '##'' for double sharp, 'bb' for double flat.
- PitchString :
string
MusicLetter + [AccidentalString] + [octave number]. Must match the regular expression: /(A-G)(b{1,2}|#{1,2})?(\d{1,2})?/. Accidental and octave number are optional, but if octave number is not provided, it will default to octave 4.
- PitchClassString :
string
Name | Type | Description |
---|---|---|
tonic | Pitch |
the tonic of this scale. Although all Pitch instances have an octave number, it is not used in the Key methods. |
modeName | string |
a string representing the mode name. If custom mode is provided, defaults to 'custom-scale' |
mode | Array.<string> |
an array of interval strings representing the interval each scale degree is from tonic |
scale | Array.<PitchString> |
an array of pitch class strings |
- Key
- new Key(tonic, mode)
- .toString() ⇒
String
- .inKey(pitch) ⇒
boolean
- .accidentalOn(pitch) ⇒
string
- .pitchAtDegree(degree) ⇒
Pitch
- .scaleDegree(pitch) ⇒
number
- .plusInterval(pitch, intervalSize) ⇒
Pitch
- .range(lo, hi) ⇒
Array.<Pitch>
Creates a new key. Note that most Key methods use pitch classes without reguards to octave number.
Param | Type | Description |
---|---|---|
tonic | Pitch | PitchString |
the [tonic](@link https://en.wikipedia.org/wiki/Tonic_(music)) of this scale. Octave number may be provided, but do not affect the Key methods. |
mode | string | Array.<string> |
a string representing a mode name (minor, major, dorian) or an array of interval strings representing the interval each scale degree is from tonic |
Kind: instance method of Key
Returns: String
- the tonic + the modeName ('Bb major')
is this pitch a member of this key?
Kind: instance method of Key
Returns: boolean
- is this pitch in the key?
Param | Type | Description |
---|---|---|
pitch | Pitch | PitchString |
a pitch string or Pitch |
Example
var a_major = new Key('A3', 'major')
a_major.inKey('C3') => false
a_major.inKey('C#3') => true
given a letter and key, returns the accidental that should be on this letter in this key. This method only works for standard keys like major or dorian which map evenly to the seven music letters.
Kind: instance method of Key
Returns: string
- the accidental that needs to be added to this letter for it
to be in the key
Param | Type | Description |
---|---|---|
pitch | Pitch | PitchString |
a pitch string or Pitch |
key.pitchAtDegree(degree) ⇒ Pitch
returns the Pitch at the requested scale degree. Although Pitches default to octave number 4, this should be thought of as a pitch class
Kind: instance method of Key
Returns: Pitch
- a pitch class string
Param | Type | Description |
---|---|---|
degree | number |
the desired scale degree of this scale (an integer > 0) |
Example
var a_major = new Key('A3', 'major')
a_major.scaleDegree(3) => 'C#4'<Pitch>
a_major.scaleDegree(10) => 'C#4'<Pitch>
returns the scale degree of this pitch or -1 if it is not in the key
Kind: instance method of Key
Returns: number
- the scale degree of this pitch or -1 if not in key
Param | Type | Description |
---|---|---|
pitch | Pitch | PitchString |
a pitch string or Pitch |
Example
var a_major = new Key('A3', 'major')
a_major.scaleDegree('C3') => -1
a_major.scaleDegree('C#3') => 3
key.plusInterval(pitch, intervalSize) ⇒ Pitch
gets the correct pitch in the key which is the given interval size away
Kind: instance method of Key
Returns: Pitch
- the resulting Pitch
Param | Type | Description |
---|---|---|
pitch | Pitch | PitchString |
the starting Pitch or pitch string |
intervalSize | number |
an interval as a positive or negative number. |
Example
var a_flat_major = new Key('Ab', 'major')
a_flat_major.plusInterval('C4', 2) => Pitch: Db4
a_flat_major.plusInterval('C4', -2) => Pitch: Bb3
a_flat_major.plusInterval('Eb2', 4) => Pitch: Ab2
a_flat_major.plusInterval('G5', -10) => Pitch: Eb4
key.range(lo, hi) ⇒ Array.<Pitch>
Get all the notes in this key between lo and hi (both inclusive)
Kind: instance method of Key
Returns: Array.<Pitch>
- an array of Pitches with all the notes of this key
between lo and hi (both inclusive)
Throws:
- an Error if lo and hi are not both inKey
Param | Type | Description |
---|---|---|
lo | Pitch | PitchString |
the starting Pitch or pitch string |
hi | Pitch | PitchString |
the ending Pitch or pitch string |
Kind: global class
Properties
Name | Type | Description |
---|---|---|
Pitch.name | PitchString |
this pitch in scientific pitch notation |
- Pitch
- new Pitch(sciPitch)
- .toString() ⇒
PitchString
- .valueOf() ⇒
Number
- .equals(that) ⇒
Boolean
- .isEnharmonic(that) ⇒
Boolean
- .isHigher(that) ⇒
Boolean
- .sciPitch() ⇒
PitchString
- .letter() ⇒
MusicLetter
- .accidental() ⇒
AccidentalString
- .octave() ⇒
Number
- .pitchClass() ⇒
PitchClassString
- .numAccidental() ⇒
Number
- .midi() ⇒
Number
- .semitonesTo(that) ⇒
Number
- .intervalSize(that) ⇒
Number
- .simpleIntervalSize(that) ⇒
Number
- .interval(that) ⇒
String
- .simpleInterval(that) ⇒
String
- .plusInterval(interval) ⇒
Pitch
Creates a new immutable Pitch or if given an existing Pitch, returns it.
Throws:
- Will throw an error if string is not a valid pitch
Param | Type | Description |
---|---|---|
sciPitch | PitchString | Pitch |
a pitch string in scientific pitch notation or a Pitch. |
Example
var p = new Pitch('Bb3')
p.name => 'Bb3'
// if you forget the 'new' keyword, the constructor will call it for you
var p2 = Pitch('C4')
p2 instanceof Pitch => true
// if given a Pitch as its argument, the same Pitch will be returned
var p3 = Pitch(p2)
p2 === p3 => true
// this can be used to write functions which accept pitch strings or Pitches as a parameter
pitch.toString() ⇒ PitchString
Kind: instance method of Pitch
Returns: PitchString
- string in scientfic pitch notation
Kind: instance method of Pitch
Returns: Number
- the midi number of this pitch, so enharmonic notes will be equal
See: pitch.midi()
Kind: instance method of Pitch
Returns: Boolean
- is this pitch spelled the same as that pitch?
Param | Type | Description |
---|---|---|
that | Pitch | PitchString |
a Pitch or a pitch string |
Kind: instance method of Pitch
Returns: Boolean
- does this pitch sound identical to that pitch?
Param | Type | Description |
---|---|---|
that | Pitch | PitchString |
a Pitch or a pitch string |
Kind: instance method of Pitch
Returns: Boolean
- does this pitch sound higher than that pitch?
See: isHigher
Param | Type | Description |
---|---|---|
that | Pitch | PitchString |
a Pitch or a pitch string |
pitch.sciPitch() ⇒ PitchString
Kind: instance method of Pitch
Returns: PitchString
- in scientfic pitch notation
(same as pitch.name)
pitch.letter() ⇒ MusicLetter
Kind: instance method of Pitch
Returns: MusicLetter
- will return 'A', 'B', 'C', 'D', 'E', 'F', or 'G'
pitch.accidental() ⇒ AccidentalString
Kind: instance method of Pitch
Returns: AccidentalString
- 'b', 'bb', '#', '##' (double sharp is not 'x'),
or '', the empty string if there is no accidental.
Kind: instance method of Pitch
Returns: Number
- the octave number (C4 is
middle C)
pitch.pitchClass() ⇒ PitchClassString
Kind: instance method of Pitch
Returns: PitchClassString
- the pitch class,
same as pitch.sciPitch() but without octave number.
returns the number of accidentals on this letter: positive for sharps, negative for flats.
Kind: instance method of Pitch
Returns: Number
- how many half steps from its letter, will be in the range [-2, 2]
Example
var p = new Pitch('Abb3')
p.halfSteps() => -2
What is the midi number of this pitch?
Kind: instance method of Pitch
Returns: Number
- the midi number for this pitch. C4 is 60.
Example
toMidi('C4') => 60
toMidi('B#3') => 60
toMidi('Bb3') => 58
toMidi('A#3') => 58
Kind: instance method of Pitch
Returns: Number
- how many half steps are there between these pitches?
Param | Type | Description |
---|---|---|
that | Pitch | PitchString |
a Pitch or a pitch string |
Kind: instance method of Pitch
Returns: Number
- the interval size between these pitches
See: intervalSize
Param | Type | Description |
---|---|---|
that | Pitch | PitchString |
a Pitch or a pitch string |
Kind: instance method of Pitch
Returns: Number
- the simple interval size between these pitches in range [1,7]
See: simple
Param | Type | Description |
---|---|---|
that | Pitch | PitchString |
a Pitch or a pitch string |
Kind: instance method of Pitch
Returns: String
- the interval between these pitches
See: interval
Param | Type | Description |
---|---|---|
that | Pitch | PitchString |
a Pitch or a pitch string |
Kind: instance method of Pitch
Returns: String
- the simple interval between these pitches
See: simple
Param | Type | Description |
---|---|---|
that | Pitch | PitchString |
a Pitch or a pitch string |
pitch.plusInterval(interval) ⇒ Pitch
Kind: instance method of Pitch
Returns: Pitch
- the resulting Pitch
See: plusInterval
Param | Type | Description |
---|---|---|
interval | String | Number |
an interval string or number with or without quality. If interval quality is not provided, accidentals on this Pitch will be ignored. |
Example
var pitch_C4 = new Pitch('C4')
plusInterval(pitch_C4, 10) => Pitch: E5
plusInterval(pitch_C4, -10) => Pitch: A2
plusInterval(pitch_C4, 'm10') => Pitch: Eb5
plusInterval(pitch_C4, '-d7') => Pitch: D#3
returns the intervals that define the scale degrees of a given mode
Kind: global function
Returns: Array.<string>
- an array of interval strings representing the
interval each scale degree is from tonic, always starting with 'P1' for tonic
Param | Type | Description |
---|---|---|
modeName | 'major' | 'minor' | 'ionian' | 'dorian' | 'phrygian' | 'lydian' | 'mixolydian' | 'aeolian' | 'locrian' |
a mode name |
Example
modeIntervals('major') => ['P1', 'M2', 'M3', 'P4', 'P5', 'M6', 'M7']
modeIntervals('dorian') => ['P1', 'M2', 'm3', 'P4', 'P5', 'M6', 'm7']
scaleSet(tonic, mode) ⇒ Array.<PitchString>
given a pitch string and scale mode, build a pitch class scale from that pitch
Kind: global function
Returns: Array.<PitchString>
- an array of pitch class strings (without octave number)
See: for a similar function which uses octave numbers, see scale
Param | Type | Description |
---|---|---|
tonic | PitchString |
the [tonic](@link https://en.wikipedia.org/wiki/Tonic_(music)) of this scale. If octave number is provided, it will be ignored. |
mode | string | Array.<string> |
a string representing a mode name (minor, major, dorian) or an array of interval strings representing the interval each scale degree is from tonic |
Example
scale('Eb4', 'major')
=> ['Eb', 'F', 'G', 'Ab', 'Bb', 'C', 'D']
scale(tonic, mode) ⇒ Array.<PitchString>
given a pitch string and scale mode, build a scale from that pitch
Kind: global function
Returns: Array.<PitchString>
- an array of pitch strings
Param | Type | Description |
---|---|---|
tonic | PitchString |
the [tonic](@link https://en.wikipedia.org/wiki/Tonic_(music)) of this scale |
mode | string | Array.<string> |
a string representing a mode name (minor, major, dorian) or an array of interval strings representing the interval each scale degree is from tonic |
Example
scale('Eb4', 'major')
=> ['Eb4', 'F4', 'G4', 'Ab4', 'Bb4', 'C5', 'D5']
the interval quality between two pitch strings
Kind: global function
Returns: String
- a character representing the interval between the two pitches:
-
'P' = perfect
-
'm' = minor
-
'M' = major
-
'd' = diminished
-
'A' = augmented
Throws: -
an error if either string is not a valid pitch
Param | Type | Description |
---|---|---|
sciPitch1 | PitchString |
a pitch in scientific pitch notation. |
sciPitch2 | PitchString |
a pitch in scientific pitch notation. |
Example
intervalQuality('C4', 'E4') => 'M'
intervalQuality('E4', 'Eb4') => 'm'
intervalQuality('C4', 'F4') => 'P'
intervalQuality('C4', 'F#4') => 'A'
intervalQuality('B3', 'Ab4') => 'd'
the generic interval size between two pitch strings, disregarding accidentals
Kind: global function
Returns: Number
- the absolute interval size between the two pitches. Always positive, even if
the first argument is higher than the second.
Throws:
- an error if string is not a valid pitch
See: simple for returning the simple interval size
Param | Type | Description |
---|---|---|
sciPitch1 | PitchString |
a pitch in scientific pitch notation. |
sciPitch2 | PitchString |
a pitch in scientific pitch notation. |
Example
intervalSize('C4', 'E4') => 3
intervalSize('E4', 'C4') => 3
intervalSize('C4', 'E5') => 10
intervalSize('C4', 'Eb5') => 10
intervalSize('C5', 'C5') => 1
the generic simple interval size (1-7) between two pitch strings, disregarding accidentals
Kind: static method of intervalSize
Returns: Number
- the simple interval size between the two pitches in range [1, 7].
Contrary to standard practice, an octave is considered compound and reduces to 1.
Throws:
- an error if string is not a valid pitch
Param | Type | Description |
---|---|---|
sciPitch1 | PitchString |
a pitch in scientific pitch notation. |
sciPitch2 | PitchString |
a pitch in scientific pitch notation. |
Example
intervalSize.simple('C4', 'E4') => 3
intervalSize.simple('C4', 'E5') => 3
intervalSize.simple('C1', 'E9') => 3
the interval between two pitch strings
Kind: global function
Returns: String
- the interval between the two pitches
Throws:
- an error if either string is not a valid pitch
See: simple for returning the simple interval
Param | Type | Description |
---|---|---|
sciPitch1 | PitchString |
a pitch in scientific pitch notation. |
sciPitch2 | PitchString |
a pitch in scientific pitch notation. |
Example
interval('C4', 'E4') => 'M3'
interval('E4', 'Eb4') => 'm3'
interval('C4', 'F4') => 'P4'
interval('C4', 'F#4') => 'A4'
interval('B3', 'Ab4') => 'd7'
the simple interval between two pitch strings
Kind: static method of interval
Returns: Number
- the simple interval between the two pitches.
Contrary to standard practice, an octave is considered compound and reduces to 1 as in simple
Throws:
- an error if string is not a valid pitch
Param | Type | Description |
---|---|---|
sciPitch1 | String |
a pitch in scientific pitch notation. |
sciPitch2 | String |
a pitch in scientific pitch notation. |
Example
interval.simple('C4', 'E4') => 'M3'
interval.simple('C4', 'E5') => 'M3'
interval.simple('C1', 'E9') => 'M3'
does this pitch sound higher than that pitch?
Kind: global function
Returns: boolean
- is sciPitch1 higher than sciPitch2?
Throws:
- Will throw an error if string is not a valid pitch
Param | Type | Description |
---|---|---|
sciPitch1 | PitchString |
a pitch in scientific pitch notation. |
sciPitch2 | PitchString |
a pitch in scientific pitch notation. |
Example
isHigher('D4', 'C4') => true
isHigher('C4', 'D4') => false
isHigher('C4', 'B#3') => false // enharmonic, so they actually sound equal
isHigher('B##3', 'C4') => true // B##3 sounds higher than C4
parses an interval string or number and return its properties in an object or return false if the string or number is not valid
Kind: global function
Returns: Object
| false
- False if invalid interval else an object
with the following properties:
- interval: string
- direction: number -1 or 1
- quality: string of 'm', 'M', 'P', 'd', or 'A' OR null if not given
- size: number, size of the interval, never negative
- simpleSize: number in range [1,7]
- perfectable: boolean (if false, this is an imperfect interval)
- octaves: number of octave changes. Will be >= 0.
- halfsteps: number|undefined if given quality, number of halfsteps this interval translates to
Param | Type | Description |
---|---|---|
interval | String | Number |
an interval string with interval quality or a number representing only interval size. Both types of input may be signed ('-P5' or -5) to indicate a descending interval. |
Example
parseInterval('-M6') => {interval: '-M6', direction: -1, quality: 'M', size: 6, simpleSize: 6,
perfectable: false, octaves: 0, halfsteps: 9}
parseInterval(12) => {interval: '12', direction: 1, quality: null, size: 12, simpleSize: 5,
perfectable: true, octaves 1}
parseInterval('M5') => false
parses a pitch string and return its components in an object or false if the string is not valid
Kind: global function
Returns: object
| false
- False if invalid pitch string or an object
with the following properties:
- letter: string
- accidental: AccidentalString
- numAccidental: number of accidentals [-2, 2], positive for sharps, negative for flats
- octave: integer (if not provided, defaults to 4)
- sciPitch: PitchString
Param | Type | Description |
---|---|---|
sciPitch | PitchString |
a pitch in scientific pitch notation |
Example
parsePitch('Bb3') => {letter: 'B', accidental: 'b', numAccidental: -1, octave: 3, sciPitch:'Bb3'}
parsePitch('Xb4') => false
plusInterval(sciPitch, interval) ⇒ PitchString
| function
given pitch string plus given interval string equals new pitch string
Optionally, give only one parameter and get back a function with that parameter set as the default.
Kind: global function
Returns: PitchString
| function
- the resulting pitch string, or if one argument is null, returns
a function with the provided argument set as a default.
Throws:
- an error if pitch string or interval string is not valid
Param | Type | Description |
---|---|---|
sciPitch | PitchString |
a pitch in scientific pitch notation. |
interval | String | Number |
an interval string or number with or without quality. If quality is not provided, accidentals on given pitch will be ignored. |
Example
plusInterval('C4', 10) => 'E5'
plusInterval('C4', -10) => 'A2'
plusInterval('C4', 'm10') => 'Eb5'
plusInterval('C4', '-d7') => 'D#3'
var majorscale = ['P1', 'M2', 'M3', 'P4', 'P5', 'M6', 'M7', 'P8']
majorscale.map(plusInterval('Eb4', null))
=> ['Eb4', 'F4', 'G4', 'Ab4', 'Bb4', 'C5', 'D5', 'Eb5']
majorscale.map(plusInterval('Eb4', null)).map(plusInterval(null, '-m9'))
=> ['D3', 'E3', 'F#3', 'G3', 'A3', 'B3', 'C#4', 'D4']
the number of semitones between these two pitch strings
Kind: global function
Returns: Number
- the semitones between these two pitch strings.
Throws:
- Will throw an error if string is not a valid pitch
Param | Type | Description |
---|---|---|
sciPitch1 | PitchString |
a pitch in scientific pitch notation. |
sciPitch2 | PitchString |
a pitch in scientific pitch notation. |
Example
semitonesBetween('C4', 'Db4') => 1
semitonesBetween('C4', 'B#3') => 0
semitonesBetween('C4', 'C5') => 12
simplify compound intervals to within the range of 1-7. Works for negative intervals as well.
Kind: global function
Returns: Number
- the simplified interval
Throws:
- Will throw an error if intervalSize is 0
Param | Type | Description |
---|---|---|
intervalSize | Number |
any valid interval number |
Example
simplifyIntervalSize(10) => 3
simplifyIntervalSize(-12) => -5
simplifyIntervalSize(-4) => -4
simplifyIntervalSize(8) => 1
sortPitches(pitches) ⇒ Array.<PitchString>
helper function to sort an array of PitchStrings from lowest to highest
Kind: global function
Returns: Array.<PitchString>
- a new clone of the provided pitch string
array sorted from low pitch to high pitch
Param | Type | Description |
---|---|---|
pitches | Array.<PitchString> |
an array of pitch strings |
the midi number of this pitch string
Kind: global function
Returns: Number
- the midi number for this pitch. C4 is 60.
Enharmonic notes will return the same
midi number.
Throws:
- Will throw an error if string is not a valid pitch
Param | Type | Description |
---|---|---|
sciPitch | PitchString |
a pitch in scientific pitch notation. |
Example
toMidi('C4') => 60
toMidi('B#3') => 60
toMidi('Bb3') => 58
toMidi('A#3') => 58
helper function to clone a simple object/array made up of primitives. Will not work if the object or array contains non-primitives.
Kind: global function
Returns: object
| array
- a new clone of the provided object or array
Param | Type | Description |
---|---|---|
obj | object | array |
an object array made up only of primitives |
[A-G] representing a musical lettername
'#' for sharp, 'b' for flat. '##'' for double sharp, 'bb' for double flat.
MusicLetter + [AccidentalString] + [octave number]. Must match the regular expression: /(A-G)(b{1,2}|#{1,2})?(\d{1,2})?/. Accidental and octave number are optional, but if octave number is not provided, it will default to octave 4.
Kind: global typedef
Example
'C4' // middle C on a piano, the fourth octave
'B3' // the B one note below C4 on the piano (octave numbers change on C)
'Eb3' // Eb in octave 3
'F#2' // F# in octave 2
'F##7' // F double sharp in octave 7
'Dbb5' // D double flat in octave 5
MusicLetter + [AccidentalString].
Kind: global typedef
Link: same as PitchString but without octave number.
Example
'C'
'Eb'
'F#'
'F##'
'Dbb'