ChordPro(3pm)

📦

version 6.101.0 · 4 versions

🎶 ChordPro(3pm) — the lyrics-and-chords glow-up 💖

User Contributed Perl Documentation · ChordPro(3pm)

okay bestie, buckle UP, because this is the page that teaches you about chordpro: the program that takes your sad little text file of lyrics + chords and turns it into sheet music so pretty people will literally ask you where you got it. 💅

✨ NAME ✨

ChordPro — a lyrics and chords formatting program 🎸

✨ SYNOPSIS ✨

Run it straight through Perl like this:

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

And once the chordpro program itself has been installed the way it's supposed to be, you just go:

chordpro [ options ] [ file ... ]

✨ DESCRIPTION ✨

So here's the tea 🫖: chordpro reads one or more text files. Those files contain the lyrics of one song — or like, a whole bunch of songs, no big deal — plus the chord information tucked in next to them.

Then it does its little magic and generates a photo-ready, professional looking, impress-your-friends piece of sheet music. Print it on whatever printer is nearest to you. Obsessed, honestly. 🎀

Here's what typical ChordPro input looks like — this is the standard, no cap:

{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}

See how the chords live inside square brackets right before the syllable they belong to? That's the whole vibe. The directives in curly braces are the structure: title, subtitle, chorus markers, comments, all of it. 🦋

Fun fact for the lore girlies: chordpro is a rewrite of the Chordii program. Glow-up of the century, fr fr.

Want more info about the ChordPro file format itself — the whole syntax situation? Go here: <https://www.chordpro.org>. 👑

✨ COMMAND LINE OPTIONS ✨

okay bestie, this is the good stuff — every flag you can throw at chordpro and what it actually does 💖

--about (short: -A) — prints version info about the ChordPro program. That's it, that's the whole job, no other processing happens, it just says hi and dips 👑
--back-matter=FILE — appends the contents of the named PDF document to the output. perfect if you want some back matter pages at the end 🎀
--config=JSON (shorter: --cfg) — a JSON file that defines how the program behaves and how the output gets laid out. see ChordPro::Config for the deets.

you can drop this option more than once, no cap — every additional config file overrides the corresponding definitions that are currently active 🔥

--cover=FILE — prepends the contents of the named PDF document to the output. cover pages, slay ✨

💅 Chordii compatibility options 💅

the following Chordii command line options are recognized. note that not all of them actually do something 😭 (it's giving legacy support energy).

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. different things, bestie, don't mix them up 🫶

--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) — not supported. use "pdf.even-odd-pages" in the config instead.
--odd-pages-number-left — not supported. use "pdf.even-odd-pages" in the config instead.
--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. it's a look-don't-touch situation 🫶

--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. stack 'em up 🔥

--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 modifying just a few items at a time ✨

--print-default-config — if used once, behaves like --print-template-config. this is to avoid confusing novice users.

to get the full default configuration, repeat this option.

--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 immediately 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 💖

okay so bestie, fonts. There are literally two ways to specify them: with a font filename, and with a built-in font name. that's it, that's the vibe.

A font filename must be either an absolute filename, or a relative filename which is interpreted relative to the font path. And what even is the font path? slay, so glad you asked — it consists of:

the 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. no fake files, she will simply not render for you.

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

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

those are the classics, the old money of fonts honestly. 💅

🌈 MOTIVATION 🌈

okay why a rewrite of Chordii? good question, bestie, sit down.

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

ChordPro version 5 adds a number of new features, and that was pushing the limits of the very old program. like, the poor thing was going through it. 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 the author decided to create a new reference implementation from the ground up. 🫶 Chose a programming language that is flexible and very good at handling Unicode data. And that is fun to program in. (main character behavior, honestly.)

✨ 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) 👀 like it's coming, it's cooking, give it a minute.

👑 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. found a bug? tell them, don't just suffer in silence bestie 😭

A user community discussing ChordPro can be found at https://groups.google.com/forum/#!forum/chordpro. come hang out, it's giving group chat. 🌸

🎀 LICENSE 🎀

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

that's the whole legal tea. same terms as Perl itself, no cap. 💜

and that's the whole page, bestie!! we ate. 💅✨

this is perl v5.40.1 realness, dated 2026-05-03, and it lives in section ChordPro(3pm) — go forth and format your chords, you gorgeous genius. 🎀🦋🌸💖

📦 where this page comes from

ubuntu stonking: chordpro 6.101.0+ds-1 · Artistic-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms