npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

pitch-utils

v0.3.1

Published

Pitch and frequency functions

Downloads

8

Readme

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

src/index.ts:54


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


MIDINoteNumber

Ƭ MIDINoteNumber: number

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

Defined in

src/index.ts:70


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


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


Octave

Ƭ Octave: number

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

Defined in

src/index.ts:65


Ratio

Ƭ Ratio: number

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

Defined in

src/index.ts:42


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


Semitones

Ƭ Semitones: number

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

Defined in

src/index.ts:48

Variables

A4

Const A4: 440

A4 frequency in Hz

Defined in

src/index.ts:95


blackNotesOnPiano

Const blackNotesOnPiano: string[]

Defined in

src/index.ts:136


chromaticScale

Const chromaticScale: string[]

Normalized note names in the chromatic scale, using sharps

Defined in

src/index.ts:99


enharmonicChromaticScale

Const enharmonicChromaticScale: string[][]

Note names with alternate enharmonic names

Defined in

src/index.ts:116


whiteNotesOnPiano

Const whiteNotesOnPiano: string[]

Defined in

src/index.ts:133

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


centsToMidi

centsToMidi(cents): MIDINoteNumber

Example

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

Parameters

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

Returns

MIDINoteNumber

Defined in

src/index.ts:295


centsToRatio

centsToRatio(cents): Ratio

Example

centsToRatio(1200) // 2

Parameters

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

Returns

Ratio

Defined in

src/index.ts:277


centsToSemitones

centsToSemitones(cents): Semitones

Example

centsToSemitones(100) // +1

Parameters

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

Returns

Semitones

Defined in

src/index.ts:269


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


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


getNoteIndexInOctave

getNoteIndexInOctave(note): number

Parameters

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

Returns

number

Defined in

src/index.ts:158


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


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


hzToMidi

hzToMidi(hz): MIDINoteNumber

Example

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

Parameters

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

Returns

MIDINoteNumber

Defined in

src/index.ts:556


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


hzToNoteObject

hzToNoteObject(hz): NoteObject

Parameters

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

Returns

NoteObject

Defined in

src/index.ts:495


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


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


isNoteBlackOnPiano

isNoteBlackOnPiano(note): boolean

Example

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

Parameters

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

Returns

boolean

Defined in

src/index.ts:382


isNoteWhiteOnPiano

isNoteWhiteOnPiano(note): boolean

Example

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

Parameters

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

Returns

boolean

Defined in

src/index.ts:373


midiToCents

midiToCents(midi): Cents

Parameters

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

Returns

Cents

Defined in

src/index.ts:455


midiToHz

midiToHz(midi): Hz

Parameters

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

Returns

Hz

Defined in

src/index.ts:452


midiToNoteName

midiToNoteName(midi, roundingMethod?): string

Parameters

| Name | Type | Default value | | :------ | :------ | :------ | | midi | number | undefined | | roundingMethod | RoundingMethod | "nearest" |

Returns

string

Defined in

src/index.ts:461


midiToNoteObject

midiToNoteObject(midi): NoteObject

Parameters

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

Returns

NoteObject

Defined in

src/index.ts:467


midiToRatio

midiToRatio(midi): Ratio

Parameters

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

Returns

Ratio

Defined in

src/index.ts:458


midiToSemitones

midiToSemitones(midi): Semitones

Example

midiToSemitones(69) // 0

Parameters

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

Returns

Semitones

Defined in

src/index.ts:449


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


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


namedNoteToMidi

namedNoteToMidi(note): MIDINoteNumber

Example

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

Parameters

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

Returns

MIDINoteNumber

Defined in

src/index.ts:363


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


namedNoteToSemitones

namedNoteToSemitones(note): Semitones

Example

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

Parameters

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

Returns

Semitones

Defined in

src/index.ts:308


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


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


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


ratioToMidi

ratioToMidi(ratio): MIDINoteNumber

Example

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

Parameters

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

Returns

MIDINoteNumber

Defined in

src/index.ts:436


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


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


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


semitonesToMidi

semitonesToMidi(semitones): MIDINoteNumber

Example

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

Parameters

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

Returns

MIDINoteNumber

Defined in

src/index.ts:257


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

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

Properties

detune

detune: (cents: number) => Pitch

Type declaration

▸ (cents): Pitch

Parameters

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

Returns

Pitch

Defined in

src/index.ts:654


frequency

frequency: number = A4

frequency of note in hertz

Defined in

src/index.ts:591


hz

hz: number

base value for calculations

Defined in

src/index.ts:588


transpose

transpose: (semitones: number) => Pitch

Type declaration

▸ (semitones): Pitch

Parameters

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

Returns

Pitch

Defined in

src/index.ts:643

Accessors

cents

get cents(): number

Returns

number

Defined in

src/index.ts:610


closestNoteAbove

get closestNoteAbove(): NoteObject

Returns

NoteObject

Defined in

src/index.ts:628


closestNoteBelow

get closestNoteBelow(): NoteObject

Returns

NoteObject

Defined in

src/index.ts:623


midi

get midi(): number

Returns

number

Defined in

src/index.ts:616


noteObject

get noteObject(): NoteObject

Returns

NoteObject

Defined in

src/index.ts:620


ratio

get ratio(): number

Returns

number

Defined in

src/index.ts:613


semitones

get semitones(): number

Returns

number

Defined in

src/index.ts:607

Methods

addCents

addCents(cents): Pitch

Parameters

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

Returns

Pitch

Defined in

src/index.ts:650


addSemitones

addSemitones(semitones): Pitch

Parameters

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

Returns

Pitch

Defined in

src/index.ts:639


modRatio

modRatio(ratio): Pitch

Parameters

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

Returns

Pitch

Defined in

src/index.ts:656


quantize

quantize(roundingMethod?): Pitch

Parameters

| Name | Type | Default value | | :------ | :------ | :------ | | roundingMethod | RoundingMethod | "nearest" |

Returns

Pitch

Defined in

src/index.ts:634


shift

shift(hz): Pitch

Parameters

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

Returns

Pitch

Defined in

src/index.ts:645


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