pitch-utils v0.3.1
- pitch-utils
- Installation
- Usage
- Conversion Overview
- Type Aliases
- Variables
- Functions
- centsToHz
- centsToMidi
- centsToRatio
- centsToSemitones
- cleanNoteName
- formatHz
- getNoteIndexInOctave
- getRoundingFunction
- hzToCents
- hzToMidi
- hzToNoteName
- hzToNoteObject
- hzToRatio
- hzToSemitones
- isNoteBlackOnPiano
- isNoteWhiteOnPiano
- midiToCents
- midiToHz
- midiToNoteName
- midiToNoteObject
- midiToRatio
- midiToSemitones
- namedNoteToCents
- namedNoteToHz
- namedNoteToMidi
- namedNoteToRatio
- namedNoteToSemitones
- quantizeHz
- ratioToCents
- ratioToHz
- ratioToMidi
- ratioToSemitones
- semitonesToCents
- semitonesToHz
- semitonesToMidi
- semitonesToRatio
- Classes
pitch-utils
This (ESM) module provides a collection of functions for converting between pitch and frequency units.
Installation
npm install pitch-utilsUsage
import { hzToSemitones } from "pitch-utils";
hzToSemitones(880, 440); // +12Conversion Overview
| → hz | → ratio | → semitones | → cents | → midi | → named | → note object | |
|---|---|---|---|---|---|---|---|
| hz → | N/A | hzToRatio | hzToSemitones | hzToCents | hzToMidi | hzToNoteName | hzToNoteObject |
| ratio → | ratioToHz | N/A | ratioToSemitones | ratioToCents | ratioToMidi | Unimplemented | Unimplemented |
| semitones → | semitonesToHz | semitonesToRatio | N/A | semitonesToCents | semitonesToMidi | Unimplemented | Unimplemented |
| cents → | centsToHz | centsToRatio | centsToSemitones | N/A | centsToMidi | Unimplemented | Unimplemented |
| midi → | midiToHz | midiToRatio | midiToSemitones | midiToCents | N/A | Unimplemented | Unimplemented |
| named → | namedNoteToHz | namedNoteToRatio | namedNoteToSemitones | namedNoteToCents | namedNoteToMidi | N/A | Unimplemented |
Classes
Type Aliases
Cents
Ƭ Cents: number
A granular pitch offset unit, e.g. +100, -200, 0.
Supports positive and negative numbers.
Defined in
Hz
Ƭ Hz: number
A frequency unit reflecting the number of cycles per second, e.g. 440, 523.2511, or 1600 (1.6kHz).
Supports positive numbers.
Defined in
MIDINoteNumber
Ƭ MIDINoteNumber: number
Integer representation of pitch in 0, 127, e.g. 12 (C0), 69 (A4), 127 (G9).
Defined in
NoteName
Ƭ NoteName: string
A note name with its octave, e.g. C4, A♯3, F♯5.
Also accepts lowercase and keyboard-accessible accidentals like bb3 and b#3.
Defined in
NoteObject
Ƭ NoteObject: Object
Object with note properties for flexible formatting.
Type declaration
| Name | Type |
|---|---|
detune | Cents |
hz | Hz |
note | NoteName |
octave | Octave |
Defined in
Octave
Ƭ Octave: number
Integer pitch grouping, e.g. -1, 4, 10.
Defined in
Ratio
Ƭ Ratio: number
A frequency ratio, e.g. 1.5, 2, 0.5.
Supports positive numbers.
Defined in
RoundingMethod
Ƭ RoundingMethod: "nearest" | "up" | "down"
Rounding method for converting between frequency units.
Todo
maybe eventually this can include hz rounding in addition to pitch rounding
Defined in
Semitones
Ƭ Semitones: number
A semitone pitch offset, e.g. +3, -5, 0.
Supports positive and negative numbers.
Defined in
Variables
A4
• Const A4: 440
A4 frequency in Hz
Defined in
blackNotesOnPiano
• Const blackNotesOnPiano: string[]
Defined in
chromaticScale
• Const chromaticScale: string[]
Normalized note names in the chromatic scale, using sharps
Defined in
enharmonicChromaticScale
• Const enharmonicChromaticScale: string
Note names with alternate enharmonic names
Defined in
whiteNotesOnPiano
• Const whiteNotesOnPiano: string[]
Defined in
Functions
centsToHz
▸ centsToHz(cents, baseHz?): Hz
Example
centsToHz(1200) // 880Parameters
| Name | Type | Default value |
|---|---|---|
cents | number | undefined |
baseHz | number | A4 |
Returns
Defined in
centsToMidi
▸ centsToMidi(cents): MIDINoteNumber
Example
centsToMidi(0) // 69
centsToMidi(1200) // 81Parameters
| Name | Type |
|---|---|
cents | number |
Returns
Defined in
centsToRatio
▸ centsToRatio(cents): Ratio
Example
centsToRatio(1200) // 2Parameters
| Name | Type |
|---|---|
cents | number |
Returns
Defined in
centsToSemitones
▸ centsToSemitones(cents): Semitones
Example
centsToSemitones(100) // +1Parameters
| Name | Type |
|---|---|
cents | number |
Returns
Defined in
cleanNoteName
▸ cleanNoteName(dirtyNote): string
Replaces keyboard-accessible accidentals with their unicode equivalents and makes note name uppercase.
Example
cleanNoteName("C#4") // "C♯4"
cleanNoteName("bb4") // "B♭4"Parameters
| Name | Type | Description |
|---|---|---|
dirtyNote | string | dirty note name, with name, optional accidental, and octave |
Returns
string
Defined in
formatHz
▸ formatHz(hz, precision?, alwaysIncludeSign?): string
Formats a number in Hz to a string with kilohertz support Assumes tabular numeral usage, and includes trailing zeros for alignment.
Example
formatHz(232.5) // "232.50Hz"
formatHz(2325) // "2.33kHz"
formatHz(2325, 2, true) // "+2.33kHz"Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
hz | number | undefined | - |
precision | number | 2 | - |
alwaysIncludeSign | boolean | false | whether to include (+) signs |
Returns
string
Defined in
getNoteIndexInOctave
▸ getNoteIndexInOctave(note): number
Parameters
| Name | Type |
|---|---|
note | string |
Returns
number
Defined in
getRoundingFunction
▸ getRoundingFunction(roundingMethod): (x: number) => number | (x: number) => number | (x: number) => number
Selects a Math.* rounding function based on RoundingMethod union type
Parameters
| Name | Type |
|---|---|
roundingMethod | RoundingMethod |
Returns
(x: number) => number | (x: number) => number | (x: number) => number
Defined in
hzToCents
▸ hzToCents(targetHz, baseHz?): Cents
Example
hzToCents(880, 440) // -1200Parameters
| Name | Type | Default value |
|---|---|---|
targetHz | number | undefined |
baseHz | number | A4 |
Returns
Defined in
hzToMidi
▸ hzToMidi(hz): MIDINoteNumber
Example
hzToMidi(440) // 69
hzToMidi(880) // 81Parameters
| Name | Type |
|---|---|
hz | number |
Returns
Defined in
hzToNoteName
▸ hzToNoteName(hz, roundingMethod?): string
Example
hzToNoteName(260) // C
hzToNoteName(260, Math.floor) // B
hzToNoteName(263) // C
hzToNoteName(263, Math.ceil) // C♯Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
hz | number | undefined | frequency of note in hertz |
roundingMethod | RoundingMethod | "nearest" | whether to round up, down, or naturally |
Returns
string
Defined in
hzToNoteObject
▸ hzToNoteObject(hz): NoteObject
Parameters
| Name | Type | Description |
|---|---|---|
hz | number | frequency of note in hertz |
Returns
Defined in
hzToRatio
▸ hzToRatio(targetHz, baseHz?): Ratio
Example
hzToRatio(880) // 2
hzToRatio(440, 880) // 0.5Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
targetHz | number | undefined | target frequency in hertz |
baseHz | number | A4 | base frequency in hertz |
Returns
Defined in
hzToSemitones
▸ hzToSemitones(targetHz, baseHz?): Semitones
Example
hzToSemitones(880, 440) // -12Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
targetHz | number | undefined | target frequency in hertz |
baseHz | number | A4 | base frequency in hertz |
Returns
Defined in
isNoteBlackOnPiano
▸ isNoteBlackOnPiano(note): boolean
Example
isNoteBlackOnPiano("Cb4") // false
isNoteBlackOnPiano("A♯3") // trueParameters
| Name | Type |
|---|---|
note | string |
Returns
boolean
Defined in
isNoteWhiteOnPiano
▸ isNoteWhiteOnPiano(note): boolean
Example
isNoteWhiteOnPiano("C4") // true
isNoteWhiteOnPiano("A♯3") // falseParameters
| Name | Type |
|---|---|
note | string |
Returns
boolean
Defined in
midiToCents
▸ midiToCents(midi): Cents
Parameters
| Name | Type |
|---|---|
midi | number |
Returns
Defined in
midiToHz
▸ midiToHz(midi): Hz
Parameters
| Name | Type |
|---|---|
midi | number |
Returns
Defined in
midiToNoteName
▸ midiToNoteName(midi, roundingMethod?): string
Parameters
| Name | Type | Default value |
|---|---|---|
midi | number | undefined |
roundingMethod | RoundingMethod | "nearest" |
Returns
string
Defined in
midiToNoteObject
▸ midiToNoteObject(midi): NoteObject
Parameters
| Name | Type |
|---|---|
midi | number |
Returns
Defined in
midiToRatio
▸ midiToRatio(midi): Ratio
Parameters
| Name | Type |
|---|---|
midi | number |
Returns
Defined in
midiToSemitones
▸ midiToSemitones(midi): Semitones
Example
midiToSemitones(69) // 0Parameters
| Name | Type |
|---|---|
midi | number |
Returns
Defined in
namedNoteToCents
▸ namedNoteToCents(note): Cents
Example
namedNoteToCents("C4") // -900Parameters
| Name | Type | Description |
|---|---|---|
note | string | note name, e.g. C4, A♯3, F♯5 |
Returns
Defined in
namedNoteToHz
▸ namedNoteToHz(note): Hz
Example
namedNoteToHz("C4") // 261.6256
namedNoteToHz("A♯3") // 233.0819Parameters
| Name | Type | Description |
|---|---|---|
note | string | note name, e.g. C4, A♯3, F♯5 |
Returns
Defined in
namedNoteToMidi
▸ namedNoteToMidi(note): MIDINoteNumber
Example
namedNoteToMidi("A4") // 69
namedNoteToMidi("C4") // 60Parameters
| Name | Type |
|---|---|
note | string |
Returns
Defined in
namedNoteToRatio
▸ namedNoteToRatio(note, baseNote?): Ratio
Example
namedNoteToRatio("A4") // 1
namedNoteToRatio("A♯3") // 0.5Parameters
| Name | Type | Default value |
|---|---|---|
note | string | undefined |
baseNote | string | "A4" |
Returns
Defined in
namedNoteToSemitones
▸ namedNoteToSemitones(note): Semitones
Example
namedNoteToSemitones("C4") // +3
namedNoteToSemitones("A♯3") // -11Parameters
| Name | Type |
|---|---|
note | string |
Returns
Defined in
quantizeHz
▸ quantizeHz(hz, roundingMethod?): Hz
Example
quantizeHz(450) // 440
quantizeHz(450, "down") // 440
quantizeHz(450, "up") // ~466.17Parameters
| Name | Type | Default value |
|---|---|---|
hz | number | undefined |
roundingMethod | RoundingMethod | "nearest" |
Returns
Defined in
ratioToCents
▸ ratioToCents(ratio): Cents
Example
ratioToCents(2) // 1200
ratioToCents(3) // 1902Parameters
| Name | Type | Description |
|---|---|---|
ratio | number | decimal or fractional ratio |
Returns
Defined in
ratioToHz
▸ ratioToHz(ratio, baseHz?): Hz
Example
ratioToHz(2) // 880
ratioToHz(3) // 1320Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
ratio | number | undefined | decimal or fractional ratio |
baseHz | number | A4 | optional base note |
Returns
Defined in
ratioToMidi
▸ ratioToMidi(ratio): MIDINoteNumber
Example
ratioToMidi(1) // 69
ratioToMidi(2) // 81Parameters
| Name | Type |
|---|---|
ratio | number |
Returns
Defined in
ratioToSemitones
▸ ratioToSemitones(ratio): Semitones
Example
ratioToSemitones(2) // 12
ratioToSemitones(3) // ~19.02Parameters
| Name | Type | Description |
|---|---|---|
ratio | number | decimal or fractional ratio |
Returns
Defined in
semitonesToCents
▸ semitonesToCents(semitones): Cents
Example
semitonesToCents(-12) // -1200
semitonesToCents(0.5) // 50Parameters
| Name | Type | Description |
|---|---|---|
semitones | number | semitone offset |
Returns
Defined in
semitonesToHz
▸ semitonesToHz(semitones, baseHz?): Hz
Example
semitonesToHz(3) // 523.2511
semitonesToHz(-3, 523.2511) // 440Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
semitones | number | undefined | semitone offset |
baseHz | number | A4 | optional base note |
Returns
Defined in
semitonesToMidi
▸ semitonesToMidi(semitones): MIDINoteNumber
Example
semitonesToMidi(0) // 69
semitonesToMidi(12) // 81Parameters
| Name | Type |
|---|---|
semitones | number |
Returns
Defined in
semitonesToRatio
▸ semitonesToRatio(semitones): Ratio
Example
semitonesToRatio(12) // 2
semitonesToRatio(-12) // 0.5Parameters
| Name | Type | Description |
|---|---|---|
semitones | number | semitone offset |
Returns
Defined in
Classes
Pitch
Example
const note = new Pitch(440)
note.noteObject.note // "A4"
note.modRatio(3/1)
note.noteObject.note // "E6"Constructors
constructor
• new Pitch(frequency?)
Parameters
| Name | Type | Default value | Description |
|---|---|---|---|
frequency | number | A4 | frequency of note in hertz |
Defined in
Properties
detune
• detune: (cents: number) => Pitch
Type declaration
▸ (cents): Pitch
Parameters
| Name | Type |
|---|---|
cents | number |
Returns
Defined in
frequency
• frequency: number = A4
frequency of note in hertz
Defined in
hz
• hz: number
base value for calculations
Defined in
transpose
• transpose: (semitones: number) => Pitch
Type declaration
▸ (semitones): Pitch
Parameters
| Name | Type |
|---|---|
semitones | number |
Returns
Defined in
Accessors
cents
• get cents(): number
Returns
number
Defined in
closestNoteAbove
• get closestNoteAbove(): NoteObject
Returns
Defined in
closestNoteBelow
• get closestNoteBelow(): NoteObject
Returns
Defined in
midi
• get midi(): number
Returns
number
Defined in
noteObject
• get noteObject(): NoteObject
Returns
Defined in
ratio
• get ratio(): number
Returns
number
Defined in
semitones
• get semitones(): number
Returns
number
Defined in
Methods
addCents
▸ addCents(cents): Pitch
Parameters
| Name | Type |
|---|---|
cents | number |
Returns
Defined in
addSemitones
▸ addSemitones(semitones): Pitch
Parameters
| Name | Type |
|---|---|
semitones | number |
Returns
Defined in
modRatio
▸ modRatio(ratio): Pitch
Parameters
| Name | Type |
|---|---|
ratio | number |
Returns
Defined in
quantize
▸ quantize(roundingMethod?): Pitch
Parameters
| Name | Type | Default value |
|---|---|---|
roundingMethod | RoundingMethod | "nearest" |
Returns
Defined in
shift
▸ shift(hz): Pitch
Parameters
| Name | Type |
|---|---|
hz | number |
Returns
Defined in
fromNamedNote
▸ Static fromNamedNote(note): Pitch
initialize from NamedNote
Example
Pitch.fromNamedNote("A3").hz // 220Parameters
| Name | Type |
|---|---|
note | string |