# @tonaljs/pitch-distance

> Parse intervals in shorthand notation

Latest version **5.0.5** (published 2025-01-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install @tonaljs/pitch-distance
pnpm add @tonaljs/pitch-distance
yarn add @tonaljs/pitch-distance
bun add @tonaljs/pitch-distance
```

## 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 | 5.0.5 |
| Published | 2025-01-03 |
| First published | 2023-11-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 19.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | danigb@gmail.com |
| Maintainers | danigb |
| Keywords | note, music, theory, interval, shorthand notation |

## Links

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

## Dependencies (3)

- [@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-interval](https://npm.io/package/@tonaljs/pitch-interval.md) 6.1.0

## Recent versions

- 5.0.5 (latest) — 2025-01-03
- 5.0.4 — 2024-07-23
- 5.0.3 — 2024-02-03
- 5.0.2 — 2024-02-03
- 5.0.1 — 2024-01-04
- 5.0.0 — 2023-11-29

## README

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

> Pitch distance and transposition

## Usage

⚠️ It's probably you don't need to use this package directly. Use [tonal-note](/packages/note).

```js
import { transpose, distance } from "@tonaljs/pitch-distance";
transpose("C4", "5P"); // => "G4"
distance("C4", "G4"); // => "5P"
```

## API

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

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

Examples:

```js
transpose("d3", "3M"); // => "F#3"
transpose("D", "3M"); // => "F#"
["C", "D", "E", "F", "G"].map((pc) => transpose(pc, "M3"));
// => ["E", "F#", "G#", "A", "B"]
```

This function always returns a string:

```js
transpose("one", "two"); // => ""
```

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

Find the distance between two notes. It returns the interval name, or "" if not valid parameters.

Examples:

```js
distance("C3", "E4"); // => "10M"
```

If one of the note is a pitch class, the interval will be simple:

```js
distance("C", "E"); // => "3M"
distance("C", "E4"); // => "3M"
distance("C4", "E"); // => "3M"
```

This function always returns a string:

```js
distance("today", "tomorrow"); // => ""
```

## Want more?

Take a look to [@tonaljs/note](/packages/note) or [@tonaljs/interval](/packages/interval) modules.

## FAQ

#### How do I get the note frequency and midi number?

```js
note("C4").octave; // => 4
note("C4").midi; // => 60
```

#### How do I know if a note name is valid?

```js
note("C4").empty; // => false
note("x").empty; // => true
note("x").name; // => ""
note("x").octave; // => undefined
// remove all invalid note names
[...].map(note).filter(n => !n.empty).map(n => n.name)
```

#### How do I know if two notes are enharmonics?

You can test the midi numbers:

```js
note("Cb4").midi === note("B3").midi;
```

Or better yet, use the `height` property that is also present on pitch classes (in notes without octaves midi property is `null`):

```js
note("Cb").height === note("B").height;
```

### How do I change the octave of a note?

```js
note("Cb4").pc + 5; // => "Cb5"
```

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