tonal-key

tonal-key

tonal-key is a collection of functions to create and manipulate music keys.

This is part of tonal music theory library.

You can install via npm: npm i --save tonal-key

API Reference

names(alias) ⇒ Array

Get a list of valid mode names. The list of modes will be always in increasing order (ionian to locrian)

isKeyMode(m) ⇒ Boolean

Check if the given string is a valid mode name

build(tonic, mode) ⇒ Key

Build a key object from tonic a mode.

A key object is an array with the mode name and the tonic (or false if no tonic specified)

isKey(obj) ⇒ Boolean

Test if a given object is a key object

hasTonic(obj) ⇒ Boolean

Test if the given object is a key with tonic

fromAlter(alt) ⇒ Key

Create a major key from alterations

fromAcc(acc) ⇒ Key

Create a major key from accidentals

fromName(name) ⇒ Key

Create a key from key name

asKey(obj) ⇒ Key

Try to interpret the given object as a key. Given an object it will try to parse as if it were a name, accidentals or alterations.

relative(mode, key)

Get relative of a key. It can be partially applied.

alteration(key) ⇒ Integer

Get key alteration. The alteration is a number indicating the number of sharpen notes (positive) or flaten notes (negative)

signature()

Get the signature of a key. The signature is a string with sharps or flats.

accidentals()

An alias for signature()

alteredNotes(key) ⇒ Array

Get a list of the altered notes of a given key. The notes will be in the same order than in the key signature.

names(alias) ⇒ Array

Get a list of valid mode names. The list of modes will be always in increasing order (ionian to locrian)

Kind: global function
Returns: Array - an array of strings

Param	Type	Description
alias	Boolean	true to get aliases names

isKeyMode(m) ⇒ Boolean

Check if the given string is a valid mode name

Kind: global function

Param	Type
m	String

build(tonic, mode) ⇒ Key

Build a key object from tonic a mode.

A key object is an array with the mode name and the tonic (or false if no tonic specified)

Kind: global function
Returns: Key - a key data object

Param	Type	Description
tonic	String	the key tonic (or null or false to no tonic)
mode	String	the keymode

Example

var key = require('tonal-key')
key.build('g3', 'minor') // => ['minor', 'G']
key.build(false, 'locrian') // => ['locrian', false]

isKey(obj) ⇒ Boolean

Test if a given object is a key object

Kind: global function
Returns: Boolean - true if it's a key object
See: build

Param	Type	Description
obj	Object	the object to test

hasTonic(obj) ⇒ Boolean

Test if the given object is a key with tonic

Kind: global function
Returns: Boolean - true if it a key with tonic

Param	Type	Description
obj	Object	the object to test

fromAlter(alt) ⇒ Key

Create a major key from alterations

Kind: global function
Returns: Key - the key object

Param	Type	Description
alt	Integer	the alteration number (positive sharps, negative flats)

Example

var key = require('tonal-key')
key.fromAlter(2) // => ['major', 'D']

fromAcc(acc) ⇒ Key

Create a major key from accidentals

Kind: global function
Returns: Key - the key object

Param	Type	Description
acc	String	the accidentals string

Example

var key = require('tonal-key')
key.fromAlter('bb') // => ['major', 'Bb']

fromName(name) ⇒ Key

Create a key from key name

Kind: global function
Returns: Key - the key object or null if not valid key

Param	Type	Description
name	String	the key name

Example

var key = require('tonal-key')
key.fromName('C3 dorian') // => ['dorian', 'C']
key.fromName('blah') // => null

asKey(obj) ⇒ Key

Try to interpret the given object as a key. Given an object it will try to parse as if it were a name, accidentals or alterations.

Kind: global function
Returns: Key - the key object or null

Param	Type
obj	Object

relative(mode, key)

Get relative of a key. It can be partially applied.

Kind: global function

Param	Type	Description
mode	String	the relative destination
key	String	the key source

Example

var key = require('tonal-keys')
key.relative('dorian', 'C major') // => ['dorian', 'D']
// partially application
var minor = key.relative('minor')
minor('C major') // => ['minor', 'A']

alteration(key) ⇒ Integer

Get key alteration. The alteration is a number indicating the number of sharpen notes (positive) or flaten notes (negative)

Kind: global function

Param	Type
key	String | Integer

Example

var key = require('tonal-keys')
key.alteration('A major') // => 3

signature()

Get the signature of a key. The signature is a string with sharps or flats.

Kind: global function
Example

var key = require('tonal-keys')
key.signature('A major') // => '###'

accidentals()

An alias for signature()

Kind: global function

alteredNotes(key) ⇒ Array

Get a list of the altered notes of a given key. The notes will be in the same order than in the key signature.

Kind: global function

Param	Type
key	String | Nunber

Example

var key = require('tonal-keys')
key.alteredNotes('Eb major') // => [ 'Bb', 'Eb', 'Ab' ]