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.