Skip to content

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

Pace partial captions and run the translation service natively on MLX

a0d2e705b4d5c
diff --git a/app/src/main/java/com/streamvault/app/player/LiveTranslationSession.kt b/app/src/main/java/com/streamvault/app/player/LiveTranslationSession.kt
index 10618755..2d176e40 100644
--- a/app/src/main/java/com/streamvault/app/player/LiveTranslationSession.kt
+++ b/app/src/main/java/com/streamvault/app/player/LiveTranslationSession.kt
@@ -27,6 +27,9 @@ private const val MAX_PENDING_AUDIO_BUFFERS = 120
// the subtitle doesn't change faster than a viewer can read. Trades a little
// latency for readability; intermediate updates during this window are coalesced.
private const val MIN_CAPTION_DISPLAY_MS = 2_200L
+// Partials re-transcribe the whole phrase, so consecutive ones can rewrite the
+// line wholesale; hold each at least this long or the text is unreadable churn.
+private const val MIN_PARTIAL_DISPLAY_MS = 1_500L
// Clear the caption after this much idle time with no new text (TV-caption feel).
private const val SUBTITLE_LINGER_MS = 20_000L
@@ -149,10 +152,11 @@ class LiveTranslationSession(
}
/**
- * Paces caption changes for readability. Partial lines update immediately and
- * any queued updates are drained in order so finals aren't skipped. Finalised
- * phrases dwell for [MIN_CAPTION_DISPLAY_MS]. Clears after [SUBTITLE_LINGER_MS]
- * of no updates.
+ * Paces caption changes for readability: every rendered text dwells on screen
+ * (finals [MIN_CAPTION_DISPLAY_MS], partials [MIN_PARTIAL_DISPLAY_MS]) before
+ * the line may change. The channel is conflated, so after a dwell we always
+ * jump straight to the newest text — pacing can never build up a backlog.
+ * Clears after [SUBTITLE_LINGER_MS] of no updates.
*/
private suspend fun displayLoop() {
while (scope.isActive) {
@@ -163,7 +167,6 @@ class LiveTranslationSession(
}
val tick = result.getOrNull() ?: break // channel closed -> session ended
showCaptionTick(tick)
- drainQueuedCaptionTicks()
}
}
@@ -171,17 +174,7 @@ class LiveTranslationSession(
if (tick.text.isBlank()) return
renderCaption(tick.text)
hasVisibleCaption = true
- if (tick.isFinal) {
- delay(MIN_CAPTION_DISPLAY_MS)
- }
- }
-
- /** Show any captions that arrived while the previous tick was on screen. */
- private suspend fun drainQueuedCaptionTicks() {
- while (scope.isActive) {
- val next = captionUpdates.tryReceive().getOrNull() ?: break
- showCaptionTick(next)
- }
+ delay(if (tick.isFinal) MIN_CAPTION_DISPLAY_MS else MIN_PARTIAL_DISPLAY_MS)
}
private fun renderCaption(text: String) {
@@ -207,10 +200,10 @@ private fun newAudioChannel(): Channel<LiveAudioPcmBuffer> = Channel(
onBufferOverflow = BufferOverflow.DROP_OLDEST
)
-private fun newCaptionChannel(): Channel<CaptionTick> = Channel(
- capacity = 64,
- onBufferOverflow = BufferOverflow.DROP_OLDEST
-)
+// Conflated: only the newest pending caption is kept. A final superseded during a
+// dwell is skipped in favour of the next phrase's text, which is the trade we want
+// — show the most current state rather than replaying stale revisions.
+private fun newCaptionChannel(): Channel<CaptionTick> = Channel(Channel.CONFLATED)
private fun convertToPcm16Mono16k(buffer: LiveAudioPcmBuffer, fallbackStartMs: Long): ConvertedPcmChunk? {
if (buffer.encoding != C.ENCODING_PCM_16BIT || buffer.sampleRate <= 0 || buffer.channelCount <= 0) {
diff --git a/docs/LOCAL_LIVE_TRANSLATION.md b/docs/LOCAL_LIVE_TRANSLATION.md
index 205773e9..f68f558a 100644
--- a/docs/LOCAL_LIVE_TRANSLATION.md
+++ b/docs/LOCAL_LIVE_TRANSLATION.md
@@ -78,7 +78,12 @@ This yields English output subtitles from multilingual speech inputs.
## Quick local startup (ready-to-run)
-### Docker (recommended)
+See [TRANSLATION_SERVICE_OPERATIONS.md](TRANSLATION_SERVICE_OPERATIONS.md) for
+the day-to-day start/stop guide. Short version: use
+`tools/live-translation-service/run-native.sh` (native MLX, GPU). Docker is
+CPU-only on macOS and runs slower than real time, so captions fall behind.
+
+### Docker (not recommended on macOS — CPU-only, slower than real time)
The service ships with a `Dockerfile` and `docker-compose.yml`
(`tools/live-translation-service/`). The container restarts automatically if the
diff --git a/docs/TRANSLATION_SERVICE_OPERATIONS.md b/docs/TRANSLATION_SERVICE_OPERATIONS.md
new file mode 100644
index 00000000..9d373d1c
--- /dev/null
+++ b/docs/TRANSLATION_SERVICE_OPERATIONS.md
@@ -0,0 +1,106 @@
+# 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](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
+
+```bash
+/Users/a/Desktop/iptv-ui/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:
+
+```bash
+nohup /Users/a/Desktop/iptv-ui/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](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
+
+```bash
+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.
+
+```bash
+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
+
+```bash
+kill $(lsof -ti :8765)
+```
+
+or, equivalently:
+
+```bash
+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)
+
+```bash
+kill $(lsof -ti :8765)
+nohup /Users/a/Desktop/iptv-ui/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 do it: macOS privacy protection (TCC) blocks
+launchd background processes from reading anything under `~/Desktop`, where
+this repo lives ("Operation not permitted"). If auto-start ever matters,
+either move the repo out of `~/Desktop` 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:
+
+```bash
+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.
diff --git a/tools/live-translation-service/run-native.sh b/tools/live-translation-service/run-native.sh
new file mode 100755
index 00000000..6653023d
--- /dev/null
+++ b/tools/live-translation-service/run-native.sh
@@ -0,0 +1,27 @@
+#!/bin/zsh
+# Runs the live translation service natively on the Mac so Whisper uses the
+# M-series GPU via MLX. Docker on macOS has no GPU access; its CPU backend runs
+# slower than real time and captions drift minutes behind.
+SERVICE_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+export HF_HOME="${HF_HOME:-$SERVICE_DIR/.hf-cache}"
+export WHISPER_MODEL="${WHISPER_MODEL:-large-v3}"
+export WHISPER_BACKEND="${WHISPER_BACKEND:-mlx}"
+export WHISPER_MLX_MODEL="${WHISPER_MLX_MODEL:-mlx-community/whisper-large-v3-mlx}"
+
+# Caption readability tuning. Broadcast audio rarely drops below the default
+# silence threshold (0.01), so phrases were all hitting the 12s hard cap as one
+# huge rewriting line. Cut on real pauses and keep phrases sentence-sized; MLX
+# transcribes ~10x faster than real time, so frequent finals are cheap.
+export WHISPER_SILENCE_RMS="${WHISPER_SILENCE_RMS:-0.02}"
+export WHISPER_SOFT_LIMIT_SECONDS="${WHISPER_SOFT_LIMIT_SECONDS:-4}"
+export WHISPER_MAX_PHRASE_SECONDS="${WHISPER_MAX_PHRASE_SECONDS:-7}"
+# Min spacing between partial (in-progress) updates; each partial re-transcribes
+# the whole phrase and can rewrite the line, so don't emit them faster than the
+# app's caption dwell.
+export WHISPER_UPDATE_INTERVAL="${WHISPER_UPDATE_INTERVAL:-1.5}"
+
+exec "$SERVICE_DIR/.venv/bin/uvicorn" service:app \
+ --app-dir "$SERVICE_DIR" \
+ --host 0.0.0.0 \
+ --port 8765