1. Roman Gorodeckij
  2. chordpro

Overview

HTTPS SSH
This is the README for an as-yet unnamed Python version of ChordPro as 
implemented by Jeremy Sproat.  Please be aware that this software is very much  
of alpha quality, and is subject to change.



#######
LICENSE
#######

Anything I wrote that is bundled with this package is placed in the public 
domain (where appropriate), meaning you can take it and mostly do with it what 
you want - mostly.  (But please respect the rights of song writers.)

This package includes items that are not in the public domain.

See the attached file license.txt for the gory details.



############
REQUIREMENTS
############

This was written and tested using Python v2.5.1 and v2.6.2.  (Yeah, I need to 
upgrade.)

It also uses the free version of the Python Imaging Library if you want to 
render chord grids to PNG; I'm currently using 1.1.6.

This software has been tested on Windows XP SP3 and Ubuntu Linux 9.04 "Jaunty 
Jackalope".



##################
CHORDPRO EXPLAINED
##################

ChordPro is a text-based format for simple guitar chord notation in songs.  It 
is easy for a human being to read and write, but simple enough for a program to 
convert into a nicely-formatted song sheet.

The ChordPro specification was originally implmented in C as "chord" by Martin 
Leclerc and Mario Dorion back in 1993.  chord converted ChordPro files into 
PostScript.  It has since been forked and reimplemented a number of different 
ways, most of which output PostScript, PDF or HTML.

Back in 2005 I noticed a need of a wiki-friendly ChordPro parser, and so I 
started on one for the excellent PmWiki engine.  A combination of real-world 
issues and a pesonal scathing dislike for coding in PHP had led me to abandon 
the project, but fortunately someone else has picked it up.

Since then there have been a small handful of similar projects, but none I have 
seen have satisfied all my ChordPro needs, which include ease of use and 
graphical rendering of chord grids.  (This project isn't easy to use just yet, 
but at least it renders chord grids into ASCII and PNG image files.)



######################
CHORDPRO SPECIFICATION
######################

There are numerous explanations of the ChordPro format in the links section at 
the end of this document.  Here's a brief taste::

    {title:This Land is Your Land}
    {subtitle:copyright 1945 Woody Guthrie}

    {define: D  x  x  0  2m 3r 2i}
    {define: G  3m 2i 0  0  0  3p}
    {define: A7 x  0  2i_2i_2i 3r}

    {comment: Chorus}
    {start_of_chorus}
    [D]This land is [G]your land, this land is [D]my land
    From Cali[A7]fornia to the New York [D]Island
    From the redwood [G]forests to the Gulf Stream [D]waters
    [A7]This land was made for you and [D]me
    {end_of_chorus}

    {comment: Verse 1}
    [D]As I was [G]walking that ribbon of [D]highway
    I looked a[A7]bove me, there in the [D]sky way
    I saw be[G]low me the golden [D]valley
    [A7]This land was made for you and [D]me

As you can see, the chords are mixed in with the lyrics, and there are various 
directives embedded in curly braces.  Chords can show up in the middle of 
words, for example when a chord change happens between syllables of a word.
Chords are defined at the top so their diagrams can be printed.

You don't need to be so verbose with the markup; the minimal markup in this 
next example will likely suffice for up to (or more than) 99% of your needs::

    [D]This land is [G]your land, this land is [D]my land
    From Cali[A7]fornia to the New York [D]Island
    From the redwood [G]forests to the Gulf Stream [D]waters
    [A7]This land was made for you and [D]me

    [D]As I was [G]walking that ribbon of [D]highway
    I looked a[A7]bove me, there in the [D]sky way
    I saw be[G]low me the golden [D]valley
    [A7]This land was made for you and [D]me

You can keep a chord catalog of all your useful chords in a separate file, 
which will help keep your ChordPro song files looking clean.



#####
USAGE
#####

There's just a bare-bones API right now.  A front-end script is in the works.

Here's a simple example - this script renders a ChordPro file into an ASCII 
songsheet::

    from chordpro import *
    
    chordfile = open(filename)
    tokens = tokenize(chordfile)
    document = parse(tokens)
    
    # optional - let's include chords that we didn't explicitly define
    # SBChords.master from Songbird Suite
    chord_catalog = ChordCatalog('SBChords.master')
    
    for line in renderToAscii(document, chord_catalog=chord_catalog):
        print line



##############
EXAMPLE OUTPUT
##############

So here's what the ChordPro song looks like when rendered into ASCII::

                      T h i s   L a n d   i s   Y o u r   L a n d

                c o p y r i g h t   1 9 4 5   W o o d y   G u t h r i e

                             D             G             A7
                        X=X=O======   ====O=O=O==   X=O========
                        |_|_|_|_|_|   |_|_|_|_|_|   |_|_|_|_|_|
                        |_|_|_O_|_O   |_O_|_|_|_|   |_|_O_O_O_|
                        |_|_|_|_O_|   O_|_|_|_|_O   |_|_|_|_|_O
                        | | | | | |   | | | | | |   | | | | | |
                              2 3 1   2 1       4       1 1 1 3

    Chorus
        D            G                       D
        This land is your land, this land is my land
                 A7                     D
        From California to the New York Island
                         G                          D
        From the redwood forests to the Gulf Stream waters
        A7                             D
        This land was made for you and me

    Verse 1
    D        G                      D
    As I was walking that ribbon of highway
              A7                    D
    I looked above me, there in the sky way
            G                 D
    I saw below me the golden valley
    A7                             D
    This land was made for you and me

(Trust me, the HTML-and-PNG version looks even better.)


#######
ROADMAP
#######

This software is still in its early stages.  Kind of a sketch, really.

I intend this software to satisfy several criteria:

*   Above all else: be easy to use, easy to embed, easy to extend
*   Out of the box, render ChordPro files to ASCII and HTML, and render the 
    chord grids too
*   Use a forgiving parser, since a good amount of ChordPro-formatted files out 
    there aren't 100% pure ChordPro (and there's really no strict ChordPro 
    definition anyhow)
*   Use an output-agnostic document model to make other output formats like 
    PostScript and PDF easier to implement
*   Know enough about guitar chords and music theory to allow  transposition of 
    songs; this feature seen on http://www.chordie.com blows my mind

Things that would be nice to have in the future (but I won't hold up v1.0 for):

*   GUI for people who are intimidated by command-line apps
*   Render to PS, PDF, SVG, etc.
*   Parse and render tablature as graphics
*   Extension of the ChordPro specification and writing of custom directives

Things that I have no expectation of happening, ever (but I won't complain if 
SOMEONE ELSE put effort into):

*   Output to MIDI
*   GUI for editing
*   Import from website
*   Integration with online services



######
THANKS
######

This software is nothing if not an expression of admiration for the following
people, to whom I am grateful:

*   Martin Leclerc and Mario Dorion for their original vision of ChordPro
*   Andy Gryc, whose Chord Magic Pro program is the only DOS program I still 
    use on a regular basis, and whose Songbird Chords program first exposed me
    to ChordPro many years ago
*   The fine folks who implemented www.chordie.com - whose transposing feature 
    really lit a fire under my ass to figure out how it's done and then to get 
    this project started
*   Guido van Rossum and the others behind the Python language - it's like what 
    BASIC was originally meant to be, except done right and with batteries 
    included
*   Fredrik Lundh and the others at pythonware.com behind the Python Imaging 
    Library
*   I'm sure there's others - if I forgot to mention you, it's not because I'm
    ungrateful.  Pass me a note.



#####
LINKS
#####

*   Original chord program: 
    http://www.harmony-central.com/Software/Unix/chord.tar.Z
*   Wikipedia article on chord: 
    http://en.wikipedia.org/wiki/Chord_(software)
*   Chordii, a fork of chord: 
    http://sourceforge.net/projects/chordii/
*   WebChord, a Perl-based parser with a live web demo:
    http://webchord.sourceforge.net/
*   PmWiki implementation: 
    http://www.pmwiki.org/wiki/Cookbook/ChordPro
*   Songbird Suite by Andy Gryc, an old program but renders ChordPro files and 
    does much more (and has the excellent master chord list "SBChords.master"): 
    http://www.gryc.ws/songbirdsuite.htm
*   Chordie.com, search and download (and transpose!) lots of chord files: 
    http://www.chordie.com/
*   ChordSmith, a Java application that transposes ChordPro files:
    http://www.statistics101.net/chordsmith/