TwelveTet

TwelveTet is a minimalistic twelve-tone equal temperament library for Javascript. It helps you manipulate pitches and their frequencies using a simple fluent interface.

Please, refer to the Installation, Usage and API sections for more information.

Installation

Install the latest stable version of TwelveTet using npm:

npm install twelvetet

You can also access the files on unpkg.com.

You can use TwelveTet with module bundlers.

The npm package includes precompiled production and development UMD builds in the dist/ folder. They can be used without a bundler.

The UMD builds make TwelveTet available as window.TwelveTet global variable.

TwelveTet works in any modern browser and Node.js.

Usage

import TwelveTet from 'twelvetet'

const tuningFrequency = 440
const twelvetet = new TwelveTet(tuningFrequency)

let pitch

// create a pitch from a frequency
pitch = twelvetet.pitch(440)
console.log(pitch.toString())               // 'A4'

// create a pitch from an out-of-tune frequency
pitch = twelvetet.pitch(438)
console.log(pitch.offset())                 // 0.07887184708183335
console.log(pitch.toString())               // 'A4'
console.log(pitch.valueOf())                // 440

// create a pitch by its scientific notation
pitch = twelvetet.pitch('A4')
console.log(pitch.valueOf())                // 440

// navigate between pitches
pitch = twelvetet.pitch('A4').next()
console.log(pitch.toString())               // 'A#4'

// get intervals
pitch = twelvetet.pitch('A4')
console.log(pitch.intervalTo(pitch.next())) // 1

API

Classes

TwelveTet

Kind: global class

• TwelveTet
  • new TwelveTet([tuningFrequency])
  • .pitch(value)

new TwelveTet([tuningFrequency])

| Param | Type | Default | Description | | --- | --- | --- | --- | | [tuningFrequency] | Number | 440 | The tuning frequency in hertz. |

Example

import TwelveTet from 'twelvetet'

let twelvetet

// instantiate with default tuning frequency of 440 Hz
twelvetet = new TwelveTet()

// instantiate with given tuning frequency
const tuningFrequency = 432
twelvetet = new TwelveTet(tuningFrequency)

twelveTet.pitch(value)

Returns a pitch

Kind: instance method of TwelveTet

| Param | Type | | --- | --- | | value | Number | String | Pitch |

Example

import TwelveTet from 'twelvetet'

const tuningFrequency = 440
const twelvetet = new TwelveTet(tuningFrequency)


let pitch

// create a pitch with the given frequency
pitch = twelvetet.pitch(440)
console.log(+pitch)           // 440
console.log(pitch.toString()) // 'A4'

// create a pitch with an out-of-tune frequency
pitch = twelvetet.pitch(438)
console.log(+pitch) // 440
console.log(pitch.toString()) // 'A4'
console.log(pitch.offset())   // 0.07887184708183335

// create a pitch with scientific notation
pitch = twelvetet.pitch('A4')

// create a pitch with another pitch
pitch = twelvetet.pitch(pitch.next())
console.log(pitch.toString()) // 'A#4'

~Pitch

Kind: inner class

• ~Pitch
  • new Pitch(inputFrequency, tuningFrequency)
  • .class() ⇒ Number
  • .octave() ⇒ Number
  • .offset() ⇒ Number
  • .next([semitones]) ⇒ Pitch
  • .previous([semitones]) ⇒ Pitch
  • .intervalTo(value)
  • .intervalFrom(value)
  • .toString([useFlat])
  • .valueOf()
  • .equals(value) ⇒ Boolean

new Pitch(inputFrequency, tuningFrequency)

Represents a pitch.

| Param | Type | Description | | --- | --- | --- | | inputFrequency | Number | A positive number representing the input frequency in hertz. | | tuningFrequency | Number | A positive number representing the tuning frequency in hertz. |

pitch.class() ⇒ Number

Returns the pitch class

Kind: instance method of Pitch
Returns: Number - An integer between 0 and 11 representing the pitch class

pitch.octave() ⇒ Number

Returns the pitch octave.

Kind: instance method of Pitch
Returns: Number - An integer representing the pitch octave.

pitch.offset() ⇒ Number

Returns the number of semitones between the input and the normalized frequencies.

Kind: instance method of Pitch
Returns: Number - The number of semitones between the input and the normalized frequencies.

pitch.next([semitones]) ⇒ Pitch

Returns the next pitch at the given number of semitones away from the current pitch.

Kind: instance method of Pitch

| Param | Type | Default | Description | | --- | --- | --- | --- | | [semitones] | Number | 1 | An integer representing the number of semitones. |

Example

import TwelveTet from 'twelvetet'

const tuningFrequency = 440
const twelvetet = new TwelveTet(tuningFrequency)

const pitch = twelvetet.pitch('A4')
const pitches = {
  'A#4': pitch.next(), // or pitch.next(1)
  'B4': pitch.next(2), // or pitch.next().next()
  'G#4': pitch.next(-1)
  'G4': pitch.next(-2)
}

pitch.previous([semitones]) ⇒ Pitch

Returns the previous pitch at the given number of semitones away from the current pitch.

Kind: instance method of Pitch

| Param | Type | Default | Description | | --- | --- | --- | --- | | [semitones] | Number | 1 | An integer representing the number of semitones. |

Example

import TwelveTet from 'twelvetet'

const tuningFrequency = 440
const twelvetet = new TwelveTet(tuningFrequency)

const pitch = twelvetet.pitch('A4')
const pitches = {
  'G#4': pitch.previous(), // or pitch.previous(1)
  'G4': pitch.previous(2), // or pitch.previous().previous()
  'A#4': pitch.previous(-1)
  'B4': pitch.previous(-2)
}

pitch.intervalTo(value)

Returns the number of semitones between the current pitch and the pitch represented by the given value

Kind: instance method of Pitch

| Param | Type | Description | | --- | --- | --- | | value | Number | String | Pitch | A value representing a pitch. It can be any of the following: a positive number representing a frequency in hertz. If the frequency is out-of-tune, intervalTo returns the interval between the frequency of the current pitch and the normalized frequency. a string representing scientific pitch notation an instance of Pitch. |

pitch.intervalFrom(value)

Returns the number of semitones between the pitch represented by the given value and the current pitch.

Kind: instance method of Pitch

| Param | Type | Description | | --- | --- | --- | | value | Number | String | Pitch | A value representing a pitch. It can be any of the following: a positive number representing a frequency in hertz. If the frequency is out-of-tune, intervalFrom returns the interval between the normalized frequency and the frequency of the current pitch. a string representing scientific pitch notation an instance of Pitch. If the pitch is from an out-of-tune frequency, intervalFrom returns the interval between the normalized frequency and the frequency of the current pitch. |

pitch.toString([useFlat])

Returns scientific notation of the current pitch

Kind: instance method of Pitch

| Param | Type | Default | Description | | --- | --- | --- | --- | | [useFlat] | Boolean | false | If true, use the flat enharmonic equivalent. |

Example

import TwelveTet from 'twelvetet'

const tuningFrequency = 440
const twelvetet = new TwelveTet(tuningFrequency)

const pitch = twelvetet.pitch('A#4')
console.log(pitch)                // 'A#4'
console.log(pitch.toString())     // 'A#4'
console.log(pitch.toString(true)) // 'Bb4'

pitch.valueOf()

Returns the normalized frequency of the pitch.

Kind: instance method of Pitch
Example

import TwelveTet from 'twelvetet'

const tuningFrequency = 440
const twelvetet = new TwelveTet(tuningFrequency)

// returns the normalized frequency
const pitch = twelvetet.pitch(438)
console.log(+pitch)          // 440
console.log(pitch.valueOf()) // 440

pitch.equals(value) ⇒ Boolean

Returns a boolean indicating whether the two pitches are equal.

Kind: instance method of Pitch

| Param | Type | Description | | --- | --- | --- | | value | Number | String | Pitch | A value representing a pitch. It can be any of the following: a positive number representing a frequency in hertz. If the frequency is out-of-tune, intervalFrom returns the interval between the normalized frequency and the frequency of the current pitch. a string representing scientific pitch notation an instance of Pitch. If the pitch is from an out-of-tune frequency, intervalFrom returns the interval between the normalized frequency and the frequency of the current pitch. |

License

This project is MIT-licensed