The ‘Chord/ChordPro’ format, version 4.6

Chord or ChordPro is the name of a simple text format for the notation of lyrics with chords. Although primarily intended for guitarists, it can be used for all kinds of musical purposes.

The Chord format is invented by the original authors of the Chord program, Mario Dorion and Martin Leclerc. For unknown reasons the users of the format started to call it ChordPro.

Several tools exist that can process data in ChordPro format: to print nice song sheets, create web pages, or to transform it in into a format suitable for other tools.

The following specification of the ChordPro format is based upon the original Chord program, and must therefore be considered official. The reference implementation is the Chordii program, which is the current incarnation of the original Chord program. Common extensions to ChordPro are denoted in green.

ChordPro processing programs usually produce nicely formatted printed output, or HTML pages, or something else meant for viewing. How the output should look like is not part of the ChordPro data standard. The reference implementation produces PDF documents, suitable for viewing and printing. Details like page margins, borders and fonts can be controlled using external configuration files. For more information, see the ChordPro program documentation.

Most characteristics are quite generic. For example, a piece of text can be shown in a way that makes it different from the rest of the text. Where appropriate, a blue note will indicate the way the reference implementation does it.

Data files that contain ChordPro data are usually given a file name extension .cho. Other often used extensions are .crd, .chordpro, and .chopro.

General description of the ChordPro format

A ChordPro data file is a simple text file, which is interpreted line by line. Line endings should obey the rules of the platform. Chordii: Line endings according to the Unix, Linux, Microsoft Windows and OS/X platforms are all handled on all platforms.

ChordPro file processing tools may impose restrictions on the encoding of the data in the file. Some tools may require the data to be in ASCII encoding, other tools may allow a Unicode encoding. Chord version 3.6 and later accepts the full ISO 8859.1 (Latin1) character set. Chordii: Version 4.5 can be build to accept the full ISO 8859.2 character set.

Lines that have a # symbol at the very beginning of the line are ignored. They can be used to insert comments into the ChordPro file. These comments are completely ignored and should not be confused with the comment directive, see below.

Lines that start with { and end with } (curly brackets or braces) are directives. They are used to pass instructions to the program that processes the data. Leading and trailing whitespace is allowed, but discouraged.

Song lines

Lines that are not directives are song lines. They contain the lyrics of the song. Inside lyric lines the chords are specified between [ and ] (square brackets). Chords should immediately precede the syllable of text they apply to. For example:

Swing [D]low, sweet [G]chari[D]ot,
When processed, this results in:
D G D Swing low, sweet chariot,

Directives

Many directives have long and short alternatives. For example, the long form for the directive ‘title’ is title, and the short alternative is t. It is, however, advised to use the long alternative whenever possible, since the short alternatives may lead to confusion.

For directives that take arguments, the arguments are separated from the directive name by a : (colon) or a space. The reference implementation uses any sequence of colons and spaces to separate the parts of the directive.

Preamble directives

{new_song}
{ns}

Starts a new song. This is implied at the start of a ChordPro data file.

Metadata directives

{title:text}
{t:text}

Define text as the song title.
Chordii: The title is shown in a bigger size on top of the page.

{subtitle:text}
{st:text}

Define text as a subtitle. More than one subtitle is possible.
Chordii: The subtitles are shown under the title on top of the page.

Formatting directives

{comment:text}
{c:text}

Define text as a comment. The comment text will be shown in an outstanding manner. It can be used for example to call a chorus.
Chordii: The text is shown on a grey background.

{comment_italic:text}
{ci:text}

Similar to {comment:text}. The comment text will be shown in an outstanding manner, most likely using an italic font.
Chordii: The text is shown in an italic font on a grey background.

{comment_box:text}
{cb:text}

Similar to {comment:text}. The comment text will be shown in an outstanding manner, most likely using a box.
Chordii: The text is shown with a box drawn around it.

{start_of_chorus}
{soc}
{end_of_chorus}
{eoc}

Define the lines between start and end as the chorus. The lines are normal song lines, but will be shown in an outstanding manner.
Chordii: A vertical line is drawn to the left of the chorus part.

{start_of_tab}
{sot}
{end_of_tab}
{eot}

Defines a section of guitar TAB instructions.
Chordii: The text will be shown as is, in a fixed-width font so it aligns vertically.

{define ... }

Defines a guitar chord. There are several variant implementations of this command.
Chordii: {define:name base-fret offset frets pos pos ... pos}
pos … define the string positions, all relative to the offset. Strings are enumerated from left (lowest) to right (highest), as they appear in the chord diagrams.

Output related directives

{textfont:fontname}
{tf:fontname}

Sets the font used to print text to fontname. This must be the name of a known PostScript font.
Chordii: Default font for text is Times-Roman.

{textsize:fontsize}
{ts:fontsize}

Sets the size of the font used for texts.
Chordii: Default font size for text is 12.

{chordfont:fontname}
{cf:fontname}

Sets the font used to print chords to fontname. This must be the name of a known PostScript font.
Chordii: Default font for chords is Helvetica-Oblique.

{chordsize:fontsize}
{cs:fontsize}

Sets the size of the font used for chords.
Chordii: Default font size for chords is 9.

{chordcolour:colour}

 Chordii: Sets the colour used for chords.
Colour may be a known colour, such as red, or a #-coded colour, e.g. #fcfe1a.

{no_grid}
{ng}

Suppresses printing of the list of chords at the end of the current song.

{grid}
{g}

Enables printing of the list of chords at the end of the current song.
Chordii: The -g and -G command line options can be used to control what chords are printed.

{titles:flush}

Chordii: If flush is left, song titles are printed to the left of the page. If flush is center, or if this directive is missing, titles are printed centered on top of the page.

{new_page}
{np}

Forces a page break.
Chordii: When printing in 2-up or 4-up page mode, this command forces a logical page break. Otherwise it is the same as a physical page break.

{new_physical_page}
{npp}

Forces a physical page break.

{columns:number}
{col:number}

Specifies the number of columns to print the current song in.

{column_break}
{colb}

Forces a column break.

{pagetype:type}

Chordii: Sets the page type for the PostScript output. type can be either a4 or letter.