WorshipSong Band File Format

WorshipSong Band uses a single file to encapsulate an entire song.  All files for a song (including the ‘Tracks.txt file described below), are placed in a zip archive along with all other tracks and an optional branding icon. Zip files are a standard way of collecting and distributing files on all computer platforms. We recoommend WinRAR or Winzip (available on Mac or PC) to compress zip files, or standard operating system utilities may be used.  WorshipSong Band directly loads these zip files at runtime to populate your library and load songs, therefore no unpacking of the zip file is required when you install the song in your WorshipSong Band library. See the 'Help and Features' page for information on loading zip files into an installation of WorshipSong Band.  In version 2.4.1 and above, a text editor is built in to allow editing the tracks.txt file (Windows/Mac only).  This editor may be accessed by pressing the'E' key whan a song is loaded in WorshipSong Band.  For a tutorial on creating tracks.txt files, see Adding Songs.  A Tracks.txt template is here.

Tracks.txt File and Tags

To use WorshipSong Band, you must include a simple, human readable text file in the zip archive.  This is used  to describe features of a song to be presented and used in WorshipSong Band.  This file must be  called ‘Tracks.txt’ and consists of a number of tagged blocks.  A header section is always at the top.  For all blocks except the chords and header, there should be no blank lines within the block tags.


Header

[Header]  (Required) This tag is followed by the main information for a song.  The [End Header] tag terminates this section.. The lines are

- Version number.  The current version number is 0

- Song title

- Song provider

- Song writer(s)

- Song Genre (user defined)

- Song Key

- Song Beats per minute

- Song length in Minutes:Seconds format.  If you specify 0:00 OpenSetList will use the time of the longest track

- Song time signature.  Used when WorshipSong generates metronome tracks on the fly.  One of 2/4, 3/4, 4/4, 6/8, or 8/8


Example Header block:

[Header] //#version | Name | Source | Songwriter | Genre | BPM | |PlayTime
0
Today is the Day
PraiseCharts
Lincoln Brewster
Praise/Worship
D
5.00:00
4/4
Additional information, such as copyright notations
[End Header]
 

Tracks

The simplest WorshipSong Band file is a single MP3 track, which can be a split track of an entire song, or it may consist of up to 14 multitracks.

[Tracks]  (Required except for Pad Files) This tag is followed by the track list for the song (can be empty).   Tracks can be in MP3, OGG, WAV, AIFF, or FLAC format.  They should be stereo tracks, and should not be panned (unless the Split or Split Click tracktype is used).  WorshpSong pans clicks and tracks automatically during playback if split playback mode is selected.   MP3 compressed tracks give good performance and results on all platforms and are recommended for mobile platform use. If you are using an older platform such as a first generation IPad  It is recommended to keep the total track size (before creating the zip file) to less than 100MB to conserve device memory.  For an 12 track song, this will likely require a lower compression bitrate.  WorshipSong Band plays back songs from in-memory compressed streams, so songs are not decompressed except as they are played.  An end tag in the format [End Tracks] is required for the [Tracks] tag.

For each track:

- Track display name.  This should be 6 characters max.  There are two special track names: "Click" and "Cues", that both cause the contents of the track to be routed to the click audio output.

- Track file name, not case sensitive.  The track file should be present in the zip archive.

- Track Type Tag (Optional).  One of [Percussion], [Melodic], [Vocal], [Split], or [Split Click].   Tracks following this tag are treated as tracks of the given type.  Percussion tracks do not shift pitch.  Vocal tracks are notated for future use.  Split and Split Click tracks become separate mixer channels.  If these tags aren’t used tracks are assumed to be Melodic.

 

Example Tracks block:

 

[Tracks]
[Percussion]
Click
Click.mp3
Drums
Drums.mp3
[Melodic]
Bass
Bass.mp3
EG
EG.mp3
AG
AG.mp3
Piano
Piano.mp3
Strings
Strings.mp3
[Vocal]
Vocal
Vocal.mp3
BGV
BGV.mp3
[End Tracks]

 

Example Split Click block (becomes 2 channels, a click and a synth track):

[Tracks]|
[Spilt Click]
Click
Cornerstone Split Click(C).mp3
[End Tracks]

 

Example Split Click block (becomes 3 channels):

[Tracks]
[Spilt Click]
Click
Cornerstone Split Click(C).mp3
[Melodic]
Track
Cornerstone Rhythm (C).mp3
[End Tracks]

 


Sections

[Sections]  (Optional) This tag is followed by the sections of the song.  This divides the song up into sections based on play time that can be used for looping or showing chords.  Some songs will be well suited to looping, and others will not have been recorded with looping in mind.  See the WorshipSong Band web site for information on how to derive correct times for sections from tracks. An end tag in the format [End Sections] is required for the [Sections] tag.
For each section:

- Section display name.  This should fit in the available time space when the program displays the song

- Section time.  Time can be in two formats, and should be consistent through the entire [Sections] block:

- Minutes:seconds.decimal seconds format specifies the start of the section.  Using this format he first section should begin at 0:00
- A single integer beats format.  Using this format, the time specifies the number of beats in the section, and the time for the section is computed based on the set tempo for the song.

- Section cue tag (optional, WSB version 1.2 and higher).  Cue tag for section, allowing a direct jump to this section with a foot controller.  Can be one of  [Cue Point I], [Cue Point V], [Cue Point C], [Cue Point B], or [Cue Point O], for Intro, Verse, Chorus, Bridge, Outro, respectively.  Only one section should be designated for each type, if used, and not all tags must be specified.

Example Sections block using beats format:

 

[Sections] // #sections | name | start < name | start >… (max 16)
Intro
8
V1
32
[Cue Point V]
Chorus
32
V2
32
Chorus
32
[Cue Point C]
Solo
24
Bridge
40
Chorus2
32
[End Sections]


Example Sections block using time format:

 

[Sections] // #sections | name | start < name | start >… (max 16)
Intro
0:00
V1
0:23.996
[Cue Point V]
Chorus
0:56.020
V2
1:27.988
Chorus
2:00.006
[Cue Point C]
Solo
2:31.980
Bridge
2:55.977
Chorus2
3:27.973
[End Sections]

 


Presets

[Presets]  (Optional) This tag is followed by volume presets for the tracks.  This can be used to encode preset dynamics into song available by a single selection.  An end tag in the format [End Presets] is required for the [Presets] tag.
For each preset:

- Preset display name.  10 characters max

- Comma delimited list of levels that matches the numerical order of the tracks, from 0 to 10.  Can include decimal point for precise levels.


Example Presets block:

[Presets] //#Num presets | name | levels < name | levels >… (max 6)
All In
10, 10, 10, 10, 10, 10, 10, 10
Fade 1
10, 5.5, 10, 6, 9, 6, 9, 9
Drums
10, 0, 10, 0, 0, 0, 0, 0
[End Presets]

 


Chords

[Chords]  (Optional) This is the integrated chord chart for the song.  The chord chart matches chord and lyric information with the sections of the song defined in the Sections section, and a sections block must be provided to add chord charts.  An end tag in the format [End Chords] is required for the [Chords] tag.  The chord chart tag is followed by a set of chord blocks in the following format

 

[Section Name].  Must match a section from the Sections block.  The max spacing for a chord line on a ¾ aspect ratio device such as an IPad is about 70 characters, so break up the chord chart accordingly.  The spacing you prescribe in the text file for where chords fall over the text will appear in the display, even though the display uses proportional font spacing for readibility.  For each pair of lines in the chord chart for this section, put two lines:

- Chord line

- Lyric line (can be blank, must be present to preserve the spacing)

- [Lyric Break].  Cues a break in the lyric when displayed externally

- Lyric Break is followed by a time, in Minutes:seconds.decimal seconds or beats since the start of the section or last lyric break

- When a new section name is encountered the last one ends.  An extra blank line can precede this for readability.

- Only one chart section is needed for each uniquely named section

- Use [End Chords] tag to close off the chord chart


Example Chords block:

[Chords] // section name | chord line | text line…………….Limit|
[Intro]
A   E  F#m7  D
 
[V1]
      D                A      F#m7  E     D               A F#m E
I’m casting my cares aside.     Im leaving my past behind.
     D                A            F#m7      E       D    Bm7  D
Im setting my heart and mind on You,     Jesus.
[Lyric Break]
32
     D                 A    F#m7   E      D                   A F#m E
I’m reaching my hands to Yours,   believing there’s so much more,
D                     A          F#m7        E          D       Bm7 D
Knowing that all You have in store for me is good, its good.
 
[Chorus]
               A                    E              F#m7      D
Today is the day You have made. I will rejoice and be glad in it.
                    A                    E             F#m7      D
Today is the day You have made. I will rejoice and be glad in it.
[Lyric Break]
32
      Bm              A/C#                  D                E
And I won’t worry about tomorrow; Im trusting in what You say.
                A  F#m7  E           D       A  F#m7  E
Today is the day.           Today is the day.
 
[V2]
     D                A   F#m7   E        D             A    F#m  E
Im putting my fears aside.    Im leaving my doubts behind.
      D                A              F#m7    E   D   Bm7  D
Im giving my hopes and dreams to You,  Jesus.
[Lyric Break]
32
      D                 A    F#m7  E             D          A F#m  E
Im reaching my hands to Yours,   believing theres so much more,
D                     A          F#m7      E          D       Bm7  D
Knowing that all You have in store for me is good, its good.
 
[Solo]
E    A/C#    F#m    D    A
 
[Bridge]
A
I will stand upon Your truth. (I will stand upon Your truth.)
And all my days, Ill live for You. (All my days, I’ll live for You.)
[Lyric Break]
32
A
And I will stand upon Your truth. (I will stand upon Your truth.)
        Bm          D
And all my days, Ill live for You. (All my days, I’ll live.)
 
[Chorus2]
                   A                    E             F#m7       D
Today is the day You have made. I will rejoice and be glad in it.  
                 A                    E             F#m7       D
Today is the day You have made. I will rejoice and be glad in it.
[Lyric Break]
32
      Bm               A/C#              D              E
And I won’t worry about tomorrow. Im giving You my fears and sorrows.
Bm                           A/C#                    D         E
Where You lead me, I will follow; Im trusting in what You say.
[Lyric Break]
32
                A  F#m7  E           D         A  F#m7 E
Today is the day.             Today is the day.
               A  F#m7  E           D         A  F#m7 E
Today is the day.             Today is the day.
 
[End Chords]



Info

 

[Info]  (Optional) This is text you can provide to describe the song when it is selected in the library page.  An end tag is required.

- A line of text.  About 50 characters maximum

Example Info block:

[Info] // <line>………………………….Limit|
Lincoln Brewster has written a modern version of the
old Kid’s classic ‘This is the day’ for the modern
church.  This multi-track by PraiseCharts features a
driving beat, a smoking guitar riff, and  will
definitely get your congregation going!
[End Info]

 


Guide Track

[Guide Track] (Optional) The guide track section provides optional information to tailor the guide track (click and cues) that can be automatically played with tracks or a chord chart.  An end tag in the format [End Guide Track] is required for the [Guide Track] tag. Its format is:

- Name of the click.  The built-in click names are Bottle, Ping, Snap, Soft, Tambourine, Tone, Wood.  'Default' chooses the setting chosen in the app. 
- Cues On or Cues Off.  Controls whether audio cues are played for this guide track.  Default is Cues On
- Sync On or Sync Off.  Controls whether playback time is synced to song sections.  Default is Sync On
- Start Delay, in Minutes:seconds.decimal seconds format.  This is used to delay the click. Only values less that one beat length (in seconds) are supported

- End Short Time, in beats or Minutes:seconds.decimal seconds format.  The time before song end this guide track will fade out.

Example Guide Track block:

[Guide Track] Click to Use | Cue State | Sync State | Start Delay | End Delay
     Default
     Cues On

     
     Sync On

     0:0.44

     24

     [End Guide Track]

 


Presentation

[Presentation] (Optional, V 2.9 and above) The presentation block is used to specify video file names and automatic pad controls.  An end tag in the format [End Presentation] is required for the [Presentation] tag. Its format is:

-[Video Name] (Optional, Windows and Mac only) One line that must identify the file name of a video file located in the Videos subfolder of the WSB Library folder on the network node that is being used for lyric display (see networking) or the playback platform if networking is not being used.  This video will play in a loop and display underneath the lyric display during the entire time this song is loaded.  The selected image background logic will be used in any of the following cases:

          - The video file is not found in the specified location
          - The video file fails to successfully load
          - The [Video Name] tag or the [Presentation] block is omitted
          - WSB on the the platform does not support video

-[Pad Fade Times](Optional), two lines containing times in beats or Minutes:seconds.decimal seconds format.  The first time is the time after start of song to cue an automatic fade out action for pads.  The second time is the time before the end of the song to cue an automatic fade in action.  These only trigger the actions specified, as if you had initiated them yourself 

-[Pad Bank Name](Optional), One line that must be the name of a pad set as found on the settings page (see Pads below).  Whenever pads are faded in or cross faded while this song is loaded, the named pad bank will first be automatically selected. A value of Default or omitting this tag means the pad bank selected on the settings menu will be used

Example Presentation block:

[Presentation]
[Video Name]
LightStreaksDeepBlue.wmv
[Pad Fade Times]
24
24
[Pad Bank Name]
Default
[End Presentation]


Pads

One or more files in your library may be a collection of ambient pads.  These are used for the ambient pads feature.  This file should provde at least 12 ambient pads, one for each key.  Minor keys can also be specified.  The tag format is as follows.

[Pads]  (Special File Type, Optional) This tag is followed by a list of pads,one for each key.  Pads can be in MP3, OGG, WAV, AIFF, or FLAC format.  An end tag in the format [End Pads] is required for the [Pads] tag.

For each pad file:

- The key for the pad file, upper case

- Pad file name, not case sensitive.  The pad file should be present in the zip archive

Example Pads block:

[Pads]
D
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 02 Depth (Water in D).ogg
G
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 03 Glass (Water in G).ogg
C
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 04 Crystalline (Water in C).ogg
F
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 05 Flood (Water in F).ogg
Bb
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 06 Brookstones (Water in Bb).ogg
Eb
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 07 Elemental (Water in Eb).ogg
Ab
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 08 Angelfish (Water in Ab).ogg
Db
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 09 Downpour (Water in Db).ogg
Gb
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 10 Gulfstream (Water in Gb).ogg
B
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 11 Blue (Water in B).ogg
E
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 12 Estuary (Water in E).ogg
A
Karl Verkade - Water- Music for Meditation (Ambient Pads II) - 13 Atlantic (Water in A).ogg
[End Pads]

Typically your WorshipSong installation will come with a set of default pads and an example fileThis format is provided if you wish to customize this feature.


Cues

One or more files in your library may be a collection of cues.  These are used for the built-in cues feature.  This file should provide cues for each section header used in your library that you want an audio cue for. Tag format is as follows.

[Cues]  (Special File Type, Optional) This tag is followed by a list case insensitive strings that will match a given cue, folowed by the audio file for each cue.  Cues can be in MP3, OGG, WAV, AIFF, or FLAC format.  An end tag in the format [EndCuess] is required for the [Cues] tag.

 

Example Cues block:

[Cues]
Ch
Cho
Chorus
Chorus.ogg
V
Verse
V1
V2
Verse.ogg
[End Cues]

 Typically your WorshipSong installation will come with a set of default cues and an example file. This format is provided if you wish to customize this feature.

 

 


Stem Assignments

Stem assignments are used to allow additional audio output channels (above the standard 2/4 channel output scheme) to be used on Windows and MacOS platforms.  They may also be specified in a file called "MasterTracks.txt", which will contain a setof stem assignments inherited by all songs in your library.  This will enable you to use a track naming convention to set up extended audio busses.

[Stem Assignments]  (Optional) This tag is followed by a list of track display names followed by hardware channel numbers [End Stem Assignment] is required for the [Stem Assignments] tag.

For each stem assignment:

- Track display name.  These match the track display names used in the [Tracks] section
- Track channel number.  Any number from 1 to 16, or "Off" for certain built-in mixes.  Channels can be reused, allowing groups of tracks to be sent to a single channel.  If you are retaining the standard 4 channel output channels, this should be a number from 5 to 16.

These names can also be used for built-in tracks: 

- "Built In Pads":  This will route the built in pad track to the desired channel
- "Built In Cues": This will route the built in cues to the desired channel
- "Stereo Mix Left": This will re-route the left stereo full mix from channel 1 to another channel.  You can also specify "Off" to turn off this mix on channel 1 (enabling channel 1 to be used as an additional bus)
- "Stereo Mix Right": This will re-route the right stereo full mix from channel 2 to another channel.  You can also specify "Off" to turn off this mix on channel 2 (enabling channel 2 to be used as an additional bus)
- "Band Mix Left": This will re-route the left band mix from channel 3 to another channel.  You can also specify "Off" to turn off this mix on channel 3 (enabling channel 3 to be used as an additional bus)
- "Band Mix Right": This will re-route the right band mix from channel 4 to another channel.  You can also specify "Off" to turn off this mix on channel 4 (enabling channel 4 to be used as an additional bus)

The example below would be a use of an 8 channel audio output.  It turns off the standard band mixes but retains the house stereo mix on channels 1 and 2, and routes clicks/metronome/cues to channel 3, Drums and Bass to 4, Electric Guitars to 5, Acoustic Guitar to 6, Piano/Keys to 7,and vocals to channel 8.  You could then route these busses to band members individually as needed.

 

Example Stem Assignments block:

[Stem Assignments]
Band Mix Left
Off
Band Mix Right
Off
Metr
3
Click
3
Built In Cues
3
Drums
4
Bass
4
EG1
5
EG2
5
RG
5
AG
6
Piano
7
Keys
7
Vocal
8
BGV
8
[End Stem Assignments]

 

 


Branding Icon

The WorshipSong Band ZIP file can contain a file to be used for branding.  This file should be an image file in Targa (TGA) or bitmap (BMP) format, 64×64 pixels or less for efficiency, named either "icon.tga" or "icon.bmp".  TGA format will allow for a transparent background for slightly better presentation, and many free online tools can convert to this format.

The best practice will be to establish a brand/genre combination for resources you provide for WorshipSong Band that will result in the user community gaining confidence in the quality of resources you provide and trust in your brand.  WorshipSong Band is obviously a very flexible tool, and you can certainly release low quality content for it, or very high quality content created with with attention to detail.  Like any musical endeavor, attention to quality will result in a much better reception.

 


Background Image

The WorshipSong Band ZIP file can contain a file to be used as the background for a song.  This file should be an image file in Targa (TGA) or bitmap (BMP) format, 1024x576 pixels, named either "background.tga" or "background.bmp".  The image should be designed so that it still works well when centered on a 4/3 aspect ratio screen with equal amounds cropped from the left or right sides to fit the image to the aspect ratio without warping.  The use of these images in the lyric display is selectable by the end user.

 


Notes

The best practice is to use a sample song and modify it.  Run the song in your copy of WorshipSong Band on your PC or Mac to verify everything work as expected before sending it out.  The most common mistakes will be:

- Mispelling track names or adding extra spaces or lines.  The program tries to compensate for extra spaces before and after names but its a good idea to be precise.Use copy and paste for file names.

- Not adding blank lines in the chord chart so the chord and lyric lines get confused

- Mispelling section names in the chord chart, so the program cannot match the section with the chord.

- Not matching the levels with the tracks, or specifying too few levels in presets

- Section times or beat counts not matching the recording

 

 


Window Sizes

 

For Windows only, a text file named "windowsizes.txt" may be placed in the Library folder and used to control window sizes.  It can contain the following tags:

[Lyric Window Rect]  (Special File Type, Optional) This tag is followed by 4 lines, specifying the lyric window's X, Y, Width, and Height in pixels on the extended Window desktop. X of 0 is at the left, a Y of 0 is at the top.  The window will have no border

[Main Window Rect]  (Special File Type, Optional) This tag is followed by 4 lines, specifying the main window's X, Y, Width, and Height in pixels on the extended Window desktop. X of 0 is at the left, a Y of 0 is at the top.  The window will have no border. This means you will need to close the program using the taskbar since there will be no toolbar available to exit.

Example Window Sizes block:

 

[Lyric Window Rect]
1366
0
860
540
[Main Window Rect]
0
0
1366
768

 

 

 

©worshipsong 2016

Login or Register

LOG IN