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

See the 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
$schema string

The schema for this config file.

Default: ""
config object

For GUI.

6 nested properties
type const: "config" | const: "style" | const: "stylemod" | const: "instrument" | const: "task" | string | string[]

One or more of "config", "style", "style_mod", "instrument", "task" ...

title string

Title for menus, choices, if applicable.

description string

Helpful descriptive text.

exclude_id boolean | string

Exclusive control. If multiple configs have the same exclude_id, only one will be used.

default boolean

True if this is the default config for a specific type. Do not use unless you know what you are doing!

omit boolean

Do not show this config in the GUI.

include string[]

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 control global behaviour of the ChordPro program and can be changed by configs and command line.

27 nested properties
chordnames string

Strictness of parsing chord names. Values are "strict" (only known chord forms) 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[]

Either the number of columns, default: 1, or an array with column widths.

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

Eliminate capo by transposing chords.

Default: false
common-keys boolean

Replace keys with more than 6 sharps or flats by their more common enharmonic equivalents.

Default: true
enharmonic-transpose boolean

Force enharmonic when transposing (experimental).

Default: true
fsharpkey boolean

The key F# (6 sharps) is usually represented as its enharmonic equivalent Gb (6 flats). Set this to true if you want F sharp instead of G flat.

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.

Default: true
lyrics-only boolean

Suppress chords, only outputs lyrics.

Default: false
maj7delta boolean

Substitute delta for maj7 in chord names. This will fallback to the ChordProSymbols 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

Stricter checks and more warnings.

Default: true
suppress-empty-chords boolean

Suppress empty chord lines.

Default: true
suppress-empty-lyrics boolean

Suppress blank lyrics lines.

Default: true
titles string

Titles flush. Obsolete, use page headings/footers instead.

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

Transcode chords to a different notation system.

Default: ""
transpose number | string

Transpose the song by a number of semitones. A positive number transposes up, a negative number transposes down. An optional postfix of "s" or "f" can be used to enforce the use of sharps resp. flats when a transposed chord requires accidentals. A postfix of "k" will use the key signature to determine whether flats or sharps are needed.

Default: 0
pattern=^[-+]?\d+[sf]?$
transpose-sf-key boolean

Always apply "k" semantics if no other postfix was specified.

Default: false
truesf boolean

Substitute Unicode sharp/flats in chord names. This will fallback to the ChordProSymbols the selected chord 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"
wraplines boolean

Wrap long lines. This may trigger issue #355.

Default: true
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

Showing chord diagrams. Selects which chords to show 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

Shows selected or all chord diagrams at end. "all": shows all chords "user": shows user defined chords only "none": suppresses chords from being printed.

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. See the docs for details.

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 description 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: ""
keys object

ChordPro tries to follow ABC (abc2svg) as much as possible.

2 nested properties
flats boolean

The key F# is often used as is and not represented as an enharmonic equivalent. Set this to true if you want Gb instead of F#.

Default: false
force-common boolean

Replace keys with an excessive number of sharps by their more common enharmonic equivalents. See also settings.transpose-sf-key.

Default: false
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
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 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 always use real sharps and flats for output, but many 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 sounding 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"

The default classifier is "pct_chords" and is based on the percentage of chords recognized.

Default: "pct_chords"
7. object object
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

Settings for the parser/preprocessor. 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. Use wisely.

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
25 nested properties
a2crd boolean | integer
abc boolean | integer
assets boolean | integer
chords boolean | integer
config boolean | integer
csv boolean | integer
echo boolean | integer
fonts boolean | integer
images boolean | integer
layout boolean | integer
ly boolean | integer
meta boolean | integer
mma boolean | integer
ops boolean | integer
paths boolean | integer
pp boolean | integer
runtimeinfo boolean | integer
song boolean | integer
songfull boolean | integer
spacing boolean | integer
svg boolean | integer
txtblk boolean | integer
x1 boolean | integer
x2 boolean | integer
x3 boolean | integer

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 the 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
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", For filtering plugins. const: "filter"
handler string required
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.

Default: ""
preprocess object

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

omit boolean

If true, no delegation will be handled.

Default: false
html

Specific settings for the HTML backend.

pdf

Specific settings for the PDF backend.

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

Settings for the parser/preprocessor. 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. Use wisely.

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 boolean | integer
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.