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
| Field | Required | Default | Description |
|---|---|---|---|
beatsPerBar | no | 4 | Beats per bar for timing math (typically 4 or 3). |
offset | no | 0 | Seconds of audio before bar 1 starts. Use this to skip silence, count-ins, or pickups in the recording. |
sections | yes | — | 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).
| Field | Required | Default | Description |
|---|---|---|---|
start | no | auto | Absolute bar number where this section begins. If omitted, it auto-fills from the previous section’s end. |
bars | no | inferred | Length of the section in bars. If omitted, inferred from the lines (counting bars, multiplied by any line-level repeat modifier). |
lines | no | — | Array of bar-aware ChordPro strings. One entry per visual line. |
notes | no | — | Section-level performance notes, keyed by instrument. See “Section-level notes” below. |
beatsPerBar | no | top-level | Per-section override. Currently parsed but not used for timing — top-level value is applied uniformly. |
When to set start and bars explicitly
- Don’t set them when sections run back-to-back. The parser will fill them in correctly.
- Set
startwhen a section begins at a specific bar that isn’t the next free bar (e.g., a repeated chorus that jumps back, or a section that starts after a gap). - Set
barswhen the line count doesn’t match the actual section length — for example, a long instrumental section represented by a single line that’s understood to repeat for 16 bars.
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.
| Form | Example | In key C | In key D |
|---|---|---|---|
| Arabic | [1], [4], [5] | C, F, G | D, G, A |
Arabic + m | [2m], [6m] | Dm, Am | Em, Bm |
| Roman | [I], [ii], [V], [vi] | C, Dm, G, Am | D, Em, A, Bm |
Roman + m | [VIm], [IIm] | Am, Dm | Bm, Em |
| Slash bass | [1/3], [I/3], [4/6] | C/E, C/E, F/A | D/F#, D/F#, G/B |
| Accidental | [b7], [#4], [bVII] | Bb, F#, Bb | C, G#, C |
| With extension | [1maj7], [5sus4], [V7], [ii7] | Cmaj7, Gsus4, G7, Dm7 | Dmaj7, Asus4, A7, Em7 |
Resolution rules:
- Quality precedence: explicit
msuffix > Roman case > major default. SoVIm→ minor (case overridden),vi→ minor,VI→ major,6m→ minor,6→ major. - Slash bass is parsed and transposed independently:
[1/3]in D →D/F#. - Accidentals shift the scale degree:
[b7]in C →Bb;[#4]in C →F#. - Extensions and quality suffixes pass through verbatim:
[1maj7]in F →Fmaj7. - Diminished (
°ordimafter the number) suppresses the implicit minormfrom a lowercase Roman, so[vii°]→B°(notBm°). - 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.
| Modifier | Meaning |
|---|---|
(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
- 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. - Find the tempo. This is informational only — tempo lives in the song YAML, not here. Don’t add a
tempofield to the chart. - 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”).
- 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. - 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. - 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. - Use empty bars (
| |) when a printed measure has no chord change and no lyrics. - Use beat slashes when the printed chart shows rhythmic detail like “A / / D” within a single measure.
- Leave
startoff. Let the parser auto-fill. Only setstartif a section explicitly jumps to a non-sequential bar. - Leave
barsoff unless the line transcription doesn’t reflect the true length (e.g., a “play 16 bars” instrumental shown as a single example line). - 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. - Set
offsetto 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.
- Can’t tell where a chord change falls within a bar? Place it at the start of the bar (most common case). Don’t fabricate beat slashes.
- Can’t tell how many bars an instrumental runs for? Set an explicit
bars:based on what the printed chart shows, even if the lines field has fewer bars; add a note explaining. - Lyrics are unclear or partly cut off? Transcribe what’s legible and add a YAML comment (
# unclear: ...) on the affected line. Don’t invent words. - Section names overlap (two “Chorus” labels)? Number them (
Chorus 1,Chorus 2) — section keys must be unique in YAML. - Repeats marked with “x4” or repeat bars? Use
(x4)line modifier on a single line rather than copying the line four times. - Anacrusis / pickup in the source? Put the pickup word(s) before the first
|on the line where the new bar starts.
What NOT to do
- Don’t add a
tempofield — it goes in the song file. - Don’t try to encode dynamics, articulations, or non-rhythmic notation. Those go in
{Instrument: text}notes. - Don’t use bracketed text for anything other than chords.
[verse],[bridge], etc. are not valid — use section keys. - Don’t put chord names without brackets in the lyric stream.
Ain lyrics means the literal letter A, not the chord. - Don’t use Markdown, HTML, or other formatting inside lines. The parser only understands the syntax above.
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"