Add or edit a song

Quick start

1. Open My Songs and click Add song (/my-songs/new), or Edit on an existing row (/my-songs/{id}/edit).
2. On the Edit tab, enter ChordPro-style song text (see ChordPro format below).
3. Set Title and Language if needed — title can also come from {title: ...} in the song text.
4. Switch to Preview to check parsed lyrics (and Chords when chord markers are present).
5. Click Save song (create) or Save changes (edit). WorshipDeck returns you to /my-songs.

You should have a valid church song ready to Compose or edit again later. For the list page and compose entry, see My songs.

Deep dive

Page header

Add Song and Edit Song share the same editor form. The page title includes a contextual ? that links to this article (MySongs.editorPageHelp).

Editor layout

The editor includes:

Control	Purpose
Edit / Preview tabs	Author source text or review the parse
Title	Optional display title — inferred from {title: ...} when omitted
Language	English or Spanish
Song text	ChordPro (or plain lyrics) textarea
Format guide	Collapsible quick examples — secondary ? links here for the full ChordPro reference
Save song / Save changes	Create or update the church song
Cancel	Return to /my-songs without saving

Create vs edit

Mode	Route	API	After success
Create	/my-songs/new	POST /api/my-songs with sourceText, optional title, languageCode	Toast Song saved. → /my-songs
Edit	/my-songs/{id}/edit	PATCH /api/my-songs/{id} with the same fields	Toast Changes saved. → /my-songs

Preview

Preview shows the parsed title, artists, and key when available. When the song has chord markers (hasChords), Lyrics and Chords chips let you switch views.

Songs with hasChords enable Show chords on confidence monitor in Compose a worship presentation. Lyrics-only songs skip that toggle.

ChordPro format

WorshipDeck parses song text as ChordPro-style markup. Use metadata lines, section headers, lyric lines, and optional chord markers.

Metadata directives

Put metadata on its own line using {key: value} syntax:

Key	Example	Notes
title	{title: Amazing Grace}	Also available in the Title field
artist / artists	{artist: John Newton}	Comma-separated for multiple writers
key	{key: G}	Displayed as Key: G in lists
tags / tag	{tags: worship, grace}	Church metadata
tempo	{tempo: 72}	Optional
copyright / copyrights	{copyright: © 2024 Church}	Optional
ccli	{ccli: 1234567}	Optional
language	{language: en}	Usually set via Language field instead

Duplicate metadata keys on separate lines are rejected.

Section headers

Start each section with a header on its own line — no colon inside the braces:

{verse 1}
{chorus}
{bridge}

Lyric lines follow the header. Every lyric line must appear under a section header.

Chord markers

Attach chords to lyric lines with bracket tokens:

[G]Amazing [G/B]grace how [C]sweet the [G]sound

Spaces inside brackets are allowed ([ G ]). Unmatched [ or ] brackets cause parse errors.

Lyrics-only songs

Omit chord markers entirely. Use section headers and plain lyric lines. The song will not show a Chords badge and compose will not offer confidence-monitor chords.

Comments

Optional comment lines use ChordPro-style blocks:

/# This line is ignored #/

Size limits

Limit	Value
Total source size	200 KB
Sections	50 max
Total lines	2,000 max
Lines per section	200 max

Full examples

With chords:

{title: Amazing Grace}
{artist: John Newton}
{key: G}

{verse 1}
[ G ]Amazing [G/B]grace how [C]sweet the [G]sound
That [G]saved a [D7]wretch like [G]me

{chorus}
[ G ]Praise the [C]Lord [G]forever

Lyrics only:

{title: Prayer of Thanks}
{artist: Jane Doe}

{verse 1}
We thank You Lord for every blessing
We praise Your holy name

{chorus}
Amen, amen

Parse errors and validation

WorshipDeck validates song text before save. If errors exist, save is blocked with Fix the song text errors before saving. and a list under the song text.

Error (summary)	Typical fix
Title is required	Add {title: ...} or fill the Title field
At least one section with lyrics is required	Add a section header and lyric lines
Add a section header before lyrics	Put {verse 1} (or similar) above lyric lines
Unmatched chord bracket	Close every [ with ] on the same line
Section has no lyric lines	Add lyrics under the section header
Duplicate metadata key	Remove the duplicate {key: ...} line
Unknown / unsupported directive	Fix typo in {key: value} or use a supported key
Malformed directive-like syntax	Use {key: value} for metadata, {section name} for sections
Song text exceeds limits	Shorten text or split into fewer sections
Repeated section label	Rename or merge duplicate {chorus} headers

Open Preview to see the first blocking error quickly.

Tips

• Put {title:} and {artist:} in the song text so metadata travels with the source when you export or paste.
• Use the inline Format guide for quick examples; use this article for the full reference and error list.
• Save early, then iterate in Edit — Compose reads the latest saved revision.
• After compose, refine lyrics in the Worship song editor inside the presentation.

Troubleshooting

Fix the song text errors before saving

• Read the error list under Song text and correct syntax — see Parse errors and validation.

Chords not in preview

• Add [ChordName] markers on lyric lines. Plain parentheses are not chords.

Could not save song

• Check network connectivity. Fix parse errors before retrying.

Edit page shows Loading…

• Refresh if the song failed to load. Confirm the song still exists on My Songs.