Skip to content

StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.

3.5 KB
Raw Blame

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.