Skip to content

Syntax of the Song Format

Jump to bottom
Jan Martin Reckel edited this page Jan 18, 2022 · 7 revisions

The Syntax of the Song-Format is very easy and designed to present a lightweight way of saving song lyrics in a text file. It is supposed to enable editing directly from a text editor without any different tools.

Hint: Until now, this song format is just partially supported by Cantara 2 RC, but will be completely supported in the final Version Cantara 2.

General Structure

Generally, a song file consists of stanzas, seperated by two line breaks. One line break will be treated as a line break inside a verse. For example, an implementation of the song "Amazing Grace" would look like this (save it under Amazing Grace.song to give the song title as well):

Amazing grace, how sweet the sound`
That saved a wretch like me`
I once was lost, but now I am found`
Was blind, but now I see`

'Twas grace that taught my heart to fear`
And grace my fears relieved`
How precious did that grace appear`
The hour I first believed`

Additional Syntax

Additional Syntax can be used with an # at the beginning of the line, followed by a double point : a space and the value. Each syntax instruction has to be a new line. Possible song annotations are:

  • #title
  • #author
  • #composer
  • #ccli-number
  • #copyright

With that in mind, Amazing Grace could look like this:

#title: Amazing Grace
#author: John Newton
#copyright: Public Domain

Amazing grace, how sweet the sound`
That saved a wretch like me`
I once was lost, but now I am found`
Was blind, but now I see`

'Twas grace that taught my heart to fear`
And grace my fears relieved`
How precious did that grace appear`
The hour I first believed`

Defining Stanzas, Chorus' and Repitions

For defining stanzas, chorus's and repition's, there are generally two ways. First, you can just write every part of the song as it comes, including all the repitions. Second, you can define part names and later recall them. Part definitions work with # and the name of the part behind. Recalls are done by @ and the name of the part behind. Let us say we would like to use "Amazing Grace", but this time with the first stanza repeated after the second one:

#title: Amazing Grace
#author: John Newton
#copyright: Public Domain

#stanza1
Amazing grace, how sweet the sound`
That saved a wretch like me`
I once was lost, but now I am found`
Was blind, but now I see`

#stanza2
' T was grace that taught my heart to fear`
And grace my fears relieved`
How precious did that grace appear`
The hour I first believed`

@stanza1

Adding Chords and music sheets

Cantara soon will have the ability to export songs in a special format for musicians. For that, chords can be added by using square brackets. For example:

A[G]mazing [G7]grace, how [C]sweet the [G]sound`
That [Em]saved a [G]wretch like [D]me` [D7]
I [G]once was [G7]lost, but [C]now I am [G]found`
Was [Em]blind, but [Am]now [D]I [G]see`

If there is a sheet file, it can be also linked within the document. It is recommend to place the file in the same folder:

#sheet-file: <relative path>

Defining multiple song Song flows

Sometimes, you would like to not use all stanzas of a song, or you would like to create several song flows in general. This can be done in two ways:

  1. Just copy the file to a new one, where you remove, add or change the lyrics according to your wishes and save them to a new file, for example Amazing Grace [only first stanza].song

  2. Define additional song flows inside the song-file. The first song flow is always the one "as it comes". Additional ones are added with song-flow: and the part names in their right order:

    #song-flow: stanza1

Clone this wiki locally