Compose a worship presentation

Quick start

1. From Songs library or My songs, click Compose on a song.
2. Step 1 — Presentation details: set title, folder, Screen layout, aspect ratio, title/credits slides, and Worship outputs.
3. Step 2 — Select a theme: pick a required presentation theme.
4. Step 3 — Edit lyrics: adjust ChordPro Song text; fix parse errors before continuing.
5. Step 4 — Arrange sections: drag sections into the arrangement, split slides; optionally use Suggest arrangement (beta).
6. Click Create presentation — WorshipDeck opens /presentations/{id} for worship editing.

You should land on a worship deck (isWorshipSong) with optional lower-third and confidence variants.

Deep dive

Shared wizard (catalog and My Songs)

/songs/{id}/compose and /my-songs/{id}/compose share one wizard (ComposeSongPage + SongComposeWizard). Bootstrap loads via GET /api/songs/compose/{id}?source=:

Entry	Route	Bootstrap source
Catalog	/songs/{id}/compose	library
Church song	/my-songs/{id}/compose	church

The header shows Compose "{song title}" with Step {n} of 4: {step title}. Contextual help:

Surface	Location	Article
SongCompose.page	? next to the H1 title	This article (full wizard)
SongCompose.outputs	? next to Worship outputs on Step 1	This article (outputs focus)

Catalog browse and My Songs CRUD stay in Songs library and My songs — this article covers the wizard only.

Wizard steps

Step	Title (UI)	What you set
1	Presentation details	Title, folder, screen layout, aspect ratio, title/credits slides, worship outputs
2	Select a theme	Required theme (Next disabled until a theme is selected)
3	Edit lyrics	ChordPro source; parse errors block Step 4
4	Arrange sections	Section order, slide splits; optional AI suggest; Create presentation

Step 1 — Presentation details

Field	Purpose
Presentation title	Deck name (required to continue)
Folder	Optional presentations folder
Screen layout	Routes main / Variant 1 / Variant 2 to physical screens — see Screen layout assignment
Aspect ratio	16:9, 9:16, or 4:3
Add title slide	Optional opening title slide
Add credits slide	Optional closing credits slide
Worship outputs	Lower third and confidence toggles (section below)

Worship output variants

Compose auto-builds up to three content variants per lyric slide. Builder uses lower third displayIndex: 1 and confidence displayIndex: 2. Screen layouts name those slots Variant 1 and Variant 2. The filmstrip letters variants A / B (not plan-draft “B/C” wording).

Output	Variant index	Filmstrip	Compose toggle	Content
Main congregation slide	0 (main)	Numbered main thumbnails	Always on	Full lyrics (+ chords on main when the song has chord content)
Lower third	1	Letter A	Lower third (variant 1) + text/background colors	Bottom overlay text
Confidence monitor	2	Letter B	Confidence monitor (variant 2) + optional chords toggle + colors	Stage/congregation confidence lyrics

Mental model: Content variants.

Not the same as the Chords presenter tab. Musician full-deck chord charts use /presentations/{id}/chords — see Presenter views. Confidence-monitor chords are a content variant on the worship deck, not that presenter tab.

Lower third (variant 1)

Enable Lower third (variant 1) to generate filmstrip letter A slides with a bottom overlay style. When enabled, pick:

• Lower third text color (default #FFFFFF)
• Lower third background color (default #0EB258)

Use lower third for IMAG/streaming layouts where the main slide stays full-screen and a caption bar shows the current lyric line. Map this output to the layout slot named Variant 1.

Confidence monitor (variant 2)

Enable Confidence monitor (variant 2) to generate filmstrip letter B slides for a stage or stream confidence feed — typically larger type and fewer words per slide than the main output. When enabled, pick:

• Confidence text color (default #FFFFFF)
• Confidence background color (default #000000)
• Show chords on confidence monitor — only when the song has chords (see next section)

Map this output to the layout slot named Variant 2.

With or without chords

ChordPro [chord] markers (and stored lyricsWithChords) set hasChords on the song:

Song	Confidence enabled?	Show chords on confidence monitor
Has chords (hasChords)	Yes	Toggle visible — turn on for chords on confidence, off for lyrics-only confidence while the source still has chords
Lyrics only	Yes	Toggle hidden — confidence is lyrics-only
Either	No	Toggle hidden

Musicians who need a full chord chart during the service should use the Chords presenter tab — Presenter views — not the confidence variant.

Screen layout assignment

The Screen layout dropdown lists templates from Screen layouts (including No layout and {name} (default)). Each layout maps content types — main slide, Variant 1, Variant 2, speaker notes, blank — to physical Screens.

Step 1 shows this hint:

Map variant 1 to your streaming lower third and variant 2 to the confidence monitor in your screen layout.

Operators choose layouts in present mode — Screens and layouts. Admins define physical screens first, then bind them in layout templates. This article does not walk through the layout builder.

Step 2 — Select a theme

Pick a presentation theme (required). Themes control fonts and colors on generated worship slides. The theme grid opens on the Worship category by default. Use Popular, All, other category tabs, or Search themes to browse. Next stays disabled until a theme is selected.

Step 3 — Edit lyrics

Edit the ChordPro Song text before arranging. The wizard validates with parseSongText — fix errors before Next (Fix the song text errors before continuing.). Edits here apply to this presentation; they do not change the catalog or My Songs library copy unless you save there separately.

Step 4 — Arrange sections

Drag or double-click sections from the Sections pool into Arrangement, reorder, and use Split slides to break lines across slides. At least one arranged section is required (Add at least one section to the arrangement.).

AI arrangement (beta)

When bootstrap includes aiSongArrangementBeta (aiSongArrangementBetaEnabled for your church — env AI_SONG_ARRANGEMENT_BETA and optional church allowlist), Step 4 shows Suggest arrangement. That opens Review arrangement suggestions (ArrangementSuggestions): select section labels and slide splits, then Apply to arrangement.

This beta may not appear for all churches. If the button is missing, arrange sections manually.

After compose

Create presentation calls POST /api/presentations/compose-song with an Idempotency-Key so retries of the same payload do not create duplicate decks. On success you navigate to /presentations/{id}.

The result is a worship presentation. Further lyrics, arrangement, and chord styling live in Worship songs in presentations (and the presentation editor). Do not expect the compose output toggles inside the editor panel.

Re-apply from the editor

Re-applying the song from the worship editor (WorshipSongEditorPanel → worship-song apply) rebuilds slides from the arrangement and preserves snapshot.options.lowerThird and snapshot.options.confidence. Compose toggles are not re-exposed in the editor — change outputs by re-composing from Songs / My Songs, or by editing variant slides manually.

Tips

• Configure screen layouts before Sunday so Variant 1 and Variant 2 land on the correct outputs.
• Disable confidence chords when the stream feed should stay lyrics-only even though musicians use the Chords tab elsewhere.
• Finalize section order in Step 4 before heavy color tweaks on variant slides in the editor.

Troubleshooting

Select a theme / Next disabled on Step 2

• Step 2 requires a theme. Pick any theme card, then continue.

Fix the song text errors before continuing

• Return to Step 3 and correct ChordPro syntax shown in the preview.

Add at least one section to the arrangement

• In Step 4, drag at least one section into the arrangement list.

Lower third or confidence not on the right screen

• Confirm the presentation’s Screen layout maps Variant 1 and Variant 2 to the intended screens — see Screens and layouts.

Show chords on confidence monitor missing

• The song has no chord markers (hasChords false), or Confidence monitor (variant 2) is off. Add [chord] syntax in My songs or Step 3, then enable confidence.

Re-apply didn’t change lower third or confidence

• The editor preserves compose snapshot options; toggles are not in the worship editor. Re-compose from Songs / My Songs, or edit variant slides manually — see Worship songs in presentations.

Suggest arrangement missing

• AI arrangement beta (aiSongArrangementBeta) may be off for this church. Arrange sections manually.

Could not create the presentation

• Need at least one arranged section, a theme on Step 2, and clean Step 3 parse results. Check connectivity and retry (the request uses an idempotency key for the same payload). If the song revision changed during compose, refresh and start again from Compose.