Song file format

A song file consists of tokens, separated by whitespace (spaces, tabs or newlines). There are two mandatory tokens which must appear in order at the beginning of a song: the time signature, and the key signature. These must be followed by one or more chord tokens. A chord token consists of three mandatory elements (chord duration, root, type) and one optional element (bass note). A chord token must not contain any embedded spaces.

DurationAn integer specifying the duration of the chord in beats.
RootThe root of the chord, as a note name, e.g. C, Bb, F#, etc.
TypeThe chord type, e.g. maj7, -7, etc. Only chord types defined in the chord dictionary are permitted.
BassA slash followed by a bass note name, e.g. /E. This element is optional. The bass function only respects alternate bass notes if the slash chords setting is enabled.

The simplest possible song file is given below. It's in 4/4 time and the key of C, and consists of a single measure of C major.

4/4 C

Here's a slightly more complicated song. It's in 4/4 time and the key of Bb, and consists of II, V, I, followed by a minor turnaround back into II. Note that the final measure is split into two chords. The total length is four measures or 16 beats.

4/4 Bb
4C-7 4F7 4Bbmaj7 2D-7b5 2G7b9

Comments are permitted, though only comments at the start of the file are guaranteed to be preserved. The single-line comment delimiter is two consecutive slashes. Property assignments may also be specified at the start of the file, after the time and key signatures but before the first chord token. Currently the only properties supported are T (tempo) and K (transposition to the specified key). Here's an example showing comments, property assignments, and an alternate bass note.

// this song specifies a tempo of 140
// and transposition to the key of Eb
4/4 Bb T=140 K=Eb
4C-7 4F7/C 4Bbmaj7 2D-7b5 2G7b9

Songs can contain sections, which repeat a specific number of times or indefinitely. A section is defined by enclosing one or more chords in square brackets. The brackets must be separated from the chord symbol(s) they enclose by one or more spaces. The section's closing bracket can optionally specify a repeat count. The repeat count must be an integer greater than zero, and must immediately follow the closing bracket. If no repeat count is specified, the section is repeated indefinitely, or until the section is advanced via the Next Section command. Here's an example that demonstrates sections. The first section repeats indefinitely, whereas the second section repeats twice.

4/4 C
[ 4D-7 4G7 ]
[ 4E-7b5 4A7b9 ]2

Sections can optionally be named. To create a named section, the section's opening bracket must be immediately preceded by the section name, which must not contain any spaces. The following example demonstrates named sections.

4/4 C
vamp[ 4D-7 4G7 ]
break[ 4E-7b5 4A7b9 ]2