The song text format

"Le chansonnier" displays and print nicely-formatted songs whith chords name, diagrams, column layout ... but internally they are stored as plain text.
The song plain-text format is visible in two places:

In the Song Editor pane.
When song text are exported in '.sng' files.

This plain-text format was designed to be simple to understand and edit directly in a text editor. The purpose of this page is to explain it.

Song text format overview

A typical song text will look like the following:

It is composed of the following parts (always in this order). Each part is described in more details in a chapter below.

The song properties: the properties are only present in '.sng' files. They encode all the data known about the song.
In the song editor pane, they are not displayed because, in the application itself they are displayed (and updated) in the Song details edition dialog.
Property format:
```
{propertyName: propertyValue}
```
Some optional comments. Comments are lines starting with the '#' character.
Format:
```
# comment text
# ...
```
Some optional chord definitions.
Chords definition can be made at the song global scope when the whole song uses everywhere a special fingering for one chords. In this case, instead of repeating the fingering each time the chord appear in the song, it can be defined once in a "chord definition" section.
Format:
```
{chords}
chord-name=chord-position
...
```
Blocks: Blocks are the body of the song text. They are displayed as an unbreakable rectangular area containing text and optionally chords. Blocks can also have a label. When you write a song, you typically create one block per verse and one block for the chorus.
Blocks can be of two types:
- Default Text/chord block.
  Format:
```
{block: label}
block text
...
```
- A preformatted block, it will be displayed as-is without any enhancement and in a monospaced font.
  This is mainly used to encode little tablatures into the song (hence the 'tab' name for this block).
  Format:
```
{tab: label}
block text
...
```

The song properties

The song properties hold data about the song. This data is used to make the 'header' part (displaying title, singer, creation date, authors... ) when the song is displayed.
The format of a property is:

{propertyName: propertyValue}

Where the property name must be one of the names described below.

Available properties are:

Title: The song title
Singer: the singer name
Language: the song language (using the ISO-2 language code. ex: 'en' for english, 'fr' for french ...)
Year: the song creation year.
Origin_title: the song original title (when this song is translated from another language).
Origin_singer: the song original singer (when this song is translated or a reprise of a less-known singer).
Origin_language: the song original language (when this song is translated from another language).
Words: the name(s) of author(s) who wrote original words (separated by commas if more than one).
Music: the name(s) of musician(s) who wrote the song music (separated by commas if more than one).
Translation: the name(s) of author(s) who translated the song text (separated by commas if more than one).
Arrangement: the name(s) of musician(s) who arranged the song music (separated by commas if more than one).
Capo: the capo preferred position (usually the position to used to match original recording key).

In "Le chansonnier" song data, author names and song titles can define a 'prefix'. (Like 'The' for 'The Beatles'). Prefix (and author first names) are ignored when sorting (So 'The Beatles' appear under the index letter 'B' not 'T'). They are sometimes displayed before and sometimes after the author (last) name depending on the context. Unfortunately, when the name of an author is written in plain text, the program cannot deduce wich part is 'prefix' or first name and which part is the name itself. So, when writing any author name in properties, the prefix or first name should be explicitely put between brackets. The same apply to the song titles (if you want to define prefixes there also).

Note: if you are editing the songs inside "Le Chansonnier" application, you will not see the properties as they are managed in the Song details edition dialog. They just appear when the song text is exported to the ".sng" format.

Example of song properties:

{Title: [A] hard day's night}
{Singer: [The] Beatles}
{Language: en}
{Year: 1964}
{Words: [John] Lennon, [Paul] Mc Cartney}
{Music: [John] Lennon, [Paul] Mc Cartney}

The song comments

The comments put in the song text that are not visible in the rest of the application.
All line starting with a '#' character is a comment.

Example of comment:

# -----------------------------------
#
# Encoded for learning purpose only
# By O. Berlanger :-)
#
# -----------------------------------

The chord definitions

The chord definition section is a way to define defaults positions globally for some chords in the song. Use it when you use special fingering for some chords troughout the song, or to define positions of special chords that are not known by default in the system.
The alternative is to define the positions in the song text each time the chord occurs.
Note that, chords definition has no visual conterpart. It's just definig defaults. So, the fact that chords diagrms are displayed or the set of chords displayed as diagarms is not controlled by it.

The format of chord position definitions is:

{chords}
chordName1=position1
chordName2=position2
...

Go to Chord definitions to see what a chord name or chord position is.

Example of global chord position definitions:

{chords}
D/C=x30232
G7M/SI=x20032
Gm7M/Bb=x10032
D5=x00235

The text/chord block

The default text/chord block is the block that is used to encode most of the songs. You tipycally use one block per verse and one block for the chorus. In this usual scheme, the verse have label "1.", "2.", "3." ... and the chorus simply "Chorus.".

This block can contain chords, the chords are inserted in the text between brackets. When the block is rendered, they will be displayed in block in an inserted line above the line of text. The position of the chord on this above line is set to match the point where the bracket are inserted in text.
Go to Chord definitions to see what a chord name or chord position is.

Note: A block cannot contain more than one consecutive blank line. WHen there are two (or more) consecutive blank lines, the program splits the block in two by creating a new block (without label).

Example of text/chord block:

{block: Chorus.}
When I'm [Bm]home,
Everything [Em]seems to be all [Bm]right,
When I'm [G=320033]home,
[Em]Feeling you holding me [C]tight, [D]tight, yeah.

The monospaced block

The monosplaced block is a way to introduce small tablatures in your song book. It is typically used to display small introduction or bridge riffs.
Note that the application does not interpret the content in any way, So, even if it contains chords they will not have a special display and they will not ne translated or transposed as the rest of the song.

Example of monospaced block:

{tab: Intro.}
    B                 E                 A                D
E|-----------------|--0---0---0---0---|-0---0---0---0--|-2----|
B|--4---4---4---4--|--0---0---0---0---|-2---2---2---2--|-3----|
G|--4---4---4---4--|--1---1---1---1---|-2---2---2---2--|-2----|
D|--4---4---4---4--|--2---0---2---2---|-2---2---2---2--|-0----|
A|--2---0---x---x--|----------4---2---|-0---0---0---0--|------|
E|----------4---2--|------------------|-----3---2---0--|------|

The chord definition

Chords are the central point of the application. So they deserve a powerful definition so that the system can detect them, translate them (in english style: "A", "B", "C" or french style: "Do", "Ré", "Mi"), to transpose them and to generate finger position diagrams.
A chord is composed of two parts:

The chord name: something simple as "G" or more complex like "Gsus4/B"
The chord position: it's a suite of characters specifying the positions of fingers (see below).

The chord name

The chord name itself is composed of several parts (appearing in this order, where only the first 'note name' is mandatory):

The note name: one of "A", "B", "C", "D", "E", "F", "G", "DO", "RE", "MI", "FA", "SOL", "LA", "SI".
The parsing is case-insensitive, but the application always display note names in uppercase.
The alteration: sharp "#" or flat "b".
The chord 'symbol': it's a suite of digit and letters giving the type of chord (like 'minor', 'augmented fourth' ...).
in fact, you can put the coding you like because the program doesn't try to interpret this part. The only side effect of using atypic 'symbol' is that the program might not find a default position for this chord and hence you are obliged to provide it.
The bass: a slash '/' followed by a note name and optionally an alteration.

A name where all the elements appear is, for example: G#m7/Bb

The chord position

The chord name is enough in simple cases, because the program knows the poistion of a lot of chords. But when you want to use exotic chords, or exotic fingering for usual chords or simply two different fingering for the same chord in one song, then you have to specify the chord position.
The chord position is composed of the following (in this order):

the equal '=' character.
six digits or letters denoting the finger position on each string. The first is for the lowest bass 'E' string, the second for the 'A' string and so on...
The possible values for those digits or letters are:
- 0: the zero denotes an open string.
- 1 to 9: put a finger in the frett 1 to 9
- a to j: put a finger in the frett 10 to 20 where:
  - a: is for frett 10
  - b: is for frett 11
  - c: is for frett 12
  - and so on ...
- x: is a muted string (or simply a not-played string)
After that you can add indication about barres: the '|' character alone tells to do a barre trough the whole frett.
The '|' character followed by a digit or a letter tell to do a small barre (a single finger pressing several strings but not all) on the corresponding frett.

Examples of chord position

C=030210

The simple C major chord.
Note that, as it is the default position for this chord,
so you don't have to provide the position part for this chord.

G=355433|

The G chord using a barre at frett 3.

C13=x32355|5

The C13 chord is an example usage of a small barre
(the pinky finger press two strings on frett 5).