danielgamage/pitch-utils

Pitch, frequency conversion utilities

• pitch-utils
  • Installation
  • Usage
  • Conversion Overview
  • Type Aliases
    • Cents
    • Hz
    • NoteName
    • NoteObject
    • Octave
    • Ratio
    • RoundingMethod
    • Semitones
  • Variables
    • A4
    • chromaticScale
    • enharmonicChromaticScale
  • Functions
    • centsToHz
    • centsToRatio
    • centsToSemitones
    • cleanNoteName
    • formatHz
    • getNoteIndexInOctave
    • getRoundingFunction
    • hzToCents
    • hzToNoteName
    • hzToNoteObject
    • hzToRatio
    • hzToSemitones
    • namedNoteToCents
    • namedNoteToHz
    • namedNoteToRatio
    • namedNoteToSemitones
    • quantizeHz
    • ratioToCents
    • ratioToHz
    • ratioToSemitones
    • semitonesToCents
    • semitonesToHz
    • semitonesToRatio
  • Classes
    • Pitch

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	→ named	→ note object
hz →	N/A	hzToRatio	hzToSemitones	hzToCents	hzToNoteName	hzToNoteObject
ratio →	ratioToHz	N/A	ratioToSemitones	ratioToCents	Unimplemented	Unimplemented
semitones →	semitonesToHz	semitonesToRatio	N/A	semitonesToCents	Unimplemented	Unimplemented
cents →	centsToHz	centsToRatio	centsToSemitones	N/A	Unimplemented	Unimplemented
named →	namedNoteToHz	namedNoteToRatio	namedNoteToSemitones	namedNoteToCents	N/A	Unimplemented

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

---

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

---

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

---

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

---

Octave

Ƭ Octave: number

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

Defined in

src/index.ts:64

---

Ratio

Ƭ Ratio: number

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

Defined in

src/index.ts:41

---

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

---

Semitones

Ƭ Semitones: number

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

Defined in

src/index.ts:47

Variables

A4

• Const A4: 440

A4 frequency in Hz

Defined in

src/index.ts:89

---

chromaticScale

• Const chromaticScale: string[]

Normalized note names in the chromatic scale, using sharps

Defined in

src/index.ts:93

---

enharmonicChromaticScale

• Const enharmonicChromaticScale: string[][]

Note names with alternate enharmonic names

Defined in

src/index.ts:110

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

---

centsToRatio

▸ centsToRatio(cents): Ratio

Example

centsToRatio(1200) // 2

Parameters

Name	Type
cents	number

Returns

Ratio

Defined in

src/index.ts:252

---

centsToSemitones

▸ centsToSemitones(cents): Semitones

Example

centsToSemitones(100) // +1

Parameters

Name	Type
cents	number

Returns

Semitones

Defined in

src/index.ts:244

---

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

---

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

---

getNoteIndexInOctave

▸ getNoteIndexInOctave(note): number

Parameters

Name	Type
note	string

Returns

number

Defined in

src/index.ts:143

---

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

src/index.ts:133

---

hzToCents

▸ hzToCents(targetHz, baseHz?): Cents

Example

hzToCents(880, 440) // -1200

Parameters

Name	Type	Default value
targetHz	number	undefined
baseHz	number	A4

Returns

Cents

Defined in

src/index.ts:439

---

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

src/index.ts:378

---

hzToNoteObject

▸ hzToNoteObject(hz): NoteObject

Parameters

Name	Type	Description
hz	number	frequency of note in hertz

Returns

NoteObject

Defined in

src/index.ts:388

---

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

---

hzToSemitones

▸ hzToSemitones(targetHz, baseHz?): 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:425

---

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

---

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

---

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

---

namedNoteToSemitones

▸ namedNoteToSemitones(note): Semitones

Example

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

Parameters

Name	Type
note	string

Returns

Semitones

Defined in

src/index.ts:273

---

quantizeHz

▸ quantizeHz(hz, roundingMethod?): Hz

Example

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

Parameters

Name	Type	Default value
hz	number	undefined
roundingMethod	RoundingMethod	"nearest"

Returns

Hz

Defined in

src/index.ts:450

---

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

---

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

---

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

---

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

---

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

---

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

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

src/index.ts:469

Properties

detune

• detune: (cents: number) => Pitch

Type declaration

▸ (cents): Pitch

####### Parameters

Name	Type
cents	number

####### Returns

Pitch

Defined in

src/index.ts:533

---

frequency

• frequency: number = A4

frequency of note in hertz

Defined in

src/index.ts:471

---

hz

• hz: number

base value for calculations

Defined in

src/index.ts:468

---

transpose

• transpose: (semitones: number) => Pitch

Type declaration

▸ (semitones): Pitch

####### Parameters

Name	Type
semitones	number

####### Returns

Pitch

Defined in

src/index.ts:522

Accessors

cents

• get cents(): number

Returns

number

Defined in

src/index.ts:492

---

closestNoteAbove

• get closestNoteAbove(): NoteObject

Returns

NoteObject

Defined in

src/index.ts:507

---

closestNoteBelow

• get closestNoteBelow(): NoteObject

Returns

NoteObject

Defined in

src/index.ts:502

---

noteObject

• get noteObject(): NoteObject

Returns

NoteObject

Defined in

src/index.ts:499

---

ratio

• get ratio(): number

Returns

number

Defined in

src/index.ts:495

---

semitones

• get semitones(): number

Returns

number

Defined in

src/index.ts:489

Methods

addCents

▸ addCents(cents): Pitch

Parameters

Name	Type
cents	number

Returns

Pitch

Defined in

src/index.ts:529

---

addSemitones

▸ addSemitones(semitones): Pitch

Parameters

Name	Type
semitones	number

Returns

Pitch

Defined in

src/index.ts:518

---

modRatio

▸ modRatio(ratio): Pitch

Parameters

Name	Type
ratio	number

Returns

Pitch

Defined in

src/index.ts:535

---

quantize

▸ quantize(roundingMethod?): Pitch

Parameters

Name	Type	Default value
roundingMethod	RoundingMethod	"nearest"

Returns

Pitch

Defined in

src/index.ts:513

---

shift

▸ shift(hz): Pitch

Parameters

Name	Type
hz	number

Returns

Pitch

Defined in

src/index.ts:524

---

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