StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.
Kotlin iptv-player
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.ktindex 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 endedshowCaptionTick(tick)- drainQueuedCaptionTicks()}}@@ -171,17 +174,7 @@ class LiveTranslationSession(if (tick.text.isBlank()) returnrenderCaption(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.mdindex 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 thediff --git a/docs/TRANSLATION_SERVICE_OPERATIONS.md b/docs/TRANSLATION_SERVICE_OPERATIONS.mdnew file mode 100644index 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.shnew file mode 100755index 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