StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.
Translation Service — Start / Stop Guide
How to run the local live-translation service that the app's LIVE playback
uses for translated subtitles. For the feature itself (API contract, streaming
model, tuning), see LOCAL_LIVE_TRANSLATION.md.
Run it natively, not in Docker. Docker on macOS has no GPU access, so the container falls back to a CPU backend that transcribes ~3.5x slower than real time — finalized phrases queue up and captions drift minutes behind live audio. The native MLX (Metal GPU) backend transcribes a ~12s phrase in ~1.3s.
Start
Run from the repository root:
./tools/live-translation-service/run-native.sh
Runs in the foreground on port 8765 (Ctrl-C to stop). To keep it running after the terminal closes, start it in the background with logging:
nohup ./tools/live-translation-service/run-native.sh \
>> ~/Library/Logs/live-translation.log 2>&1 &
The script selects the MLX (GPU) backend with large-v3 and applies the
caption-readability tuning (silence threshold, phrase caps, partial interval).
Every setting is an overridable env var — see the script and
LOCAL_LIVE_TRANSLATION.md for the full list.
The model is cached in tools/live-translation-service/.hf-cache; first-ever
start downloads ~3 GB, after that startup takes a few seconds (the model is
warmed before the port starts accepting work).
Check it's running
curl -s http://localhost:8765/health
Healthy response includes "status":"ok" and "backend":"mlx" — if backend
says faster-whisper, you're on the slow CPU path; check that the script (not
a bare uvicorn) started it.
tail -f ~/Library/Logs/live-translation.log # live logs (if started via nohup)
In the logs, queued final chunk=N (queue=M) with M steadily growing means
the service can't keep up with real time — captions are falling behind.
Stop
kill $(lsof -ti :8765)
or, equivalently:
pkill -f "uvicorn service:app"
Sessions are in-memory only; stopping mid-playback is safe. The app shows "Live translation unavailable" and resumes when the service is back.
Restart (e.g. after changing settings)
From the repository root:
kill $(lsof -ti :8765)
nohup ./tools/live-translation-service/run-native.sh \
>> ~/Library/Logs/live-translation.log 2>&1 &
sleep 5 && curl -s http://localhost:8765/health
After a reboot
The service does not start automatically — you must rerun the start
command. A LaunchAgent can't reliably do it if the repo is checked out under a
TCC-protected location such as ~/Desktop, ~/Documents, or ~/Downloads:
macOS privacy protection blocks launchd background processes from reading those
directories ("Operation not permitted"). If auto-start matters, check the repo
out somewhere unprotected (e.g. ~/src) or grant /bin/zsh Full Disk Access in
System Settings → Privacy & Security.
Endpoints the app uses
| Client | Endpoint |
|---|---|
| Android emulator | http://10.0.2.2:8765 |
| Fire TV / real device | http://<Mac LAN IP>:8765 |
The service binds 0.0.0.0, so LAN devices can reach it directly.
Docker (legacy — not recommended)
The compose setup still exists for reference:
cd tools/live-translation-service
docker compose up -d # start
docker compose down # stop
Expect captions to lag minutes behind live audio (CPU-only, slower than real time). Only useful if the API needs to be up and translation latency is irrelevant.