tonal-interval

interval

tonal-interval is a collection of functions to create and manipulate music intervals.

The intervals are strings in shorthand notation. Two variations are supported:

• standard shorthand notation: type and number, for example: 'M3', 'd-4'
• inverse shorthand notation: number and then type, for example: '3M', '-4d'

The problem with the standard shorthand notation is that some strings can be parsed as notes or intervals, for example: 'A4' can be note A in 4th octave or an augmented four. To remove ambiguity, the prefered notation in tonal is the inverse shortand notation.

This is part of tonal music theory library.

Usage

import * as interval from 'tonal-interval'
// or var interval = require('tonal-interval')
interval.semitones('4P') // => 5
interval.invert('3m') // => '6M'
interval.simplify('9m') // => '2m'

Install

API Documentation

• interval
  • .toInterval(interval) ⇒ String
  • .num(interval) ⇒ Integer
  • .value(interval) ⇒ Integer
  • .props(interval) ⇒ Array
  • .fromProps(props) ⇒ String
  • .semitones(ivl) ⇒ Integer
  • .fromSemitones(num) ⇒ String
  • .ic(interval) ⇒ Integer
  • .type(interval) ⇒ String
  • .invert(interval) ⇒ String | Pitch
  • .simplify(interval) ⇒ String | Array

interval.toInterval(interval) ⇒ String

Get interval name. Can be used to test if it's an interval. It accepts intervals as pitch or string in shorthand notation or tonal notation. It returns always intervals in tonal notation.

Kind: static method of interval
Returns: String - the interval name or null if not valid interval

Param	Type	Description
interval	String | Pitch	the interval string or array

Example

interval.toInterval('m-3') // => '-3m'
interval.toInterval('3') // => null

interval.num(interval) ⇒ Integer

Get the number of the interval (same as value, but always positive)

Kind: static method of interval
Returns: Integer - the positive interval number (P1 is 1, m2 is 2, ...)

Param	Type	Description
interval	String | Pitch	the interval

Example

interval.num('m2') // => 2
interval.num('P9') // => 9
interval.num('P-4') // => 4

interval.value(interval) ⇒ Integer

Get the interval value (the interval number, but positive or negative depending the interval direction)

Kind: static method of interval
Returns: Integer - the positive interval number (P1 is 1, m-2 is -2, ...)

Param	Type	Description
interval	String | Pitch	the interval

Example

interval.num('m2') // => 2
interval.num('m9') // => 9
interval.num('P-4') // => -4
interval.num('m-9') // => -9

interval.props(interval) ⇒ Array

Get interval properties. It returns an object with:

• num: the interval number (always positive)
• alt: the interval alteration (0 for perfect in perfectables, or 0 for major in majorables)
• dir: the interval direction (1 ascending, -1 descending)

Kind: static method of interval
Returns: Array - the interval in the form [number, alt]

Param	Type	Description
interval	String | Pitch	the interval

Example

interval.parse('m2') // => { num: 2, alt: -1, dir: 1 }
interval.parse('m9') // => { num: 9, alt: -1, dir: 1 }
interval.parse('P-4') // => { num: 4, alt: 0, dir: -1}
interval.parse('m-9') // => { num: 9, alt: -1, dir: -1 }

interval.fromProps(props) ⇒ String

Given a interval property object, get the interval name

Kind: static method of interval
Returns: String - the interval name

Param	Type	Description
props	Object	the interval property object - num: the interval number - alt: the interval alteration - dir: the direction

interval.semitones(ivl) ⇒ Integer

Get size in semitones of an interval

Kind: static method of interval
Returns: Integer - the number of semitones or null if not an interval

Param	Type
ivl	String | Pitch

Example

import { semitones } from 'tonal-interval'
semitones('P4') // => 5
// or using tonal
tonal.semitones('P5') // => 7

interval.fromSemitones(num) ⇒ String

Get interval name from semitones number. Since there are several interval names for the same number, the name it's arbitraty, but deterministic.

Kind: static method of interval
Returns: String - the interval name

Param	Type	Description
num	Integer	the number of semitones (can be negative)

Example

import { fromSemitones } from 'tonal-interval'
fromSemitones(7) // => '5P'
// or using tonal
tonal.fromSemitones(-7) // => '-5P'

interval.ic(interval) ⇒ Integer

Get the interval class number of a given interval.

In musical set theory, an interval class is the shortest distance in pitch class space between two unordered pitch classes

As paramter you can pass an interval in shorthand notation, an interval in array notation or the number of semitones of the interval

Kind: static method of interval
Returns: Integer - A value between 0 and 6

Param	Type	Description
interval	String | Integer	the interval or the number of semitones

Example

interval.ic('P8') // => 0
interval.ic('m6') // => 4
['P1', 'M2', 'M3', 'P4', 'P5', 'M6', 'M7'].map(ic) // => [0, 2, 4, 5, 5, 3, 1]

interval.type(interval) ⇒ String

Get interval type. Can be perfectable (1, 4, 5) or majorable (2, 3, 6, 7) It does NOT return the actual quality.

Kind: static method of interval
Returns: String - 'P' for perfectables, 'M' for majorables or null if not valid interval

Param	Type
interval	String | Pitch

Example

interval.type('5A') // => 'P'

interval.invert(interval) ⇒ String | Pitch

Get the inversion (https://en.wikipedia.org/wiki/Inversion_(music)#Intervals) of an interval.

Kind: static method of interval
Returns: String | Pitch - the inverted interval

Param	Type	Description
interval	String | Pitch	the interval to invert in interval shorthand notation or interval array notation

Example

interval.invert('3m') // => '6M'
interval.invert('2M') // => '7m'

interval.simplify(interval) ⇒ String | Array

Get the simplified version of an interval.

Kind: static method of interval
Returns: String | Array - the simplified interval

Param	Type	Description
interval	String | Array	the interval to simplify

Example

interval.simplify('9M') // => '2M'
['8P', '9M', '10M', '11P', '12P', '13M', '14M', '15P'].map(interval.simplify)
// => [ '8P', '2M', '3M', '4P', '5P', '6M', '7M', '8P' ]
interval.simplify('2M') // => '2M'
interval.simplify('-2M') // => '7m'