tonal-interval
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.2 • Public • Published

    Interval

    npm version tonal

    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

    // es6
    import * as Interval from "tonal-interval"
    // es5
    const Interval = require("tonal-interval")
    // part of tonal
    import { Interval } from "tonal"
    

    Interval.semitones("4P") // => 5 Interval.invert("3m") // => "6M" Interval.simplify("9m") // => "2m"

    Install

    npm install tonal-interval

    API Documentation

    Interval.num(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.name(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.semitones(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.chroma(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

    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
    Interval.ic(10) // => 2
    ["P1", "M2", "M3", "P4", "P5", "M6", "M7"].map(ic) // => [0, 2, 4, 5, 5, 3, 1]

    Interval.ic(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.build(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.simplify(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~names(qualities) ⇒ Array

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

    Kind: inner method of Interval
    Returns: Array -

    the interval names

    Param Type Description
    qualities string

    (Optional, default "PMm") the valid types

    Example

    Interval.names() // => [ "1P", "2m", "2M", "3m", "3M", "4P", "5P", "6m", "6M", "7m", "7M", "8P" ]
    Interval.names("P") // => [ "1P", "4P", "5P", "8P" ]
    Interval.names("PM") // => [ "1P", "2M", "3M", "4P", "5P", "6M", "7M", "8P" ]
    Interval.names("Pm") // => [ "1P", "2m", "3m", "4P", "5P", "6m", "7m", "8P" ]
    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: inner 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: inner 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~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: inner 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.Distance.fromSemitones(-7) // => "-5P"

    Install

    npm i tonal-interval

    DownloadsWeekly Downloads

    392

    Version

    2.2.2

    License

    MIT

    Unpacked Size

    49.4 kB

    Total Files

    15

    Last publish

    Collaborators

    • danigb