chord-finder 🎵

A lightweight, zero-dependency, high-performance TypeScript library designed to deduce the name of a chord from a set of at least 2 notes. It ranks and returns the most likely chord matches (e.g., C major, C minor) based on pitch-class interval matching and a specialized scoring algorithm.

Features

• Zero Runtime Dependencies: Keep your project lean and fast.
• Robust Note Parsing: Handles standard notes (e.g., "C4", "Eb5"), double accidentals ("Cx", "Dbb"), and Unicode symbols ("♯", "♭").
• Flexible Note Formats: Supports both string inputs (e.g., "C5", "Eb5") and object inputs (e.g., { note: "C", octave: 5 }).
• Slash Chords & Inversions: Accurately detects when the lowest-sounding note is not the root and outputs standard slash chord notation (e.g., Cm/G instead of standard root position).
• Smart Spelling Resolution: Prefers flat-leaning defaults if any flat accidentals are present in the input notes, and sharp-leaning defaults otherwise.
• Complex Chord Support: Pre-configured with a comprehensive dictionary of chord types (dominants, suspended, minor-major, add9/add11/add13, diminished, half-diminished, augmented, power chords, and partial triads).
• Advanced Scoring Algorithm: Matches notes using subset math and ranks them by confidence, accounting for missing notes (e.g., omitted fifths) and inversions.

Installation

Install the library using npm:

npm install chord-finder

Quick Start

import { detectChords } from "chord-finder";

// 1. Basic Triad
const chords = detectChords(["C", "Eb", "G"]);
console.log(chords[0].name); // "Cm"

// 2. Inversion (with octaves)
// G4 is the lowest note, so it's treated as the bass note.
const inverted = detectChords(["C5", "Eb5", "G4"]);
console.log(inverted[0].name); // "Cm/G"
console.log(inverted[0].notes); // ["G", "C", "Eb"] (ordered starting from bass note)

// 3. Power chord (2 notes)
const power = detectChords(["C", "G"]);
console.log(power[0].name); // "C5"

// 4. Ambiguity / Multiple candidates (e.g. C and E)
const ambiguous = detectChords(["C", "E"]);
console.log(ambiguous.map(c => c.name)); 
// ["C", "C7", "C6", "Cmaj7", "Cadd9", "Am/C", ...]

API Reference

detectChords(notes: NoteInput[], options?: DetectOptions): ChordResult[]

Deduces a list of candidate chords containing the given notes.

Parameters

• notes: An array of NoteInput (can be string or NoteObject).
• options: Optional configuration:
  • scoreThreshold (default: 4.0): Matches scoring below this threshold are discarded.
  • limit (default: 10): Maximum number of results to return.

Input Types

type NoteInput = string | NoteObject;

interface NoteObject {
  note: string;    // e.g. "C#"
  octave?: number; // e.g. 4
}

Returns

An array of ChordResult objects:

interface ChordResult {
  name: string;        // e.g. "Cm/G" or "Cmaj7"
  fullName: string;    // e.g. "C minor / G" or "C major 7th"
  root: string;        // e.g. "C"
  bass: string;        // e.g. "G"
  suffix: string;      // e.g. "m", "maj7"
  quality: string;     // e.g. "minor", "major", "diminished", "suspended"
  notes: string[];     // Pitch spellings ordered from bass up, e.g. ["G", "C", "Eb"]
  score: number;       // Confidence score
}

parseNote(noteInput: NoteInput): ParsedNote

Helper function to parse a note representation into its structured components.

Complex & Historical Chord Examples

The library is audited to properly identify complex and ambiguous harmonic structures:

1. The Tristan Chord (F, B, D#, G#)

Wagner's famous unresolved chord. The library detects:

• Fm7b5 (F half-diminished 7th spelled enharmonically in root position) — ranked 1st.
• G#m6/F (G# minor 6th with F in the bass, representing the inverted interpretation) — ranked 2nd.

2. Alexander Scriabin's Mystic Chord (C, F#, Bb, E, A, D)

The famous whole-tone/acoustic scale synthetic quality. The library detects:

• C13#11 (C dominant 13th sharp 11th with a missing fifth) — ranked 1st.

3. The Jimi Hendrix Chord (E7#9 on E, G#, B, D, G)

The classic blues/rock chord clashing major and minor thirds:

• E7#9 (E dominant 7th sharp 9th) — ranked 1st.

4. Bill Evans "So-What" Voicing (E, A, D, G, B)

The famous quartal jazz voicing:

• Em11 (E minor 11th in root position) and G6/9/E (G6/9 with E in the bass) are both suggested, capturing the inherent ambiguity.

5. Steely Dan "Mu Chord" (C, D, E, G)

The major add2/add9 chord in close voicing:

• Cadd9 — ranked 1st.

Development

Scripts defined in the package for testing and building:

# Run the test suite (Node.js native runner, zero external test dependencies!)
npm run test

# Compile the TypeScript library (outputs ESM files to dist/)
npm run build

License

This project is licensed under the MIT License. See the LICENSE file for details.