We are moving to GitLab

After many years of using Bazaar and, sadly they are being abandoned by their creators, and so to ensure the longevity of OpenLP, we have decided to move to GitLab.

Keep up to date with the status of our move by checking the Moving_to_GitLab page.

Development:SingingTheFaith Format

From OpenLP
Jump to: navigation, search

Note that this importer is not available in the current 2.4.6 version of OpenLP. It is awaiting incorporation into the latest development version

The Methodist church has a new hymn book Singing the Faith which uses, where it makes sense, updated language. It also includes many hymns which are more recent than those in Hymns and Psalms.

An electronic version of Singing the Faith is available at [1]. Note that this is Windows only, and requires the purchase of a key, which ties the purchased program to a particular computer. Further details are available at the Singing the Faith Plus website. There is a Word Document at [2] which has some screenshots. As well as the purchased program key the program requires your CCLI reference number. Some of the songs are not covered by CCLI, and require the user to contact the copyright holder before reproducing or projecting them. These have not been tested with the importer. Please do not share the exported text versions of songs, or the OpenLP exported OpenLyrics versions of these beyond your local church, as detailed in the Copyright matters page on the Singing The Faith website.

For importing a song into OpenLP you should export the song, or songs, as Text. This will create a file called, for example H101.txt

The basic text format is verses, with the first line of each verse labelled with a verse number and the other lines indented to line up. These are followed by author and copyright information. A chorus is more deeply indented than the verse.

Over half the songs are in this format and the SingingTheFaith import module will import them into OpenLP with no further processing being required. If the SongbookNumberInTitle Hint (see below) is used then the songs will be created with a title (for our example) of 'STF101 - Before the world began,' . The song numbers are 3 digits padded with leading zeros, e.g. STF037. The song will have a comment to say which version of the SingingTheFaith importer was used to import the song. Songs which have been imported with the Singing The Faith import module should show, in the Comments Field, the version of the Importer module (not the same as the OpenLP version) used to import the song. If a hint from the hints file described below was used then the version of the hints file should be shown in the comments field as well. The OpenLP Songbook field is set to 'Singing The Faith' and the OpenLP Song Number field is populated.

The rest of the songs require either Hints, or manual intervention before they are suitable for projection. If the importer can detect a problem with the importation of the song the title will be preceded by 'z' so it sorts after all the other songs. Note that not all problems can be automatically detected. Some songs flagged for manual attention may always require editing, for example STF603 will need the line '(name) and (name) we offer our love' updated to reflect the names of the couple getting married. Others, may have comments entries suggesting formatting in the projected text which is beyond the capabilities of the current import module, may be able to be automatically transformed in a future version of the import module and hints file.

The Hints file

The importer looks for a file called 'hints.tag' in the same directory as the imported song(s).

The hints file looks something like the following

Tag-STFHints-version: 1.0
Version: 1
Hymn: 2
VerseOrder: V1,C1,V2,C1,V3,C1
Hymn: 8
AddSpaceAfterColon: 2,11,20,33

and so on

Every line is a tag, followed by a semi-colon and then a value. The 'End' tag is the end of an entry.

The very first entry is a header, and the Version used in the header will be placed in a comment in the imported song in OpenLP if the hints file is used for that song.

Hints for individual hymns are of two basic types, whole hymn hints and hymn line hints.

Importer Hints

These control the overall behaviour of the importer module and are placed in the header, i.e. the first block


The version of the hints file. If reporting an issue with a Hymn imported via the module, please include this number, which should be included in the Comments for the imported Song.


Although OpenLP has fields for SongBook and Song Number, and these are populated by the import module, the church where I project has, probably as an inherited practice from before we used OpenLP, a convention of using an abbreviated Songbook name and a 3 digit Song Number in the Title of the song.

SongbookNumberInTitle: False

The default for this field is False, however the distributed Hints file has this set to True to match our current practice.

If you wish to change and have only recently imported the Hymns, you can search for everything with STF in the title, select them all and remove and then update your Hints file and re-add them. (Check you still have your set of exported H1.txt etc files !)

Whole Hymn Hints


Followed by an integer hymn number. Everything up to the next 'End:' relates to that hymn

Hymn: 35


Adds the value as a comment. There can be more than one of these for a Hymn

AddComment: Verse 6 should only be sung on Christmas Day


Supplies the CCLI number for that Hymn


Do not use a change of indentation to start a chorus. The value Yes should be given with this

IgnoreIndent: Yes


Forces the name of the Song to start with 'z' to indicate that this song will need editing before it can be projected. Once the song has been edited, remove the 'z' from the title.


Normally the first line of the song is used as the title. This allows that to be overridden.

SongTitle: Think of a world without any flowers


Overrides of supplies a verse order. The values are separated by commas, rather than spaces as they are in the OpenLP Verse Order in the Editor

Hymn Line Hints

The supplied value is the line of comma separated lines to which the hint applies.


In the exported text version some hymns lack a space after a colon, making the projected version hard to read. This hint adds a space after a colon on those lines

AddSpaceAfterColon: 2,3,11,20


As above, for semicolons


The line should be used as the author of the Hymn, without splitting


The line should be moved to the OpenLP comments, not displayed as a one line verse, or used as an author.


The line should be ignored completely. The most common case for this is a line in the Hymn text saying


There should be an appropriate VerseOrder entry to supply this information


The line should be preserved as a blank line, without starting a new verse


This is particularly used for Canticles and Psalms. The printed editions have the lines which should be said by the whole congregation in bold type. Unfortunately the text export does not preserve this information and it has be be added back in via hints, which was simpler than parsing the exported .rtf (Rich Text Format) versions, which do have this information. You may want to create a Psalm variant of your normal Theme, to emphasis the difference between the words spoken by the worship leader and those spoken by the whole congregation.


The value is of the form 'line number' 'source verse number' 'substitution strings separated by vertical bar' The line is replaced by a copy of the source verse with all the lines substituted by the substitution strings

VariantVerse: 15 1 Blessed be the name of the Lord/Glory to the name of the Lord|blessed be the name/glory to the name

In the original text line 15 might have read '2 Glory to the name of the Lord ...'

Note that multiple substitution strings may be needed as the substitutions are case sensitive.