chordpro

# ChordPro Format Reference

Official spec: https://www.chordpro.org/chordpro/

## Bluegrass Songbook Format Strategy

We use **ChordPro-compatible syntax** with extensions:
- Standard ChordPro for portability (works in other apps)
- `{meta: key value}` pattern for all metadata (consistent, explicit)
- `{meta: x_*}` for custom Bluegrass Songbook fields
- ABC notation for fiddle tunes (via `{start_of_abc}`)

## File Extensions

`.pro`, `.cho`, `.crd`, `.chopro`, `.chord`

## Line Types

```chordpro
# Comment (ignored by processors)
{directive: value}           # Metadata or formatting control
Lyrics with [C]inline [G]chords
                              # Blank line (section separator)
```

## Chord Syntax

```chordpro
[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):
- Nashville: `[1]`, `[4]`, `[5]`, `[b7]`
- Roman: `[I]`, `[IV]`, `[V]`, `[bVII]`

## Metadata Directives

**Bluegrass Songbook uses `{meta: key value}` pattern for consistency:**

```chordpro
{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):
```chordpro
{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):
```chordpro
# 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):
```chordpro
{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) |

## Environment Directives (Sections)

| 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:**
```chordpro
{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):
```chordpro
{start_of_intro}
...
{end_of_intro}
```

## Formatting Directives

```chordpro
{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
```

## Output Control

```chordpro
{new_song}           # or {ns} - start new song in multi-song file
{new_page}           # or {np}
{column_break}       # or {colb}
```

## Chord Definitions & Diagrams

```chordpro
{define: Asus4 base-fret 1 frets x 0 2 2 3 0}
{chord: Asus4}       # Display diagram inline
```

## Transposition

```chordpro
{transpose: +2}      # Transpose up 2 semitones
{transpose: -3}      # Transpose down 3
```

## Complete Example

```chordpro
# 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}
```

## Fiddle Tune Example (with ABC)

```chordpro
{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}
```

## Bluegrass Songbook Conventions

This project uses these conventions:

1. **Metadata pattern**: Use `{meta: key value}` for all metadata (consistent, explicit)
2. **Metadata order**: title, artist, composer, key, tempo, then x_* fields
3. **Custom fields**: Use `x_` prefix for Bluegrass Songbook extensions
4. **Verse markers**: Use `{start_of_verse}`/`{end_of_verse}` for clear boundaries
5. **Chord positioning**: Place `[chord]` immediately before the syllable
6. **Fiddle tunes**: Use `{start_of_abc}`/`{end_of_abc}` for notation
7. **Comments**: Use `{comment: ...}` for performance instructions

## Common Keys in Bluegrass/Country

| 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 |

## Validation Checklist

- [ ] `{meta: title ...}` and `{meta: artist ...}` present
- [ ] `{key: ...}` matches the arrangement
- [ ] `{meta: composer ...}` if known (not `writer`)
- [ ] All chords are valid (no typos)
- [ ] Verses wrapped in `{start_of_verse}`/`{end_of_verse}`
- [ ] Chord placement is before syllables, not after
- [ ] File ends with newline

## Related Files

- Parser: `sources/classic-country/src/parser.py`
- Index builder: `scripts/lib/build_index.py`
- Frontend renderer: `docs/js/search.js`