Getting started

Your first Sunday

One laptop at the sound desk. The congregation uses their own phones. Total setup time is about ten minutes, most of it printing the flyer.

1. Download and open the app. The app is in a private beta: email support@lithos.community with your congregation and the languages you need, and the installers come by reply. The macOS build is signed and notarized. On Windows, SmartScreen shows “Windows protected your PC” the first time — click More info → Run anyway. Then Windows asks whether to let Lithos through the firewall: tick both Private and Public networks, or phones on the church WiFi will never reach it.
2. Choose Standalone on the launch card when this laptop runs the service. To use an existing host, choose Connect to a server, select it from the nearby-server list (or enter its address), and enter its operator PIN. Then tick the audio devices this computer may share. You can change the checklist later under This computer → Audio devices.
3. Complete first-run setup. Paste your provider key, choose the listener languages, and set an operator PIN. This one PIN guards the staff pages — operator, presenter, playout — so make it 6+ characters that aren't a year or 1234 (the app refuses weak ones).
4. Manage your API key — translation is done by an AI provider using your own account. Google Gemini (aistudio.google.com/apikey) is the recommended one — it covers 70+ languages. Paste it on the Operator tab → Setup & advanced → API keys → Save → Test; the test opens a real session so you know it works before Sunday.
5. Turn on your languages. Languages start off — tick the ones you need under Setup & advanced → Languages (add more with + Add language). Each enabled language is one live translation stream, billed per minute by your provider while the service runs — the cost meter on the Operator tab shows the running estimate. (Which languages each provider offers, voices, and the source language are in the languages guide.)
6. Check the hall. The Rooms card includes the default room, initially named Main group and marked hall. Rename it for your building, check its languages, and set Auto-stop after to cover the meeting. New rooms, including a fresh hall, start with a 60-minute cap; raise it before a longer service.
7. Print the flyer. The Join QR card holds your guest WiFi name and password (they become a join-the-WiFi QR on the flyer) and a 🖨 Print flyer button. People scan step 1 to hop on the WiFi and step 2 to open the page — nothing to install.
8. Go live. Switch to the Presenter tab, pick the microphone, tap ● Go live, and speak — that starts the translation too, so there is nothing to start first. Phones show live captions immediately; a tap adds audio for earbuds. If you have a projector, the This computer tab lets you enable a display; then assign its room, languages, layout and join QR on Playout devices. Between meetings just Stop on the Operator tab and Start again — phones stay connected and pick up where they were.

You could stop here. One speaker, every language, phones and a projector — that's a whole Sunday.

A box that's always on

Instead of someone's laptop, run Lithos headless on a mini-PC, a spare machine in a closet, or a Raspberry Pi — everyone (including the speaker) connects from a browser. It's the same product with no screen attached.

With Docker installed, it's a two-line file and one command:

# .env — an API key and the staff PIN is all it takes
GEMINI_API_KEY=your-key-here
LT_OPERATOR_PIN=hosanna-42

./run.sh   # finds your LAN address and starts the server

The log prints two links: http://<your-ip>:8080 for the congregation, and https://<your-ip>:8443 for staff pages (the operator console and the presenter's mic need a secure page — staff tap through a one-time certificate notice; the congregation never sees one).

No Docker? Bare Node works too

On a fresh Ubuntu box (verified on Ubuntu 24.04), install Node 22, then install and run from the project folder:

# Node 22 via NodeSource — curl + ca-certificates are the only prerequisites
sudo apt-get update
sudo apt-get install -y curl ca-certificates
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt-get install -y nodejs

# Skips the ~100 MB desktop binary the server never uses — kind to a Pi
ELECTRON_SKIP_BINARY_DOWNLOAD=1 npm install

GEMINI_API_KEY=your-key-here LT_OPERATOR_PIN=hosanna-42 npm run server

Make it come back by itself

A server you started in a terminal — or in a screen session — is gone after a power cut, and it goes quietly: no error, no warning, just pages that don't load on Sunday morning. The release tarball installs it as a service instead, so the box comes back on its own.

tar xzf lithos-server-node-0.7.0.tar.gz
cd lithos-server-node-0.7.0
sudo ./install.sh

It creates a dedicated account, installs the program files and the service, and stops before starting — the example PIN can't do anything, and a server that comes up unable to work looks broken rather than unconfigured. Set your PIN and key, then start it:

sudo nano /etc/lithos-server/server.env   # PIN + an API key
sudo systemctl start lithos-server
journalctl -u lithos-server -f

A Pi usually has no system Node, and its own package manager offers a version that's too old. The installer notices, tells you exactly what it would change — a third-party apt repository, permanently, on that machine — and asks. Say no and it prints the commands to run by hand; nothing happens without an answer. --with-node answers in advance.

Three directories, deliberately: /opt/lithos-server is program files and gets replaced wholesale on upgrade; /etc/lithos-server is your settings; and /var/lib/lithos-server holds groups, languages, room assignments and transcripts. That last one is the thing to back up. Re-running install.sh from a newer tarball upgrades in place and never touches either of the last two.

Optional: lose the certificate warning

You don't need this — the one-time notice on staff pages is harmless to tap through, and most rooms never bother. But if you want a clean padlock (or you're deploying on a real domain), you have three ways — each walked through step by step in the certificate guide, which also explains when the built-in certificate changes and what to do when an iPhone won't tap through:

• A LAN-trusted cert with mkcert — best for a building you control. Make a local certificate authority once, issue a cert for the server, and point Lithos at it:

  mkcert -install                        # one-time: create + trust a local CA
  mkcert 192.168.1.230 localhost         # issue a cert for the server's LAN IP

  then start the server with LT_TLS_CERT=/certs/cert.pem and LT_TLS_KEY=/certs/key.pem pointing at those files. Devices that trust the CA see no warning anywhere; the rest still work with the one-time tap.
• Bring your own certificate — already have a real one (a domain, an internal CA)? Point the same LT_TLS_CERT / LT_TLS_KEY variables at it.
• Put a reverse proxy in front — Caddy or nginx terminating TLS (handy for a cloud/DNS deploy with a real certificate). Set LT_BEHIND_PROXY=1 so Lithos knows it's already behind HTTPS.

One caution with mkcert: the root CA you install on a phone is a powerful trust anchor — only add it to devices you own, and keep its key safe.

Things worth knowing

• Everything you set from the operator page persists — languages, groups, room speakers, WiFi for the flyer — in a Docker volume that survives updates and restarts. (Avoid docker compose down -v; the -v deletes that volume.)
• The speaker presents from a phone: open /presenter on the staff link, PIN in, tap Go live. A wired headset mic beats holding the phone.
• The projector is just a browser: open /projector on any TV or PC and full-screen it.
• Prefer a file to a web form? Drop a config.json next to the compose file for languages and groups; operator-page edits still win.

You could stop here. A box in a closet, phones in the pews, nobody owns a laptop cable anymore.

Every room in the building

Classes & breakout groups

Each class gets its own translation room: its own languages, its own speaker, its own audience. On the operator page, Rooms → Edit rooms → + Add room (e.g. Sunday School, Youth Group). The teacher opens the presenter page, picks their class in Present to, and taps Go live — that starts the class; nothing bills until then. The full walk-through — adding and editing classes, how they start and stop, a Sunday with two of them — is the groups guide.

People can join a class before it starts — the picker marks it “starts soon,” their phone waits quietly, and the moment the teacher goes live everyone connects at once. The teacher even sees how many phones are waiting.

Groups nobody set up in advance: a small-group discussion, an interview, a hallway huddle. With attendee groups switched on, anyone starts one from their own phone and the others join by a 6-digit code or QR; it is encrypted, unlisted, and gone when they're done. Turning it on, the caps that bound the bill, and how private it really is are in the private groups guide.

Room speakers & output boxes

Open Playout devices (/playout) to route speakers, microphones and displays. Each device shows the computer it belongs to. Use + also play for… to add the rooms a speaker serves and choose a language for each. Changes apply immediately. A device assigned several rooms follows the one that went live most recently.

• This laptop: select outputs and microphones under This computer → Audio devices. Microphones are never selected automatically; a presenter must pick one before it streams.
• A second laptop: install the app, choose Connect to a server, select the host and share the devices you want it to use.
• A Raspberry Pi in another room: extract the playout tarball and run sudo ./install.sh. It reads the sound cards actually present and writes them into /etc/lithos-playout/devices.json, one output each, named after the card — rename them to what the room calls them. Set the host and PIN in /etc/lithos-playout/playout.env, start it, and the devices appear on Playout devices to be assigned. It runs as a service, so it comes back after a reboot like the server does.

  Across buildings, set the host's address explicitly — LT_SERVER=auto finds hosts by broadcast and that stops at the subnet. Set LT_BOX to the site's name too; it's what keeps two rooms that both have a "Speaker" apart.

• A browser speaker: open /speaker, name the computer, enter the operator PIN to register it, and add outputs. Use Show devices to make Chrome list USB and HDMI outputs; it requests and releases the mic. Test the output, then keep the tab open and the laptop awake.
• A room PA: tick this is the room’s PA on the output and check its playback options. A newly marked speaker waits until the speaker finishes by default. Its default routing plays for a phone speaker or when the room microphone switches language.
• A screen: enable a display under This computer, or open /projector on a TV or browser and use the corner gear to register it. Assign its room, languages, layout and QR on Playout devices. Different screens can show different rooms.

A camera as the room microphone

No microphone to spare? If the room already has a camera on the network, its audio can be the input. Only the audio track is pulled — a 4K camera costs its audio bitrate and almost no CPU — and it appears on Playout devices like any other microphone.

The address is the hard part: the path is vendor-specific and the camera rarely tells you. The playout tarball includes a finder:

./find-camera.sh                 # look for cameras on this network
./find-camera.sh 192.168.1.50    # or probe one you already know

It prints the line to paste into devices.json, and tells you whether the stream carries audio as well as video — a picture-only path opens perfectly happily and is no use as a microphone, which is a confusing half-hour to spend after you've wired it up. An NDI|HX camera works here directly; it's ordinary RTSP underneath.

If a camera feed sounds far too quiet, don't reach for gain. Some cameras send the same microphone on both channels with one inverted, and folding those to mono by averaging cancels the voice — 20 to 35 dB of it on real hardware, which is enough to look like a dead microphone. Lithos measures the two channels instead of assuming, and the log says which it's reading: stream channels: reading difference means it found an inverted pair and is subtracting rather than averaging. sum means ordinary stereo — and a quiet feed then really is a level problem, worth fixing at the camera.

See the whole room audio path

Follow a voice from microphone → room → language → physical output. The graph on Playout devices shows who has the floor, how many phones need each language, and which output deserves attention.

• Blue paths show audio moving. In the app, the ribbons animate; the counts show phones listening in each language.
• A phone can take the floor. In Sunday School, Ana’s phone feeds translation while the teacher’s mic yields.
• Amber calls out an output to check. This example routes the PA through the system default, which may be the speaker the mic can hear.

Test the room before people arrive

The Room audio graph on Playout devices traces microphones through rooms and languages to outputs. Right-click a node (long-press on a phone, or focus it and press Enter). An output offers Test chime for each device; the same 🔔 Test button appears on its device row. Chimes do not start translation or incur provider charges.

A room offers Send English test speech through its real translation path. On a stopped room, Start & send English test speech starts translation and shows its per-minute cost. This test is billed; stop the room afterwards if you are only checking setup.

Play a pre-translated video

On the Operator page, upload a clip’s audio tracks, one per language. The browser converts supported media to mono audio; PCM16 mono WAV can be uploaded directly. Mark the video's own soundtrack original. Choose whether the clip is shared or belongs to one group when first uploading it, then choose the room to play it to. Each room has its own player and Stop button, so two classes can use the same clip independently.

Languages with uploaded tracks hear those tracks. Missing languages can receive live translation from the original if that room is already running; playing a clip does not start a billed engine. The microphone is suppressed during playback. With no original or running translation, missing tracks mean silence for those languages.

The congregation speaks back

Any phone can request the mic and be translated for everyone — one voice at a time. The presenter's Participants panel is the switchboard: turn on Allow congregation speaking (until you do, phones show no speak button at all). Each class has its own Allow participants speaking switch, which is remembered after a restart. Grant requests by hand, or flip Let anyone interject for a hands-free discussion. Exactly one voice ever feeds translation, so a teacher on a mic and participants on phones never garble each other. Attendees can also spin up their own temporary PIN-protected group for a hallway conversation — it disappears when they're done.

This is the whole vision: the main hall, every classroom, and the hallway in between — each hearing in its own language.

When something's wrong