Skip to content

API.md

Latest commit

 

History

History
157 lines (130 loc) · 6.3 KB

API.md

File metadata and controls

157 lines (130 loc) · 6.3 KB

Functions

parse(str, strict) ⇒ Object

Parse a string with an interval in shorthand notation (https://en.wikipedia.org/wiki/Interval_(music)#Shorthand_notation) and returns an object with interval properties.

type(num) ⇒ String

Get the type of interval. Can be perfectavle ('P') or majorable ('M')

shorthand(simple, alt, oct, dir)

Build a shorthand interval notation string from properties.

build(simple, alt, oct, dir)

Build a special shorthand interval notation string from properties. The special shorthand interval notation changes the order or the standard shorthand notation so instead of 'M-3' it returns '-3M'.

The standard shorthand notation has a string 'A4' (augmented four) that can't be differenciate from 'A4' (the A note in 4th octave), so the purpose of this notation is avoid collisions

qToAlt(num, quality) ⇒ Integer

Get an alteration number from an interval quality string. It accepts the standard dmMPA but also sharps and flats.

altToQ(num, alt) ⇒ String

Get interval quality from interval type and alteration

parse(str, strict) ⇒ Object

Parse a string with an interval in shorthand notation (https://en.wikipedia.org/wiki/Interval_(music)#Shorthand_notation) and returns an object with interval properties.

Kind: global function
Returns: Object - an object properties or null if not valid interval string The returned object contains:

  • num: the interval number
  • q: the interval quality string (M is major, m is minor, P is perfect...)
  • simple: the simplified number (from 1 to 7)
  • dir: the interval direction (1 ascending, -1 descending)
  • type: the interval type (P is perfectable, M is majorable)
  • alt: the alteration, a numeric representation of the quality
  • oct: the number of octaves the interval spans. 0 for simple intervals.
  • size: the size of the interval in semitones
Param Type Description
str String the string with the interval
strict Boolean (Optional) if its false, it doesn't check if the interval is valid or not. For example, parse('P2') returns null (because a perfect second is not a valid interval), but parse('P2', false) it returns { num: 2, dir: 1, q: 'P'... }

Example

var parse = require('interval-notation').parse
parse('M3')
// => { num: 3, q: 'M', dir: 1, simple: 3,
//      type: 'M', alt: 0, oct: 0, size: 4 }

type(num) ⇒ String

Get the type of interval. Can be perfectavle ('P') or majorable ('M')

Kind: global function
Returns: String - P if it's perfectable, M if it's majorable.

Param Type Description
num Integer the interval number

shorthand(simple, alt, oct, dir)

Build a shorthand interval notation string from properties.

Kind: global function

Param Type Description
simple Integer the interval simple number (from 1 to 7)
alt Integer the quality expressed in numbers. 0 means perfect or major, depending of the interval number.
oct Integer the number of octaves the interval spans. 0 por simple intervals. Positive number.
dir Integer the interval direction: 1 ascending, -1 descending.

Example

var interval = require('interval-notation')
interval.shorthand(3, 0, 0, 1) // => 'M3'
interval.shorthand(3, -1, 0, -1) // => 'm-3'
interval.shorthand(3, 1, 1, 1) // => 'A10'

build(simple, alt, oct, dir)

Build a special shorthand interval notation string from properties. The special shorthand interval notation changes the order or the standard shorthand notation so instead of 'M-3' it returns '-3M'.

The standard shorthand notation has a string 'A4' (augmented four) that can't be differenciate from 'A4' (the A note in 4th octave), so the purpose of this notation is avoid collisions

Kind: global function

Param Type Description
simple Integer the interval simple number (from 1 to 7)
alt Integer the quality expressed in numbers. 0 means perfect or major, depending of the interval number.
oct Integer the number of octaves the interval spans. 0 por simple intervals. Positive number.
dir Integer the interval direction: 1 ascending, -1 descending.

Example

var interval = require('interval-notation')
interval.build(3, 0, 0, 1) // => '3M'
interval.build(3, -1, 0, -1) // => '-3m'
interval.build(3, 1, 1, 1) // => '10A'

qToAlt(num, quality) ⇒ Integer

Get an alteration number from an interval quality string. It accepts the standard dmMPA but also sharps and flats.

Kind: global function
Returns: Integer - the interval alteration

Param Type Description
num Integer | String the interval number or a string representing the interval type ('P' or 'M')
quality String the quality string

Example

qToAlt('M', 'm') // => -1 (for majorables, 'm' is -1)
qToAlt('P', 'A') // => 1 (for perfectables, 'A' means 1)
qToAlt('M', 'P') // => null (majorables can't be perfect)

altToQ(num, alt) ⇒ String

Get interval quality from interval type and alteration

Kind: global function
Returns: String - the quality string

Param Type Description
num Integer | String the interval number of the the interval type ('M' for majorables, 'P' for perfectables)
alt Integer the interval alteration

Example

altToQ('M', 0) // => 'M'