Songs & Scripture

Present hymns and scripture passages reliably without an internet connection using local SQLite database corpora, automated stanza splitting, and visual line-budget pagination.

Written for WorshipDeck 0.1.2

Built-In Hymnal and Bible

WorshipDeck stores two complete English liturgical texts inside its local SQLite database (data.db):

  • Seventh-day Adventist Hymnal (SDAH): All 695 hymns, complete with titles, author metadata, stanza numbers, and chorus refrains.
  • King James Version (KJV): All 31,102 verses across 66 books of the Old and New Testaments.
The bundled hymnal and Bible are in English. Indonesian hymnals and Bible translations are not bundled out of the box due to copyright distribution restrictions.

Songbooks and Lyric Parsing

When you enter a hymn number or paste custom lyrics into a service, WorshipDeck divides the song across multiple consecutive slides:

Input Pattern Layout Slot Used Rendered Content
Hymn Header title Song title slide displaying {song_number} and {song_title}.
Verse 1, Bait 1, etc. verse Stanza slide containing the verse number and verse lyric lines. Double line breaks create continuation slides if a stanza is lengthy.
Chorus, Reff, Refrain reff Chorus slide containing the repeated refrain text. An empty Chorus header automatically repeats the lyrics of the previous chorus.

Song sets allow you to organize songs by service category (e.g. Opening Hymns, Praise Set, Vespers) and assign a cohesive background image that automatically applies to all stanzas in that set.

Scripture Lookup Syntax

Search and present Bible passages by typing standard references into the service form or directly into the operator console's live Scripture panel:

Reference Format Example Syntax Result
Single Verse John 3:16 Displays the single verse on one slide.
Verse Range John 3:16-17 Fetches consecutive verses and paginates them across slides.
Comma Separator John 3:16,18 Interpreted as a verse range spanning from verse 16 through 18.
Whole Chapter Psalm 23 Loads the complete chapter and splits it into sequential reading slides based on the line budget.

Per Verse vs Inline Modes

In the Scripture module, administrators can toggle how passage text is formatted across slides:

  • Per Verse: Each verse begins on a fresh slide line with a prominent verse number indicator, ideal for responsive liturgical readings where the congregation follows along verse by verse.
  • Inline: Consecutive verses flow together as a continuous narrative paragraph with superscript verse numbers, ideal for narrative epistles, parables, and longer responsive readings.

In addition to prepared service slides, the operator console includes a live Scripture Overlay panel. Type a reference during the sermon and click Push to screen to project the passage immediately as an overlay on top of active background graphics, without having to prepare a slide in advance.

Line-Budget Automatic Pagination

When a scripture passage or long hymn verse exceeds screen dimensions, WorshipDeck prevents text overflow using a deterministic line-budget algorithm:

  • Budget Limits: Text is capped at approximately 60 characters per line and a maximum of 10 lines per slide.
  • Long Verse Isolation: A single verse containing 450 characters or more is automatically isolated onto its own slide.
  • Viewport Scaling: Scripture text dynamically scales so that the entire text block fits within 82% of stage container height (82cqh) and 85% of container width, preserving clean margins.
  • Continuation Indicators: When a passage spans across multiple slides, continuation badges (such as John 3:16-17 (continued)) are automatically appended to subsequent slides.

Adding Custom Bible Translations

To add additional Bible translations for your congregation:

  1. Prepare a structured JSON file containing the 66 canonical books, chapter indices, and verse strings.
  2. Place the file into the server's data directory under data/<locale>/bible-translation/<code>.json (for example, data/id/bible-translation/tb.json).
  3. Restart the server. The translation will appear in the translation dropdown under Settings → Worship Settings.