# @tonaljs/voice-leading

> Voice leading logic for transitions between voicings

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

## Install

```sh
npm install @tonaljs/voice-leading
pnpm add @tonaljs/voice-leading
yarn add @tonaljs/voice-leading
bun add @tonaljs/voice-leading
```

## 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.1.2 |
| Published | 2025-06-04 |
| First published | 2023-11-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 8.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | felix91@gmail.com |
| Maintainers | danigb |
| Keywords | chord, voicing, voicings, music, theory, @tonaljs |

## Links

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

## Dependencies (1)

- [@tonaljs/note](https://npm.io/package/@tonaljs/note.md) 4.12.1

## Recent versions

- 5.1.2 (latest) — 2025-06-04
- 5.1.1 — 2025-01-03
- 5.1.0 — 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-28

## README

# @tonaljs/voice-leading

Contains a collection of functions to find optimal transitions between chord voicings. Used by [@tonaljs/voicing](../voicing).

## Usage

ES6:

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

Nodejs:

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

## API

### VoiceLeading

```ts
declare type VoiceLeadingFunction = (
  voicings: string[][],
  lastVoicing: string[]
) => string[];
```

A function that decides which of a set of voicings is picked as a follow up to lastVoicing.

Example:

```ts
const topNoteDiff: VoiceLeadingFunction = (voicings, lastVoicing) => {
  if (!lastVoicing || !lastVoicing.length) {
    // if no lastVoicing is given
    return voicings[0];
  }
  const topNoteMidi = (voicing: string[]) =>
    Note.midi(voicing[voicing.length - 1]) || 0;
  const diff = (voicing: string[]) =>
    Math.abs(topNoteMidi(lastVoicing) - topNoteMidi(voicing));
  return voicings.sort((a, b) => diff(a) - diff(b))[0]; // return voicing with least diff
};
```

Usage

```ts
topNoteDiff(
  [
    ["F3", "A3", "C4", "E4"], // top note = E4
    ["C4", "E4", "F4", "A4"], // top note = A4
  ],
  ["C4", "E4", "G4", "B4"] // top note = B4
);
// ['C4', 'E4', 'F4', 'A4'] // => A4 is closer to B4 than E4
```

[show available voice leading functions](./index.ts).

See [@tonaljs/voicing](../voicing) for usage examples.

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