Configuration file contents

General settings

These settings control global behaviour of the ChordPro program and can be changed from the command line.

// General settings, to be changed by legacy configs and
// command line.
"settings" : {
    // Titles flush: default center.
    "titles" : "center",
    // Columns, default one.
    "columns" : 1,
    // Suppress empty chord lines.
    // Overrides the -a (--single-space) command line options.
    "suppress-empty-chords" : true,
    // Suppress chords.
    // Overrides --lyrics-only command line option.
    "lyrics-only" : false,
    // Chords inline.
    // May be a string containing pretext %s posttext.
    // Defaults to "[%s]" if true.
    "inline-chords" : false,
    // Chords under the lyrics.
    "chords-under" : false,
    // Memorize chords.
    "memorize" : false,
    // Transcoding.
    "transcode" : null,
    // Always decapoize.
    "decapo" : false,
},

Metadata

The metadata setting contains three items:

keys: The list of recognized metadata keys.
For these keys you can use {meta key ...} as well as {key ...}.
strict: If true, {meta ...} will accept any key.
Otherwise, only the keys named in the keys here are allowed.
separator: To concatenate multiple values when metadata are used in title fields.

Important: the keys title and subtitle must always be in this list.

"metadata" : {
    "keys" : [ "title", "subtitle",
               "artist", "composer", "lyricist", "arranger",
               "album", "copyright", "year",
               "key", "time", "tempo", "capo", "duration" ],
    "strict" : true,
    "separator" : "; ",
},

Instrument description

Describes the instrument used. For example:

"instrument" : "Guitar, 6 strings, standard tuning",

Other properties of an instrument are its tuning and chord definitions. Usually the instrument definition is maintained in a separate configuration file for maximum flexibility.

See Defining an instrument for details.

Strings and Tuning

Define the instrument tuning as a list of notes in scientific pitch notation.

For example, to specify tuning for a 4-string soprano ukulele:

"tuning" : [ "G4", "C4", "E4", "A4" ],

Setting the tuning to any value except null will discard all built-in chords!

User defined chords

The configuration file can hold any number of predefined chords.

// "base" defaults to 1.
// Use 0 for an empty string, and -1 for a muted string.
"chords" : [
    {
        "name"  : "Bb(low)",
        "base"  : 1,
        "frets" : [ 1, 1, 3, 3, 3, 1 ],
        "fingers" : [ 1, 1, 2, 3, 4, 1 ],
    },
    {
        "name"  : "Bb(high)",
        "base"  : 6,
        "frets" : [ 1, 3, 3, 2, 1, 1 ],
        "fingers" : [ 1, 3, 4, 2, 1, 1 ],
    },
],

base specifies the topmost position of the chord diagram. It must be 1 or higher. If base is greater than 1 its value is printed at the side the diagram, as can be seen in the illustration below.

The frets positions are the positions in the chord diagram as shown. The following two definitions are the same chord, shown in two different positions:

{ "name" : "F#", "base" : 1, "frets" : [ 2, 4, 4, 3, 2, 2 ] },
{ "name" : "F#", "base" : 2, "frets" : [ 1, 3, 3, 2, 1, 1 ] },

As can be seen, the "fingers" part is optional.

It is possible to define a new chord based upon an existing definition, e.g.

{ "name" : "Bmin"      , "copy" : "Bm" },
{ "name" : "F#"        , "copy" : "F", "base" : 2 },

Printing chord diagrams

By default, ChordPro will include diagrams for all known chords that have been used in a song.

// "auto": automatically add unknown chords as empty diagrams.
// "show": prints the chords used in the song.
//         "all": all chords used.
//         "user": only prints user defined chords.
//         "none": no song chords will ne printed.
// "sorted": order the chords by key.
"diagrams" : {
    "auto"     :  false,
    "show"     :  "all",
    "sorted"   :  false,
},

If auto is set to true, unknown chords will be printed as empty diagrams. This makes it easy to manually put the finger positions on paper. Of course, adding a chord definition is usually a better alternative.

Here you can set the title text for the table of contents. By default this is the string "Table of Contents".

The song titles in the table of contents are in the same order as in the document. By setting order to "alpha", the titles are sorted alphabetically.

// Table of contents.
"toc" : {
    // Title for ToC.
    "title" : "Table of Contents",
    // Sorting order.
    // Currently only sorting by page number and alpha is implemented.
    "order" : "page",
},

Includes

A config file can specify a list of other config files that are to be processed before the contents of the current file. This makes it straightforward to create config files that extend existing config files.

For example:

{ "include" : [ "modern1" ],
  "settings" : {
      "colums" : 2
  }
}

This config file would first load the preset config modern1, and then set the number of output columns to 2.

include takes a list of preset configs like modern1, or file names. If a file name is not absolute, it is taken relative to the location of the including config file.

Diagnostic message format

When ChordPro detects errors while analyzing a song, it will use this format to show diagnostic messages.

In the format, %f will be replaced by the song file name, %n by the line number in the file where the error was detected, %m by the diagnostig message, and %l will be replaced by the original content of the line.

"diagnostics" : {
    "format" : "\"%f\", line %n, %m\n\t%l",
},

Configuration file contents - Generic