ChordPro 6 Release Information

Release information for the ChordPro file format.

For release information for the ChordPro program, see here.

Since ChordPro 5 never had an official release, its release notes have been merged here.

Markup

In all texts (lyrics, titles, chordnames, comments, etc.) markup instructions can be used to manipulate the appearance.

The markup instructions resemble the Pango Markup Language as defined by the Gnome organisation.

For example:

[C]Roses are <span color="red">red</span>, [G]<b>don't forget!</b>

The ChordPro program will produce something similar to:

Example markup

Annotations

Annotations are arbitrary remarks that go with a song. They are specified just like chords, but start with an * symbol.

For example:

[Em]This is the [*Rit.]end my [Am]friend.

The ChordPro program will produce something similar to:

Example annotation

Even though they are written using chord-like syntax, it is important to know that annotations are not chords. In particular:

  • ChordPro processing tools may choose to show annotations in a different way than chords.
  • No attempts will be made to transpose, transcode, or draw chord diagrams for annotations.

Images

Images can be inserted in the song using the image directive. Useful for logo’s and score fragments.

Example image

Delegates

Delegation is a means to pass arbitrary data to an external program that will generate an image. The image is then inserted as with the {image} directive.

A popular delegate is [ABC[(https://abcnotation.com/). The above example image could have been acquired via delegation:

{start_of_abc}
X:1
K:F
M:4/4
[AE]2 | [FC]6 [AC]2 | [FD]3 [FD] [(D(B,] [C)A,)]3 |

{end_of_abc}

Metadata

Metadata can be used to maintain information about the song. See also Using metadata in texts.

All metadata can be specified with a directive named after the metadatum, or with an explicit meta directive.

The following metadata are supported:

album
Specifies the album that contains the song. Multiple titles can be specified using multiple directives.
arranger
Specifies the arranger of the song. Multiple arrangers can be specified using multiple directives.
artist
Specifies the artist. Multiple artists can be specified using multiple directives.
capo
The position of the capo, if any.
composer
Specifies the composer of the song. Multiple composers can be specified using multiple directives.
copyright
Copyright information for the song in the form year rights holder.
duration
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 and 4:28 are the same.
key
Specifies the key the song is written in, e.g. C or Dm. Multiple specifications are possible, each specification applies from where it appears in the song.
lyricist
Specifies the writer of the lyrics of the song. Multiple lyricists can be specified using multiple directives. If no lyricist is specified, it is assumed that the composer did all the work.
sorttitle
Specifies the title to be used for sorting, e.g. in the table of contents.
tempo
Specifies the tempo in number of beats per minute for the song, e.g 80. Multiple specifications are possible, each specification applies from where it appears in the song.
time
Specifies the time signature for the song, e.g 4/4 or 6/8. Multiple specifications are possible, each specification applies from where it appears in the song.
year
The year this song was first published, as a four-digit number.

Conditional directives

All directives can be equipped with a selector by appending a selector name to the name of the directive, separated by a dash (hyphen) -. If the selector fails, the directive is skipped.

For example:

{define-ukulele Dm base-fret 1 frets 2 2 1 0}
{define-guitar  Dm base-fret 1 frets x 0 3 2 3 1}

This will define the appropriate Dm chord for either ukulele or guitar.

Selection can be reversed by appending a ! to the selector.

How selectors are defined depends on the ChordPro processing tool. The ChordPro program uses the config values for instrument.type and user.name.

Enhanced chord definitions

The define and chord directives have been enhanced to understand finger positions (for string instruments) and keyboard keys (for keyboards).

For example, for guitar:

{define  Dm base-fret 1 frets x 0 3 2 3 1 fingers 0 0 3 2 1 4}

For a keyboard:

{define  Dm keys 0 3 7 12}

Note that the keys are relative. 0 is the root, 3 the minor third, 7 the fifth and so on.

To modify an existing chord, use copy:

{define Bstar copy B frets x 2 4 4 x}

To change the name as shown, use display:

{define Bstar display B*}

All parts are optional. It is even possible to define a chord without additional information.

{define Bstar}

For more details, see Define Directive.

Chord grids

Not to be confused with chord diagrams, chord grids form an easy way to denote the rhythmic structure of a song part.

New lyrics section directives

The following directives are added:

  • start_of_verse (short: sov)
  • end_of_verse (short: eov)
  • start_of_bridge (short: sob)
  • end_of_bridge (short: eob)

The purpose of these directives is to be able to identify portions of the song. ChordPro processing tools may choose to use this information, e.g. to show a bridge in a different way than a verse.

In addition to these directives it is possible to add your own section directives, for example {start_of_lead} or {start_of_coda}. All sections must be closed with the corresponding {end_of_section}.

The ChordPro program treats all sections (except chorus, tab, grid, abc and ly) as lyrics.

Modified section directives

In a tab section ({start_of_tab} or {sot} the lines that follow are taken as literally as possible. The lines will not be folded or changed. Markup is left as is, and directives are considered literal text except for {end_of_tab} and {eot}.

Section labels

All section directives can take an optional label, which can be used to tag individual sections. For example:

{start_of_verse: Verse 1}
[A]Hello there!
{end_of_verse}
 
{start_of_verse: Verse 2}
[B]Nice seeing you.
{end_of_verse}

The ChordPro program will add a left margin to the output and place the label text in this margin.

Example labels

New directives for fonts, sizes and colours (v5)

You can set fonts, sizes and colours for text (lyrics), chord, title, footer, toc (table of contents), and tab.

For example:

{titlecolour:blue}
{footersize:10}

Without argument a setting will revert to its previous value, e.g.

{textsize:14}
[A]Lyrics size 14
{textsize:20}
[B]Lyrics size 20
{textsize}
[C]Lyrics size 14

New directive: highlight (v5)

This is a synonym to comment. It is included for compatibility with 3rd party implementations of the ChordPro file format.

New directive: chord (v5)

This directive is syntactically identical to define, but instead of defining a new chord it displays the chord diagram where it occurs.