Ciro Durán A Live Archive

Chordpro notes

Since I started playing ukulele I’ve been interested in making my own chord sheets, and a common way I’ve seen these done is using Microsoft Word and use the fonts from Chordette. This is, in fact, how I started writing them.

However, I’ve been told of Chordpro. The website and the software made me go back to the 2000s in a good way, just look at that lens flare:

Chordpro logo

My mind suddenly clicked with all the weird pages I had seen shared all around. These sometimes have chord sheets with ancient looking fonts, suggesting they may have been shared from olden times, passed down by generations of chord sheet writers. The other mind click was, also Jim’s Ukulele Songbook, which uses Chordpro syntax.

In general, it looks like a weird intersection between music writers and people who use command line tools.

So these notes act as a way to show my Chordpro setup, and how I got there. It’s not as much as a tutorial (at least yet) as it requires some familiarity with the command line interface. Chordpro itself has a user forum, which has been partly useful, as the documentation from the program itself sometimes assumes you already know what you’re looking for and it can be overwhelming for the first-time user.

If this document generates enough interest, I’d be happy to release my config files so you could use them.

What is Chordpro?

Chordpro is essentially a command line tool. This means that the program runs on a terminal, or command line window. For example:

$ chordpro ciro-songbook.cho -o ciro-songbook.pdf

The previous line will read a plain text file named ciro-songbook.cho and produce a PDF with the same name.

Command line tools are what makes the internet tick (literally), but I’m afraid if I’d suggest this to someone who is not used to them in the first place I’d scared them away really quickly. At least not in this age of graphical tools. However, given my interest in using plain text as much as possible I think it’s really worth doing some signal boosting to this kind of tools.

The file may contain something like this:

{title: Moliendo Café}
{composer: Hugo Blanco, José Manzo Perroni}
{year: 1961}
{key: Am}
{time: 4/4}

{comment:Verse 1}

[Am]Cuando la tarde langui[E7]dece renacen las [Am]sombras,
y en la quie[Am]tud los cafetales [A7]vuelven a sen[Dm]tir,
el chas tristón, canción de a[Bb]mor de la [E7]vieja mo[Am]lienda,
que en el le[B7]targo de la [E7]noche parece ge[Am]mir.

When you run chordpro, you get a PDF that contains this:

Moliendo Café

The chord charts you see there are for a ukulele, but it can be easily changed to guitar, Venezuelan cuatro, or keyboard charts. The configuration system from Chordpro allows to separate the song data from how you present it. You can also export to PDF or to HTML for uploading as a website (Jim’s Ukulele Songbook uses chordpro in the background for this).

These notes will cover how to install and use Chordpro for Linux (or Windows if using Linux under WSL).

Installing Chordpro

Installation instructions in Chordpro website

If you are using Windows command line tools and not using WSL you are missing a better command line than cmd.exe. Follow the instructions to install WSL in Microsoft docs. I use Debian as my choice for Linux. You should also get Windows Terminal.

Once in Debian, you can install chordpro by running: $ sudo cpan install chordpro

After installing Chordpro, you should be able to produce a PDF from the example from earlier, although the results won’t be the same as in the image.

Installing on Windows without WSL

TO-DO: It’s possible to use Chordpro in Windows command line, will update later.

Chordpro configuration

Chordpro configuration is the part where I think the website could improve. The docs are through, but it hardly gives any examples of use, so you are left with the task of experimenting, changing things and running chordpro until you are satisfied with the results.

Chordpro configuration files are JSON-formatted, and you can write them as composable files. This way, you can change the config files you use for several use cases: a configuration for a website, another for ukulele, another for guitar, another for printing, etc. The JSON format that Chordpro uses is relaxed on purpose for ease of use. This JSON format allows you to put comments (which begin with //) and leave the last element of an object or an array with a comma.

The best way to begin with your own config is to print the default configuration with the command $ chordpro --print-default-config, you can also redirect this to a file:

$ chordpro --print-default-config >basic-config.json

Now, this will print the entire configuration defaults in one file. As you write your own config, you may want to copy these parts to a new file, and delete them from the old file. This way you can start having composable configuration files. This means that you can mix and match configuration files as you need them. Need a guitar chord sheet instead of a ukulele one? Change one included file and you’re done.

Configuration file directories

There are three directories where chordpro looks for configuration files:

  • The working directory (where you’re calling chordpro from)
  • The chordpro user library (stored in the $CHORDPRO_LIB environment variable, usually ~/.config/chordpro), config files must be in the config subdirectory, e.g. ~/.config/chordpro/config.
  • Chordpro’s presets library (in my machine /usr/local/share/perl/5.28.1/App/Music/ChordPro/res)

You can figure out the last two directories in your machine by running $ chordpro --about.

Using configuration files

You use a config file by passing the location to the --config option, e.g.: chordpro moliendo.cho -o moliendo.pdf --config=config/base.json. In this example, there is a config directory in the working directory, with a base.json file.

When you want to want to pass more than one config file, you pass several --config options, e.g. chordpro moliendo.cho -o moliendo.pdf --config=config/base.json --config=config/ukulele-ext.json. This bit differs from the website, which says that you pass config files in the same parameter, comma separated.

Chordpro will first look for a file in the working directory. Then it will try to look in $CHORDPRO_LIB/config directory, and then it will look in the preset library. When you want a config file from the user library or the preset library, you put only the config file name, without the .json extension, e.g. --config=modern1. The presets are listed in the website. Some that might interest you:

  • ukulele adds ukulele chords, standard concert GCEA tuning
  • keyboard adds keyboard charts
  • modern1 uses sans-serif fonts

Configuration settings

TO-DO: Highlight interesting configuration settings

Chordpro syntax

You’ve already seen the syntax in the first example. This is a plain text file, so you need a text editor (notepad++ or VSCode are fine, don’t use Word). Create an empty file and copy/paste the following.

{title: Burrito Sabanero}
{composer: Hugo Blanco}
{year: 1972}
{key: C}
{time: 4/4}


[C] [G] [D7] [G] [C] [G] [D7] [G]

{comment:Verse 1}

Con mi burrito saba[C]nero voy ca[D7]mino de Be[G]lén
Con mi burrito saba[C]nero voy ca[D7]mino de Be[G]lén

Si me [C]ven, si me [G]ven, voy ca[D7]mino de Be[G]lén
Si me [C]ven, si me [G]ven, voy ca[D7]mino de Be[G]lén

This shows quite a few extra things, but this is what you’ll use most often. The lines between curly brackets are directives, and in the example they are used as data about the song. You can control how they look and positioned in the configuration. You might only need title if you don’t know the rest of it. The comment directive allows you to organize the song in sections.

This is pretty much what you need to know to get started. Save this to a file named burrito.cho, run chordpro burrito.cho -o burrito.pdf and you’ll have a PDF with the song. Add the --config files you want to control how the song and chords are laid out.


Si me [C]ven, si me [G]ven, voy ca[D7]mino de Be[G]lén
Si me [C]ven, si me [G]ven, voy ca[D7]mino de Be[G]lén

The start_of_chorus and end_of_chorus defines an “environment”, which is the word chordpro uses for specific blocks of text. This allows Chordpro to highlight the chorus as you want (e.g. indent the chorus and put a vertical line to the left).

There is another useful directives which is start_of_tab and end_of_tab, which allows you to put ASCII tabs that line up well. As for the tabs themselves, you might need to type them yourself.

   G            F            Am           E

There are other environments, like start_of_abc or start_of_ly which accept ABC Notation and LilyPond instructions. These are programs that accept plain text with a certain syntax and output actual scores. You might need to set up either of these programs before you can use these environments. It seems interesting enough to go into there, as future work.

Song books

You can have more than one song in the same file, which will allow you to produce a song book. Use the {new_song} directive to separate each song. You can change the configuration to add an index by song name and an idex by artist, which is generated automatically for you.