Key Detection
Infer the tonic key from a chord sequence.
Functions
detectKey
detectKey(chords: Chord[], declaredKey?: string | null, config?: DetectKeyConfig): string | nullInfer the tonic key from a chord sequence. Returns a key string (e.g. `'Am'`, `'G mixolydian'`) or `null` if no key scores above the minimum confidence threshold. If `declaredKey` is provided and scores above zero, it is returned unchanged unless it has zero diatonic overlap with the chords.
rankKeys
rankKeys(chords: Chord[], limit: number): RankedKey[]Rank the most plausible keys for a chord sequence, best first. The winner (with its tiebreak resolution) is forced to the front; remaining slots are filled by descending score. Returns `[]` when no key scores above zero. Intended for `key:` autocomplete — the `ratio` gives a cheap "fit" indicator.
scoreAllKeys
scoreAllKeys(chords: Chord[]): Map<string, number>Returns a score for every known key against the given chord sequence.
Types
DetectKeyConfig
interface
Options for `detectKey`.
forceKey?: string- Skip scoring entirely and return this key string.
fSharpOrGFlat?: "f-sharp" | "g-flat"- Resolve the ambiguous F♯/G♭ enharmonic key to one spelling. Defaults to `'f-sharp'`.
RankedKey
interface
A ranked key candidate produced by .
key: string- Canonical key string, e.g. `'Eb major'`, `'C minor'`, `'D dorian'`.
ratio: number- `score / bestScore` — `1` for the top candidate, lower for the rest.
score: number- Raw diatonic + quality score from .