# @tonaljs/note

> Parse and manipulate music notes in scientific notation

Latest version **4.12.1** (published 2025-06-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @tonaljs/note
pnpm add @tonaljs/note
yarn add @tonaljs/note
bun add @tonaljs/note
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.12.1 |
| Published | 2025-06-04 |
| First published | 2019-06-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 50.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | danigb@gmail.com |
| Maintainers | danigb |
| Keywords | note, music, theory, music-theory |

## Links

- npm: https://www.npmjs.com/package/@tonaljs/note
- npm.io page: https://npm.io/package/@tonaljs/note

## Dependencies (5)

- [@tonaljs/midi](https://npm.io/package/@tonaljs/midi.md) 4.10.2
- [@tonaljs/pitch](https://npm.io/package/@tonaljs/pitch.md) 5.0.2
- [@tonaljs/pitch-note](https://npm.io/package/@tonaljs/pitch-note.md) 6.1.0
- [@tonaljs/pitch-distance](https://npm.io/package/@tonaljs/pitch-distance.md) 5.0.5
- [@tonaljs/pitch-interval](https://npm.io/package/@tonaljs/pitch-interval.md) 6.1.0

## Recent versions

- 4.12.1 (latest) — 2025-06-04
- 4.12.0 — 2025-01-03
- 4.11.0 — 2024-07-23
- 4.10.3 — 2024-02-03
- 4.10.2 — 2024-02-03
- 4.10.1 — 2024-01-04
- 4.10.0 — 2023-01-12
- 4.9.0 — 2023-01-12
- 4.8.0 — 2022-11-29
- 4.7.3 — 2022-11-29
- 4.7.2 — 2022-11-29
- 4.7.1 — 2022-11-29
- 4.7.0 — 2022-11-28
- 4.6.10 — 2022-11-18
- 4.6.5 — 2021-09-05
- … 20 more at https://npm.io/package/@tonaljs/note/versions

## README

# @tonaljs/note ![tonal](https://img.shields.io/badge/@tonaljs-note-yellow.svg?style=flat-square) [![npm version](https://img.shields.io/npm/v/@tonaljs/note.svg?style=flat-square)](https://www.npmjs.com/package/@tonaljs/note)

> A collection of functions to manipulate musical notes

## Usage

ES6:

```js
import { Note } from "tonal";
```

nodejs:

```js
const { Note } = require("tonal");
```

single module:

```js
import { get } from "@tonaljs/note";
```

## API

### Note properties

#### `Note.get(noteName: string) => Note`

Given a note name, it returns an object with the following properties:

- name: the note name
- pc: the pitch class name
- letter: the note letter
- step: the letter number (0..6)
- acc: the note accidentals
- alt: the accidental number (..., -1 = 'b', 0 = '', 1 = '#', ...)
- oct: the octave (or null if not present)
- chroma: the note chroma (0..11)
- midi: the note midi or null if octave is not present
- freq: the note frequency in Hertzes, or null if the octave is not present

```js
Note.get("C4"); // => { name: "C4", midi: 60, ... }
```

It has several shorthands to retrieve properties easily:

```js
Note.name("fx4"); // => "F##4"
Note.pitchClass("Ab5"); // => "Ab"
Note.accidentals("Eb"); // => 'b'
Note.octave("C4"); // => 4
Note.midi("A4"); // => 69
Note.freq("A4"); // => 440
Note.chroma("D"); // => 2

["C", "D", "E"].map(Note.chroma); // => [0, 2, 4]
```

#### `Note.fromMidi(midi: number) => string`

Given a midi number, returns the note name. This function is the same as `midiToNoteName` from [@tonaljs/midi](/packages/midi)

```js
Note.fromMidi(61); // => "Db4"
Note.fromMidi(61.7); // => "D4"
[60, 61, 62].map(Note.fromMidi); // => ["C4", "Db4", "D4"]
```

There's also a `Note.fromMidiSharps` version:

```js
Note.fromMidiSharps(61); // => "C#4"
```

#### `Note.fromFreq(freq: number) => string`

Given a frequency in Hz, returns the note name.

```js
Note.fromFreq(440); // => "A4"
```

It rounds to the nearest name:

```js
[440, 550, 660].map(t.Note.fromFreq); // => [ 'A4', 'Db5', 'E5' ]
```

There's also a `Note.fromFreqSharps` version:

```js
[440, 550, 660].map(t.Note.fromFreqSharps); // => [ 'A4', 'C#5', 'E5' ]
```

### Transposition and distances

#### `transpose(note: string, interval: string) => string`

Transpose a note by an interval. It returns the note name or "" if not valid parameters.

Examples:

```js
Note.transpose("d3", "3M"); // => "F#3"
Note.transpose("D", "3M"); // => "F#"
```

`transposeBy` and `transposeFrom` are curried versions of this function to make easy work with arrays:

```js
["C", "D", "E"].map(Note.transposeBy("5P"));
// => ["G", "A", "B"]
```

```js
["1P", "3M", "5P"].map(Note.transposeFrom("C"));
// => ["C", "E", "G"]
```

#### `transposeFifths(noteName: string, fifths: number) => string`

Transpose a note a given number of fifths:

```js
Note.transposeFifths("G4", 3); // => "E6"
Note.transposeFifths("G", 3); // => "E"

[0, 1, 2, 3, 4, 5, 6].map((n) => transposeFifths("F#", n));
// => ["F#", "C#", "G#", "D#", "A#", "E#", "B#"]
[0, -1, -2, -3, -4, -5, -6].map((n) => transposeFifths("Bb", n));
// => ["Bb", "Eb", "Ab", "Db", "Gb", "Cb", "Fb"]
```

#### `Note.distance(from: string, to: string) => string`

Find the interval between two notes:

```js
Note.distance("C", "D").toEqual("2M");
Note.distance("C3", "E3").toEqual("3M");
Note.distance("C3", "E4").toEqual("10M");
```

### Named collections

#### `names(array?: any[]) => string[]`

Get note names of an array of anything. Notice that names are normalized:

```js
Note.names(["fx", "bb", 12, "nothing", {}, null]); // => ["F##", "Bb"];
```

Without parameters, it returns a list of natural pitch classes:

```js
Note.names(); // => ["C", "D", "E", "F", "G", "A", "B"]
```

You may be in a situation where you have note names with octaves, but don't want them, remove them like this:

```js
Note.names(["C2", "C#3", "Db4", 12, "nothing", {}, null]).map(Note.pitchClass); // => ['C', 'C#', 'Db']
```

#### `sortedNames(array?: any[], comparator?: NoteComparator) => string[]`

Sort an array of note names in ascending order. Pitch classes are listed before notes. Anything that is not a note is removed:

```js
Note.sortedNames(["c2", "c5", "c1", "c0", "c6", "c"]);
// => ['C', 'C0', 'C1', 'C2', 'C5', 'C6']
Note.sortedNames(["c", "F", "G", "a", "b", "h", "J"]);
// => ['C', 'F', 'G', 'A', 'B']
```

An optional comparator can be passed as a second argument:

```js
Note.sortedNames(["c2", "c5", "c1", "c0", "c6", "c"], Note.descending);
// => ['C6', 'C5', 'C2', 'C3', 'C1', 'C0']
```

#### `sortedUniqNames(array?: any[]) => string[]`

Sort notes ascending and remove duplicates.

### Enharmonics

#### `simplify(noteName: string) => string`

Given a note name, return the same note with less accidentals (or "" if not a valid note):

```js
Note.simplify("C#"); // => "C#"
Note.simplify("C##"); // => "D"
Note.simplify("C###"); // => "D#"
```

#### `enharmonic(noteName: string, pitchClass?: string) => string`

Given a note name, returns its enharmonic (or "" if not valid note):

```js
Note.enharmonic("C#"); // => "Db"
Note.enharmonic("C##"); // => "D"
Note.enharmonic("C###"); // => "Eb"

Note.enharmonic("C##b"); // => ""
```

Using enharmonic on a natural will return the same value passed in:

```js
Note.enharmonic("C"); // => "C"
Note.enharmonic("C4"); // => "C4"
```

The destination pitch class can be enforced to calculate the octave:

```js
Note.enharmonic("F2", "E#"); // => "E#2"
Note.enharmonic("B2", "Cb"); // => "Cb3"
Note.enharmonic("C2", "B#"); // => "B#1"
```

Enforced pitch class must have the same chroma as the note, otherwise "" is returned:

```js
Note.enharmonic("F2", "Eb"); // => ""
```

---
_Source: https://npm.io/package/@tonaljs/note · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._