# ChordPro directives

ChordPro directives are used to control the appearance of the printed output. They define meta-data like titles, add new chords, control page and column breaks. Therefore it is not always easy to make a distinction between the semantics of a directive, and the way these semantics are implemented in the ChordPro processing program, the formatter.

For example, the title directive.

{title: Swing Low Sweet Chariot}

The directive name is ‘title’, and its argument is the text ‘Swing Low Sweet Chariot’. This directive defines meta-data, the song title. That is the semantic part. What the formatter does with this meta-data is up to the program and not part of the ChordPro File Format Specification. You can consider directives to be a friendly request, or suggestion, but the actual implementation is left to the formatter. For a meta-data item like the song title it will probably be printed on top of the page and be included in a table of contents, if any.

The Chordpro Reference Implementation provides a default implementation in the style of the original chord program. It can be used as a reference to what a directive is assumed to do. It must however be emphasised that the reference implementation can be configured to use different page styles, fonts, sizes, colours, and so on. Where appropriate, this document refers to the default style.

Many directives have long and short names. For example, the long (full) name for the directive title is ‘title’, and the short (abbreviated) name is ‘t’. It is, however, advised to use the full name whenever possible, since the abbreviations may lead to confusion or ambiguity if new directives are added.

For directives that take arguments, the arguments are separated from the directive name by a colon : and/or whitespace.

# Preamble directives

• new_song (short: ns)

# Meta-data directives

Each song can have meta-data associated, for example the song title. Meta-data are mostly used by programs that help organizing collections of ChordPro songs.

• title (short: t)
• sorttitle
• subtitle (short: st)
• artist
• composer
• lyricist
• copyright
• album
• year
• key
• time
• tempo
• duration
• capo
• meta

See also Using metadata in texts.

# Formatting directives

• comment (short: c)
• highlight
• comment_italic (short: ci)
• comment_box (short: cb)
• image

# Environment directives

Environment directives always come in pairs, one to start the environment and one to end it.

• Introduction to environments
• start_of_chorus (short: soc), end_of_chorus (short: eoc)
• chorus
• start_of_verse (short: sov), end_of_verse (short: eov)
• start_of_bridge (short: sob), end_of_bridge (short: eob)
• start_of_tab (short: sot), end_of_tab (short: eot)
• start_of_grid (short: sog), end_of_grid (short: eog)

# Delegated environment directives

These environment directives turn their content into something else, usually an image, and embed the result in the ChordPro output.

• Introduction to delegated environments
• start_of_abc / end_of_abc
• start_of_ly / end_of_ly
• start_of_svg / end_of_svg
• start_of_textblock / end_of_textblock

# Chord diagrams

• define
• chord

# Transposition

• transpose

# Fonts, sizes and colours

These directives can be used to temporarily change the font, size and/or colour for lyrics, chords, and more. To permanently change these the reference implementation uses much more powerful configuration files.

• chordfont (short: cf), chordsize (short: cs), chordcolour
• chorusfont, chorussize, choruscolour
• footerfont, footersize, footercolour
• gridfont, gridsize, gridcolour
• tabfont, tabsize, tabcolour
• tocfont, tocsize, toccolour
• textfont (short: tf), textsize (short: ts), textcolour
• titlefont, titlesize, titlecolour

# Output related directives

• new_page (short: np)
• new_physical_page (short: npp)
• column_break (short: colb)
• pagetype

The following directives are legacy from the old chord program. The modern reference implementation uses much more powerful configuration files for this purpose.

• diagrams
• grid (short: g)
• no_grid (short: ng)
• titles
• columns (short: col)

# Custom extensions

To facilitate using custom extensions for application specific purposes, any directive with a name starting with x_ should be completely ignored by applications that do not handle this directive. In particular, no warning should be generated when an unsupported x_directive is encountered.

It is advised to follow the x_ prefix by a tag that identifies the application (namespace). For example, a directive to control a specific pedal setting for the MobilsSheetsPro program could be named x_mspro_pedal_setting.

# Conditional directives

All directives can be conditionally selected by postfixing the directive with a dash (hyphen) and a selector.

If a selector is used, ChordPro first tries to match it with the instrument type (as defined in the config file). If this fails, it tries to match it with the user name (as defined in the config file). Finally, it will try it as a meta item, selection will succeed if this item exists and has a ‘true’ value (i.e., not empty, zero, false or null). Selection can be reversed by appending a ! to the selector.

For example, to define chords depending on the instrument used:

{define-guitar:  Am base-fret 1 frets 0 2 2 1 0 0}
{define-ukulele: Am base-fret 1 frets 2 0 0 0}

An example of comments depending on voices:

{comment-alto:  Very softly!}
{comment-tenor: Sing this with power}

When used with sections, selection applies to everything in the section, up to and including the final section end directive:

{start_of_verse-soprano}
...anything goes, including other directives...
{end_of_verse}

Note that the section end must not include the selector.