church-translate/Releases/INSTALL.md

Church Translate — Installing at a Campus

What you need

• An Apple Silicon Mac (M1 or newer). 16 GB+ RAM recommended.
• The sermon audio reaching that Mac: Dante Virtual Soundcard, Waves, or any input device. A mixer direct-out of the pastor's mic is ideal.
• Wi-Fi that phones in the room can join (guest network is fine, but test the QR code — some guest networks isolate clients from each other, which blocks the listener page; ask IT to allow "client-to-client" for the Mac, or put the Mac on the same network as the congregation).

Install

1. Copy Church Translate-3.0.1-arm64.dmg to the Mac, open it, drag the app to Applications.
2. First launch on a new Mac (macOS 15+): macOS will block the app because it is not notarized. Open System Settings → Privacy & Security, scroll down, and click Open Anyway next to the Church Translate message, then launch again. (One time only.)
   • Alternative for a tech: xattr -dr com.apple.quarantine "/Applications/Church Translate.app"
3. First run downloads the speech and translation models (~2 GB). Let it finish once on good internet — after that the app works fully offline except internet sharing.

The one networking rule

The Mac must be ON a network the phones can reach — in practice: keep the Mac's Wi-Fi ON and joined to the same Wi-Fi the congregation uses (wired AV networks are usually isolated VLANs phones cannot route to). The Setup pane lists every address the Mac has and marks which network each one is; the QR uses the highlighted one, and Wi-Fi is preferred automatically. If phones "can't open the page", this is almost always why.

Set up (5 minutes)

1. Setup pane → Input device: pick the Dante/Waves/interface channel the sermon arrives on. Speak: the meter should go green past the notch.
2. Adjust Sensitivity during a soundcheck: voice crosses the notch, room noise does not. (This is remembered.)
3. Operator pane → add front-page languages, pin ("Always translate") the languages your campus serves, add corrections (what it heard => what it should say) as you find them.
4. Print the poster / share the QR — congregation phones open the local address shown on the Setup pane.

Stream Deck / Companion

Operator pane shows four URLs (Start / Stop / Toggle / Status) for Bitfocus Companion "Generic HTTP" buttons. Status returns live, ready, or offline as plain text.

Livestream viewers (YouTube)

1. Setup pane → Internet sharing → "Share to the internet".
2. Copy the https://….trycloudflare.com link into the stream description or a pinned comment. The link is new each time you start sharing — paste a fresh one each stream (only the streaming campus needs this).
3. Operator pane → Stream delay: set roughly your stream's latency (typically 10–30s for YouTube) so captions/voice line up with the video. The room always sees live.

• Optional permanent link: create a named Cloudflare Tunnel on a church domain (one-time IT task, free) pointing at http://<mac>:3100, and put that URL in the operator "publicUrl" setting; then the QR/poster use it too.

Free professional voices (optional, one-time setup, $0)

The app can run studio-quality voices ON the Mac itself — no subscription, no usage fees, weights are Apache-licensed (owned forever). Covers Spanish, Portuguese, Chinese, Korean, French (+ English, German, Italian, Russian). One-time setup per Mac (~10 min, ~2GB download):

bash "/Applications/Church Translate.app/Contents/Resources/app/tools/setup-local-voices.sh"

Then: Operator pane → Premium voices → "Local (this Mac — free)". If the local engine ever fails, the built-in voices take over automatically. Languages it doesn't cover (Vietnamese, Arabic, Haitian) stay on the built-in voices. fish.audio (prepaid pay-per-use, not a subscription) remains available as an alternative for those languages.

The two Portugueses

"Português (Brasil)" and "Português (Portugal)" carry genuinely different text — one translation is produced, then each variant applies its own corpus-tested grammar pass (você/tu system, está falando / está a falar, me disse / disse-me, vocabulary). Have a native speaker of each spot-check a service before promoting it heavily.

During the service

The Operator pane's health line is the one thing to watch:

• Green — healthy; shows how far behind the speaker the captions are.
• Amber — running behind; idle languages may be trimmed to catch up.
• Red — something is wrong (not connected / badly behind). Restart the app if it does not clear itself in a minute; settings and corrections are safe (automatic backups, 30 kept).

Per-campus checklist (before the first Sunday)

• Audio feed reaches the Mac and the meter goes green on speech
• Phone on the congregation Wi-Fi can open the QR link and hear a voice
• Languages pinned; corrections list started
• Stream Deck buttons tested (if used)
• A volunteer knows: green/amber/red, and "restart the app" as the fix

Updates

Replace the app with a newer DMG the same way. Settings, corrections, models, and voices all survive updates (they live outside the app). Check the version in the DMG filename; the app's build number is in Finder → Get Info.

Known limits

• Apple Silicon only (this build).
• Haitian Creole (and ~70 other languages) are captions-only — no synthesized voice exists for them; the phone's own voice is used where the device has one.
• The internet-sharing link changes on every start (that is how account-less tunnels work) — use a named tunnel for a permanent link.