trav
4eec2598a8
Self-hosted live captioning from steveseguin/captionninja and steveseguin/caption-local. Upstream publishes no images, so images/build.sh builds them from pinned commits.
99 lines
4.4 KiB
Markdown
99 lines
4.4 KiB
Markdown
# CAPTION.Ninja + Caption Local
|
|
|
|
Self-hosted live captioning: [CAPTION.Ninja](https://github.com/steveseguin/captionninja)'s
|
|
capture/editor/overlay pages and private caption relay, plus
|
|
[Caption Local](https://github.com/steveseguin/caption-local) Whisper speech-to-text.
|
|
Nothing is sent to caption.ninja, Google or any cloud STT provider.
|
|
|
|
<!-- metadata -->
|
|
* **Category**: Apps
|
|
* **Status**: 1, alpha
|
|
* **Image**: [`git.autonomic.zone/recipe-maintainers/caption-ninja-*`](https://git.autonomic.zone/recipe-maintainers/-/packages), 1, built from upstream source (see [Images](#images))
|
|
* **Healthcheck**: Yes
|
|
* **Backups**: No (no user data; the model volume is a cache)
|
|
* **Email**: No
|
|
* **Tests**: 3
|
|
* **SSO**: No
|
|
<!-- endmetadata -->
|
|
|
|
## Services
|
|
|
|
| Service | Hostname | What |
|
|
| --- | --- | --- |
|
|
| `app` | `$DOMAIN` | nginx serving the caption.ninja pages |
|
|
| `relay` | `wss://$DOMAIN/relay` | private caption relay (Node, `ws`), rooms `source` and `output` |
|
|
| `stt` | `$STT_DOMAIN` | Caption Local (faster-whisper, CPU), also serves its own capture page |
|
|
|
|
Captions flow: **capture** (microphone → STT) publishes to room `source` → **editor**
|
|
reviews and forwards to room `output` → **overlay** (OBS browser source / audience).
|
|
|
|
## Basic usage
|
|
|
|
1. Set up Docker Swarm, [`abra`][abra] and [`coop-cloud/traefik`][cc-traefik]
|
|
2. Make the images available on the server (see [Images](#images))
|
|
3. `abra app new caption-ninja --secrets`
|
|
4. `abra app config YOURAPPDOMAIN`: set `DOMAIN` and `STT_DOMAIN` (both need DNS).
|
|
The STT host needs RAM for the model: about 1.5 GB for `small`. Set `CAPTION_THREADS` to at most your core count.
|
|
5. `abra app deploy YOURAPPDOMAIN`. On first start `stt` downloads the Whisper
|
|
model into the `models` volume, so it can take several minutes to turn healthy.
|
|
|
|
## Using it
|
|
|
|
Read the tokens (keep them private; read tokens are for viewers, write tokens publish):
|
|
|
|
```
|
|
abra app run YOURAPPDOMAIN relay -- sh -c 'for s in src_read src_write out_read out_write; do echo "$s=$(cat /run/secrets/$s)"; done'
|
|
abra app run YOURAPPDOMAIN stt -- cat /run/secrets/stt_api_key
|
|
```
|
|
|
|
1. Open `https://$STT_DOMAIN/`, enter the `stt_api_key` service token, then pick a microphone.
|
|
2. Under **Send captions to caption.ninja → Use a private relay**, enter:
|
|
relay `wss://$DOMAIN/relay`, caption website `https://$DOMAIN/`, source room
|
|
`source` + `src_write` token, editor output room `output`. Enable sharing.
|
|
3. Open the generated **editor** link and enter `src_read` and `out_write`.
|
|
4. In the editor, create the view-only OBS/overlay link with `out_read`.
|
|
|
|
Alternatively use `https://$DOMAIN/capture-local.html` with service address
|
|
`https://$STT_DOMAIN`.
|
|
|
|
**Note:** the other caption.ninja pages (`index.html`, `translate.html`, …) still
|
|
default to the public relay `wss://api.caption.ninja`. Only `capture-local.html`,
|
|
`editor.html` and `overlay.html` support the private relay.
|
|
|
|
## Images
|
|
|
|
Upstream publishes no Docker images, so `images/build.sh` builds them from pinned
|
|
upstream commits. It needs Docker, git and no registry credentials:
|
|
|
|
```
|
|
scp -r images SERVER:caption-ninja-build/
|
|
ssh SERVER 'bash caption-ninja-build/images/build.sh'
|
|
```
|
|
|
|
The images are tagged with their registry names, so a single-node swarm can deploy
|
|
straight from the local tags. To publish them to the registry from a machine
|
|
that has `docker login git.autonomic.zone`:
|
|
|
|
```
|
|
for img in $(ssh SERVER "docker images --format '{{.Repository}}:{{.Tag}}' | grep caption-ninja-"); do
|
|
ssh SERVER docker save "$img" | docker load && docker push "$img"
|
|
done
|
|
```
|
|
|
|
To upgrade, bump the commits in `images/build.sh` and the tags in `compose.yml`.
|
|
|
|
## Security notes
|
|
|
|
* Caption Local only accepts `Host: localhost` (upstream expects an SSH tunnel), so
|
|
Traefik rewrites the Host header for `$STT_DOMAIN`; `stt` is still only reachable
|
|
through Traefik, and every API call needs the token.
|
|
* The STT token is a single shared token, not per-user auth. Anyone with it can use
|
|
your CPU for transcription. Rotate it with `abra app secret` + redeploy.
|
|
* Relay origins are `https://$DOMAIN` and `https://$STT_DOMAIN`; add more exact
|
|
origins with `RELAY_EXTRA_ORIGINS` (e.g. `https://steveseguin.github.io`).
|
|
* To revoke relay tokens, generate new secret versions and redeploy (restart
|
|
disconnects all clients and clears the 2-minute replay buffer).
|
|
|
|
[abra]: https://git.coopcloud.tech/coop-cloud/abra
|
|
[cc-traefik]: https://git.coopcloud.tech/coop-cloud/traefik
|