User Guide

Download the installer for macOS or Windows, open it, and you're in — WorshipHub is a single native app with no dependencies, no account, and no internet requirement for its core features.

Fixing macOS opening errors ("App is damaged" or blocked)

When downloading and installing any of our desktop apps (WorshipHub, WorshipHub Notes, or WorshipHub Songs) on macOS from the internet, Gatekeeper may block the app showing an alert such as "App is damaged and can't be opened. You should move it to the Trash" or "Unidentified developer".

This is caused by macOS quarantine attribute on web downloads. To fix it quickly, open Terminal on your Mac and run the command corresponding to the app you installed:

# For WorshipHub:
sudo xattr -rd com.apple.quarantine /Applications/"WorshipHub.app"

# For WorshipHub Notes:
sudo xattr -rd com.apple.quarantine /Applications/"WorshipHub Notes.app"

# For WorshipHub Songs:
sudo xattr -rd com.apple.quarantine /Applications/"WorshipHub Songs.app"

(When using sudo, Terminal will prompt for your Mac password. Type it and press Enter).

The main window

The app is organized into three areas:

• Left panel — your libraries: Songs, Bible, and Media (images, videos, YouTube links).
• Center — the Service List (the running order for today) and the slide grid of whatever item is selected.
• Right panel — the Preview: what's LIVE right now, what's NEXT, the Project button, and Black/Logo controls.

Projecting

Connect a second display (projector or TV), then press the Project button — or ⌘P / Ctrl+P. The output window opens on the secondary display, truly fullscreen and borderless. Pressing Project again (or Escape inside the output window) closes it.

• Double-click any slide to send it live instantly.
• Arrow keys move to the next/previous slide, rolling over between service items.
• B toggles a black screen; L shows your church logo on black. Both are instant takeovers you can toggle off the same way.

Text appearance

The header bar has font size (A- / A+), bold, italic, and alignment controls — they apply to the projected output live. Your font size is remembered between sessions.

Tip: everything in this guide that mentions phones — Remote Control, Captions, Sermon Notes — needs no app store install. They're web apps opened by scanning a QR code from the desktop app.

The Service List is the running order for your event: songs, Bible passages, images, videos, and YouTube clips, in the order you'll present them.

Adding items

• Songs — press the + on any song in the library. If the song has translations, every language comes along and you can switch live.
• Bible verses — browse to a chapter, tap the verses you want, and press Add Verses. Each verse becomes its own slide, labeled V1, V2… (see the Bible chapter of this guide).
• Images & videos — add files to the Media library, then push them into the service. Each becomes a single slide.
• YouTube — paste a link. The app fetches the real title and thumbnail automatically, and plays the video embedded in the output window — no browser popup.

Drag items with the handle to reorder them. The ✕ removes an item.

Switching languages live

Song items with translations show a language dropdown in the slide-grid header — switching it re-renders every slide in that language for the rest of the session. Each individual slide also has a small chip to override just that one slide temporarily. Bible items work the same way: if you have several Bible versions downloaded, a projected passage can flip between versions or languages without leaving the live view.

Saving and opening services

File ▸ Save Service writes the entire running order into a single portable file:

• Songs are embedded — opening the file on another computer restores any songs missing from that machine's library.
• Images and videos are embedded too.
• YouTube clips are downloaded into the file when possible, so they play with zero internet at presentation time.

Open the file on the church computer with File ▸ Open Service and everything is exactly as you built it at home.

What's behind your lyrics matters. WorshipHub renders backgrounds on the GPU as real GLSL shaders — not looping video files — so they run smoothly even on modest hardware.

Animated backgrounds

Open the background picker in the header. There are 16 animated effects (Liquid Mesh, Aurora Flow, Rain of Grace, Stained Glass, Crystal Sea…), each with speed and complexity sliders. Effects take their colors from your selected gradient, so everything stays on-palette.

Your own backgrounds

Press ＋ Add background inside the picker to create a custom preset: choose the two gradient colors, optionally force a particle/accent color, name it, and save. Custom presets persist and can be deleted anytime. You can also upload static background images (Settings ▸ Church Identity) and flash them fullscreen from the Preview panel.

Video & YouTube playback

When a video or YouTube slide is live, the Preview panel shows a transport bar: play/pause and a draggable timeline with current position and duration. Scrub anywhere and the output seeks instantly. Videos loop at the end, matching how ambient loops are used in services.

Black, Logo, and overrides

Black (B) blanks the output; Logo (L) shows your uploaded church logo on black; a background image can also take over the full screen. These three are mutually exclusive and instant — pressing one clears the others. Subtitles hide automatically while Black or Logo is up.

Displays

The app picks the secondary display automatically and re-detects when you plug in a projector after launch. You can also choose the output display manually in the header — a manual choice is never overridden.

The Bible panel gives you offline scripture, verse-by-verse projection, and live version switching.

Downloading translations

Open the Bible panel and search the catalog — hundreds of translations are available, filtered by language (English, Español, Français, Italiano). Press download on the ones you want: the full text is stored locally in the app's database, so everything works offline afterwards. Delete any translation later from the same list.

Browsing and projecting

Pick a translation, then a book, then a chapter. Tap individual verses to select them and press Add Verses — the passage lands in the Service List as one item with one slide per verse (labeled V1, V2…), titled like "John 3:16-18". Double-click any verse slide to project it; arrow keys walk the passage verse by verse.

Switching version or language live

If a passage's book and chapter exist in more than one downloaded translation, the item gets the same language dropdown songs have — switch the whole passage to another version (say NIV → RVR1960) mid-service, or override a single verse slide temporarily. Only translations that actually contain that chapter are offered.

Verses from other apps

Verses can also arrive in the service from the phone Remote (its Bible tab) and from Sermon Notes (its editor and Podium mode) — they show up formatted identically, one slide per verse, and de-duplicate automatically if the same passage is sent twice.

The Remote is a web app for phones, tablets, and laptops — nothing to install.

Turning it on and pairing

Enable Tools ▸ Turn On Remote Control in the desktop app. A QR code and a 6-digit PIN appear in Settings ▸ Remote Access. On the phone, open the Remote app, scan the QR (or type the address shown), and enter the PIN if asked.

After the first successful pairing the phone receives a device token and is remembered — it won't ask for the PIN again, even after the desktop restarts or the tunnel address changes. Manage trusted devices (rename, revoke, mark as output) in Settings ▸ Connected Devices.

What you can do from the phone

• Control tab — next/previous slide, black screen, logo, and live status.
• Service tab — see the running order, jump to any slide, reorder items.
• Library tab — add songs to the service, browse the Bible (chapters are fetched from the desktop's downloaded translations) and send verses, paste YouTube links, and upload photos/videos straight from the phone's camera roll.
• Language switching — the same per-item and per-slide language dropdowns the desktop has.

The layout adapts: phones get bottom tabs, tablets and laptops get a full multi-column control surface.

A phone as a second projector

In Settings ▸ Connected Devices, mark a device as Output. That device's Remote then shows a Project button which opens a fullscreen window on a screen attached to it — useful for a lobby TV or an overflow room driven by a spare laptop. If the browser blocks automatic fullscreen, a Fullscreen button appears inside the projection window itself.

Sermon Notes is a separate app for the pastor — writing during the week, preaching on Sunday. It runs as a desktop app or in the browser.

Writing

A clean rich-text editor: headings, bold/italic, lists, and Bible quote blocks. Insert a passage from the built-in Bible browser and every verse appears with a small verse number — so you always see where verse 1 ends and verse 2 begins. Sermons save locally and can sync to your own Supabase project.

Connecting to the main app

In Notes ▸ Settings ▸ Transcription Server, enter the desktop app's address (or scan its QR). The first connection asks for approval on the desktop screen — one tap on Allow, and the device is trusted from then on. The token survives restarts and tunnel address changes.

Podium mode

Podium turns the sermon into a clean, large-type teleprompter with a service timer. Two live superpowers:

• Tap a verse, project it. Every verse in a Bible quote is individually tappable — touch verse 2 and verse 2 goes live on the projector, added to the service automatically (no duplicates if it's already there). This works even if the desktop doesn't have that Bible translation downloaded — the text travels from the sermon itself.
• Send all passages ahead of time. One button pushes every quoted passage into the running order before the sermon starts.

The pastor's mic

Podium can also stream the pastor's voice for Live Translation. Two modes (chosen in the desktop's Settings ▸ Live Translation): stream raw audio for the desktop's Whisper model to transcribe, or — on modest computers — let the phone's own browser do the speech recognition and send finished text back.

WorshipHub can transcribe the sermon as it's preached and put it on screen, on the livestream, and on every listener's phone.

On the projector

Toggle Tools ▸ Live Translation (Presentation) and subtitles appear in a bar at the bottom of the projected output. Speech-to-text runs entirely on your computer with Whisper (two model sizes — Lite and Pro — downloadable in Settings; Metal-accelerated on Apple Silicon). When the target language is English, Whisper translates directly; other targets currently show the transcription.

Styling the subtitles

Settings ▸ Live Translation ▸ Subtitles: pick the text color, size, background color, and background opacity (the bar stays slightly translucent by design). A live preview shows exactly what the projector will render. Subtitles are always capped at 3 lines — older words scroll away so the screen never floods.

Congregation Captions

Turn on Tools ▸ Captions App and share the QR (flash it on the projector via Tools ▸ Show Join QR). Each member opens a web page on their own phone and picks their own reading language — English, Español, Français, Deutsch, Italiano. The translation model (~40 MB, Opus-MT) downloads into their browser once and runs locally: zero cloud costs, works for any number of listeners. Text-to-speech can read the translation aloud through earphones — replacing dedicated translation-receiver hardware.

Where the voice comes from

The pastor's microphone is the Sermon Notes app (Podium mode). The desktop picks who transcribes: its own Whisper models, or the phone's browser recognizer for low-power computers. Either way, captions viewers and the projector see the same text.

If your church livestreams with OBS (or vlc/any browser-source-capable software), WorshipHub gives you two ready-made overlays. Both are plain web pages served by the desktop app — you add them as Browser Sources.

The two sources

1. Live subtitle overlay — the current caption on a transparent background, styled by your Settings (color, size, background, 3-line cap). It idles blank and lights up when transcription starts.
2. Join QR — the Congregation Captions QR on a transparent background, so viewers at home can scan it right off the stream.

Adding them to OBS

Open Settings ▸ Live Translation ▸ For OBS. Copy each URL with its copy button and paste it into a new Browser Source in OBS. The subtitle URL already carries your styling as parameters (size, color, bg, bgcolor) — change the style in Settings and re-copy to update.

Use the tunnel address. OBS's embedded browser can't accept a self-signed LAN certificate, so if OBS runs on another machine — or you want it bulletproof — turn on a Secure Tunnel first and copy the URLs while it's up: they'll use the tunnel's publicly-trusted HTTPS address.

Live control during the stream

Two menu switches under Tools:

• Show/Hide Subtitles (OBS) — mutes the overlay for the stream without touching the projector's subtitles or the congregation's phones.
• Show/Hide Join QR (OBS) — hides the QR overlay when you want it off-screen.

Both take effect within a couple of seconds; the sources can stay in your OBS scene permanently and just idle blank when everything's off.

The companion apps normally require every device to be on the same Wi-Fi as the desktop. A Secure Tunnel removes that limit: it publishes the desktop's local server at a public HTTPS address, without router configuration or port forwarding.

Why you'd want one

• Phones on cellular data (no church Wi-Fi) can still use Remote, Notes, and Captions.
• OBS Browser Sources get a publicly-trusted certificate — the LAN address uses a self-signed one that OBS's browser can't easily accept.
• Members at home can open the Captions page from anywhere.

Providers

Settings ▸ Secure Tunnel supports four backends — install the one you pick on the presentation computer:

There's an auto-start toggle so the tunnel comes up on its own every time the app launches.

The address is not permanent

With the free tiers, the public URL changes every time the tunnel restarts — that's normal, not a bug. WorshipHub handles the consequences for you:

• Every QR code (Remote, Captions, Notes pairing) regenerates automatically the moment the tunnel connects or drops.
• Paired devices stay trusted: the device token is independent of the address, so phones do not need re-approval after the address changes — they just need the new address, easiest by re-scanning the QR.
• OBS Browser Source URLs must be re-copied after the address changes, unless you pay for a fixed domain (ngrok) or use Tailscale, whose address is stable within your tailnet.

Your song library lives in a local database — no account, no cloud requirement. When you have more than one computer (or want an off-site backup), two sync options are built in.

LAN sync (computer to computer)

Settings ▸ Data Sync. Put one computer in Server mode and the other in Client mode — they discover each other automatically on the local network, and Sync Now transfers the library, including all song translations. Use it to prep on a laptop at home, then push everything to the sanctuary computer on Sunday.

Cloud sync (Supabase)

If you want sync over the internet, WorshipHub connects to your own free Supabase project — you own the database, WorshipHub is just a client.

1. Create a project at supabase.com (free tier is plenty).
2. Copy the project URL and the anon/public key into Settings ▸ Cloud Sync.
3. Press Copy SQL and run it once in Supabase's SQL editor — it creates the tables (safe to re-run; it's idempotent).
4. Sync manually or enable auto-sync.

The Sermon Notes app has its own separate Supabase configuration (its own tables, same setup steps) — a pastor's sermons and the church's song library stay independent by design.

What syncs where