Development:Song Importer Developers Guide

The Song Import Wizard has been designed to be pluggable for easily adding importers for more song formats. Adding a new importer involves little more than writing a parser for the new song format.

Song Import Wizard
Familiarize yourself with the Song Import Wizard, such as the controls used on the source page and progress page.

The Song Import Wizard is constructed by the SongImportForm class, found in. You generally shouldn't have to modify this class, but it can be helpful to understand how it works.

Base SongImport Class
Each song importer extends the base SongImport class, found in. It provides several methods you may wish to use which implement common functionality.


 * Override this static method to validate the source prior to import.
 * Override this static method to validate the source prior to import.


 * Create defaults for song properties - if importing many songs at once, call this before each song to ensure a clean beginning. You can also refer to this method's implementation to see all the song properties that are available.
 * Create defaults for song properties - if importing many songs at once, call this before each song to ensure a clean beginning. You can also refer to this method's implementation to see all the song properties that are available.


 * Called when a song could not be imported. The error is displayed to the user in a box below the progress bar on the progress page.
 * Called when a song could not be imported. The error is displayed to the user in a box below the progress bar on the progress page.


 * Get rid of some dodgy unicode and formatting characters we're not interested in.
 * Get rid of some dodgy unicode and formatting characters we're not interested in.


 * Build the copyright field.
 * Build the copyright field.


 * Add the author. OpenLP stores them individually so split by 'and', '&' and comma. However need to check for 'Mr and Mrs Smith' and turn it to 'Mr Smith' and 'Mrs Smith'.
 * Add the author. OpenLP stores them individually so split by 'and', '&' and comma. However need to check for 'Mr and Mrs Smith' and turn it to 'Mr Smith' and 'Mrs Smith'.


 * Add an author to the list.
 * Add an author to the list.


 * Add a verse. This is the whole verse, lines split by \\n. It will also attempt to detect duplicates. In this case it will just add to the verse order.
 * Add a verse. This is the whole verse, lines split by \\n. It will also attempt to detect duplicates. In this case it will just add to the verse order.


 * Repeat the previous verse in the verse order.
 * Repeat the previous verse in the verse order.


 * Check the mandatory fields are entered (i.e. title and a verse). Author not checked here, if no author then "Author unknown" is automatically added.
 * Check the mandatory fields are entered (i.e. title and a verse). Author not checked here, if no author then "Author unknown" is automatically added.


 * All fields have been set to this song. Write the song to disk.
 * All fields have been set to this song. Write the song to disk.

Writing an Import class
Begin by creating a new module containing a single class that extends the base SongImport class.
 * The class name should be the name of the format, and use CamelCase, for example "ZionWorxImport".
 * The module will have the same name, but lowercase, and will be in.

The  method provides an opportunity to validate the import source before attempting to parse it. This method is called when the user clicks "Next" from the source page of the wizard. If their source does not pass validation, they will see an error dialog explaining this (you can define the error message with in the next section).

Example implementation from the PowerSongImport class: If validation fails, the user will be told "You need to specify a valid PowerSong 1.0 database folder."

The import source is provided in. This can be either a list of files, a single file, or a single folder, as determined by the particular song format.

Registering an Import class
You need to "register" your importer, so the Song Import Wizard knows about it. This is done in the SongFormat class in the  module.

import statement
Add an import statement at the top of the module.

Song formats enumeration
Add your song format to the alphabetic enumeration of song formats, being sure to re-number the formats further down the list.

get_format_list
Add your song format to the  method.

Set attribute values
You can set various attributes for your song format which define its appearance and behaviour in the Song Import Wizard. Locate the  dict in the SongFormat class, and add a section for your song format. A few attributes are required for every song format, but most are optional. Default values for the optional attributes are supplied by the  dict.

Example implementation for the PowerSong format:

Required attributes

 * Import class, e.g.
 * Import class, e.g.


 * Name of the format, e.g.
 * Name of the format, e.g.


 * Prefix for Qt objects. Use mixedCase, e.g.
 * Prefix for Qt objects. Use mixedCase, e.g.

Optional attributes

 * Whether song format importer is disablable. If, then   must also be defined.
 * Whether song format importer is disablable. If, then   must also be defined.


 * Whether format accepts single file, multiple files, or single folder (as per  options).
 * Whether format accepts single file, multiple files, or single folder (as per  options).


 * File extension filter for the file selection dialog.
 * File extension filter for the file selection dialog.

Optional/custom text strings

 * Combo box selector (default value is the format's ).
 * Combo box selector (default value is the format's ).


 * Required for disablable song formats.
 * Required for disablable song formats.


 * Title for the file selection dialog (default includes the format's ).
 * Title for the file selection dialog (default includes the format's ).


 * Message displayed if  returns.
 * Message displayed if  returns.


 * Short description (1-2 lines) about the song format.
 * Short description (1-2 lines) about the song format.

Existing Song Importers
You may find some inspiration in the exising song import classes, especially those which parse a similar underlying file format.