The .song file format
Every song in Songbooks is one plain-text .song document: a short header, then one or more labeled sections, each holding a chord grid and/or lyrics — and, optionally, a real note-level riff written in a clean LilyPond-compatible subset. This page is the complete grammar.
A complete example
title: Just Like Heaven
artist: The Cure
key: C
time: 4/4
tempo: 120
chord: C X32010
chord: G 320033
chord: Am X02210
chord: F 133211
[Verse]
grid: | C | G | Am | F |
[C]Show me, show me, show me [G]how you do that trick
The [Am]one that makes me [F]scream, she said
That's a whole playable song: a header (only title is required) with four chord: diagrams, one section with a four-bar chord grid, and lyrics with inline [Chord] markers. Everything below adds optional depth on top of this same shape — more header fields, more section fields, multi-chord bars, repeats, and real note-level tab/staff notation in place of the plain chord-over-slash grid, like this real riff:
A second example: a real riff
title: Bad Spell
artist: Larkin Poe
time: 4/4
tempo: 84
[Intro]
grid: | R | R | R |
score[guitar]: g,4 <d' g'>8. g,16 bes,8 c d f16 g
g,4 <d' g'>8. bes16( c'4) bes8 \tuplet 3/2 { g16 f d } g,4
Real LilyPond source, note for note, from this app's own legacy corpus (Mercy/bad-spell/intro.ly) — just written the way a score[label]: block actually holds it: inline, right in the .song file, no \include/\chordmode/\new TabStaff boilerplate to copy in first. See Note-level scores below for the full subset this parses.
Header fields
Each header line is key: value, before the first [Section]. Every field is optional except title.
| Field | Meaning |
|---|---|
title | Song title. |
artist | Artist/band name. |
key | Key signature, e.g. Bb, F#m. The song's plain chord: diagrams are for this key. |
tempo | Beats per minute, e.g. 96. |
swing | Swung playback for written straight notes: 8 plays eighths as a shuffle (the triplet's long-short), 16 does the same for sixteenths. Leave it out for straight time. |
time | Time signature, e.g. 4/4, 6/8. |
capo | Capo fret, printed as an annotation. |
transpose | Semitones to transpose for display — never changes the chord text itself. To rewrite the song in another key, use Transpose in the editor instead. |
gp_source | The name of the Guitar Pro file kept with the song (set when one is imported or saved). See Guitar Pro file. |
content | gp when the Guitar Pro file is the whole song (an instrumental, a lesson): the page opens on the file's score, and sections, grid and lyrics are optional. |
map | A short "·"-separated overview of the song's structure (e.g. Verse · Chorus · Verse). |
reference | A reference URL (usually YouTube) for this song. |
flats | yes to spell transposed chords with flats instead of sharps. When the song itself is transposed, chords are spelled for the new key (flats in Bb, sharps in E); this only decides for C and Am. |
cover / cover-credit | A cover image URL and its photo credit. |
chord: | One fretboard diagram — see Chord diagrams. Repeatable. |
chord[Key]: | One fretboard diagram entered for another key of the song — see Diagrams for several keys. Repeatable. |
Sections
A section starts with [Label] on its own line — Verse, Chorus, Bridge, or any free text. [Label] (repeat) marks a bare repeat: just the label, no grid or lyrics of its own.
Inside a section, before any grid/lyric lines, a few more fields are recognized:
| Field | Meaning |
|---|---|
time: | Per-section time-signature override. |
bars: | How many bars per printed row — one number for all rows (bars: 4), or a comma list for different row lengths (bars: 4,5, the last value repeating). |
times: | How many times this section is actually played through (>1 — affects the structure map, not the printed grid). |
note: | A free-text performance direction for this section occurrence (e.g. GTR + claviers only). Repeatable. |
score[label]: | A note-level voice for this section (drum, bass, guitar...) — see Note-level scores. |
Chord grid
A grid: line (or several, concatenated) holds the chord changes as |-separated bars:
grid: | Gm | Bb . D . | Cm7 |
Inside a bar, chord tokens are space-separated; . or % repeats the previous chord; a bare chord fills the whole bar.
| Syntax | Meaning |
|---|---|
|: ... :| | A repeated bracket (plain "x2" implied). |:4 ... states an explicit repeat count. |
(1.) / (1,2.) | A volta (first/second-ending) marker, right after a bar's own opening. |
{2/4} | A one-bar meter override. |
~ on a chord token | Tie — the chord sounds through, not restruck. |
R / r | A full bar of rest. |
Chord:4. | A duration tag — a dotted-quarter hold, for example — stripped for display, kept for rhythm. |
Lyrics
Any section line that isn't a recognized field is a lyric line, with chords inline as [Chord] right before the syllable they land on:
Pla[Gm]ceholder words [Bb]here
Chord diagrams
A chord: header line adds one fretboard box to the legend strip under the title — the same small grid-with-dots diagram a real printed songbook carries:
chord: Cm 8:XX3(111)
chord: G 7:XX(3121)
chord: Ab 8:X4312X
The name is a normal chord symbol (same grammar as the grid/lyrics). The spec is [fret:]strings, one character per string, left to right = lowest-pitched string to highest:
| Character | Meaning |
|---|---|
X | Muted string. |
O / 0 | Open string. |
a digit 1–9 | A fretted dot at that row (relative to the leading fret number, or row 1 = open position if none given). |
(digits) | A barre across those strings, drawn at the lowest enclosed row. |
This spec is byte-compatible with the legacy LaTeX songs package's own \gtab grid notation — real legacy diagrams paste in unchanged.
Diagrams for several keys
A chord shape only fits one key. Plain chord: lines are for the song's own key:. A diagram entered for another key names that key in brackets, the same way score[label]: names its voice:
key: G
chord: G 320003
chord: C X32010
chord[A]: A X02220
chord[A]: D XX0232
Here the chart shows the G and C boxes. The A set is kept for when the song is played in A: transpose the view up two semitones on the song page and its diagrams swap to that set. A key with no set of its own shows no diagrams, with a short note instead. chord[Bb]: and chord[A#]: mean the same key; chord[G]: in a song whose key: is G is the same as a plain chord:.
Transpose in the editor (Source tab) rewrites the song into a new key for real: every chord in the grids and in [Chord] lyric markers, slash basses included, and the key: line. Chords are spelled the way the new key reads (Bb in F, A# in E). N.C., %, rests, repeat and volta marks, durations, comments, notes and score[label]: voices are left exactly as written. The old key's plain chord: lines become chord[Old]: lines, and lines already marked with the new key become the song's plain set. The change is saved like any other edit, so the song's history keeps the previous version. Transposing back gives the original text.
Guitar Pro file (gp[Track]:)
A song can keep one Guitar Pro file (earlier versions stay in its history). Its notes are never copied into the text: a section points at bars of the file instead, and the song page draws them there.
[Verse 1]
grid: |E7 | A7 | E7 | . |
gp[Lead guitar]: 9-12
gp[Bass]: 9-12 staff
gp: 13-16
| Syntax | Meaning |
|---|---|
gp[Lead guitar] | A track of the file, by its name in Guitar Pro (case and accents don't matter), or by number: gp[#2]. A bare gp: means every track, as Guitar Pro's multi-track view shows them. |
9-12, 9, 1-4, 9-12 | Bars, numbered as Guitar Pro numbers them. Repeat signs inside the bars are played as written, so 1-12 with a repeat around it lasts 24 bars. |
tab, staff, tab+staff, slash | Optional: how to draw it. Left out, each reader gets the notation they chose for guitar or bass; a reader's own choice also wins over the line's. |
Tempo, time signature, key, swing, section names, chords and chord diagrams are in both the text and the file. When they disagree, editors see it on the song page and pick: the file's value, the text's (written into a new version of the file), or both kept as they are. Nothing is changed on its own.
Note-level scores (score[label]:)
A section can carry one or more score[label]: blocks — real note-level tab/notation for a named voice (drum, bass, a custom name like guitar-1), not just chord changes. The content is plain text, right in the .song file, the same as grid: or lyrics — no separate database row, nothing to look up: the file is meant to be the whole song, readable and git-diffable on its own, notation included. Edited directly in Source, with a live preview as you type. Only a clean, intentionally bounded subset of real LilyPond is understood:
For anything longer than a riff, keep the notes in the song's Guitar Pro file instead: it holds every technique, and has its own editor.
score[guitar-1]: \new TabStaff {
\set TabStaff.minimumFret = 3
\relative {
g,4 <d' g'>8. g,16 bes,8 c d f16 g
}
}
A block's content continues on following lines until a blank line, the next recognized field, or a new [Section] — unless it's wrapped in a balanced { ... } (the full form above), in which case it continues until those braces close, blank lines and all.
Pitch & duration
| Syntax | Meaning |
|---|---|
c d e f g a b | Note names (Dutch/LilyPond spelling). |
cis / ces | Sharp / flat (-is / -es). |
' / , | Octave up / down, relative to the previous note (real LilyPond "nearest pitch within a fourth" rule). |
4 8 16 ... | Duration (quarter, eighth, sixteenth...); a trailing . dots it. Omitted duration repeats the last one written. |
r4 | A rest. |
~ | Tie into the next note of the same pitch. |
<c e g>4 | A chord cluster. |
\tuplet 3/2 { g16 f d } | A triplet (or any N-in-the-time-of-M grouping). |
\relative { ... } | Wraps a passage in relative-pitch mode. Riffs may also be written in plain absolute pitch with no wrapper. |
See it rendered in the "Bad Spell" riff above.
Tuning & frets
Fret and string numbers are never written explicitly — they're computed the same way real LilyPond does, from the written pitch, the tuning, and the minimum-fret preference. The label itself picks the default tuning, so the common case needs no boilerplate at all:
score[bass]: d,4 d d d d d d dbass gets standard 4-string bass tuning; any other label (a custom name like guitar-1, or no label at all) gets standard 6-string guitar. A bare sequence like that is read in absolute pitch — real LilyPond's own default absent a \relative wrapper. For anything the shortcut can't express (an unusual tuning, an explicit minimum fret), fall back to the full form, same as the guitar example above:
score[bass]: \new TabStaff \with { stringTunings = #bass-tuning } {
\set TabStaff.minimumFret = 7
...
}
\set TabStaff.minimumFret = N may appear mid-riff to push a later passage higher up the neck.
Hammer-on / pull-off
A real LilyPond slur across two notes, on a tab staff, is how a hammer-on (ascending) or pull-off (descending) is written — the direction (and the printed "H"/"P" letter) is worked out automatically from the two pitches:
score[guitar]: \set TabStaff.minimumFret = 3
g,4( a,) a, a,Slides
A grace note slurred-and-glissando'd into the main note is a slide — the grace note's own duration doesn't matter (it borrows time), only its pitch:
score[guitar]: f4~ f8 ees8~ \grace f16( \glissando g8)Bends & palm mute
This part of the grammar is this app's own addition — it doesn't appear in real LilyPond. It's for a riff you type or paste in by hand. This syntax reuses LilyPond's own genuine text-articulation form (note^"label") rather than inventing a new token.
| Label | Meaning |
|---|---|
^"full" | A whole-step bend. |
^"1/2", ^"1/4", ^"3/4" | A fractional-step bend. |
^"1 1/2" | A mixed-number bend (one and a half steps). |
^"full (release)" | Bends up, then releases back down before the beat ends. |
^"PM" / ^"P.M." | Palm mute. Consecutive muted notes draw one "P.M." label with a dashed line, not one label per note. |
score[guitar]: e8^"full" e8 e8^"PM" e8^"PM" e4Drum notation
Real LilyPond's own percussion grammar — no fret or string numbers, just a fixed vocabulary of drum-piece names and the same duration syntax as above. The drum (or drums) label goes straight to the content: no \new DrumStaff, no \drummode — those are implicit in a score[drum]: block, never written out by hand. Written alongside a grid:, the section's chord names float above the drum staff's own bars (first beat of each bar only), exactly like a real chart hands a drummer the changes without asking them to read a chord grid:
[Chorus]
grid: |: D | % | % | % :|
score[drum]: bd4 hh8 hh8 sn4 hh8 hh8
bd4 hh8 bd8 sn4 hh8 hh8That's a "D" over bar 1, nothing on the bars after it — same convention a real chord-grid row uses (a chord only prints again when it actually changes).
| Name | Drum piece |
|---|---|
bd | Bass drum (kick) |
sn | Snare |
ss | Side stick |
hh / hhc | Hi-hat, closed |
hho | Hi-hat, open |
hhp | Hi-hat, pedal |
cymc | Crash cymbal |
cymr | Ride cymbal |
tomfl / tomfh | Floor tom, low / high |
toml / tomm / tomh | Tom, low / mid / high |
cb | Cowbell |
Two or more hits on the same beat (a kick and a closed hi-hat together, say) are written as a chord, same bracket syntax as a pitched one: <bd hh>4. A run of consecutive full-bar rests (r1) draws as one real engraved multi-measure-rest glyph, not one empty bar per rest.
Drummer view renders the WHOLE song as one continuous staff, the drum-notation counterpart of Song Map's own continuous chord-grid score — every section's bars flow straight into the next, with a real rehearsal-style marker on each section's own first bar instead of separate per-section blocks. A section with its own score[drum]: shows that real notation (chord names floating above it, as above); a section with none still collapses to a plain bar-count rest, same as it always has, but drawn by the same engraving engine as the real notation around it — so a run of several "just the bar count" sections packs multiple onto the same line instead of each getting its own, often mostly-empty row.
Multiple voices (drums, bass, guitars...)
A section can carry several score[label]: blocks side by side — one per instrument, each edited and previewed on its own:
score[drum]: bd4 hh8 hh8 sn4 hh8 hh8
bd4 hh8 bd8 sn4 hh8 hh8
score[bass]: d,4 d d d d d d d
score[guitar-1]: <e, b e>4 <e b e> <e b e> <e b e>
score[guitar-2]: e'8 g e g e g e gThese voices show up two ways. A section with exactly ONE melodic (non-drum) voice has it overlay the chord chart automatically — the common case for a hand-written riff. A section with SEVERAL keeps the chart as pure chords instead of guessing, and a reader picks which one's full notation to see from the instrument picker beside the view-mode tabs (Song and Song map both read the same choice; pick "Chords" to go back to the plain grid) — the render above picks bass for illustration, since a real reader would make that same choice from the picker. drum never goes through that picker — Drummer view shows it on its own, continuously across the whole song. Every voice is preserved and live-previewed in Source regardless of which one is currently showing elsewhere.
Mixing a melodic voice with the chord grid
A melodic voice (bass, guitar) and the section's own grid: describe the same bars two ways — the voice is the detailed notation, the grid is the chord changes. They don't need to agree on every bar:
- If every bar in a printed row has riff data, that whole row prints as real tab/notation, replacing the chord-grid row entirely (chord names float above it, read from the grid, positioned independently of the riff's own note timing).
- If only some bars in a row have riff data, those bars show the riff as a smaller overlay above their own normal chord-grid bar — "detailed here, plain changes there," on the same line.
- A later row with no riff data at all for any of its bars prints as an ordinary chord-grid row — the chart naturally switches back to plain changes on the next line.
grid: | D | D | G | G |
score[guitar]: <a, d fis>4 <a d fis> <a d fis> <a d fis>Only the first bar has riff data here, so just that bar prints as real notation — the rest of the row stays a plain chord-grid bar, same row. An intro with a real riff and a verse that's just chord changes can likewise sit in the same section-less chart, each rendered the way it actually has data for — no separate toggle needed anywhere. A drum voice doesn't follow this rule — see above.
How it renders
Chord-grid rows render as HTML/CSS in the browser and as pure-Go vector drawing in the PDF export — no shared third-party engine. A fully riff-covered row renders differently per target: on the web it's handed to a vendored copy of alphaTab as real engraved notation (proper stems, beams, hammer-on/pull-off slurs, bends); in the PDF export it's drawn by this app's own native tab engraver, built from the same real engraving proportions (stem length, beam thickness, logarithmic note spacing) rather than guessed numbers.
A song can also carry real reference audio alongside its notation — not a file attached separately, but an MP3 stored against the song itself and played back right from the page: a YouTube reference, a band's own recording, or (most relevant here) a Guitar Pro file's own embedded backing track, carried in by the Guitar Pro importer with the same bar sync the imported notation uses, so playback and the chart stay lined up as you listen.