.chords

.chords is a plain-text file format for writing down the harmony of a piece of music — its chord progression, apart from any melody. A file is a handful of header lines giving the meter, the key, and how long a plain chord symbol lasts, followed by the chords themselves in bars separated by |, much as you would sketch a progression on paper:

M: 4/4
L: 1/1
K: C
C | Am | F | G7 |]

Because it is ordinary ASCII text, a progression can be typed in any editor, pasted into an email, and tracked in version control — while still being precise enough for software to parse, transpose to another key, analyze in Roman numerals, and compare against another progression. The chord-quality vocabulary is fixed and closed: every suffix a file may use is enumerated below, and anything outside that list is a parse error rather than a guess, so two programs reading the same file always agree on what Cm7b5 means.

It is similar in spirit to ABC notation — a convenient, human-readable, standardized way of notating musical material in digital form — and borrows ABC's conventions wherever they fit, including the M:/L:/K: header style, key syntax, and quoted annotations. Where ABC notates tunes, .chords notates changes. chords-js is the reference implementation.

This page is the canonical public reference for the format — the language itself, not any one implementation's API. For the library that reads and renders it, see the chords-js docs.

Tutorial

A `.chords` file builds up from four required lines and a row of bars. Five steps, each adding one idea.

1. The minimum file

Every file starts with a version line, then three required headers, then the body.

%chords-1.0
M: 4/4
L: 1/1
K: C
C | F | G | C |]

%chords-1.0 must be the first line, verbatim. M: is the meter, K: is the key the chords below are written in, and L: is the default chord duration — L: 1/1 means "a bare chord fills one whole bar," so this progression is four bars, one chord each: C, F, G, C. |] marks the final barline. Paste it into the live demo to see it rendered.

2. Chord qualities

A chord symbol is a root letter plus an optional quality suffix. An empty suffix means a major triad.

Am | Dm7 | G7 | Cmaj7 |]

Am is A minor, Dm7 is D minor seventh, G7 is a dominant seventh, Cmaj7 is a major seventh. The full quality vocabulary — every suffix the parser accepts — is below.

3. More than one chord per bar

Space-separated chords share a bar, and their durations must sum to exactly one measure.

L: 1/2
Am D7 | G7 Cmaj7 |]

With L: 1/2, a bare chord is now half a bar, so two bare chords fill one measure. A waltz with three chords per bar would use L: 1/3 or write explicit fractions like C/3 F/3 G/3 against L: 1/1 — see Durations.

4. Repeats and endings

|: and :| mark a repeated section, and |1 / |2 mark a first/second ending.

|: Am | Dm7 |1 G7 :| |2 Cmaj7 |]

This plays Am, Dm7, G7, back to Am, Dm7, then Cmaj7 instead of G7 the second time through — the common lead-sheet shape for a form with a different ending on the last pass.

5. Annotations and sections

Quoted text is a pass-through note, not a chord, and P: lines mark named sections.

P: A
"Intro" Am | Dm7 | G7 | Cmaj7 |
P: B
F | G | Am | Am |]

That's the whole grammar. Everything past this point is reference material: the full header table, the body syntax precisely, the complete chord-quality vocabulary, and the Roman-numeral input vocabulary.

File anatomy

%chords-1.0
T: Autumn Leaves
C: Joseph Kosma
M: 4/4
L: 1/1
K: Em
Am7 | D7 | Gmaj7 | Cmaj7 |
F#m7b5 | B7 | Em | Em |]

Line 1 is the version line. Header fields follow, one per line, in any order — the header ends at the first line that begins with a chord token or a barline. The remaining lines are the body: bars of chords separated by |. Blank lines and % comment lines are allowed anywhere and ignored.

Header fields

Any other ABC v2.1 information-field letter (A B D F G H I N O S U V W Z, …) is also accepted, stored, and passed through — this is how provenance fields like O: (origin) or S: (source) travel with a file. A header letter that matches nothing is a warning, not a hard error.

The body

body := bar ( barline bar )* final-barline?
bar  := chord ( SP chord )*

Bars are separated by |; chords within a bar are space-separated. The body may span multiple physical lines — line breaks between bars are purely cosmetic.

Barlines and repeats

A :| with no matching |: loops back to the start of the body — the common lead-sheet case (e.g. a jazz standard with a repeat sign and no explicit opening one). D.C./D.S. as structural jumps are not supported — write those forms out in full; the marking itself can still travel as a quoted annotation (below).

No-chord

N.C. is a no-chord/silence token — use it where the harmony genuinely drops out, not for a held chord (a hold is just a longer duration).

Annotations

Text in double quotes is a pass-through note, borrowed directly from ABC — it has no duration, isn't validated as a chord, and attaches to the bar it precedes.

"Intro" C | F | G | A7 "D.S. al Fine" |]

Part markers

A line of the form P: <name> marks a section — ABC's P: field, used inline in the body rather than as a header.

P: A
Gm7 C7 | Gm7 C7 :|
P: B
F7 | Bb6 | G7 | C7 |]

Chord symbols

chord      := root accidental? quality? ( "/" bass )? duration?
root       := "A" | "B" | "C" | "D" | "E" | "F" | "G"
accidental := "#" | "b"
bass       := root accidental?

The root is always an uppercase letter, optionally followed by # or b. The quality is any canonical suffix or alias from the vocabulary below — an empty quality means a major triad. Slash bass is / followed by a note letter: G/B, Cmaj7/E.

Examples: A, Em, Gmaj7, D7, C#m7b5, Bb, F/A, Gsus4, Am7/D.

Durations

Durations are measure-relative, not whole-note-relative like ABC's L:. With the common L: 1/1, a bare chord fills one whole bar in any meter; C/2 is half a bar, C/3 a third of a bar.

/ is overloaded between slash-bass and fractional duration, disambiguated by what follows it: a note letter (A–G) means bass, a digit means duration. Both together, in order: Cmaj7/E2 is Cmaj7 over E for 2 units; Cmaj7/E/2 is Cmaj7 over E for half a unit. A bar's chords must always sum to exactly one measure.

Chord quality vocabulary

Every quality suffix must resolve to one of these 34 canonical types (directly or via a listed alias) — an unrecognized suffix is a hard parse error, not a graceful degrade. This is the one place .chords deliberately diverges from ABC, which leaves chord quality implementation-defined.

Roman numerals

Roman-numeral chords are canonical input vocabulary, first-class beside absolute symbols — not just a display mode. parseRomanBody takes no key; Roman is key-independent by design.

romanToken   := accidental* numeral suffix? bassPart? durationTail?
accidental   := 'b' | '#'
numeral      := 'I'..'VII'   (major family)
              | 'i'..'vii'   (minor family)
suffix       := any alias or display spelling of a chord type
bassPart     := '/' accidental* numeral
durationTail := the ordinary duration syntax ('/2', '4', '3/2')

Case carries the triad quality — uppercase is major-family, lowercase is minor-family:

Case and suffix must agree — Im7 is rejected (the numeral says major, the quality says minor), with a suggested correction (i7). A suspended chord has no third, so its case carries no information: both Isus4 and isus4 are accepted.

Two things that look like exceptions but aren't, because they can't be detected as errors:

• /X after a numeral is a slash bass, not a secondary dominant. V/V means "V with scale-degree 5 in the bass," not "the dominant of the dominant." Secondary-dominant notation doesn't exist in this vocabulary yet.
• An arabic suffix is a chord type, not figured bass. IV6 is a major sixth chord, exactly as C6 is. Inversions are written as slash bass: I/III, IV/VI, V7/II.

Try any of the examples on this page in the chords-js live demo.