Chart Format

A chart is a YAML file that drives the synchronized rehearsal view: lyrics, chords, performance notes, and section markers, all aligned to bar numbers and played in time with the audio.

This guide is the reference for both humans authoring charts by hand and for AI assistants drafting charts from PDFs or lead sheets. It covers every feature the parser understands.

Quick example

beatsPerBar: 4
offset: 0
sections:
  Intro:
    lines:
      - "|[A]  |[A] / / [A/C#](x4)"
  Verse 1:
    lines:
      - "|[A]I'm not [A/C#]here for |[D]someone else"
      - "|[A]Have my [A/C#]target |[D]have no doubts"
      - "|[F#m]Lost in the [D]sound, hand and |[A]heart both sway"
      - "My |[A]eyes [A/C#]set on |[D]you"
  Chorus:
    lines:
      - "Im |[D]not done [E]dancing but |[F#m] please .. just .. [A]kiss me"
      - "Its |[D]just me [E]dancing with |[F#m]"

That’s a complete, valid chart. start and bars are inferred. The Intro repeats one line four times, the Verse is four lines × 2 bars = 8 bars, the Chorus is 2 lines × 2 bars = 4 bars. Sections lay out sequentially starting at bar 1.

File location and naming

Charts live at src/content/charts/<song-slug>.yaml. The chart slug must match the song slug — that’s how the song page finds it. There’s one chart per song.

Top-level fields

FieldRequiredDefaultDescription
beatsPerBarno4Beats per bar for timing math (typically 4 or 3).
offsetno0Seconds of audio before bar 1 starts. Use this to skip silence, count-ins, or pickups in the recording.
sectionsyes—Ordered map of section name → section.

Tempo is not in the chart. It lives in the song file (src/content/songs/<slug>.yaml) under tempo. The chart relies on the song’s tempo plus its own beatsPerBar and offset to map bars to seconds.

Section fields

Each section is a key in the sections map. The key is the display name (e.g., Verse 1, Chorus, Bridge).

FieldRequiredDefaultDescription
startnoautoAbsolute bar number where this section begins. If omitted, it auto-fills from the previous section’s end.
barsnoinferredLength of the section in bars. If omitted, inferred from the lines (counting bars, multiplied by any line-level repeat modifier).
linesno—Array of bar-aware ChordPro strings. One entry per visual line.
notesno—Section-level performance notes, keyed by instrument. See “Section-level notes” below.
beatsPerBarnotop-levelPer-section override. Currently parsed but not used for timing — top-level value is applied uniformly.

When to set start and bars explicitly

Line syntax (bar-aware ChordPro)

Each entry in lines is a string that mixes lyrics, chords, bar lines, and performance notes. The same syntax handles everything.

Bar lines

| separates bars. The first | marks the start of bar 1; each subsequent | ends a bar and starts the next. A trailing | is allowed but doesn’t add a bar.

"|[A]hello |[D]world"        → 2 bars
"|[A]hello |[D]world |"      → 2 bars (trailing pipe ignored)
"|[A]  |  |  |"              → 3 bars (last is trailing)

Chords

[X] marks a chord. The chord attaches to the lyric immediately following it, in the same bar.

"|[A]hello"                       → bar 1: chord A on "hello"
"|[A]I'm not [A/C#]here for"      → bar 1: A on "I'm not", A/C# on "here for"
"|[F#m7]complex |[Bsus4]chords"   → bar 1: F#m7, bar 2: Bsus4

Chord names can contain anything between brackets except ]. Slashes inside brackets are slash chords ([A/C#], [D/F#]) and are NOT bar separators.

Number notation (Nashville)

Chord brackets accept scale-degree numbers as well as letter chords. Numbers are transposed to the song’s key field at render time, so a chart authored in numbers can be played in any key without rewriting.

A token is a number chord if it starts with a digit (1–7), a Roman numeral (I–VII, upper or lower case), or an accidental (b/#) followed by either. Letter chords (starting with A–G) are never transposed.

FormExampleIn key CIn key D
Arabic[1], [4], [5]C, F, GD, G, A
Arabic + m[2m], [6m]Dm, AmEm, Bm
Roman[I], [ii], [V], [vi]C, Dm, G, AmD, Em, A, Bm
Roman + m[VIm], [IIm]Am, DmBm, Em
Slash bass[1/3], [I/3], [4/6]C/E, C/E, F/AD/F#, D/F#, G/B
Accidental[b7], [#4], [bVII]Bb, F#, BbC, G#, C
With extension[1maj7], [5sus4], [V7], [ii7]Cmaj7, Gsus4, G7, Dm7Dmaj7, Asus4, A7, Em7

Resolution rules:

  1. Quality precedence: explicit m suffix > Roman case > major default. So VIm → minor (case overridden), vi → minor, VI → major, 6m → minor, 6 → major.
  2. Slash bass is parsed and transposed independently: [1/3] in D → D/F#.
  3. Accidentals shift the scale degree: [b7] in C → Bb; [#4] in C → F#.
  4. Extensions and quality suffixes pass through verbatim: [1maj7] in F → Fmaj7.
  5. Diminished (° or dim after the number) suppresses the implicit minor m from a lowercase Roman, so [vii°] → B° (not Bm°).
  6. Letter chords pass through untouched: [C] is always C, even in a number-authored chart.

Minor-key songs use relative-major numbering. A song with key: Am is numbered against C major: [1] → C, [6m] → Am, [5] → G. The song’s actual key is still Am for display purposes; numbering just uses the relative major as the reference.

Display modes: the song page offers a three-way toggle — letters (default), numbers, both. The “both” mode shows Letter(Number) (e.g., C(1)). The display mode is persisted per user via localStorage. A key picker on the same row lets the user transpose the chart for the current session.

When to use numbers vs letters: prefer numbers for original songs and any song you’re likely to transpose. Letter chords are fine for fixed-key covers or for any chart where transposability isn’t a goal — they keep working unchanged.

Lyrics

Plain text between chords and pipes is lyric. Whitespace is trimmed at chord boundaries.

Pickup / anacrusis

Text before the first | is a pickup — a syllable that belongs rhythmically to the previous bar but visually leads into this line.

"My |[A]eyes [A/C#]set on |[D]you"
 ^^                                 ← pickup ("My")
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  ← 2 bars

Pickup does NOT count as a bar.

Empty / chord-only bars

A bar with no lyric is fine. Use a chord with no following text, or no chord at all.

"|[A]  |[D]  |[A]  |[D]  |"   → four chord-only bars
"|  |  |  |"                  → four completely empty bars

Beat-level slashes (sustain beats)

A standalone / (surrounded by whitespace, NOT inside brackets) is a sustain beat. Each non-slash token is one beat; each / is one beat. This lets you place chords on specific beats within a bar.

"|[A] / / [A/C#] |"

Reads as: beat 1 = A, beat 2 = sustain, beat 3 = sustain, beat 4 = A/C#.

"|[A] / [D] / |"   → beat 1: A, beat 2: sustain, beat 3: D, beat 4: sustain
"|[A] / / / |"     → beat 1: A, beats 2-4: sustain (whole bar of A)

The rule: a / between brackets like [A/C#] is a slash chord. A / surrounded by whitespace is a beat marker. The parser only switches into beat-mode when it sees a standalone slash in the bar.

Inline performance notes

{Instrument: text} is a per-instrument note. It attaches to the bar where it appears and is shown below the lyrics, filtered by the player’s selected part.

"|[A]  |[A/C#]  |[D]  |  | {Keys: pad only} {Electric 2: clean arpeggios}"
"|[A]Have my [A/C#] target |[D] have no doubts {Electric 2: start jangle part}"

Multiple notes can appear in the same bar. The instrument name should match the song’s stem instrument names (case-insensitive) so the part filter works. Note markup is stripped from the lyric output.

Line modifiers

Trailing (...) groups at the very end of a line are line-level modifiers.

ModifierMeaning
(xN)Repeat this line N times. The line’s bars are counted N times when inferring section length.
(vamp)Marks the line as a vamp (free repeat). Display only.
(fade)Marks the line as fading out. Display only.
(anything)Any other parenthesized word is stored as a raw modifier; display behavior is up to the renderer.
"|[A]  |[A] / / [A/C#] (x4)"     → 2 bars × 4 = 8 bars total
"|[A]  |[D]  | (x2)(fade)"       → 2 bars × 2, fade out

Parentheses inside the line (e.g., (world) mid-lyric) are NOT treated as modifiers — only trailing groups are.

Section-level notes

For instructions that don’t tie to a specific lyric line — e.g., “use big pad on this whole section” — use the section-level notes field, keyed by instrument.

Chorus:
  lines:
    - "|[D]How great is [A]our |[E]God |[A]  |  |"
  notes:
    Electric 2:
      - text: "full strumming, delay on"
    Keys:
      - text: "big pad, add melody"

You can pin a section note to a specific bar (relative to section start, 1-indexed) and beat:

notes:
  Electric 2:
    - bar: 3
      beat: 3
      text: "hit accent here"

Use inline {...} notes inside lyric lines for per-line cues, and section-level notes for whole-section instructions. Either works for instrumental sections.

Timing model

Bar-to-time conversion uses the song’s tempo plus the chart’s beatsPerBar and offset:

secondsPerBar  = (beatsPerBar * 60) / tempo
barStartTime   = offset + (absoluteBarNumber - 1) * secondsPerBar

Charts assume constant tempo throughout (click-tracked recordings). Live recordings with tempo drift won’t sync accurately — that’s a known limitation.

offset is the easiest knob to misuse. If bar 1’s downbeat lands at 0.5 seconds into the audio (count-in, silence, etc.), set offset: 0.5. If you can hear a click and the chord change is misaligned by a constant amount, adjust offset until they line up.

Common patterns

Instrumental section, single line repeated:

Intro:
  lines:
    - "|[A]  |[A] / / [A/C#] (x4)"

Section with explicit length but only one descriptive line:

Solo:
  bars: 16
  lines:
    - "|[A]  |[D]  |[A]  |[E]  | {Lead: 16 bars over the verse changes}"

Multiple chords in one bar with lyrics:

- "|[A]I'm not [A/C#]here for |[D]someone else"

Chord-only bars between vocal phrases:

- "|[A]  |[D]  |[A]I'm back in |[D]now"

Bar-precise note in a section:

Bridge:
  bars: 8
  notes:
    Drums:
      - bar: 5
        beat: 1
        text: "fill into chorus"

Section that jumps backward (e.g., a tag):

Tag:
  start: 60       # explicit because we want to repeat earlier material
  bars: 4
  lines:
    - "|[D]oh |[A]oh |[E]oh |[A]"

Drafting a chart from a PDF or lead sheet

This section is for AI assistants (and humans) translating an existing chart into this format.

Step-by-step

  1. Find the time signature. 4/4 → beatsPerBar: 4. 3/4 or 6/8 → beatsPerBar: 3 (treating dotted-quarter as the beat for 6/8). If you can’t tell, default to 4.
  2. Find the tempo. This is informational only — tempo lives in the song YAML, not here. Don’t add a tempo field to the chart.
  3. Identify sections. Use the labels printed on the chart (Intro, Verse, Pre-Chorus, Chorus, Bridge, Outro, etc.). Use those as section keys verbatim, including numbering (“Verse 1”, “Verse 2”).
  4. For each section, transcribe lines bar-by-bar. One visual line on the printed chart usually maps to one entry in lines. Two to four bars per line is typical.
  5. Place chords with [X] immediately before the syllable they fall on. If the printed chart shows a chord centered over a syllable, that’s where the bracket goes.
  6. Choose number notation when appropriate. If the source uses Nashville numbers (1 4 5 6m), transcribe them as numbers — [1], [4], [5], [6m]. If the source uses letters and is unlikely to be transposed, use letters. Don’t try to convert letters to numbers without confirmation; the user can convert later if they want.
  7. Use empty bars (| |) when a printed measure has no chord change and no lyrics.
  8. Use beat slashes when the printed chart shows rhythmic detail like “A / / D” within a single measure.
  9. Leave start off. Let the parser auto-fill. Only set start if a section explicitly jumps to a non-sequential bar.
  10. Leave bars off unless the line transcription doesn’t reflect the true length (e.g., a “play 16 bars” instrumental shown as a single example line).
  11. Keep instrument names consistent with the song’s stems if you know them (e.g., Electric 1, Electric 2, Keys, Drums, Bass, Lead, Acoustic). When in doubt, use a generic name; the part filter will still display it.
  12. Set offset to 0 unless you know the audio has a count-in or pre-roll. This is something a human can tune later.

Resolving ambiguities

When the source is ambiguous, prefer leaving the chart slightly underspecified over guessing. Underspecified output the user can review beats wrong output the user has to debug.

What NOT to do

Pitfalls and gotchas

Slash inside a chord vs. beat slash. [A/C#] is a slash chord; the slash is part of the chord name. [A] / / [A/C#] has standalone slashes that are beat markers. The parser distinguishes by looking at whether the slash is between [ and ].

Trailing pipe doesn’t add a bar. |[A]hello |[D]world | is 2 bars, not 3. The trailing | is conventional and ignored.

A line with zero pipes is all pickup. If you forget the leading |, your entire line will be parsed as pickup with zero bars. Always start a content line with |.

Repeat modifiers multiply inferred bar count. |[A] |[D] | (x4) is 2 line-bars × 4 = 8 section-bars. If you also set bars: 2 explicitly, the explicit value wins and the repeat is just a display hint.

Section keys must be unique. YAML maps don’t allow duplicate keys. Use Chorus 1, Chorus 2, Final Chorus, etc.

Quoting. Lines with leading | should be quoted in YAML to avoid the parser interpreting | as a block scalar indicator. Use double quotes: "|[A]hello". The example chart uses unquoted strings for lines that don’t start with | (pickup lines), but quoting all lines is safest.

Inline notes are bar-scoped. {Keys: pad only} attaches to the bar containing it, not the line. If you want it on a specific bar, place the {...} inside that bar’s segment.

beatsPerBar per section is parsed but unused. Don’t rely on per-section time signature changes yet — only the top-level beatsPerBar affects timing.

Full annotated example

# Top-level: 4/4 time, audio starts exactly at bar 1 (no count-in).
beatsPerBar: 4
offset: 0

sections:
  # No `start` — auto-fills to bar 1.
  # No `bars` — inferred from the line: 2 bars × (x4) = 8 bars.
  Intro:
    lines:
      - "|[A]  |[A] / / [A/C#](x4)"
        # Bar 1: A held for 4 beats.
        # Bar 2: beat slashes — A on beat 1, sustain 2-3, A/C# on beat 4.
        # Whole line repeats 4 times.

  # Auto-starts at bar 9. Inferred bars: 4 lines × 2 bars = 8.
  Verse 1:
    lines:
      - "|[A]I'm not [A/C#]here for |[D]someone else"
        # Bar 1 has two chords (A on "I'm not", A/C# on "here for").
        # Bar 2 has D on "someone else".
      - "|[A]Have my [A/C#]target |[D]have no doubts"
      - "|[F#m]Lost in the [D]sound, hand and |[A]heart both sway"
      - "My |[A]eyes [A/C#]set on |[D]you"
        # "My" is a pickup — belongs rhythmically to the end of the
        # previous bar, displayed at the start of this line.

  # Inferred from the single line: 2 bars × 2 = 4 bars. Auto-starts at bar 17.
  Interlude 1:
    lines:
      - "|[A]  |[A] / / [A/C#](x2)"

  Verse 1b:
    lines:
      - "|[A]Don't just [A/C#]want a |[D]pretty face"
      - "|[A]Have my [A/C#]target |[D]have no doubts"
      - "|[F#m]Lost in the [D]sound, hand and |[A]heart both sway"
      - "My |[A]eyes [A/C#]set on |[D]you"

  # Section-level notes for whole-section cues.
  Chorus:
    lines:
      - "Im |[D]not done [E]dancing but |[F#m] please .. just .. [A]kiss me"
      - "Its |[D]just me [E]dancing with |[F#m]"
      - "Im |[D]not done [E]kissing but |[F#m] please take ... me .. [A]somewhere"
      - "Sneak |[D]out the [E]back door with |[F#m] you / [A]"
        # Beat slashes in bar 2: F#m on beat 1, sustain 2-3, A on beat 4.
    notes:
      Electric 2:
        - text: "full strumming, delay on"
      Keys:
        - text: "big pad, add melody"
        - bar: 3
          beat: 1
          text: "modulate up an octave for the last two bars"