[update: 2015-11-11 minor edits]

Summary: I made a new open source program to format song sheets in chordpro format in a variety of ways. It’s a command line thing. Not everyone understands; when I talk about it to my friends in the band I sort of accidentally seem to have nearly joined we have IM exchanges like:


I have it set up now with a cloud server watching the dropbox, so if you put in a text file with a .cho extension it will auto-generate a PDF for the song

Other band member:

The what with the what now?

So, I decided to tell you all here on the Interwebs where you will 100% get what I’m talking about.

The problem was this: I had several years worth of song-sheets downloaded from various places on the internets or typed out by hand, for my own and other people’s songs, in a variety of formats, including Word docs, RTF and PDF but mostly text files. Then I started playing music with other people again for the first time in years, and we’d be trading bits of paper and files and mailing song files to each other, and so on, always searching for a fourth-generation photocopy of something someone had in their folder. Anyway, I got to looking at ways to manage this and create consistently formatted song sheets.

Turns out there’s a handy format for marking-up songs called chordpro. This involves putting chord names in square brackets, inline, in amongst the lyrics. Like [C] this. Or [G#maj7] or this, with a {title: } at the top, and a few other simple commands. Here’s one I prepared earlier.

{title: Universe}
{st: Peter Sefton}
{key: C} 
{transpose: -3} 

[C] This is a song about [E7] everything
[F] It's really div[C]erse
[Caug9]Got something for [E7] everyone
[Am] But only [G] has one [F] verse
[F] Get it? Uni [D] Verse

{c: Pre chorus}
[D7] Here comes the chorus:

{c: Chorus}
[C] Uni [E7] verse Uni [F] verse
[F] Uni [Fm] verse Uni [C] verse

{c: Bridge}
[C] That's [G] it

{c: Coda}
[F] Sorry the song's [C] so terse

There are lots of software packages for managing chordpro songs, printing them out, showing them on your church projector, organising them on your iPad, transposing them between keys and so on, but none of the software did quite what I wanted in the way I wanted. For example, most of the packages are designed to put chords above the lyrics, but I prefer leaving the chords inline, the way Rob Weule did it in the Ukulele Club Songbook and Richard G does it in his Ukulele songs, it’s more compact for one thing not to mention easier to copy and paste. Here’s an example of some free software online which is really well done, but not what I wanted at all:

A nice online chordpro converter at
A nice online chordpro converter at

I’ve been keeping my songs in text files in Dropbox for years and that suits me. I don’t want to have to suck all the files in to the maw of some slightly dodgy open source Java application on my laptop, or upload them somewhere, or install a web application, and it hurts me to say this after all the work I put into scholarly publishing in HTML but PDF is perfect for songs which are page-based, good for printing and good for displaying on tablets.

And I like to keep my hand in with coding and, well, I have a few hours on the train every day which I don’t always use for work stuff and, you can probably see where this is heading. I got to wondering what would happen if I ran a few songs through Pandoc, the magnificent omniverous document conversion tool to make PDF and HTML versions, and one thing led to another. It started innocently enough with a simple script to process chordpro declarations into markdown. But then I asked myself; how would this look as an epub ebook made up of multiple songs? And then how do I make a word doc with a table of contents and start each song on a new page? And how might I get the script to make the songs scale (pun intended) so they fill up the page, for maximum readability? Which led to experiments with LaTeX, the taste of which I still don’t have out of my mouth entirely, and a brief flirtation with the Open Document Format and the LibreOffice presentation software (we’ve dated before but it has never worked out long-term). I finally got friendly with an amazing bit of command line software called wkhtmltopdf which can turn HTML web pages into PDF including running any javascript they contain before doing so. This way I was able to write a script that automatically scaled up text to fit an A4 page.

I told myself “I’m not going to do chord grids”, you know, little images with fret-dots etc, cos me and my music buddies are all awesome players who know every chord ever, and if not can like totally work them out in our heads, but then I wondered if there was an existing open source library that did chords for multiple instruments I could just, like, drop in to my Python program so I could re-learn the banjo chords I’ve forgotten, and learn a bit more mandolin, and it turned out that there isn’t really, but a I used a few train trips and a hot saturday arvo to write a chord-grid-drawer. Turns this chord definition I got from the open source software at Uke Geeks (thanks Buz!):

{define: Aaug frets 2 1 1 4 fingers 2 1 1 4 add: string 1 fret 1 finger 1 add: string 4 fret 1 finger 1}

Into this:



Unlike most chord drawing software I found which has built-in limitations, It will also cheerfully render a really silly chord like this, which would require twelve strings, and 33 playable frets, not to mention 11 fingers, like that the dude in one fish two fish red fish blue fish by Dr Seuss:


Look at his fingers!

One, two, three…

How many fingers

Do I see?

One, two, three, four,

Five, six, seven,

Eight, nine, ten.

He has eleven!


This is something new.

I wish I had

Eleven, too!

{define: F#stupid base-fret 22 frets 1 2 3 x 4 5 6 7 8 9 10 11 fingers 11 10 9 8 0 7 6 5 4 3 2 1}



So, I had the technology to render chords (even at grand piano scale) but then it turned I couldn’t find chord definition files for more instruments. There are lots of chord charts in image formats, of course, but no data that I can find, which led to working out how to compile this old C code and modify it a bit to produce chord-data files (my update to that code is not done enough to release).

Anyway, the above song looks like this when run through my software. Now, after a couple of months of part-time tinkering in I can type ./ -o --instrument Uke uni-verse.cho and this appears!

Uni-verse rendered for printing
Uni-verse rendered for printing

Better yet, I have it set up now with a cloud server watching the dropbox, so if you put in a text file with a .cho extension it will auto-generate a PDF for the song. That is, in our shared band folder in Dropbox, if anyone creates a new song file, a new PDF appears automagically about a second later. Drop me a line if you’d like to try it - all you have to do is share a Dropbox folder with an account of mine. This is one of my favourite deployment patterns for software, almost like a no-interface user-interface. I’ll write more about this matter soon.

Along the way I learned:

  • How to make books, by feeding in a list of files.
  • How to make a setlist book for a performance complete with additional performance notes, from a markdown file.
  • That even when we had a setlist book my bandmates typed up setlists in big writing to put on the floor, so I added a feature to write out set-per-page at the start of the book.
  • That we really need the ability to do per-performance annotations, such as who goes first and whether we have a count-in or all-in approach to the song, so notes from the setlist such as go slow get put at the top of each song.
  • How to keep two page songs on facing pages in said books so you don’t have to turn pages.
  • How to generate chord-definitions for arbitrary instruments (still working on that bit).
  • How to transpose chord definitions from one instrument to another if they have the same relative tuning between strings - eg soprano uke chords into baritone uke, or open-G banjo tuning into the C tuning used by my baby banjo, the Goldtone Plucky.
  • How to make stand-alone one page versions of songs …
  • .. automatically, whenever I drop a new on in my Dropbox, or change one.

Now, I realise that a command line thing that’s a hassle to install and will almost certainly break the moment someone other than me tries to run it has limited appeal, but I’m releasing it to the world anyway. Even if the software is not to your taste, I think some of the things I’ve done will be useful to others. For example I:

  • Liberated Buz Carter’s chord definitions for Soprano uke which were encoded in a javascript program into a stand alone file, observing the license conditions of the software of course.
  • Likewise liberated the guitar chords from the venerable chordii software.
  • Generated chord definitions for 5 string banjo G-tuning and mandolin; these may not be the best voicings or fingerings as they were auto-generated - let me know if you can help improve them.

The future

Here are some other things I am Never Ever Going To Do With This Software. Ever. Never. Absolutely promise.

  • It will never have a Graphical User Interface.

  • It will never be a web application.

  • It will never be a dot-com startup.

  • It will never be an iOS app.


If anyone wants to help we could:

  • Build a decent library of chord shapes defined in chordpro format

  • Improve the look of the generated books a lot, if anyone knows some modern HTML and CSS.

  • Make it better.


comments powered by Disqus