• pitch-utils
  • Installation
  • Usage
  • Conversion Overview
  • Classes
  • Type Aliases
    • Cents
    • Hz
    • MIDINoteNumber
    • NoteName
    • NoteObject
    • Octave
    • Ratio
    • RoundingMethod
    • Semitones
  • Variables
    • A4
    • blackNotesOnPiano
    • chromaticScale
    • enharmonicChromaticScale
    • whiteNotesOnPiano
  • Functions
    • centsToHz
    • centsToMidi
    • centsToNoteName
    • centsToNoteObject
    • centsToRatio
    • centsToSemitones
    • cleanNoteName
    • formatHz
    • getNoteIndexInOctave
    • getRoundingFunction
    • hzToCents
    • hzToMidi
    • hzToNoteName
    • hzToNoteObject
    • hzToRatio
    • hzToSemitones
    • isNoteBlackOnPiano
    • isNoteWhiteOnPiano
    • midiToCents
    • midiToHz
    • midiToNoteName
    • midiToNoteObject
    • midiToRatio
    • midiToSemitones
    • namedNoteToCents
    • namedNoteToHz
    • namedNoteToMidi
    • namedNoteToNoteObject
    • namedNoteToRatio
    • namedNoteToSemitones
    • quantizeHz
    • ratioToCents
    • ratioToHz
    • ratioToMidi
    • ratioToNoteName
    • ratioToNoteObject
    • ratioToSemitones
    • semitonesToCents
    • semitonesToHz
    • semitonesToMidi
    • semitonesToNoteName
    • semitonesToNoteObject
    • semitonesToRatio
    • validateHz
• Classes
  • Class: Pitch
    • Constructors
    • Properties
    • Accessors
    • Methods

pitch-utils

This (ESM) module provides a collection of functions for converting between pitch and frequency units.

Installation

npm install pitch-utils

Usage

import { hzToSemitones } from "pitch-utils";
hzToSemitones(880, 440); // +12

Conversion 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 | ratioToNoteName | ratioToNoteObject | | semitones → | semitonesToHz | semitonesToRatio | N/A | semitonesToCents | semitonesToMidi | semitonesToNoteName | semitonesToNoteObject | | cents → | centsToHz | centsToRatio | centsToSemitones | N/A | centsToMidi | centsToNoteName | centsToNoteObject | | midi → | midiToHz | midiToRatio | midiToSemitones | midiToCents | N/A | midiToNoteName | midiToNoteObject | | named → | namedNoteToHz | namedNoteToRatio | namedNoteToSemitones | namedNoteToCents | namedNoteToMidi | N/A | namedNoteToNoteObject |

Classes

• Pitch

Type Aliases

Cents

Ƭ Cents: number

A granular pitch offset unit, e.g. +100, -200, 0. Supports positive and negative numbers.

Defined in

src/index.ts:55

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

src/index.ts:61

MIDINoteNumber

Ƭ MIDINoteNumber: number

Integer representation of pitch in [0, 127], e.g. 12 (C0), 69 (A4), 127 (G9).

Defined in

src/index.ts:71

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

src/index.ts:37

NoteObject

Ƭ NoteObject: Object

Object with note properties for flexible formatting.

Type declaration

| Name | Type | | :------ | :------ | | detune | Cents | | hz | Hz | | note | NoteName | | octave | Octave |

Defined in

src/index.ts:76

Octave

Ƭ Octave: number

Integer pitch grouping, e.g. -1, 4, 10.

Defined in

src/index.ts:66

Ratio

Ƭ Ratio: number

A frequency ratio, e.g. 1.5, 2, 0.5. Supports positive numbers.

Defined in

src/index.ts:43

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

src/index.ts:87

Semitones

Ƭ Semitones: number

A semitone pitch offset, e.g. +3, -5, 0. Supports positive and negative numbers.

Defined in

src/index.ts:49

Variables

A4

• Const A4: 440

A4 frequency in Hz

Defined in

src/index.ts:96

blackNotesOnPiano

• Const blackNotesOnPiano: string[]

Defined in

src/index.ts:137

chromaticScale

• Const chromaticScale: string[]

Normalized note names in the chromatic scale, using sharps

Defined in

src/index.ts:100

enharmonicChromaticScale

• Const enharmonicChromaticScale: string[][]

Note names with alternate enharmonic names

Defined in

src/index.ts:117

whiteNotesOnPiano

• Const whiteNotesOnPiano: string[]

Defined in

src/index.ts:134

Functions

centsToHz

▸ centsToHz(cents, baseHz?): Hz

Example

centsToHz(1200) // 880

Parameters

| Name | Type | Default value | | :------ | :------ | :------ | | cents | number | undefined | | baseHz | number | A4 |

Returns

Hz

Defined in

src/index.ts:320

centsToMidi

▸ centsToMidi(cents, roundingMethod?): MIDINoteNumber

Example

centsToMidi(0) // 69
centsToMidi(1200) // 81

Parameters

| Name | Type | | :------ | :------ | | cents | number | | roundingMethod? | RoundingMethod |

Returns

MIDINoteNumber

Defined in

src/index.ts:330

centsToNoteName

▸ centsToNoteName(cents): string

Example

centsToNoteName(0) // "A"
centsToNoteName(1200) // "A"

Parameters

| Name | Type | | :------ | :------ | | cents | number |

Returns

string

Defined in

src/index.ts:340

centsToNoteObject

▸ centsToNoteObject(cents): NoteObject

Example

centsToNoteObject(0) // {note: "A", octave: 4, hz: 440, detune: 0}
centsToNoteObject(1200) // {note: "A", octave: 5, hz: 880, detune: 0}

Parameters

| Name | Type | | :------ | :------ | | cents | number |

Returns

NoteObject

Defined in

src/index.ts:349

centsToRatio

▸ centsToRatio(cents): Ratio

Example

centsToRatio(1200) // 2

Parameters

| Name | Type | | :------ | :------ | | cents | number |

Returns

Ratio

Defined in

src/index.ts:312

centsToSemitones

▸ centsToSemitones(cents): Semitones

Example

centsToSemitones(100) // +1

Parameters

| Name | Type | | :------ | :------ | | cents | number |

Returns

Semitones

Defined in

src/index.ts:304

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

src/index.ts:176

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

src/index.ts:220

getNoteIndexInOctave

▸ getNoteIndexInOctave(note): number

Parameters

| Name | Type | | :------ | :------ | | note | string |

Returns

number

Defined in

src/index.ts:159

getRoundingFunction

▸ getRoundingFunction(roundingMethod): (x: number) => number

Selects a Math.* rounding function based on RoundingMethod union type

Parameters

| Name | Type | | :------ | :------ | | roundingMethod | RoundingMethod |

Returns

fn

▸ (x): number

Returns a supplied numeric expression rounded to the nearest integer.

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | x | number | The value to be rounded to the nearest integer. |

Returns

number

Defined in

src/index.ts:149

hzToCents

▸ hzToCents(targetHz, baseHz?): Cents

When a baseHz is provided, returns the difference in cents

Example

hzToCents(880, 440) // +1200

Parameters

| Name | Type | Default value | | :------ | :------ | :------ | | targetHz | number | undefined | | baseHz | number | A4 |

Returns

Cents

Defined in

src/index.ts:638

hzToMidi

▸ hzToMidi(hz, roundingMethod?): MIDINoteNumber

Example

hzToMidi(440) // 69
hzToMidi(880) // 81

Parameters

| Name | Type | | :------ | :------ | | hz | number | | roundingMethod? | RoundingMethod |

Returns

MIDINoteNumber

Defined in

src/index.ts:650

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 | Description | | :------ | :------ | :------ | | hz | number | frequency of note in hertz | | roundingMethod? | RoundingMethod | whether to round up, down, or naturally |

Returns

string

Defined in

src/index.ts:566

hzToNoteObject

▸ hzToNoteObject(hz): NoteObject

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | hz | number | frequency of note in hertz |

Returns

NoteObject

Defined in

src/index.ts:580

hzToRatio

▸ hzToRatio(targetHz, baseHz?): Ratio

Example

hzToRatio(880) // 2
hzToRatio(440, 880) // 0.5

Parameters

| Name | Type | Default value | Description | | :------ | :------ | :------ | :------ | | targetHz | number | undefined | target frequency in hertz | | baseHz | number | A4 | base frequency in hertz |

Returns

Ratio

Defined in

src/index.ts:604

hzToSemitones

▸ hzToSemitones(targetHz, baseHz?): Semitones

When a baseHz is provided, returns the difference in semitones

Example

hzToSemitones(880, 440) // +12

Parameters

| Name | Type | Default value | Description | | :------ | :------ | :------ | :------ | | targetHz | number | undefined | target frequency in hertz | | baseHz | number | A4 | base frequency in hertz |

Returns

Semitones

Defined in

src/index.ts:621

isNoteBlackOnPiano

▸ isNoteBlackOnPiano(note): boolean

Example

isNoteBlackOnPiano("Cb4") // false
isNoteBlackOnPiano("A♯3") // true

Parameters

| Name | Type | | :------ | :------ | | note | string |

Returns

boolean

Defined in

src/index.ts:440

isNoteWhiteOnPiano

▸ isNoteWhiteOnPiano(note): boolean

Example

isNoteWhiteOnPiano("C4") // true
isNoteWhiteOnPiano("A♯3") // false

Parameters

| Name | Type | | :------ | :------ | | note | string |

Returns

boolean

Defined in

src/index.ts:431

midiToCents

▸ midiToCents(midi): Cents

Example

midiToCents(69) // 0
midiToCents(81) // 1200

Parameters

| Name | Type | | :------ | :------ | | midi | number |

Returns

Cents

Defined in

src/index.ts:533

midiToHz

▸ midiToHz(midi): Hz

Example

midiToHz(69) // 440
midiToHz(60) // 261.62...

Parameters

| Name | Type | | :------ | :------ | | midi | number |

Returns

Hz

Defined in

src/index.ts:524

midiToNoteName

▸ midiToNoteName(midi, roundingMethod?): string

Parameters

| Name | Type | | :------ | :------ | | midi | number | | roundingMethod? | RoundingMethod |

Returns

string

Defined in

src/index.ts:545

midiToNoteObject

▸ midiToNoteObject(midi): NoteObject

Parameters

| Name | Type | | :------ | :------ | | midi | number |

Returns

NoteObject

Defined in

src/index.ts:551

midiToRatio

▸ midiToRatio(midi): Ratio

Example

midiToRatio(81) // 2
midiToRatio(69) // 1

Parameters

| Name | Type | | :------ | :------ | | midi | number |

Returns

Ratio

Defined in

src/index.ts:542

midiToSemitones

▸ midiToSemitones(midi): Semitones

Example

midiToSemitones(69) // 0
midiToSemitones(81) // +12

Parameters

| Name | Type | | :------ | :------ | | midi | number |

Returns

Semitones

Defined in

src/index.ts:515

namedNoteToCents

▸ namedNoteToCents(note): Cents

Example

namedNoteToCents("C4") // -900

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | note | string | note name, e.g. C4, A♯3, F♯5 |

Returns

Cents

Defined in

src/index.ts:391

namedNoteToHz

▸ namedNoteToHz(note): Hz

Example

namedNoteToHz("C4") // 261.6256
namedNoteToHz("A♯3") // 233.0819

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | note | string | note name, e.g. C4, A♯3, F♯5 |

Returns

Hz

Defined in

src/index.ts:404

namedNoteToMidi

▸ namedNoteToMidi(note): MIDINoteNumber

Example

namedNoteToMidi("A4") // 69
namedNoteToMidi("C4") // 60

Parameters

| Name | Type | | :------ | :------ | | note | string |

Returns

MIDINoteNumber

Defined in

src/index.ts:417

namedNoteToNoteObject

▸ namedNoteToNoteObject(note): NoteObject

Parameters

| Name | Type | | :------ | :------ | | note | string |

Returns

NoteObject

Defined in

src/index.ts:421

namedNoteToRatio

▸ namedNoteToRatio(note, baseNote?): Ratio

Example

namedNoteToRatio("A4") // 1
namedNoteToRatio("A♯3") // 0.5

Parameters

| Name | Type | Default value | | :------ | :------ | :------ | | note | string | undefined | | baseNote | string | "A4" |

Returns

Ratio

Defined in

src/index.ts:380

namedNoteToSemitones

▸ namedNoteToSemitones(note): Semitones

Example

namedNoteToSemitones("C4") // +3
namedNoteToSemitones("A♯3") // -11

Parameters

| Name | Type | | :------ | :------ | | note | string |

Returns

Semitones

Defined in

src/index.ts:362

quantizeHz

▸ quantizeHz(hz, roundingMethod?): Hz

Example

quantizeHz(450) // 440
quantizeHz(450, "down") // 440
quantizeHz(450, "up") // ~466.17

Parameters

| Name | Type | | :------ | :------ | | hz | number | | roundingMethod? | RoundingMethod |

Returns

Hz

Defined in

src/index.ts:662

ratioToCents

▸ ratioToCents(ratio): Cents

Example

ratioToCents(2) // 1200
ratioToCents(3) // 1902

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | ratio | number | decimal or fractional ratio |

Returns

Cents

Defined in

src/index.ts:481

ratioToHz

▸ ratioToHz(ratio, baseHz?): Hz

Example

ratioToHz(2) // 880
ratioToHz(3) // 1320

Parameters

| Name | Type | Default value | Description | | :------ | :------ | :------ | :------ | | ratio | number | undefined | decimal or fractional ratio | | baseHz | number | A4 | optional base note |

Returns

Hz

Defined in

src/index.ts:465

ratioToMidi

▸ ratioToMidi(ratio, roundingMethod?): MIDINoteNumber

Example

ratioToMidi(1) // 69
ratioToMidi(2) // 81

Parameters

| Name | Type | | :------ | :------ | | ratio | number | | roundingMethod? | RoundingMethod |

Returns

MIDINoteNumber

Defined in

src/index.ts:501

ratioToNoteName

▸ ratioToNoteName(ratio): string

Parameters

| Name | Type | | :------ | :------ | | ratio | number |

Returns

string

Defined in

src/index.ts:488

ratioToNoteObject

▸ ratioToNoteObject(ratio): NoteObject

Parameters

| Name | Type | | :------ | :------ | | ratio | number |

Returns

NoteObject

Defined in

src/index.ts:491

ratioToSemitones

▸ ratioToSemitones(ratio): Semitones

Example

ratioToSemitones(2) // 12
ratioToSemitones(3) // ~19.02

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | ratio | number | decimal or fractional ratio |

Returns

Semitones

Defined in

src/index.ts:452

semitonesToCents

▸ semitonesToCents(semitones): Cents

Example

semitonesToCents(-12) // -1200
semitonesToCents(0.5) // 50

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | semitones | number | semitone offset |

Returns

Cents

Defined in

src/index.ts:259

semitonesToHz

▸ semitonesToHz(semitones, baseHz?): Hz

Example

semitonesToHz(3) // 523.2511
semitonesToHz(-3, 523.2511) // 440

Parameters

| Name | Type | Default value | Description | | :------ | :------ | :------ | :------ | | semitones | number | undefined | semitone offset | | baseHz | number | A4 | optional base note |

Returns

Hz

Defined in

src/index.ts:244

semitonesToMidi

▸ semitonesToMidi(semitones, roundingMethod?): MIDINoteNumber

Returns a MIDI note number relative to A4 (69).

Example

semitonesToMidi(0) // 69
semitonesToMidi(12) // 81

Parameters

| Name | Type | | :------ | :------ | | semitones | number | | roundingMethod? | RoundingMethod |

Returns

MIDINoteNumber

Defined in

src/index.ts:285

semitonesToNoteName

▸ semitonesToNoteName(semitones, baseHz?): string

Parameters

| Name | Type | Default value | | :------ | :------ | :------ | | semitones | number | undefined | | baseHz | number | A4 |

Returns

string

Defined in

src/index.ts:289

semitonesToNoteObject

▸ semitonesToNoteObject(semitones, baseHz?): NoteObject

Parameters

| Name | Type | Default value | | :------ | :------ | :------ | | semitones | number | undefined | | baseHz | number | A4 |

Returns

NoteObject

Defined in

src/index.ts:292

semitonesToRatio

▸ semitonesToRatio(semitones): Ratio

Example

semitonesToRatio(12) // 2
semitonesToRatio(-12) // 0.5

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | semitones | number | semitone offset |

Returns

Ratio

Defined in

src/index.ts:271

validateHz

▸ validateHz(hz): asserts hz is number

Validates that a frequency value is a positive, non-zero number. Throws an error if the value is zero, negative, or not a number.

Example

validateHz(440) // passes
validateHz(0) // throws error
validateHz(-220) // throws error
validateHz(NaN) // throws error

Parameters

| Name | Type | Description | | :------ | :------ | :------ | | hz | number | The frequency in Hz to validate |

Returns

asserts hz is number

Defined in

src/index.ts:205

Classes

Class: 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

src/index.ts:685

Properties

detune

• detune: (cents: number) => Pitch

Type declaration

▸ (cents): Pitch

detunes the pitch by a number of cents

Parameters

| Name | Type | | :------ | :------ | | cents | number |

Returns

Pitch

Defined in

src/index.ts:763

frequency

• frequency: number = A4

frequency of note in hertz

Defined in

src/index.ts:687

hz

• hz: number

base value for calculations

Defined in

src/index.ts:684

transpose

• transpose: (semitones: number) => Pitch

Type declaration

▸ (semitones): Pitch

transposes the current pitch by a number of semitones

Parameters

| Name | Type | | :------ | :------ | | semitones | number |

Returns

Pitch

Defined in

src/index.ts:750

Accessors

closestNoteAbove

• get closestNoteAbove(): NoteObject

returns the nearest note above

Returns

NoteObject

Defined in

src/index.ts:733

closestNoteBelow

• get closestNoteBelow(): NoteObject

returns the nearest note below

Returns

NoteObject

Defined in

src/index.ts:727

midi

• get midi(): number

Example

for A4, `69`

Returns

number

Defined in

src/index.ts:710

noteName

• get noteName(): string

Example

for A4, `"A"`

Returns

string

Defined in

src/index.ts:722

noteObject

• get noteObject(): NoteObject

Returns

NoteObject

Defined in

src/index.ts:714

octave

• get octave(): number

Example

for A4, `4`

Returns

number

Defined in

src/index.ts:718

Methods

addCents

▸ addCents(cents): Pitch

detunes the pitch by a number of cents

Parameters

| Name | Type | | :------ | :------ | | cents | number |

Returns

Pitch

Defined in

src/index.ts:759

addSemitones

▸ addSemitones(semitones): Pitch

transposes the current pitch by a number of semitones

Parameters

| Name | Type | | :------ | :------ | | semitones | number |

Returns

Pitch

Defined in

src/index.ts:746

centsFrom

▸ centsFrom(other): number

centsFrom, centsTo

Parameters

| Name | Type | | :------ | :------ | | other | number | Pitch |

Returns

number

Defined in

src/index.ts:781

centsTo

▸ centsTo(other): number

Parameters

| Name | Type | | :------ | :------ | | other | number | Pitch |

Returns

number

Defined in

src/index.ts:785

modRatio

▸ modRatio(ratio): Pitch

modulates the pitch by a ratio

Parameters

| Name | Type | | :------ | :------ | | ratio | number |

Returns

Pitch

Defined in

src/index.ts:766

quantize

▸ quantize(roundingMethod?): Pitch

snaps the pitch to the nearest semitone

Parameters

| Name | Type | | :------ | :------ | | roundingMethod? | RoundingMethod |

Returns

Pitch

Defined in

src/index.ts:740

ratioFrom

▸ ratioFrom(other): number

ratioFrom, ratioTo

Parameters

| Name | Type | | :------ | :------ | | other | number | Pitch |

Returns

number

Defined in

src/index.ts:790

ratioTo

▸ ratioTo(other): number

Parameters

| Name | Type | | :------ | :------ | | other | number | Pitch |

Returns

number

Defined in

src/index.ts:794

semitonesFrom

▸ semitonesFrom(other): number

semitonesFrom, semitonesTo

Parameters

| Name | Type | | :------ | :------ | | other | number | Pitch |

Returns

number

Defined in

src/index.ts:772

semitonesTo

▸ semitonesTo(other): number

Parameters

| Name | Type | | :------ | :------ | | other | number | Pitch |

Returns

number

Defined in

src/index.ts:776

shift

▸ shift(hz): Pitch

shifts the pitch by a number of hertz

Parameters

| Name | Type | | :------ | :------ | | hz | number |

Returns

Pitch

Defined in

src/index.ts:753

fromMidi

▸ Static fromMidi(midi): Pitch

Parameters

| Name | Type | | :------ | :------ | | midi | number |

Returns

Pitch

Defined in

src/index.ts:703

fromNamedNote

▸ Static fromNamedNote(note): Pitch

initialize from NamedNote

Example

Pitch.fromNamedNote("A3").hz // 220

Parameters

| Name | Type | | :------ | :------ | | note | string |

Returns

Pitch

Defined in

src/index.ts:698