App::Music::ChordPro - A lyrics and chords formatting program
perl -MApp::Music::Chordpro -e run -- [ options ] [ file ... ]
When the associated chordpro program has been installed correctly:
chordpro [ options ] [ file ... ]
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.
chordpro is a rewrite of the Chordii program, see http://www.chordii.org.
For more information about the ChordPro file format, see http://www.chordpro.org.
About ChordPro.
Specify the encoding for input files. Default is UTF-8. ISO-8859.1 (Latin-1) encoding is automatically sensed.
Only prints lyrics. All chords are suppressed.
Useful to make prints for singers and other musicians that do not require chords.
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:
Portable document format (PDF).
If a table of contents is generated with the PDF, ChordPro also writes a CSV file containing titles and page numbers. This CSV file has the same name as the PDF, with extenstion pdf replaced by <csv>.
pdf
A textual representation of the input, mostly for visual inspection.
A functional equivalent version of the ChordPro input.
A JSON file that defines the behaviour of the program and the layout of the output. See App::Music::ChordPro::Config for details.
This option may be specified more than once. Each additional config file overrides the corresponding definitions that are currently active.
Sets the starting page number for the output.
Includes a table of contents.
By default a table of contents is included in the PDF output when it contains more than one song.
Suppresses the table of contents.
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.
Prints chord grids of all user defined chords used in a song.
Prints the program version and exits.
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.
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.
Sets the font size for lyrics and comments.
Sets the font used to print the chord names.
Sets the font size for the chord names.
Sets chord grid size (the total width of a chord grid).
Prints chord grids of all chords used in a song.
Disables printing of chord grids of the chords used in a song.
Not supported.
Prints chord grids of the chords used in a song, ordered by key and type.
Prints chord grids in the order they appear in the song.
Prints even/odd pages with pages numbers left on even pages.
Prints even/odd pages with pages numbers left on odd pages.
Specifies page size, e.g. a4 (default), letter.
a4
letter
When a lyrics line has no chords associated, suppresses the vertical space normally occupied by the chords.
Adds some extra vertical space between the lines.
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.
define
Dumps a list of built-in chords in the form of define directives, and exits.
See App::Music::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.
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.
/etc/chordpro.json
This is the place where the system manager can put settings like the paper size, assuming that all printers use the same size.
Don't use the system specific config file, even if it exists.
Don't use a legacy config file, even if it exists.
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.
$HOME/.config/chordpro/chordpro.json
$HOME/.chordpro/chordpro.json
$HOME
Here you can put settings for your preferred fonts and other layout parameters that you want to apply to all chordpro runs.
Don't use the user specific config file, even if it exists.
Designates the config file specific for this run.
Default is a file named chordpro.json in the current directory.
chordpro.json
Here you can put settings that apply to the files in this directory only.
You can specify multiple config files. The settings are accumulated.
Don't use the specific config file, even if it exists.
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 --no-chord-grids is --define=chordgrid:show=0.
--define may be used multiple times to set multiple items.
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.
Prints the default configuration, and exits.
The default configuration is commented to explain its contents.
Prints the final configuration (after processing all system, user and other config files), and exits.
The final configuration is not commented. Sorry.
Prints help message. No other output is produced.
Prints the manual. No other output is produced.
Shows the program name and version.
Provides more verbose information of what is going on.
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.
fontdir
fonts
FONTDIR
.ttf
.otf
If it is not a filename, it must be the name one of the built-in fonts.
Built-in 'Adobe 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
Built-in 'Windows Fonts':
Georgia Webdings Georgia,Bold Wingdings Georgia,BoldItalic Georgia,Italic Verdana Verdana,Bold Verdana,BoldItalic Verdana,Italic
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.
This program provides alpha support for 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)
Johan Vromans <jv at CPAN dot org >
<jv at CPAN dot org >
ChordPro (the program) development is hosted on GitHub, repository https://github.com/sciurius/chordpro.
Please report any bugs or feature requests to the GitHub issue tracker, https://github.com/sciurius/chordpro/issues.
Copyright (C) 2010,2017 Johan Vromans,
This program is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
To install App::Music::ChordPro, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Music::ChordPro
CPAN shell
perl -MCPAN -e shell install App::Music::ChordPro
For more information on module installation, please visit the detailed CPAN module installation guide.