NAME

ChordPro - A lyrics and chords formatting program

SYNOPSIS

perl -MChordpro -e run -- [ options ] [ file ... ]

When the associated chordpro program has been installed correctly:

chordpro [ options ] [ file ... ]

DESCRIPTION

chordpro will read one or more text files containing the lyrics of one or many songs plus chord information. chordpro will then generate a photo-ready, professional looking, impress-your-friends sheet-music suitable for printing on your nearest printer.

Typical ChordPro input:

{title: Swing Low Sweet Chariot}
{subtitle: Traditional}

{start_of_chorus}
Swing [D]low, sweet [G]chari[D]ot,
Comin' for to carry me [A7]home.
Swing [D7]low, sweet [G]chari[D]ot,
Comin' for to [A7]carry me [D]home.
{end_of_chorus}

# Verse
I [D]looked over Jordan, and [G]what did I [D]see,
Comin' for to carry me [A7]home.
A [D]band of angels [G]comin' after [D]me,
Comin' for to [A7]carry me [D]home.

{c: Chorus}

chordpro is a rewrite of the Chordii program.

For more information about the ChordPro file format, see https://www.chordpro.org.

COMMAND LINE OPTIONS

--about (short: -A)

Prints version information about the ChordPro program. No other processing will be done.

--back-matter=FILE

Appends the contents of the named PDF document to the output. This can be used to produce documents with back matter pages.

--config=JSON (shorter: --cfg)

A JSON file that defines the behaviour of the program and the layout of the output. See ChordPro::Config for details.

This option may be specified more than once. Each additional config file overrides the corresponding definitions that are currently active.

--cover=FILE

See --front-matter.

--csv

When generating PDF output, also write a CSV file with titles and page numbers. Some tools, e.g., MobileSheets, can use the CSV to process the PDF as a collection of independent songs.

The CSV has the same name as the PDF, with extension .pdf replaced by .csv.

--decapo

Eliminate capo settings by transposing the song.

--diagrams=WHICH

Prints diagrams of chords used in a song.

WHICH can be all to print all chords used, user to only print the user-defined chords, and none to suppress printing of chord diagrams.

--encoding=ENC

Specify the encoding for input files. Default is UTF-8. ISO-8859.1 (Latin-1) encoding is automatically sensed.

--filelist=FILE

Read the names of the files to be processed from the named file.

This option may be specified multiple times.

Song file names listed on the command line are processed after the files from the filelist arguments.

--front-matter=FILE --cover=FILE

Prepends the contents of the named PDF document to the output. This can be used to produce documents with front matter (cover) pages.

--lyrics-only (short: -l)

Only prints lyrics. All chords are suppressed.

Useful to make prints for singers and other musicians that do not require chords.

--no-csv

Suppresses generating the CSV file. See --toc.

--no-strict

Enables liberal interpretation of the input with regard to the ChordPro standard. Most notably, unknown directives will not not flagged as warnings but silently ignored.

This makes it more convenient to process ChordPro files have custom directives.

--no-toc

Suppresses the table of contents. See --toc.

--output=FILE (short: -o)

Designates the name of the output file where the results are written to.

The filename extension determines the type of the output. It should correspond to one of the backends that are currently supported:

pdf

Portable document format (PDF).

txt

A textual representation of the input, mostly for visual inspection.

cho

A functional equivalent version of the ChordPro input.

--start-page-number=N (short: -p)

Sets the starting page number for the output.

--strict

Requires the input to be strictly compliant to the ChordPro standard.

This is enabled by default. See also --nostrict.

--subtitle=XXX

Subtitle (for songbooks).

--title=XXX

Title (for songbooks).

If specified and a table of contents is requested, a nice coverpage will be added.

--toc (short: -i)

Includes a table of contents.

By default a table of contents is included in the PDF output when it contains more than one song.

--transpose=N (short: -x)

Transposes all songs by N semi-tones. Note that N may be specified as +N to transpose upward, using sharps, or as -N to transpose downward, using flats.

--version (short: -V)

Prints the program version and exits.

Chordii compatibility options

The following Chordii command line options are recognized. Note that not all of them actually do something.

Options marked with * are better specified in the config file.

Note: Chordii used the term _grid_ for chord diagrams. It should not be confused with ChordPro grids.

--text-font=FONT (short: -T) *

Sets the font used to print lyrics and comments.

FONT can be either a full path name to a TrueType font file, or the name of one of the standard fonts. See section "FONTS" for more details.

--text-size=N (short: -t) *

Sets the font size for lyrics and comments.

--chord-font=FONT (short: -C) *

Sets the font used to print the chord names.

FONT can be either a full path name to a TrueType font file, or the name of one of the standard fonts. See section "FONTS" for more details.

--chord-size=N (short: -c) *

Sets the font size for the chord names.

--chord-grid-size=N (short: -s) *

Sets the total width of a chord diagram.

--chord-grids

Prints chord diagrams of all chords used in a song.

--no-chord-grids (short: -G) *

Disables printing of chord diagrams of the chords used in a song.

--easy-chord-grids

Not supported.

--no-easy-chord-grids (short: -g)

Not supported.

--chord-grids-sorted (short: -S) *

Prints chord diagrams of the chords used in a song, ordered by key and type.

--no-chord-grids-sorted *

Prints chord diagrams in the order they appear in the song.

--user-chord-grids *

Prints chord diagrams of all user defined chords used in a song.

--even-pages-number-left (short -L)

Prints even/odd pages with pages numbers left on even pages.

--odd-pages-number-left

Prints even/odd pages with pages numbers left on odd pages.

--page-size=FMT (short: -P) *

Specifies the page size for the PDF output, e.g. a4 (default), letter.

--single-space (short -a)) *

When a lyrics line has no chords associated, suppresses the vertical space normally occupied by the chords.

--vertical-space=N (short: -w) *

Adds some extra vertical space between the lines.

--2-up (short: -2)

Not supported.

--4-up (short: -4)

Not supported.

--page-number-logical (short: -n)

Not supported.

--dump-chords (short: -D)

Dumps a list of built-in chords in a form dependent of the backend used. The PDF backend will produce neat pages of chord diagrams. The ChordPro backend will produce a list of define directives.

--dump-chords-text (short: -d)

Dumps a list of built-in chords in the form of define directives, and exits.

Configuration options

See ChordPro::Config for details about the configuration files.

Note that missing default configuration files are silently ignored. Also, chordpro will never create nor write configuration files.

--nosongconfig

Don't use song specific config files, even if they exist.

--sysconfig=CFG

Designates a system specific config file.

The default system config file depends on the operating system and user environment. A common value is /etc/chordpro.json on Linux systems.

This is the place where the system manager can put settings like the paper size, assuming that all printers use the same size.

--nosysconfig

Don't use the system specific config file, even if it exists.

--userconfig=CFG

Designates the config file for the user.

The default user config file depends on the operating system and user environment. Common values are $HOME/.config/chordpro/chordpro.json and $HOME/.chordpro/chordpro.json, where $HOME indicates the user home directory.

Here you can put settings for your preferred fonts and other layout parameters that you want to apply to all chordpro runs.

--nouserconfig

Don't use the user specific config file, even if it exists.

--config=CFG (shorter: --cfg)

Designates the config file specific for this run.

Default is a file named chordpro.json in the current directory.

Here you can put settings that apply to the files in this directory only.

You can specify multiple config files. The settings are accumulated.

--noconfig

Don't use the specific config file, even if it exists.

--define=item

Sets a configuration item. item must be in the format of colon-separated configuration keys, an equal sign, and the value. For example, the equivalent of --diagrams=none is --define=diagrams:show=0.

--define may be used multiple times to set multiple items.

--no-default-configs (short: -X)

Do not use any config files except the ones mentioned explicitly on the command line.

This guarantees that the program is running with the default configuration.

--print-template-config

Prints a simplified template configuration to standard output, and exits. The configuration is commented to explain its contents.

The config contains most of the ChordPro configuration items, all commented out. It is easy to get started with configuring ChordPro by enabling and modifyng just a few items at a time.

--print-default-config

Prints the default configuration to standard output, and exits.

The default configuration is commented to explain its contents.

--print-final-config

Prints the final configuration (after processing all system, user and other config files) to standard output, and exits.

--convert-config=file

This option requires a single file name argument.

The specified config file is loaded and immedeately written out in standard format, including schema comments. After this, the program exits. No songs are processed.

Output goes to standard output unless `--output` is used to specify an alternative.

All other options are ignored.

Miscellaneous options

--help (short: -h)

Prints a help message. No other output is produced.

--manual

Prints the manual page. No other output is produced.

--ident

Shows the program name and version.

--verbose

Provides more verbose information of what is going on.

FONTS

There are two ways to specify fonts: with a font filename, and a built-in font name.

A font filename must be either and absolute filename, or a relative filename which is interpreted relative to the font path, which consists of configuration setting fontdir, the fonts resource dir, and the contents of environment variable FONTDIR. In any case, the filename should point to a valid TrueType (.ttf) or OpenType (.otf) font.

If it is not a filename, it must be the name one of the built-in PDF core fonts:

Courier                             Symbol
Courier-Bold                        Times-Bold
Courier-BoldOblique                 Times-BoldItalic
Courier-Oblique                     Times-Italic
Helvetica                           Times-Roman
Helvetica-Bold                      ZapfDingbats
Helvetica-BoldOblique
Helvetica-Oblique

MOTIVATION

Why a rewrite of Chordii?

Chordii is the de facto reference implementation of the ChordPro file format standard. It implements ChordPro version 4.

ChordPro version 5 adds a number of new features, and this was pushing the limits of the very old program. Unicode support would have been very hard to add, and the whole program centered around PostScript generation, while nowadays PDF would be a much better alternative.

So I decided to create a new reference implementation from the ground up. I chose a programming language that is flexible and very good at handling Unicode data. And that is fun to program in.

CURRENT STATUS

This program implements ChordPro version 5. It supports most of the features of Chordii, and a lot more:

* Native PDF generation

* Unicode support (all input is UTF8)

* User defined chords and tuning, not limited to 6 strings.

* Support for Nashville Numbering and Roman Numbering.

* Support for external TrueType and OpenType fonts

* Font kerning (with external TrueType fonts)

* Fully customizable layout, fonts and sizes

* Customizable backends for PDF, ChordPro, LilyPond*, LaTeX* and HTML*.

(* = under development)

AUTHOR

Johan Vromans <jv at CPAN dot org >

SUPPORT

ChordPro (the program) development is hosted on GitHub, repository https://github.com/ChordPro/chordpro.

Please report any bugs or feature requests to the GitHub issue tracker, https://github.com/ChordPro/chordpro/issues.

A user community discussing ChordPro can be found at https://groups.google.com/forum/#!forum/chordpro.

LICENSE

Copyright (C) 2010,2018 Johan Vromans,

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm App::Music::ChordPro

perl -MCPAN -e shell
install App::Music::ChordPro