degree-chords

Transpose Arabic chord-degree notation (Nashville-style) into letter chords for any key. Zero runtime dependencies.

Install

npm install degree-chords

Quick start

import { transpose } from "degree-chords";

const song = `1   2
Amazing grace how sweet the sound`;

console.log(transpose(song, { key: "C Major" }));
// C   Dm
// Amazing grace how sweet the sound

Reverse transpose letter chords back into numbers:

import { reverseTranspose } from "degree-chords";

const chart = `C   Dm
Amazing grace how sweet the sound`;

console.log(reverseTranspose(chart, { key: "C Major" }));
// 1   2
// Amazing grace how sweet the sound

API

transpose(song, options)

Transposes chord-degree lines in a song while leaving lyric lines unchanged.

transpose(song: string, options: TransposeOptions): string

reverseTranspose(song, options)

Converts letter-chord lines back into chord-degree notation for a given key.

reverseTranspose(song: string, options: TransposeOptions): string

transposeLine(line, options) / reverseTransposeLine(line, options)

Transpose a single line if it looks like a chord line (numbers or letters, respectively).

Lower-level helpers

• parseKey(input, options?) — parse "C Major", "Am", "F# minor"
• parseChordNumber(token) — parse "4maj7", "b7", "1/3"
• parseLetterChord(token) — parse "Fmaj7", "Dm", "C/E"
• chordForDegree(parsed, key) — build a chord symbol from a parsed degree
• chordToDegree(chord, key) — convert a chord symbol back to a degree token
• noteToDegree(note, key) — map a note name to a scale degree
• isChordLine(line) / isLetterChordLine(line) — detect chord vs lyric lines

Options

type TransposeOptions = {
  key: string;           // "C", "C Major", "Am", "F# minor"
  minorScale?: "natural" | "harmonic" | "melodic"; // default: "natural"
  preferFlats?: boolean; // enharmonic spelling for scale notes
  capo?: number;         // 0–11, shapes transposed down for guitar capo
};

With capo on fret 3 in C major, 1 2 becomes A Bm (shapes you finger while the song sounds in C).

Supported notation

| Input | In C Major | |-------|------------| | 1 | C | | 2, 2-, 2m | Dm | | 4maj7 | Fmaj7 | | 57, 5dom7 | G7 | | 5sus4 | Gsus4 | | 1add9 | Cadd9 | | 1/3 | C/E | | b7 | Bb | | #4 | F# | | b3m | Ebm |

Song format

Lines are transposed when every token is a chord number or a section marker like [Verse]. Lines with lowercase lyric words are left unchanged.

[Verse]
1      4      5      1
Amazing grace how sweet the sound

Diatonic defaults

Major keys: 1 maj, 2 min, 3 min, 4 maj, 5 maj, 6 min, 7 dim

Minor keys (natural): 1 min, 2 dim, 3 maj, 4 min, 5 min, 6 maj, 7 maj

Quality suffixes override these defaults (2maj, 57, 4sus4, etc.).

Limitations

• Arabic numbers only (no Roman numerals)
• Chord lines are detected heuristically; inline chords within lyrics are not supported
• Melodic minor uses the ascending form for scale degrees
• Transposed chord symbols may be longer than the original numbers, which can shift column alignment
• Reverse transpose normalizes redundant quality suffixes (e.g. 6m becomes 6 when minor is the default)

License

MIT

Demo

A local demo site lives in demo/ and is not published to npm (only dist/ is included in the package).

npm run demo:dev

Then open the URL shown in the terminal (usually http://localhost:5173).

Contributing

See CONTRIBUTING.md for setup, development workflow, and release instructions.