ChordPro format reference for creating and editing song files (.pro, .cho, .chopro). Use when working with chord sheets, song arrangements, metadata directives, transposition, or any ChordPro syntax questions.
Official spec: https://www.chordpro.org/chordpro/
We use ChordPro-compatible syntax with extensions:
{meta: key value} pattern for all metadata (consistent, explicit){meta: x_*} for custom Bluegrass Songbook fields{start_of_abc}).pro, .cho, .crd, .chopro, .chord
# Comment (ignored by processors)
{directive: value} # Metadata or formatting control
Lyrics with [C]inline [G]chords
# Blank line (section separator)
[C] # Basic major chord
[Am] # Minor chord
[Am7] # With extension
[C/B] # With bass note (slash chord)
[F#m] # With accidental
[Bbmaj7] # Flat + extension
[*Coda] # Annotation (asterisk prefix = not a chord)
[*N.C.] # "No chord" annotation
Chord structure: Root + Qualifier + Extension + /Bass
| Component | Examples |
|---|---|
| Root | C, D, E, F, G, A, B (with # or b) |
| Qualifier | m (minor), dim, aug, sus |
| Extension | 7, maj7, m7, sus4, add9, 6, 9, 11, 13 |
| Bass | /E, /G, /B (any note after slash) |
Alternate notations (supported by reference implementation):
[1], [4], [5], [b7][I], [IV], [V], [bVII]Bluegrass Songbook uses {meta: key value} pattern for consistency:
{meta: title Song Title} # Required
{meta: artist Artist Name} # Performer (from "Recorded by")
{meta: composer Writer Name} # Songwriter (from "Written by")
{meta: lyricist Lyricist} # If different from composer
{meta: album Album Name}
{meta: year 2024}
{key: G} # Musical key (standalone ok)
{time: 4/4} # Time signature
{tempo: 120} # BPM
{capo: 2} # Capo position
Note: {meta: title ...} and {title: ...} are functionally equivalent per the ChordPro spec. We prefer {meta: ...} for consistency.
Bluegrass Songbook custom fields (using x_ prefix per ChordPro spec):
{meta: x_source classic-country}
{meta: x_source_file yourcheatingheart.html}
{meta: x_enriched 2025-12-26}
{meta: x_strum_pattern boom-chick}
{meta: x_difficulty intermediate}
Provenance metadata (added automatically by workflows):
# For new submissions (via GitHub issue):
{meta: x_source manual}
{meta: x_submitted_by github:username}
{meta: x_submitted 2025-12-26}
{meta: x_submission_issue 26}
# For corrections to existing songs:
{meta: x_corrected_by github:username}
{meta: x_corrected 2025-12-26}
{meta: x_correction_issue 24}
| Field | Purpose | Example |
|---|---|---|
x_source | Original data source | classic-country, manual |
x_source_file | Original filename | songname.html |
x_enriched | Date enrichment ran | 2025-12-26 |
x_submitted_by | GitHub user who submitted | github:username |
x_submitted | Date submitted | 2025-12-26 |
x_submission_issue | GitHub issue number | 26 |
x_corrected_by | GitHub user who corrected | github:username |
x_corrected | Date corrected | 2025-12-26 |
x_correction_issue | GitHub issue number | 24 |
Version metadata (for multiple versions of the same song):
{meta: x_version_label Alternate Arrangement}
{meta: x_version_type alternate} # alternate | cover | simplified | live
{meta: x_arrangement_by John Smith} # Who created this arrangement
{meta: x_version_notes Different key, simplified chord voicings}
{meta: x_canonical_id originalsongid} # Links to primary version (optional)
| Field | Purpose | Values |
|---|---|---|
x_version_label | Display name for this version | Any descriptive text |
x_version_type | Category of version | alternate, cover, simplified, live |
x_arrangement_by | Person who created this arrangement | Name |
x_version_notes | Free-form notes about differences | Any text |
x_canonical_id | Links to the original/primary version | Song ID (filename stem) |
| Long Form | Short | Purpose |
|---|---|---|
{start_of_verse} / {end_of_verse} | {sov} / {eov} | Verse block |
{start_of_chorus} / {end_of_chorus} | {soc} / {eoc} | Chorus block |
{start_of_bridge} / {end_of_bridge} | {sob} / {eob} | Bridge block |
{start_of_tab} / {end_of_tab} | {sot} / {eot} | Tablature |
{start_of_grid} / {end_of_grid} | {sog} / {eog} | Chord grid |
With labels:
{start_of_verse: Verse 1}
{start_of_verse: label="Verse 2"}
{start_of_chorus: label="Chorus\nAll sing"} # Multi-line label
Custom sections (any name with letters/digits/underscores):
{start_of_intro}
...
{end_of_intro}
{comment: Instrumental break} # or {c: ...} - displayed as note
{comment_italic: Softly} # or {ci: ...}
{comment_box: Important} # or {cb: ...}
{highlight: Key change!}
{chorus} # Reference to repeat last chorus
{new_song} # or {ns} - start new song in multi-song file
{new_page} # or {np}
{column_break} # or {colb}
{define: Asus4 base-fret 1 frets x 0 2 2 3 0}
{chord: Asus4} # Display diagram inline
{transpose: +2} # Transpose up 2 semitones
{transpose: -3} # Transpose down 3
# Amazing Grace - Traditional hymn
{meta: title Amazing Grace}
{meta: artist Traditional}
{meta: composer John Newton}
{key: G}
{time: 3/4}
{tempo: 80}
{meta: x_source manual}
{start_of_verse: Verse 1}
A[G]mazing [G7]grace, how [C]sweet the [G]sound
That [G]saved a [Em]wretch like [D]me
I [G]once was [G7]lost, but [C]now I'm [G]found
Was [G]blind but [D]now I [G]see
{end_of_verse}
{start_of_verse: Verse 2}
'Twas [G]grace that [G7]taught my [C]heart to [G]fear
And [G]grace my [Em]fears re[D]lieved
How [G]preci[G7]ous did that [C]grace ap[G]pear
The [G]hour I [D]first be[G]lieved
{end_of_verse}
{comment: Repeat Verse 1}
{meta: title Salt Creek}
{meta: artist Traditional}
{key: A}
{time: 4/4}
{tempo: 120}
{meta: x_type fiddle-tune}
{meta: x_difficulty intermediate}
{start_of_abc}
X:1
T:Salt Creek
M:4/4
K:A
|: E2AB c2BA | E2AB c2Bc | d2fd c2ec | BAGB A2AB :|
|: c2ec B2dB | A2cA G2BG | FGAB c2BA | BAGB A2AB :|
{end_of_abc}
This project uses these conventions:
{meta: key value} for all metadata (consistent, explicit)x_ prefix for Bluegrass Songbook extensions{start_of_verse}/{end_of_verse} for clear boundaries[chord] immediately before the syllable{start_of_abc}/{end_of_abc} for notation{comment: ...} for performance instructions| Key | I | IV | V | Common Extensions |
|---|---|---|---|---|
| G | G | C | D | Em, Am, D7 |
| C | C | F | G | Am, Dm, G7 |
| D | D | G | A | Bm, Em, A7 |
| A | A | D | E | F#m, Bm, E7 |
| E | E | A | B | C#m, F#m, B7 |
{meta: title ...} and {meta: artist ...} present{key: ...} matches the arrangement{meta: composer ...} if known (not writer){start_of_verse}/{end_of_verse}sources/classic-country/src/parser.pyscripts/lib/build_index.pydocs/js/search.js