milnak/ChordPro-Directives.md

ChordPro Directives

ChordPro files are text based files that contain directives for the program loading them. This allows the program to customize how the text is displayed such as making a title larger, or by placing chords above the lyrics instead of in line with them. This makes them much more powerful than standard text files. MobileSheets tries to support some of the same features with text files (such placing chords above lyrics), but many features are ChordPro specific. That is why ChordPro files are the preferred format in MobileSheets for combining lyrics with chords. The ChordPro specification. Specifically, see ChordPro directives.

Meta-data directives

Directive	Description
{title: text}	Defines the title of the song.
{sorttitle: text}	Defines the sorting title of the song.
{subtitle: text}	Defines a subtitle of the song.
{artist: text}	Defines an artist. Multiple artists can be specified using multiple directives.
{copyright: text}	Copyright information for the song.
{album: text}	Defines an album this song occurs on. Multiple albums can be specified using multiple directives.
{year: number}	The year this song was first published, as a four-digit number.
{key: text}	Specifies the key the song is written in. Multiple key specifications are possible, each specification is assumed to apply from where it was specified.
{time: text}	Specifies a time signature. Multiple signatures are possible, each specification is assumed to apply from where it was specified.
{tempo: number}	Specifies the tempo in number of beats per minute for the song. Multiple specifications are possible, each specification applies from where it appears in the song.
{duration: number}	Specifies the duration of the song. This can be a number indicating seconds, or a time specification conforming to the extended ordinal time format as defined in ISO 8601. For example, durations 268 (seconds) and 4:28 (readable) are the same.
{capo: number}	Specifies the capo setting for the song.
{meta: field value}	Defines a meta-data item. Supported fields include: sorttitle, collection, setlist, source, genre, difficulty, custom, custom2, customgroup, keywords, rating
{footer: text}	Displays the given text at the bottom of every page.

Sizes and colours

Directive	Description
{chordsize: number}	Change size of the song chords that follow.
{chordcolour: text}	Change colour of the song chords that follow.
{chorussize: number}	Change size of the song chorus that follow.
{choruscolour: text}	Change colour of the song chorus that follow.
{footersize: number}	Change size of the song footer.
{footercolour: text}	Change colour of the song footer.
{tabsize: number}	Change the size of the guitar TAB that follow.
{tabcolour}	Change the colour of the guitar TAB that follow.
{textsize: number}	change the size of the song lyrics that follow.
{textcolour: text}	Change the colour of the song lyrics that follow.

Formatting Directives

Directive	Description
{comment: text}	Comment that is shown using an italic typeface.
{highlight: text}	Comment that is shown using using a yellow background.
{comment_box: text}	Comment that is shown using a box around the text.

Environment Directives

Directive	Description
{start_of_chorus[: label]}...{end_of_chorus}	Indicates that the lines that follow form the song’s chorus. These lines are normal song lines, but will be shown in an outstanding manner. This directive may include an optional label, to identify the chorus.
{chorus[: label]}	Indicates that the song chorus must be played here. The optional label is used as a label for the chorus.
{start_of_verse[: label]}...{end_of_verse}	Indicates that following lines form a verse of the song. This directive may include an optional label to identify the section.
{start_of_tab[: label]}...{end_of_tab}	Indicates that the lines that follow form a section of guitar TAB instructions. This directive may include an optional label.
{start_of_part: label}...{end_of_part}	Marks a custom part. The label is mandatory.

Transposition

Directive	Description
{transpose: steps}	Remainder of the song should be transposed the number of semitones according to the given value. When used at the beginning of a song, the whole song will be transposed. When used somewhere in the song it can be used to achieve modulation. If transposing results in accidentals, a positive value will use sharps, while a negative value will use flats.

Output related directives

Directive	Description
{new_page}	Forces a new page to be generated at the place where it occurs in the song.
{column_break}	Forces output to continue in the next column.

Sample chopro file

{title: Twinkle, Twinkle, Little Star}
{meta: rating 4}
{meta: setlist setlist}
{meta: collection collection}
{key: C}
{artist: Leonard Cohen}
{composer: Wolfgang Amadeus Mozart}
{meta: genre genre}
{album: The Best of Mozart}
{year: 2016}
 # "source" shows under "Types"
{meta: source source}
{meta: customgroup customgroup}
# "time" shows under "Signatures"
{time: 4/4}
{meta: keywords keywords}
{meta: custom custom}
{meta: custom2 custom2}
{meta: difficulty 8}
{tempo: 120}
# "duration" is in seconds.
{duration: 268}

{capo: 2}
{subtitle: The Last Farewell}
{copyright: 2026 Mozart Music}
{footer: This is a traditional children's song.}

# Specific sorting for this song.
{sorttitle: a song}

# Down a half
{transpose: 1}

{comment: Mozart might not have composed this melody.}

{start_of_tab: Intro Guitar}
|--------------0--0-------------------------------
|--------3--3--------3-----1--1--0--0-------------
|--0--0--------------------------------2--2--0----

|--3--3--1--1--0--0--------
|--------------------3-----
|--------------------------
{end_of_tab}

{comment_box: This is also the melody for the Alphabet Song.}}

{textcolour: blue}
{textsize: 10}
{choruscolour: red}
{chorussize: 18}
{chordcolour: green}
{footersize: 24}

{start_of_verse: Verse 1}
[C]Twinkle, twinkle, [F]little [C]star,
[F]How I [C]wonder [G7]what you [C]are!
[C]Up a[F]bove the [C]world so [G7]high,
[C]Like a [F]diamond [C]in the [G7]sky.
[C]Twinkle, twinkle, [F]little [C]star,
[F]How I [C]wonder [G7]what you [C]are!
{end_of_verse}

{column_break}

{start_of_chorus}
[C]Little, [F]little, [C]little [G7]star,
[C]Up a[F]bove the [C]clouds so [G7]far,
[C]How I wonder [F]what you [C]are!
[F]Little, [C]little, [G7]little [C]star.
{end_of_chorus}

{highlight: Additional verses can be added here.}

{chorus: Final Chorus}

{start_of_part: Outro}
[C]Little, [F]little, [C]little [G7]star,
[C]Little, [F]little, [C]little [G7]star.
{end_of_part}

{start_of_chorus: Out Chorus}
[C]A song [D] line with [E]chords   [F]
{transpose: 2}
[C]A song [D] line with [E]chords   [F]
{transpose}
[C]We're done!
{end_of_chorus}