Skip to content

Latest commit

 

History

History
850 lines (718 loc) · 35.5 KB

api.md

File metadata and controls

850 lines (718 loc) · 35.5 KB

Classes

Key
Pitch
## Functions
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.

## Typedefs
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

MusicLetter + [AccidentalString].

## Key **Kind**: global class **Properties**
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

new Key(tonic, mode)

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

key.toString() ⇒ String

Kind: instance method of Key
Returns: String - the tonic + the modeName ('Bb major')

key.inKey(pitch) ⇒ boolean

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

key.accidentalOn(pitch) ⇒ string

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>

key.scaleDegree(pitch) ⇒ number

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

Pitch

Kind: global class
Properties

Name Type Description
Pitch.name PitchString this pitch in scientific pitch notation

new Pitch(sciPitch)

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

pitch.valueOf() ⇒ Number

Kind: instance method of Pitch
Returns: Number - the midi number of this pitch, so enharmonic notes will be equal
See: pitch.midi()

pitch.equals(that) ⇒ Boolean

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

pitch.isEnharmonic(that) ⇒ Boolean

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

pitch.isHigher(that) ⇒ Boolean

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.

pitch.octave() ⇒ Number

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.

pitch.numAccidental() ⇒ 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

pitch.midi() ⇒ Number

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

pitch.semitonesTo(that) ⇒ Number

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

pitch.intervalSize(that) ⇒ Number

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

pitch.simpleIntervalSize(that) ⇒ Number

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

pitch.interval(that) ⇒ 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

pitch.simpleInterval(that) ⇒ 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

modeIntervals(modeName) ⇒ Array.<string>

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']

intervalQuality(sciPitch1, sciPitch2) ⇒ String

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'

intervalSize(sciPitch1, sciPitch2) ⇒ Number

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

intervalSize.simple(sciPitch1, sciPitch2) ⇒ Number

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

interval(sciPitch1, sciPitch2) ⇒ String

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'

interval.simple(sciPitch1, sciPitch2) ⇒ Number

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'

isHigher(sciPitch1, sciPitch2) ⇒ boolean

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

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

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

parsePitch(sciPitch) ⇒ object | 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']

semitonesBetween(sciPitch1, sciPitch2) ⇒ Number

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

simplifyIntervalSize(intervalSize) ⇒ Number

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

toMidi(sciPitch) ⇒ Number

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

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.

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

MusicLetter : 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G'

[A-G] representing a musical lettername

Kind: global typedef

AccidentalString : '#' | 'b' | '##' | 'bb'

'#' for sharp, 'b' for flat. '##'' for double sharp, 'bb' for double flat.

Kind: global typedef

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.

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

PitchClassString : string

MusicLetter + [AccidentalString].

Kind: global typedef
Link: same as PitchString but without octave number.
Example

'C'
'Eb'
'F#'
'F##'
'Dbb'