ChordPro Configuration

Configuration files for ChordPro

File match *.chordpro.json chordpro.json *.chordpro.yaml *.chordpro.yml chordpro.yaml chordpro.yml
Schema URL https://catalog.lintel.tools/schemas/schemastore/chordpro-configuration/latest.json
Source https://raw.githubusercontent.com/ChordPro/chordpro/master/lib/ChordPro/res/config/config.schema

Validate with Lintel

npx @lintel/lintel check

A configuration file for ChordPro. See ChordPro website for more details: https://www.chordpro.org/chordpro/chordpro-configuration-file/. This is a really relaxed JSON document, see https://metacpan.org/pod/JSON::Relaxed#REALLY-RELAXED-EXTENSIONS

All of

1. Generic Part object
include string[]

Includes are processed first, before the rest of the config file.

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. "include" takes a list of either filenames or preset names. If a file name is not absolute, it is taken relative to the location of the including config file.

Examples: ["guitar"]
settings object

General settings, often changed by configs and command line.

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

23 nested properties
chordnames string

Strictness of parsing chord names.

Strict (only known) or relaxed (anything that looks sane).

Default: "strict"
Values: "relaxed" "strict"
chords-canonical boolean

Always replace chords by their canonical form.

Default: false
chords-under boolean

Chords under the lyrics.

Default: false
choruslabels boolean

If false, chorus labels are used as tags.

Default: true
columns integer | enum | string | number[]

Number of columns, default: 1.

Default: 1
Examples: 2, ["*","50%"], ["50%","50%"], [0,0]
decapo boolean

Eliminate capo by transposing chords.

Default: false
enharmonic-transpose boolean

Force enharmonic when transposing (experimental).

Default: true
inline-annotations string

Annotations inline instead of above. Ignored unless inline-chords is set. Must be a string containing pretext %s posttext. Default is "%s".

Default: "%s"
inline-chords string | boolean

Chords inline instead of above. May be a string containing pretext %s posttext. Defaults to "[%s]" if set to a value that doesn't contain "%s".

Default: false
lineinfo boolean

Obsolete. Add line info for backend diagnostics.

Default: true
lyrics-only boolean

Suppress chords, only outputs lyrics. Command line: -l (--lyrics-only)

Default: false
maj7delta boolean

Substitute delta for maj7 in chord names. Will fallback to the ChordProSymbols font if the selected chord font doesn't have the glyphs.

Default: false
memorize boolean

Deprecated, Do not use.

Default: false
notenames boolean

Allow parsing of note names in [].

Default: false
strict boolean

Chords parsing strategy. Strict (only known chords) or relaxed (anything that looks sane).

Default: true
suppress-empty-chords boolean

Suppress empty chord lines. Command line: -a (--single-space).

Default: true
suppress-empty-lyrics boolean

Suppress blank lyrics lines.

Default: true
titles string

Titles flush.

Default: "center"
Values: "center" "left" "right"
transcode noteSystem | const: ""

Transcode chords to a different notation system.

Default: ""
transpose integer

Transpose chords.

Default: 0
min=-12max=12
truesf boolean

Substitute Unicode sharp/flats in chord names. Will fallback to ChordProSymbols the font doesn't have the glyphs.

Default: false
wrapindent string

Indent for wrapped lines. Actual indent is the width of the provided string value.

Default: "x"
flowtext boolean

Consider text flowed.

Default: false
chord-formats object

Format to show chord names. May contain markup

3 nested properties
common string

Format string for rendering common chord names.

Default: "%{root|%{}%{qual|%{}}%{ext|%{}}%{bass|/%{}}|%{name}}"
roman string

Format string for rendering roman chord names.

Default: "%{root|%{}%{qual|<sup>%{}</sup>}%{ext|<sup>%{}</sup>}%{bass|/<sub>%{}</sub>}|%{name}}"
nashville string

Format string for rendering nashville chord names.

Default: "%{root|%{}%{qual|<sup>%{}</sup>}%{ext|<sup>%{}</sup>}%{bass|/<sub>%{}</sub>}|%{name}}"
diagrams object

Printing chord diagrams. Selects which chords to print at the end of the song. By default, ChordPro will include diagrams for all known chords that have been used in a song. The suppress list can be used to filter chords from showing diagrams, for example for chords that you consider trivial. Note: The type of diagram (string or keyboard) is determined by the value of instrument.type.

3 nested properties
show string

Which chords used in the song to print.

Default: "all"
One of: Prints all chords used const: "all", Only prints user-defined chords const: "user", No song chords will be printed const: "none"
sorted boolean

Sorts the diagrams by key. Default is order of appearance.

Default: false
suppress string[]

Chords (names) that will not generate diagrams, e.g. if they are considered trivial.

Default:
[]
assets object

Assets (placeholder).

chords object[]

User-defined chords. This is an array of hashes, one for each chord.

Default:
[]
contents object[]

Tables of contents. An array of hashes each describing one table of contents.

diagnostics object

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. Note you cannot use song metadata here.

1 nested properties
format string

Format for error messages.

Default: ""%f", line %n, %m\n\t%l"
gridstrum object

Grid strum overrides.

1 nested properties
symbols object

Symbol or Unicode code points for the glyphs from ChordProSymbols.

instrument object

Description of the instrument. Actual values are set from an included instrument config.

2 nested properties
description string

Descriptive instrument name.

Default: ""
type string

Instrument type.

Default: ""
markup object

Settings for the markup processor. Shortcodes allow user defined markup, e.g. ....

markup.shortcode {
   heavy :  "weight='bold' size='large'"
}
Each occurrence of <heavy>...</heavy> will be replaced by
<span weight='bold' size='large'>...</span>.
1 nested properties
shortcodes object
meta Record<string, object>

Globally defined (added) meta data, This is explicitly NOT intended for the metadata items above. Do NOT remove or change _configversion!

Default:
{
  "_configversion": [
    6
  ]
}
1 nested properties
_configversion string | number

Config file version.

metadata object

Metadata. For these keys you can use {meta key ...} as well as {key ...}.

4 nested properties
autosplit boolean

Split data on separator. If enabled, metadata will be split on the separator to provide multiple values.

Default: true
keys string[]

The list of known metadata keys. For these keys you can use {meta key …} as well as {key …}. Important: "title" and "subtitle" must always be in this list.

Default:
[
  "title",
  "subtitle",
  "artist",
  "composer",
  "lyricist",
  "arranger",
  "album",
  "copyright",
  "year",
  "key",
  "time",
  "tempo",
  "capo",
  "duration"
]
uniqueItems=true
separator string

The separator is used to concatenate multiple values. To concatenate multiple values when metadata are used in title fields. If autosplit is true, the separator is also used to split values upon input.

Default: "; "
strict boolean

If true, {meta …} will only accept the keys named here in the keys field. Otherwise, any key will be accepted.

Default: true
notes object

Note (chord root) names. In case of alternatives, the first one is used for output. Note that it is tempting to use real sharps and flats for output, but most fonts don't have the glyphs.

4 nested properties
system string
One of: C, D, E, F, G, A, B const: "common", same as `common` const: "dutch", C, … A, Ais/B, H const: "german", Do, Re, Mi, Fa, Sol, … const: "latin", 1, 2, 3, … const: "nashville", I, II, III, … const: "roman", C, … A, A#/Bb, H const: "scandinavian", same as `solfège` const: "solfege", Do, Re, Mi, Fa, So, … const: "solfège"
movable boolean

Movable means position independent (e.g. nashville).

Default: false
sharp string | string[][]

Each item in the array is 1 note, chromatically from C up to B. If the element is a string, it's the only possible representation of that note. If it's an array, it's all of its possible representations.

uniqueItems=true
flat string | string[][]

Each item in the array is 1 note, chromatically from C up to B. If the element is a string, it's the only possible representation of that note. If it's an array, it's all of its possible representations.

uniqueItems=true
dates object

Defines the date format used by the metadata value today. Format is a strftime template, so the format string can use anything that strftime understands.

1 nested properties
today object

Today's date.

1 nested properties
format string

Format.

Default: "%A, %B %e, %Y"
tuning string[]

Definition of the strings for this instrument in scientific pitch notation. This is usually set from an included instrument config. Note that string 1 is the highest string. If tuning is not relevant to the instrument, setting the tuning to [ 0 ] flushes all existing definitions.

Default:
[
  "E2",
  "A2",
  "D3",
  "G3",
  "B3",
  "E4"
]
Examples: ["G4","C4","E4","A4"], [0]
user object

User settings. These (optional) settings can be used to add user information.

2 nested properties
name string

Short user name.

Default: ""
fullname string

Full user name.

Default: ""
toc object

Deprecated. Table of Contents (obsolete, do not use).

3 nested properties
line string
Default: "%{title}"
order string
Default: "page"
Values: "page" "alpha"
title string
Default: "Table of Contents"
2. PDF Output object
pdf object

Settings for PDF output.

All of: backendspec object, variant
3. HTML Output object
html object

Settings for HTML output.

All of: backendspec object, variant
4. ChordPro Output object
chordpro object

Settings for ChordPro (output) backend.

All of: backendspec object, backendChorusRecallSettings object
5. Delegate Configuration object
delegates Record<string, object>

Delegates. Basically a delegate is a section {start_of_XXX} which content is collected and handled later by the delegate module.

6 nested properties
abc object
All of: delegatespec object, variant
grille

Embedding Grilles. EXPERIMENTAL

All of: delegatespec object, object object
ly object
Any of: delegatespec object, variant
strum

Embedding Strums. EXPERIMENTAL

All of: delegatespec object, object object
svg object

Embedding SVG.

Default:
{
  "type": "image",
  "module": "SVG",
  "handler": "svg2svg"
}
All of: delegatespec object, variant
textblock

Embedding textblock.

Default:
{
  "type": "image",
  "module": "TextBlock",
  "handler": "txt2xform"
}
All of: delegatespec object, object object
6. ASCII text to ChordPro converter object
a2crd object

Settings for A2Crd (input) frontend.

3 nested properties
infer-titles boolean

Treat leading lyrics lines as title/subtitle lines. The first non-empty, non-chord, non-directive lines are taken to be the song title and subtitle.

Default: true
tabstop number

Tab stop width for tab expansion. Set to 0 to disable. Tabs in the input source are replaced by an appropriate amount of spaces.

Default: 8
classifier const: "pct_chords" | const: "classic"

Analysis strategy. Several strategies to recognize chords and lyrics lines are implemented by classifiers. Feel free to choose the strategy that yields the best results for your date.

Default: "pct_chords"
7. Settings for the parser/preprocessor object

For selected lines, you can specify a series of { "target" : "xxx", "replace" : "yyy" }. Every occurrence of "xxx" will be replaced by "yyy". Use "pattern" instead of "target" for regular expression replacement. ChordPro allows using Unicode escape sequence in the form \uXXXX. In case you need more (or less) hexadecimal digits, you can use the following preprocessor directive to replace \u{XXXX} (with an arbitrary number of hex digits) by the corresponding unicode character. Use wisely.

parser object
Default:
{
  "preprocess": {
    "all": [],
    "directive": [],
    "songline": []
  }
}
2 nested properties
altbrackets string | null

For the exceptional case you need brackets [] in your lyrics or annotations. These characters are replaced by normal brackets after chord analysis. E.g. parser.altbrackets: "«»" Use wisely. Better still, don't use this.

Default: null
preprocess object
3 nested properties
all parserPreprocessingElement[]
directive object[]
songline parserPreprocessingElement[]
8. Text Output object
text object
1 nested properties
chorus object

Appearance of chorus recall. Default: print the tag using the type. Alternatively quote the lines of the preceding chorus. If no tag+type or quote: use {chorus}. Note: Variant 'msp' always uses {chorus}.

Default:
{
  "recall": {
    "tag": "",
    "type": "",
    "quote": false
  }
}
Examples: {"recall":{"tag":"Chorus","type":"comment"}}
1 nested properties
recall object
Any of: variant, variant
9. LaTeX Configuration object
latex object

Settings for LaTeX backend.

Default:
{
  "template_include_path": [],
  "templates": {
    "songbook": "songbook.tt",
    "comment": "comment.tt",
    "image": "image.tt"
  }
}
All of: backendspec object, variant
10. Debugging object
debug object

Miscellaneous debug settings.

25 nested properties
a2crd integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
abc integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
assets integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
chords integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
config integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
csv integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
echo integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
fonts integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
images integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
layout integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
ly integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
meta integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
mma integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
ops integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
paths integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
pp integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
runtimeinfo integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
song integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
songfull integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
spacing integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
svg integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
txtblk integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
x1 integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
x2 integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1
x3 integer

A boolean value represented as an integer, 0 for false and 1 for true.

Values: 0 1

Definitions

backendspec object

Standard properties for backends.

comments string

Retain comments in the output.

Default: "ignore"
Values: "ignore" "retain"
themeColor string

Names of colours in theme.

colorspec string
color themeColor | colorspec
chordDiagramPDFLayout object
show string | const: false

Diagrams for all chords of the song can be shown at the "top", "bottom" or "right" side of the first page, or "below" the last song line. Set to false to not show any diagrams.

Default: "bottom"
Values: "top" "bottom" "below" "right" false
align string

Alignment for when show is set to "top", "bottom" or "below".

Default: "left"
Values: "left" "right" "center" "spread"
pageFormat object

Page format. All elements can have three fields, that are placed to the left side, centered, and right side of the page.

title tptspecArray | tptspecArray[] | boolean | null

Three-part title format specification, left, center, right.

subtitle tptspecArray | tptspecArray[] | boolean | null

Three-part title format specification, left, center, right.

footer tptspecArray | tptspecArray[] | boolean | null

Three-part title format specification, left, center, right.

background string

Page background. This can be used to designate an existing PDF document to be used as the background of the output page. It has the form filename or filename:page. Page numbers count from one. If odd/even printing is in effect, the designated page number is used for left pages, and the next page (if it exists) for right pages.

Examples: "examples/bgdemo.pdf", "examples/bgdemo.pdf:5"
fontConfigFont object
string required
bold string
italic string
bolditalic string
oblique string
boldoblique string
fontClass string
delegatespec object

Shared properties between all delegate types.

type string required

The result produced by the delegate handler.

Default: "image"
One of: Expects the section to produce an image that will be embedded in the ChordPro output. const: "image", Treats the section as a generic section. const: "none", Ignores the section. const: "omit"
handler string required

The entry point in the module.

Default: "default"
module string required

The name of the (perl) module that implements the delegate.

align string

Horizontal alignment of the resulting image, if type is image.

Default: "center"
Values: "left" "center" "right"
subtype enum | enum

Type of the image produced. If not specified, it will be auto-detected. For standard delegates, this is ignored, as they already know which type of image will be produced. For cusotm delegates, this can be optionally specified if type is set to "image".

config string
Default: "default"
preamble string[]

Input lines to prepend to the user data

program string

The program/command to execute. It will be wrapped in quotes when used, so paths with spaces will work without issue.

Default: ""
preprocess object

Obsolete. Please use parser.preprocess.env-... instead.

omit boolean

If true, no delegation will be handled.

Default: false
fontDescription string

A shorthand description of a font. In the format of fontclass (bold)?(italic)? fontsize.

Examples:
  • "serif bold 14"
  • "serif 11"
  • "serif 12"
  • "sans italic 10"
  • "sans italic 12"
  • "monospace 10"
  • "serif 11"
  • "sans 10"
  • "dingbats 10"
fontspec fontDescription | object

Font specification.

Examples:
  • { "description": "sans 12", "background": "foreground-light" }
  • { "description": "sans italic 12", "background": "foreground-light" }
tptspecArray string[]
tptspec tptspecArray | tptspecArray[] | boolean | null

Three-part title format specification, left, center, right.

abcDelegateFields object
lyDelegateFields object
parserPreprocessingElement object
replace string required

A string that replaces occurrences of target/pattern.

flags string

Regular expression flags.

Examples: "g", "gi"
parserspec object
altbrackets string | null

For the exceptional case you need brackets [] in your lyrics or annotations. These characters are replaced by normal brackets after chord analysis. E.g. parser.altbrackets: "«»" Use wisely. Better still, don't use this.

Default: null
preprocess object
3 nested properties
all parserPreprocessingElement[]
directive object[]
songline parserPreprocessingElement[]
backendChorusRecallSettings object
chorus object

Appearance of chorus recall. Default: print the tag using the type. Alternatively quote the lines of the preceding chorus. If no tag+type or quote: use {chorus}. Note: Variant 'msp' always uses {chorus}.

Default:
{
  "recall": {
    "tag": "",
    "type": "",
    "quote": false
  }
}
Examples: {"recall":{"tag":"Chorus","type":"comment"}}
1 nested properties
recall object
Any of: variant, variant
3 nested properties
tag string

Label for recalled chorus.

Default: "Chorus"
type string

Type for tag text.

Default: "comment"
Values: "" "comment" "comment_italic" "comment_box"
quote boolean

Quote the chorus.

Default: false
booleanInt integer

A boolean value represented as an integer, 0 for false and 1 for true.

noteSystem string
noteNameArray string | string[][]

Each item in the array is 1 note, chromatically from C up to B. If the element is a string, it's the only possible representation of that note. If it's an array, it's all of its possible representations.