Writing songs in .vct: a guide

A .vct file describes how one song goes: its tempo, its time signature, and its sections in order, with as many bars as each one lasts. From that, Visual Click Track builds the click, the voice that calls "Chorus… 3, 4" before each section, and the stage screen: where you are in the song, what comes next, and how many beats until it does. Add the words, the chords and cues for the band and they appear on the screen at the right moment too.

This guide is for the people who write the charts: worship leaders, MDs and band members. It starts with a six-line song and builds it up, one feature at a time, into a full chart. The reference at the end lists every header, modifier and option in one place. For the precise rules (the grammar, the order things are read in, the timeline the player builds), see the format specification, format.md.

Contents

• Part 1: Getting started
  • 1. Your first song
  • 2. How a file is laid out
  • 3. Sections and bar counts
• Part 2: Shaping how the song plays
  • 4. Repeats, open vamps and holds
  • 5. Tempo and time signature
  • 6. Voice cues and the countdown
  • 7. Arrangements
• Part 3: What's on the screen
  • 8. Markers: cues for the band
  • 9. Chords
  • 10. Lyrics
  • 11. Dynamics, feel, keys and who sings
  • 12. Song information
• Part 4: Beyond one song
  • 13. Backing tracks and stems
  • 14. Sets
  • 15. Sharing parts between songs
  • 16. Importing from other formats
• Part 5: Troubleshooting
  • 17. Error messages and what they mean
  • 18. Mistakes the player can't catch
• Part 6: Reference
• Appendix: the finished chart

The running example is Amazing Grace. The verses are John Newton's (public domain). The chorus was written for this guide, so there's something to repeat.

Part 1: Getting started

1. Your first song

In the player, press N on the SONGS tab (or click NEW SONG). The editor opens with a template. Replace it with this:

title:    Amazing Grace
tempo:    72
time:     4/4

Intro     4
Verse 1   8
Chorus    8
Ending    2

That's a complete song. Press F5 to hear it: two silent beats while the screen flashes a dot, one bar of count-in ("1, 2, 3, 4"), four bars of intro, and so on. Near the end of each section a voice calls the name of the next one and counts you in. The screen shows the section you're in, the one coming next, the bar and the beat. Press Esc to go back to the editor, and Ctrl/Cmd+S to save the song. It's saved in your songs folder (Documents/StageDisplay/songs) and shows up in the library.

Here is what each line means:

Everything else in this guide builds on those two kinds of line: headers (key: value) that describe the song, and sections (a name and a bar count) that list what's played, in order.

The editor helps as you type. It colours each part of a line, underlines mistakes straight away and lists them in the side panel, and suggests what can come next (press Ctrl+Space to see everything). It suggests "Verse 3" after "Verse 2", and it knows every header and modifier in this guide. Ctrl/Cmd+T switches to the Structure view, a form you can fill in instead of typing. Both views edit the same file.

2. How a file is laid out

A song file has two parts, always in this order:

1. The header: key: value lines that describe the song.
2. The body: the sections, from the first one to the last, with any lyrics, chords and cues written under the section they belong to.

The body starts at the first line that isn't a header. A header line after that is an error, so the song's details all go at the top.

# Amazing Grace, as we play it on Sundays.
title:    Amazing Grace
artist:   John Newton
key:      G
tempo:    72          # crotchets a minute

Intro     4
Verse 1   8
Chorus    8
Ending    2           # hold the last chord

A few rules are worth knowing from the start:

• Comments start with # and run to the end of the line. They're for you; the player ignores them. A # only starts a comment at the beginning of a line or after a space, so key: F#m keeps its sharp.
• Spacing is free. Use as many spaces as you like between the parts of a line, so you can line columns up. Blank lines are ignored.
• Upper and lower case don't matter in headers and modifiers (Tempo: works, and so does LOOP). Section names keep the case you give them, because that's how they're shown.
• The file is plain text (UTF-8), named something.vct. You can write it in any text editor, or on a phone, as well as in the player.

3. Sections and bar counts

A section line is a name, then a length in bars, then any number of modifiers (which come in Part 2):

<name>   <length>   [modifiers...]

Names are any text you like, spaces and numbers included: Verse 1, Pre-Chorus, Big Ending. The player knows the usual names (Intro, Verse, Pre-Chorus, Chorus, Bridge, Tag, Outro and others; the full list is in the reference) and gives each kind its own colour on the song map. A name it doesn't know works the same way and gets a plain colour.

Lengths are usually a whole number of bars. When a section ends with a short bar, add the extra beats after a +:

title:    Amazing Grace
tempo:    72

Pickup    0+2         # the band comes in on beat 3
Verse 1   8
Turn      1+2         # one bar, then two beats, straight into the chorus
Chorus    8

The short bar uses the song's beat, so 0+2 in 4/4 is two crotchets. It must be shorter than a full bar: 0+4 in 4/4 is an error, because that's just 1.

The one to watch: forgetting the bar count. Verse 1 on its own is not an error. The player reads it as a one-bar section called Verse, because the 1 is taken as the length. Check the song map after you type a numbered section: a verse that's a thin sliver instead of a long block has lost its bar count. Write Verse 1 8.

Looser spellings. If you're used to other chart formats, these all mean Verse 1 8:

Verse 1: 8
[Verse 1]  8
Verse 1 (8)

Long lines. A line starting with + and a space adds to the section line above it. This keeps things readable on a narrow phone screen:

title:    Amazing Grace
tempo:    72

Chorus    8   x2
  + say="Big chorus"
  + dyn=f

Part 2: Shaping how the song plays

Modifiers go after the bar count and change how a section plays. Some apply only to their own section; others, like a tempo change, carry on into the sections after it until you change them again. The modifier table says which is which.

4. Repeats, open vamps and holds

Play a section more than once: x2

title:    Amazing Grace
tempo:    72

Verse 1   8
Chorus    8   x2

x2 plays the chorus twice in a row (x3 three times, and so on). The screen shows Chorus 1/2, then Chorus 2/2, and the voice announces the second time round as "Again". Any lyrics, chords and cues you write under the section come back on every pass.

An open vamp: loop

Some sections don't have a fixed length: you sing the chorus until the leader moves on, or vamp under a prayer. Mark the section loop:

title:    Amazing Grace
tempo:    72

Chorus    8   loop
Ending    2

The chorus plays, and then plays again, and keeps going round. When it's time to move on, the operator presses Next (Space on the stage, or a page turner pedal). The pass that's playing finishes, and then the song carries on into the Ending. You never cut off mid-phrase: Next means "this is the last time round".

The voice cue for the next section waits for Next too. Until it's pressed the voice stays quiet at the end of each pass, and the screen's countdown is blank, because nobody knows yet when the loop will end. Press Next early in the last pass and you get the full "Ending… 3, 4" as usual. Press it in the pass's last bar and the voice says only the counts still to come.

A loop section can't also have x2. That would mean "twice, then forever", so it's an error.

Wait for the leader: hold

hold plays the section's bars, then stops the click and waits. Use it for a fermata, a free-time moment, or the last chord of the song:

title:    Amazing Grace
tempo:    72

Verse 4   8   hold    # last line, rubato; the band waits on the final chord
Tag       4
Ending    1   hold

When the leader is ready, the operator presses Next, and the next section starts straight away, on its first beat, with no extra count-in. A hold on the last section of the song waits for Next before the song finishes, so the screen doesn't go back to the menu while the chord rings.

Next can also be pressed before the hold arrives. That cancels the hold, and the song carries straight on as if it weren't there. That's handy when the leader signals in the last bar that there won't be a pause this time.

Next, in short

5. Tempo and time signature

The starting tempo

tempo: in the header is the tempo at the start, in beats per minute. It can be a decimal (tempo: 140.5), and it must be between 20 and 400.

A beat is the bottom number of the time signature: crotchets in 4/4, quavers in 6/8. So a 6/8 song felt at 60 dotted crotchets a minute is tempo: 180, because that's 180 quavers a minute. The click sounds on every quaver, with accents on 1 and 4.

Changing tempo: @

@76 changes the tempo from the start of a section, and the new tempo stays for the rest of the song (or until another @):

title:    Amazing Grace
tempo:    72

Verse 3   8
Bridge    8   @76     # lifts here...
Chorus    8           # ...and stays at 76

@72>80 is a ramp: the tempo starts at 72 and speeds up smoothly, beat by beat, to reach 80 by the end of the section. The song carries on at 80 afterwards. A ramp can slow down too (@80>66), and on an x2 section it spreads across both passes.

Changing the time signature

Write the new time signature after the bar count. Like tempo, it lasts until the next change:

title:    Amazing Grace
tempo:    72

Verse 2   8
Break     1   2/4     # one bar of two
Chorus    8   4/4     # back to four

The top number can be 1 to 32. The bottom one must be 2, 4, 8 or 16.

If only the last bar of a section is short, a length like 2+2 (section 3) is quicker than switching time signature and back.

Changing the click itself

Three modifiers change how the click sounds without changing the timing:

Then there's tacet, for when nobody plays: the click goes quiet as with quiet, and the screen shows TACET.

6. Voice cues and the countdown

This is the part the band hears most, so it's worth knowing exactly when the voice speaks.

The default

Every section except the first is announced in the last bar of the section before it. The voice says the name on beat 1, then counts the second half of the bar:

                last bar of the Verse            first bar of the Chorus
4/4             "Chorus"   ·    "3"    "4"      ▶ Chorus
3/4             "Chorus"   ·    "3"             ▶ Chorus

In a 6/8 bar it counts "4, 5, 6". In a 2-beat bar it counts only "2", and in a 1-beat bar it says the name and nothing else.

The count-in is different: it counts every beat ("1, 2, 3, 4"). The first section's name is shown on the screen during the count-in, but not spoken. count-in: 2 gives two bars of count-in, and count-in: 0 none at all (the song starts on its first beat). The most is 4.

Earlier warning: cue-ahead: 2

For a band that likes more warning, cue-ahead: 2 in the header moves the name a bar earlier. It's spoken on beat 1 of the second-to-last bar, and the whole last bar is counted:

                second-to-last bar           last bar                   ▶
cue-ahead: 2    "Chorus"  ·  ·  ·            "1" "2" "3" "4"            ▶ Chorus

ahead=1 or ahead=2 on a section sets this for that section's announcement only. If the section before is too short for a two-bar cue (a one-bar Fill, say), the cue falls back to the one-bar style.

Counting up, down, or not at all: countdown:

Changing what's said, or saying nothing

title:    Amazing Grace
tempo:    72
cue-ahead: 2

Verse 1      8
Fill         1   ahead=1             # no room for a two-bar cue
Chorus       8   x2   say="All in"
Last Chorus  8   show="Chorus (as led)"   say="Chorus"
Tag          4   silent

What the screen shows

The screen always counts, whatever the voice settings: the bars left in the section are always shown, and in the cue window (the last bar, or the last two with cue-ahead: 2) a big number counts the beats until the next section. During the count-in, the whole count-in is counted. In the last section it counts to the end of the song. While a loop is waiting for Next it's blank.

In the last bar before each section (with cue-ahead: 2 too, just the last bar), the built-in screens cover everything with the count: the next section's name ("CHORUS IN") over one big number, 4, 3, 2, 1 in 4/4, lighting up on each beat. It goes on the section's first beat, when the screen is back. The count-in's last bar is counted the same way, and when a song starts from the top, two silent beats come before the count-in while the screen flashes a dot on each, so the band can see the tempo before the count. A song with count-in: 0 starts on its first beat, with no dot.

7. Arrangements

So far the sections have been written out in the order they're played. That works well, and for many songs it's all you need. But a song that repeats a lot means writing the same chorus, with its lyrics and chords, several times. And when you play the song in more than one way (a full version and a short one, say), you'd need one file for each.

Arrangements fix both. Write each section once, then list the orders it can be played in:

title:    Amazing Grace
tempo:    72
arrangement: Full  = Intro, Verse 1, Verse 2, Chorus, Verse 3, Chorus x2, Ending
arrangement: Short = Intro, Verse 1, Chorus, Ending

Intro     4
Verse 1   8
Verse 2   8
Chorus    8
Verse 3   8
Ending    2   hold

The first arrangement is the one that plays. A set (section 14) can pick another one for a particular service.

Each item in the list can be:

title:    Amazing Grace
tempo:    72
arrangement: Radio = Verse 1, (Verse 2, Chorus) x2, Chorus*4, Ending

Verse 1   8
Verse 2   8
Chorus    8
Ending    2

Some details:

• Names are matched ignoring case and spaces, so verse1 finds Verse 1. Every name must be a section in the file.
• Lyrics, chords and cues are written once, under the section, and come with it wherever it plays. With Chorus*4, anything written past bar 4 is an error, because the shortened chorus doesn't have those bars. Use last-bar (section 8) for a cue that should land on the final bar however long the section is.
• Tempo, time signature, dynamics and feel are worked out in the order the sections are written in the file, not the order the arrangement plays them. A section plays at the tempo it has in the file, wherever the arrangement puts it. So the safest place for an @76 is on the section it belongs to, rather than relying on it carrying over from the section above.
• Once a file has an arrangement:, it always plays one. Every section you want in the default version must be in the first arrangement. A section in the file that no arrangement lists is never played.
• An arrangement can't be called Original. That name is kept for the song as written.

Which should you use? If the song is played one way and it's not long, write it out: it's easiest to read at a glance. Use arrangements when the same section comes back with lyrics or chords you'd otherwise copy, or when the band plays more than one version of the song.

Part 3: What's on the screen

The lines in this part go under a section, indented to show they belong to it. (The indent is for you; the player doesn't need it.) Each one starts with a symbol that says what it is:

Each of them is given a position inside its section: a bar, or a bar and a beat.

Bars count from 1 at the start of each section, not the song. On an x2 or loop section the positions are counted again on each pass, so a cue comes back every time round.

8. Markers: cues for the band

A marker puts a message on the screen at a given moment:

title:    Amazing Grace
tempo:    72

Intro     4
  > 3     Keys only
Verse 1   8
  > 5     Drums in
  > 8.3   Hits on 3 & 4

The message appears as a banner at bar 5, beat 1 of the verse, and stays up until the next marker or the next section.

Making a marker speak

Markers are silent unless you ask. End the line with say to have the voice read the text out, or say="…" to have it say something shorter:

title:    Amazing Grace
tempo:    72

Verse 1   8
  > 5     Drums in            say
  > 7     Big build to chorus say="Build"

If a section announcement falls on the same beat, the announcement wins.

Marker options

A marker can say more than "bar and text". These go between the position and the text, in any order:

title:    Amazing Grace
tempo:    72

Verse 2   8   x2
  > 1-4         Pads only           # stays up through bar 4
  > last-bar.3  Push!               # beat 3 of the last bar, whatever the length
  > 5  [drums]  Hits on 3 & 4       # for the drummer
  > 6  !watch   Eyes on the leader  # a kind of cue
  > 8  !stop                        # a kind needs no text: shows STOP
  > 2  pass=2   Add the harmony     # second time round only

Who sees a role's cues. Every screen shows every cue, with its role as a tag, so each player can pick out their own. A role doesn't hide cues from anyone yet: there's no setting for a screen, layout or set that shows only one role's cues.

9. Chords

There are two ways to put chords on the screen, and most songs use both.

Chords by the bar: chord lines

A marker whose text starts with | gives the chords bar by bar, starting at the marker's bar. Each |…| is one bar, and a bar can hold more than one chord:

title:    Amazing Grace
key:      G
tempo:    72

Intro     4
  > 1     | G | C  G | G | D |
Verse 1   8
  > 1     | G | G7 | C | G | G | Em | D | D |

The stage shows the current bar's chords, with the next bar's dimmed beside them. Chord names are free text, kept exactly as you write them: F#m7, D/F#, N.C. and % all work. A chord line that runs past the end of its section, or has an empty bar (| |), is an error.

You can start a chord line at any bar, and use several in a section. Here, the last bar changes on the second pass:

title:    Amazing Grace
tempo:    72

Chorus    8   x2
  > 1         | C | G | D | G | C | G | D | G |
  > last-bar  pass=2   | D |

Chords over the words

In a lyric line (section 10), a chord in square brackets, written right against a word, puts the chord over that point of the line, like a chord sheet:

title:    Amazing Grace
tempo:    72

Verse 1   8
  " 1     A[G]mazing grace, how [C]sweet the [G]sound
  " 3     That saved a wretch like [D]me

The brackets aren't part of the words; the chord is drawn above them. There must be no space between the chord and the word it falls on. [G]sound is a chord, while [Ann] words (with a space) is a tag saying who sings the line (section 10).

When to use which? Chord lines say which bar a chord is in. Chords in the words say which word it falls on. Use chord lines for bars nobody sings over (intros, turnarounds, instrumentals), and chords in the words for the rest. The strip and sheet stage layouts draw chord lines as a lead sheet. The lyrics layout can draw chords above the words.

10. Lyrics

A lyric line starts with " and a space, then a position, then the words:

title:    Amazing Grace
tempo:    72

Verse 1   8
  " 1     Amazing grace, how sweet the sound
  " 3     That saved a wretch like me
  " 5     I once was lost, but now am found
  " 7     Was blind, but now I see

On the screen, the line being sung is shown large, karaoke style, with the next line dimmed beneath it. A line that starts on a beat other than 1 is tagged ON 3 (or whichever beat) so the singers know when to come in.

The words run to the end of the line. Quote marks in them are just text, so " 3 He said "come" is fine. A # after a space still starts a comment.

Lines that start before the bar

A pickup that's sung before the downbeat belongs at the end of the section before it. It stays on the screen into the next section:

title:    Amazing Grace
tempo:    72

Intro     4
  " 4.3   A-
Verse 1   8
  " 1     -mazing grace, how sweet the sound

Lines in order

A section's lyric lines must be in order of position, with no two on the same beat. The player uses that order to show the "next" line.

Spreading lines evenly: /

If the lines of a section are spaced evenly, give them all at once, separated by / (a slash with a space each side). They're spread evenly from the position to the end of the section:

title:    Amazing Grace
tempo:    72

Verse 2   8
  " 1     'Twas grace that taught my heart to fear / And grace my fears relieved / How precious did that grace appear / The hour I first believed

That gives lines at bars 1, 3, 5 and 7. The position must be a whole bar, and the lines must divide the bars left exactly (four lines in 8 bars, yes; three lines in 8 bars, no). If they don't, the words are shown as written, slashes and all. For a slash that should never split a line, write \/.

Who sings: tags

A word in square brackets with a space after it, straight after the position, says who sings the line. It's shown beside the line:

title:    Amazing Grace
tempo:    72

Verse 3   8
  " 1     [Ann]  Through many dangers, toils and snares
  " 3     [Ann]  I have already come
  " 5     [All]  'Tis grace hath brought me safe thus far
  " 7     [All]  And grace will lead me home

A tag before /-separated lines applies to all of them. Brackets with nothing after them (" 5 [Instrumental]) are shown as the words. Other asides, like (echo), are shown as written.

Clearing the screen

A lyric line with a position but no words clears the lyrics from that beat:

title:    Amazing Grace
tempo:    72

Verse 4   8
  " 1     When we've been there ten thousand years
  " 3     Bright shining as the sun
  " 5

Without it, a line stays up until the next one starts, or until a section with no lyrics starts. After a clear, the next line appears dimmed only one bar before it's sung, rather than all through the gap.

More than one language

Put a language label straight after the quote mark to give the same words in another language. Labels are language codes: two or three lower-case letters, optionally followed by a country (fr, es, fr-CA). Lines with no label are in the song's main language, which lang: in the header names.

title:    Amazing Grace
lang:     en
tempo:    72

Verse 1   8
  " 1     Amazing grace, how sweet the sound
  "fr 1   Grâce étonnante, ô doux son
  " 3     That saved a wretch like me
  "fr 3   Qui sauva le pécheur que j'étais

The screen shows one language at a time: the unlabelled one, unless a set picks another (section 14). Each language's lines are kept in order on their own.

11. Dynamics, feel, keys and who sings

These modifiers add information for the band. They're shown as tags on the stage, and none of them changes the click.

Dynamics: dyn=

Six levels, which can be written as a music marking, a number or a word:

dyn=p sets a level. dyn=mf>ff builds across the section from one level to another. A level carries on into the sections after it until you set another. The stage shows the level as six rising bars.

Feel: feel=

One of straight, half-time, double-time, swing, rubato, build or drop. Like dyn=, it carries on until changed, so use feel=straight to go back to normal after a half-time bridge.

Changing them mid-section

A marker made only of dyn= and feel= settings changes them part-way through a section, with no banner:

title:    Amazing Grace
tempo:    72

Verse 1   8   dyn=p
  > 5     dyn=mf
  > 7.3   dyn=f  feel=build

A marker takes one level, not a build. If there's any other text in it (> 5 dyn=p but softer), it's an ordinary banner instead.

Keys and modulations: key=

The header's key: is the song's key. key=A on a section changes it from that section on. The stage marks the change with where it came from and how far it went up, e.g. KEY G > A +2. Nothing is transposed: the key is there for the band to read.

title:    Amazing Grace
key:      G
tempo:    72

Chorus       8
Last Chorus  8   key=A    # up a tone

People: lead=, harm=, band=

Put a name with spaces in quotes: lead="Sam and Ann".

Notes and jump protection

12. Song information

The rest of the header keys describe the song. None of them change how it plays.

title:     Amazing Grace
artist:    John Newton
key:       G
key[Sam]:  A
key[Ann]:  F
capo:      0
ccli:      22025
copyright: Public domain
tags:      hymn, communion
source:    Hymnal, no. 378
tempo:     72

Verse 1    8

Versions. If you keep an acoustic version of a song as its own file, give it a version::

title:     Amazing Grace
version:   Acoustic
tempo:     66

Verse 1    8

The library shows it in the version column, next to the Original. Two files with the same title and no version (or the same version) get a warning, because a list can't tell them apart. version: Original is an error: that's the label for the file with no version.

Part 4: Beyond one song

13. Backing tracks and stems

One backing track: audio:

title:        Amazing Grace
tempo:        72
audio:        amazing-grace.wav
audio-offset: 1.25

Intro         4

audio: names the recording to play along with the click, relative to the song's own folder. In the editor, the AUDIO field's CHOOSE… button opens a file picker and writes the path for you.

audio-offset: is the time, in seconds into the recording, where bar 1 of the first section begins (the downbeat after the count-in). Leave it out and the player finds it by listening for the beat; 0 means bar 1 is at the very start of the file. The editor's FIND button (Ctrl/Cmd+B) measures it and fills it in.

Anything in the recording before bar 1 plays during the count-in. If the track opens with a lead-in before the first bar (a guitar slide, a drum fill), set audio-offset: to where bar 1 starts, after the lead-in, and the lead-in plays over the end of the count-in. A one-beat slide at 110 BPM is 0.55 seconds long, so a recording that starts with one has bar 1 at about 0.55 (plus any silence before the slide). FIND can be a beat out on a track like this; check it by ear.

The click follows the recording, not the other way round, so the two never drift apart, even over a long song.

The recording is loaded when the song goes on stage, and the song can't be started until it has: the bottom of the screen says LOADING AUDIO…, then AUDIO READY, and Enter starts it from there. Starting a set usually catches its first song still loading, so it waits on stage for that Enter. This keeps the song from starting without the opening of its recording.

Once a song's recording is in, the player loads the next song of the set in the background, so moving on to it is ready straight away. Songs already played stay loaded too, so going back to one, or from the stage to the set list and back, doesn't wait again. Change a song's chart or its audio and it loads afresh.

Level: audio-gain:

audio-gain: -3 (or -3 dB, or +1.5) sets the recording's level, so tracks recorded at different volumes sit together. A boost is limited rather than allowed to clip. A song with audio-gain: plays at exactly that level; a song without it is normalised when the player's Normalise setting is on.

Stems: audio[Label]:

For a multitrack backing, name each stem with a label in square brackets:

title:        Amazing Grace
tempo:        72
audio[Drums]: stems/drums.wav
audio[Bass]:  stems/bass.wav
audio[Keys]:  stems/keys.wav   gain=-3 pan=40
audio[Guide]: stems/guide.wav  muted
audio-offset: 1.25

Intro         4

All the stems play together. On stage, keys 1 to 9 mute and unmute them, and Tab opens a mixer with volume and pan for each. After the file name you can add, in any order:

• muted starts that stem muted.
• gain= sets the stem's level in dB, like audio-gain: does for the whole recording: gain=-3 turns it down 3 dB, gain=+1.5 up (a boost is limited, not clipped; at most 40 dB either way). The mixer's volume slider still starts at 100% and moves from there.
• pan= sets where the stem starts in the mixer's pan, from pan=-100 (all the way left) to pan=100 (all the way right); pan=0 is the centre. A right click on the pan slider puts it back there.

Gain and pan are 0 unless you say, and a video made with --render uses them too. audio-offset: and audio-gain: apply to all the stems.

Stems must line up to the sample: export them from the same session in your recording software, all starting at the same point. Each label can be used once, and Backing is kept for the plain audio: track.

Both, and switching between them: audio-mode:

A song can name a full backing track and its stems. Without audio-mode:, they all play together, with the backing as one more stem called Backing. audio-mode: backing plays only the audio: track; audio-mode: stems plays only the stems. One line switches between them.

14. Sets

A set is the list of songs for a service. It's a file of its own, in the sets folder next to songs, and is usually made in the player: press N on the SETS tab to open the set editor, add songs, drag them into order and save. As a file, it looks like this:

set:          Sunday Morning
layout:       lyrics
stage-layout: click
theme:        contrast

song: amazing-grace.vct
song: "How Great Thou Art.vct"   arrangement="Short"   key=Bb   tempo=68
song: amazing-grace.vct          lang=fr

Each song can take these, after the file name:

If a song file is missing, the set shows it as one that can't be played. If an arrangement has been renamed or removed, the song plays its first one instead, with a warning.

Which screen shows what: layout: and stage-layout:

The laptop running the player is the host; any projector or monitor turned on in its displays list (D on the home screen) is a stage display. They can show different things. In the set editor these are the LAYOUT (L), STAGE DISPLAYS (D) and THEME (H) chips beside the set's name. Say the band only wants the click and the cues on the screen in front of them, while you keep the full view:

set:          Sunday Morning
stage-layout: click

song: amazing-grace.vct

click is a built-in layout with just the metronome, the count-in to each section ("Chorus in 3") and the cues. With no layout:, the host keeps its usual one.

With more than one screen, name one in square brackets to give it a layout of its own. Here the projector shows the words and every other screen the click:

set:                    Sunday Morning
stage-layout:           click
stage-layout[EPSON PJ]: singers

song: amazing-grace.vct

The name is the one the displays list shows (D on the home screen); a second screen with the same name is Name (2). Capitals don't matter. In the set editor, D (or a click on the STAGE DISPLAYS chip) opens a list with a row for every display, one for each screen connected now and each the set already names, so you can set a venue's screens up at home. Left and Right change the selected row's layout. A screen the set names that isn't plugged in is simply left out.

A song can say the same in its header, for while it's on stage. Its lines win over all of the set's, and the set's come back for the next song:

title:        Amazing Grace
tempo:        72
layout:       lyrics
stage-layout: singers

Verse 1    8

Leave the lines out and nothing changes: the host shows the player's own layout, and each stage display shows the one picked for it in the displays list (or the host's, if none was picked). A stage-layout: replaces those picks on every display while it applies, and stage-layout[Display]: on that one display. L on stage still switches the host's layout for the moment; a song with its own layout: takes over again when it comes on.

15. Sharing parts between songs

If you use the same ending, or the same count-in vamp, in many songs, keep it in a file of its own and include it:

title:    Amazing Grace
tempo:    72

Verse 1   8
Chorus    8
include:  stock/big-ending.vct

Where the include: line is, the player reads the other file's sections, markers and lyrics as if they were written there. The file is named relative to the song's folder and must be inside it (no ..). It can't contain header lines. It can include other files, up to four deep.

Two things to know: included files are read again each time the song loads, so a change to the shared file reaches every song that uses it. And the web version of the player can't read other files, so a song with include: won't open there.

16. Importing from other formats

You don't have to type every chart from scratch. The SONGS tab's IMPORT button (or I) reads songs from files or pasted text in these formats:

Always check the bar counts after an import. A chord sheet or ChordPro file doesn't say how many bars each line takes, so the import guesses: one bar per chord, or one bar per line of words with no chords. A song with no tempo gets 100 BPM. The imported file says so in a comment at the top. Play it against the recording, then fix the lengths in the editor.

Section names are guessed too when the source has none (a score marked A, B, C, or words pasted with no headings): the parts that come back become the chorus. Check them.

EXPORT (X on a song, or Ctrl+E in the editor) goes the other way, and writes a song as a chord sheet, lyrics sheet, ChordPro or .vct.

Part 5: Troubleshooting

17. Error messages and what they mean

A song with an error won't play. The editor underlines the problem and lists it with its line number. That's deliberate: a wrong bar count found mid-service is worse than no click at all. Warnings don't stop the song; they point out something the player skipped.

18. Mistakes the player can't catch

These lines are valid, so nothing is underlined, but they don't do what was meant:

• A missing bar count on a numbered section. Verse 1 alone is a one-bar section called Verse (see section 3). Look for thin slivers on the song map, or check each section's BARS in the Structure view (Ctrl/Cmd+T).
• A tag that was meant as a chord. " 1 [G] Amazing grace (with a space) is a singer tag reading "G", not a chord. Write [G]Amazing grace.
• A chord that was meant as text. [Instrumental]play (no space) is drawn as a chord called Instrumental over the word. Put a space in, or drop the brackets.
• A section left out of the arrangement. Once a file has arrangement: lines, a section that's not in the first one doesn't play by default.
• A tempo that seems to jump in an arrangement. Tempo changes follow the file's order (section 7). Put the @ on the section that needs it.
• Two markers on the same beat. Only the later one shows.
• A pass=3 cue on a section that only plays twice. It never shows.
• An unknown !word. Only !kick, !stop, !build, !breathe and !watch are cue kinds. Anything else, like !!!, is shown as text.

The surest check is to play the song through against the recording with F5 before it's needed on stage. The PRACTICE slider (or [ and ]) speeds the audition up, to 150%.

Part 6: Reference

Line types

Header keys

Section lengths

Section modifiers

"Lasts" says whether a modifier applies to its section only, or to every section after it (in file order) until changed.

Values with spaces go in double quotes. A section name that would itself look like a modifier or a length goes in quotes too: "x2" 4.

Section names

The player colours these on the song map (case doesn't matter, and a number after the name is fine): Count-in, Intro, Verse, Pre-Chorus, Chorus, Post-Chorus, Bridge, Interlude, Instrumental, Turnaround, Break, Breakdown, Fill, Build, Tag, Vamp, Refrain, Outro, Ending. Other names work the same way, with a plain colour.

Markers

> POSITION  [OPTIONS]  [TEXT]  [say | say="…"]

Chord lines

> POSITION  [pass=N]  | chords | chords | … |

One |…| group per bar from the position on. Each bar needs at least one chord, and the line must end inside the section.

Lyric lines

"[LANG] POSITION  [[Tag] ]  WORDS

Arrangement items

Set files

Limits

Appendix: the finished chart

Everything from this guide, in one song:

# Amazing Grace: verses by John Newton (public domain);
# the chorus was written for this guide.

title:      Amazing Grace
artist:     John Newton
key:        G
tempo:      72
time:       4/4
count-in:   1
cue-ahead:  2
ccli:       22025
copyright:  Public domain

arrangement: Full  = Intro, Verse 1, Verse 2, Chorus, Instrumental, Verse 3, Chorus x2, Last Chorus, Ending
arrangement: Short = Intro, Verse 1, Chorus, Ending

Intro          4    dyn=p    band="keys"
  > 1          | G | C  G | G | D |
  > 3          Keys only
  " 4.3        A-

Verse 1        8
  > 1          | G | G7 | C | G | G | Em | D | D |
  > 5          [drums]  Brushes in
  " 1          -[G]mazing grace, how [C]sweet the [G]sound
  " 3          That saved a wretch like [D]me
  " 5          I [G]once was lost, but [C]now am [G]found
  " 7          Was blind, but [D]now I [G]see

Verse 2        8    dyn=mf
  > 1          | G | G7 | C | G | G | Em | D | D |
  " 1          'Twas grace that taught my heart to fear / And grace my fears relieved / How precious did that grace appear / The hour I first believed

Chorus         8    dyn=f    lead=Sam
  > 1          | C | G | D | Em | C | G | D | G |
  " 1          [C]Oh, the grace that [G]found me
  " 3          [D]Holds me, never [Em]lets me go
  " 5          [C]Oh, the love that [G]called me
  " 7          [D]Home, now I am [G]home

Instrumental   4    dyn=mf>f   feel=build
  > 1          | C | G | D | D |
  > 3          !watch   Eyes on Sam
  " 1

Verse 3        8    @72>76   harm=Ann
  > 1          | G | G7 | C | G | G | Em | D | D |
  " 1          [Ann]  Through many dangers, toils and snares
  " 3          [Ann]  I have already come
  " 5          [All]  'Tis grace hath brought me safe thus far
  " 7          [All]  And grace will lead me home
  > 7.3        dyn=ff

Last Chorus    8    loop    key=A    show="Chorus (as led)"   say="Chorus"
  > 1          | D | A | E | F#m | D | A | E | A |
  > 5          pass=2   Down to keys    say
  " 1          [D]Oh, the grace that [A]found me
  " 3          [E]Holds me, never [F#m]lets me go
  " 5          [D]Oh, the love that [A]called me
  " 7          [E]Home, now I am [A]home

Ending         2    hold     dyn=p
  > 1          | D | A |
  > last-bar   !stop

A few things to notice:

• Chorus x2 in the Full arrangement plays the chorus twice, with the voice announcing the second time as "Again".
• Last Chorus is a separate section, not a third pass of Chorus, because it's in a new key and loops until the leader moves on.
• The pickup "A-" is at the end of the Intro, on beat 3 of its last bar, so it shows before the verse starts.
• The Instrumental's empty lyric line clears the words while nobody sings.
• Verse 3 speeds up from 72 to 76, and the rest of the song stays at 76.