# @tonaljs/scale

> Musical scales and its relations

Latest version **4.13.4** (published 2026-01-18) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.13.4 |
| Published | 2026-01-18 |
| First published | 2019-06-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 7 |
| Unpacked size | 51.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | danigb@gmail.com |
| Maintainers | danigb |
| Keywords | scale, scales, music, theory, @tonaljs |

## Links

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

## Dependencies (7)

- [@tonaljs/note](https://npm.io/package/@tonaljs/note.md) 4.12.1
- [@tonaljs/pcset](https://npm.io/package/@tonaljs/pcset.md) 4.10.1
- [@tonaljs/chord-type](https://npm.io/package/@tonaljs/chord-type.md) 5.1.1
- [@tonaljs/collection](https://npm.io/package/@tonaljs/collection.md) 4.9.0
- [@tonaljs/pitch-note](https://npm.io/package/@tonaljs/pitch-note.md) 6.1.0
- [@tonaljs/scale-type](https://npm.io/package/@tonaljs/scale-type.md) 4.9.2
- [@tonaljs/pitch-distance](https://npm.io/package/@tonaljs/pitch-distance.md) 5.0.5

## Recent versions

- 4.13.4 (latest) — 2026-01-18
- 4.13.3 — 2025-06-04
- 4.13.2 — 2025-03-09
- 4.13.1 — 2025-01-03
- 4.13.0 — 2024-07-23
- 4.12.6 — 2024-04-14
- 4.12.5 — 2024-02-03
- 4.12.4 — 2024-02-03
- 4.12.3 — 2024-01-04
- 4.12.2 — 2023-06-13
- 4.12.1 — 2023-06-13
- 4.12.0 — 2023-01-20
- 4.11.0 — 2023-01-19
- 4.10.0 — 2023-01-12
- 4.9.0 — 2023-01-12
- … 39 more at https://npm.io/package/@tonaljs/scale/versions

## README

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

[![tonal](https://img.shields.io/badge/@tonaljs-scale-yellow.svg?style=flat-square)](https://www.npmjs.com/browse/keyword/tonal)

`@tonaljs/scale` is a collection of functions to create and manipulate musical scales

## Usage

ES6:

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

nodejs:

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

Single module:

```js
import Scale from "@tonaljs/scale";
```

## API

### `Scale.names()`

List all known scale names. Same as `ScaleType.names()`

See [scale-type](/package/scale-type)

### `Scale.get(name: string) => Scale`

Get a scale from a scale name. `Scale.get` accepts tonics in the scale name and returns a [scale type](/packages/scale-type) with two more properties: `tonic` and `notes`:

```js
Scale.get("c5 pentatonic");
// =>
// {
//   empty: false,
//   name: "C5 pentatonic",
//   type: "major pentatonic",
//   tonic: "C5",
//   notes: ["C5", "D5", "E5", "G5", "A5"],
//   intervals: ["1P", "2M", "3M", "5P", "6M"],
//   aliases: ["pentatonic"],
//   setNum: 2708,
//   chroma: "101010010100",
//   normalized: "101010010100"
// }
```

### `Scale.detect(notes: string[], options: { tonic?: string, match?: "fit" | "exact" }) => string[]`

Find all scales that first a collection of notes with a given tonic:

```js
Scale.detect(["C", "D", "E", "F", "G", "A", "B"]);
// => ["C major", "C bebop", "C bebop major",
//     "C ichikosucho",  "C chromatic"];
```

You can pass an optional tonic (otherwise first note will be used):

```js
Scale.detect(["C", "D", "E", "F", "G", "A", "B"], { tonic: "A" });
// => [ 'A aeolian', 'A minor bebop', 'A chromatic' ]
```

You can ask just the exact match:

```js
Scale.detect(["D", "E", "F#", "A", "B"], { match: "exact" });
// => ["D major pentatonic"]
Scale.detect(["D", "E", "F#", "A", "B"], { match: "exact", tonic: "B" });
// => ["B major pentatonic"]
```

### `Scale.scaleChords(scale: string) => string[]`

Get all chords that fits a given scale:

```js
Scale.scaleChords("pentatonic");
// => ["5", "64", "M", "M6", "Madd9", "Msus2"]
````

### `Scale.extended(scale: string) => string[]`

Get all scales names that has the same notes and at least one more:

```js
Scale.extended("major");
// => ["bebop", "bebop dominant", "bebop major", "chromatic", "ichikosucho"]
```

### `Scale.reduced(scale: string) => string[]`

Find all scales names that are a subset of the given one (less notes but all from the given scale)

```js
Scale.reduced("major");
// => ["ionian pentatonic", "major pentatonic", "ritusen"]
```

### `Scale.scaleNotes(notes: string[]) => string[]`

Given an array of notes, return an array of sorted note names starting from the first note name of the input array.

```js
// Always start with the first note of the input array
Scale.scaleNotes(["D4", "c#5", "A5", "F#6"]); // => ["D", "F#", "A", "C#"]
// Remove duplicates
Scale.scaleNotes(["C4", "c3", "C5", "C4", "c4"]); // => ["C"]
```

### `Scale.modes(name: string) => string[][]`

Find mode names (if any) of a given scale:

```js
Scale.modeNames("C pentatonic"); // => [
//    ["C", "major pentatonic"],
//    ["D", "egyptian"],
//    ["E", "malkos raga"],
//    ["G", "ritusen"],
//    ["A", "minor pentatonic"]
//  ]
```

### `Scale.degrees(scaleName: string) => (degree: number) => string`

`Scale.degrees` returns a function to get a note name from a scale degree:

```js
const c4major = Scale.degrees("C4 major");
c4major(1); // => "C4"
c4major(2); // => "D4"
c4major(8); // => "C5"
c4major(-1); // => "B3"
c4major(-3); // => "A3"
c4major(-7); // => "C2"
```

Bear in mind that degree numbers starts with 1 and 0 returns an empty string:

```js
c4major(0); // => ""
```

Because it returns a function, it's handy to be used with `map` (and similar functions):

```js
[1, 2, 3].map(Scale.degrees("C major")) => ["C", "D", "E"]
[1, 2, 3].map(Scale.degrees("C4 major")) => ["C4", "D4", "E4"]
[-1, -2, -3].map(Scale.degrees("C major")) => ["B", "A", "G"]
```

Notice that it uses octaves if the scale tonic has an octave or pitch classes (_octaveless_ notes) otherwise.

See [`Chord.degrees`](https://github.com/tonaljs/tonal/tree/main/packages/chord#chorddegreeschordname-string--degree-number--string)

See https://en.wikipedia.org/wiki/Degree_(music)

### `Scale.steps(scaleName: string) => (degree: number) => string`

Same as `Scale.degree` but 0 is tonic. It plays better with ranges:

```js
import { Range, Scale } from "tonal";

Range.numeric([-3, 3]).map(Scale.steps("C4 major"));
// => ["G3", "A3", "B3", "C4", "D4", "E4", "F4"]
```

### `Scale.rangeOf(scaleName: string) => (from: string, to: string) => string[]`

`Scale.rangeOf` returns a function to create scale ranges:

```js
const range = Scale.rangeOf("C pentatonic");
range("C4", "C5"); // => ["C4", "D4", "E4", "G4", "A4", "C5"]
```

Please note that the scale name _must_ have tonic:

```js
const range = Scale.rangeOf("pentatonic");
range("C4", "C5"); // => []
```

This function also works with a collection of notes:

```js
const range = Scale.rangeOf("C", "Db", "G");
range("C4", "C5"); // => ["C4", "Db4", "G4", "C5"]
```

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