README
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
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. |
Number
pitch.class() ⇒ Returns the pitch class
Kind: instance method of Pitch
Returns: Number
- An integer between 0 and 11 representing the pitch class
Number
pitch.octave() ⇒ Returns the pitch octave.
Kind: instance method of Pitch
Returns: Number
- An integer representing the pitch octave.
Number
pitch.offset() ⇒ 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
pitch.next([semitones]) ⇒ 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
pitch.previous([semitones]) ⇒ 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:
|
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:
|
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
Boolean
pitch.equals(value) ⇒ 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:
|
License
This project is MIT-licensed