ChordPro format

The complete reference for the ChordPro format as SONGUIDE supports it, from chords and metadata to sections, annotations, and transposing.

ChordPro is a plain text format for song sheets. It has been around for decades, works in countless apps, and is easy to read even as raw text. SONGUIDE stores every song as ChordPro and supports most of the official ChordPro specification.

You do not need to read this whole page to use SONGUIDE. The Text editor writes ChordPro for you. This reference is for everyone who wants to edit the source directly, import files from elsewhere, or understand exactly what a directive does.

Chords

Chords go in square brackets, placed directly before the syllable they belong to:

A[G]mazing [G7]grace, how [C]sweet the [G]sound

On the song sheet, each chord is rendered above that exact syllable. SONGUIDE accepts every common notation style:

Unknown chord shapes are never rejected. Whatever is between the brackets is kept and rendered. Annotations with a * prefix look like chords on the sheet but are never transposed.

Extensions are rendered in a superscript style, like professional song sheets: the root and quality stay on the baseline and the extension is raised, for example the 7 in Am7.

Inline cues

Parenthesized performance cues inside lyrics are recognized and lifted onto the chord row in italics:

Other parenthesized text, like (oh yeah), stays in the lyrics as normal words.

Metadata directives

Directives are instructions in curly braces, one per line. These carry the song metadata:

Title, artist, key, tempo, time, and original key also appear in the Song Info tab and in your library lists. Long and short directive names are interchangeable, and other metadata directives such as {composer}, {album}, or {year} are kept in the file untouched.

{title: Amazing Grace}
{artist: John Newton}
{key: G}
{tempo: 63}
{time: 3/4}

Sections

SONGUIDE recognizes two ways of marking sections. Both render the same.

Recommended: comment headings

A {comment: ...} directive (short {c: ...}) starts a new section with that label. This is the style SongSelect and many community files use, and it is the style we recommend because one directive covers every heading you will ever need:

{comment: Verse 1}
A[G]mazing [G7]grace, how [C]sweet the [G]sound

{comment: Chorus}
My [G]chains are [D]gone, I've been set [G]free

{comment: Guitar Solo 2x}
[G] [C] [G] [D]

Any label works. If the label starts with a known section name, the section gets that type and its color. Everything else renders in a neutral gray box, with the label still shown.

Environment directives

The official paired style is also fully supported:

{start_of_verse: Verse 1}
A[G]mazing [G7]grace, how [C]sweet the [G]sound
{end_of_verse}

Supported pairs are {start_of_verse}, {start_of_chorus}, {start_of_bridge}, and {start_of_tab}, with their short forms {sov}, {soc}, {sob}, and {sot} and the matching end directives. There is no pair for intro, outro, pre-chorus, or other section types, which is why comment headings are the more flexible choice.

Section colors

On the song sheet each section is a bordered box with its label in a chip. Four section types have their own color, everything else shares a neutral gray:

Section names in other languages

Labels in several languages resolve to the right type and color while keeping their original text in the chip. For example Strophe 2 renders as a verse and Refrain as a chorus. Recognized aliases include Vers, Strophe, Couplet, Verso (verse), Coro, Refrain, Estribillo, Ritornello (chorus), Pre-Coro (pre-chorus), Puente, Pont, Ponte (bridge), Vorspiel (intro), Nachspiel (outro), and Zwischenspiel (interlude).

English labels are still the safer choice, since other apps may not recognize section names in other languages.

Section breaks and section references

An empty {comment:} closes the current section and starts a new unlabeled one, a plain visual break.

A labeled section with no content is a section reference: a compact divider telling the performer to play that section again. This keeps repeated choruses out of your song sheet:

{comment: Bridge}
[Em]My chains are gone...

{comment: Chorus}
{comment: Chorus 2x}

Both chorus lines above render as slim labeled dividers instead of full boxes.

Performance notes

{comment_box: ...} (short {cb: ...}) is a note to the performers. It appears inside the current section in amber, clearly separate from lyrics:

{comment: Intro}
{comment_box: Keys pad only, drums enter on verse 2}
[G] [C] [G] [D]

This is what SONGUIDE writes when you add a comment box row in the Text editor. Since it is a standard ChordPro directive, your notes survive when a file is opened in other apps.

Capo

Capo is personal and not part of the song. SONGUIDE therefore stores the capo fret per user and per song, outside the ChordPro file.

Set the capo from the capo wheel in the song view. With Show Capo on, chords are displayed transposed for your finger shapes while the written song sheet stays unchanged.

Show Capo applies to all songs at once and only shows or hides the capo view. Your capo settings per song are never lost. Playing guitar, you keep Show Capo on and see your finger shapes everywhere. Switch to bass and you turn Show Capo off to read the written chords everywhere, without losing a single capo fret.

A {capo: ...} directive in an imported file is kept in the source but has no effect. Set the capo in the app instead.

Guitar tab

Nothing between {start_of_tab} and {end_of_tab} is parsed as chords, and the lines stay untouched in your file. Tab rendering is not fully supported yet.

Comment lines and copyright footers

Lines starting with # are source comments per the ChordPro spec. They are kept in the file but never rendered.

Plain text CCLI and copyright footers, as exported by SongSelect, are detected and hidden on the song sheet: a line with a CCLI song number, a © year line, or SongSelect terms marks the start of the footer, and everything from there on is not rendered. The text stays in your file, so nothing is lost.

Transposing and keys

Transposing from the transpose wheel rewrites the chords in the song itself and updates {key: ...}. It is smart about spelling: flat keys get flats, sharp keys get sharps, and minor keys are spelled through their relative major. Tab blocks, annotations with *, [N.C.], and bar markers are left alone.

{original_key: ...} is never touched by transposing. It remembers the published key of the song no matter what key you play it in, and it is shown in the song header.

Supported and unsupported directives

Every directive described above is supported. The following directives are not supported. SONGUIDE never deletes them though. They are preserved in the source and simply have no visual effect:

Because unknown directives are preserved, files from other ChordPro apps round trip through SONGUIDE safely.

Import behavior in short

• Long and short directive names are both accepted, and whitespace is trimmed.
• If a metadata directive appears twice, the last one wins for the extracted value, but all occurrences stay in the file.
• Empty lines inside a section are preserved and create visual spacing in the rendered sheet. Blank lines directly before a section heading or at the very top of the file are trimmed, so spacing between sections stays consistent.
• Lines that begin with one or more directives followed by lyrics are split and both parts are handled, which repairs files that concatenate a directive with the first lyric line.

For file types, size limits, and import/export, see Import and export.