feat: caption-ninja recipe (web pages, private relay, Caption Local STT)
Self-hosted live captioning from steveseguin/captionninja and steveseguin/caption-local. Upstream publishes no images, so images/build.sh builds them from pinned commits.
This commit is contained in:
@@ -0,0 +1,98 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user