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 const interval = require('tonal-interval')
interval.semitones('4P') // => 5
interval.invert('3m') // => '6M'
interval.simplify('9m') // => '2m'

Install

API Documentation

• interval
  • .names ⇒ Array
  • .props(interval) ⇒ Object
  • .num(interval) ⇒ Integer
  • .name(interval) ⇒ String
  • .semitones(ivl) ⇒ Integer
  • .chroma(str) ⇒ Number
  • .ic(interval) ⇒ Integer
  • .build(props) ⇒ String
  • .simplify(interval) ⇒ String
  • .invert(interval) ⇒ String
  • .fromSemitones(num) ⇒ String

interval.names ⇒ Array

List basic (perfect, major, minor) interval names within a octave

Kind: static constant of interval
Returns: Array - the interval names

Param	Type	Description
qualities	String	(Optional, default "PMm") the valid types

Example

tonal.interval.names() // => [ '1P', '2m', '2M', '3m', '3M', '4P', '5P', '6m', '6M', '7m', '7M', '8P' ]
tonal.interval.names("P") // => [ '1P', '4P', '5P', '8P' ]
tonal.interval.names("PM") // => [ '1P', '2M', '3M', '4P', '5P', '6M', '7M', '8P' ]
tonal.interval.names("Pm") // => [ '1P', '2m', '3m', '4P', '5P', '6m', '7m', '8P' ]
t.interval.names("d") // => []

interval.props(interval) ⇒ Object

Get interval properties. It returns an object with:

• name: name
• num: number
• q: quality
• step: step
• alt: alteration
• dir: direction (1 ascending, -1 descending)
• type: "P" or "M" for perfectable or majorable
• simple: the simplified number
• semitones: the size in semitones
• chroma: the interval chroma
• ic: the interval class

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

Param	Type	Description
interval	String	the interval

interval.num(interval) ⇒ Integer

Get the number of the interval

Kind: static method of interval

Param	Type	Description
interval	String	the interval

Example

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

interval.name(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	the interval string or array

Example

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

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

Example

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

interval.chroma(str) ⇒ Number

Get the chroma of the interval. The chroma is a number between 0 and 7 that represents the position within an octave (pitch set)

Kind: static method of interval

Param	Type
str	String

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.build(props) ⇒ String

Given a interval property object, get the interval name

The properties must contain a num or step, and alt:

• num: the interval number
• step: the interval step (overrides the num property)
• alt: the interval alteration
• oct: (Optional) the number of octaves
• dir: (Optional) the direction

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

Param	Type	Description
props	Object	the interval property object

Example

interval.build({ step: 1, alt: -1, oct: 0, dir: 1 }) // => "1d"
interval.build({ num: 9, alt: -1 }) // => '9m'

interval.simplify(interval) ⇒ String

Get the simplified version of an interval.

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

Param	Type	Description
interval	String	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'

interval.invert(interval) ⇒ String

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

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

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

Example

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

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'