From c9c2b3f4833680b1f6d27e1c1157fa98ba72b78e Mon Sep 17 00:00:00 2001
From: silentbil <silentbil@users.noreply.github.com>
Date: Thu, 9 Jul 2026 23:54:38 +0300
Subject: [PATCH 1/2] preload subs and gemini update

---
 .../tv/data/repository/CloudSyncRepository.kt |   8 +
 .../com/arflix/tv/server/AiKeyWebPage.kt      |   2 +-
 .../tv/ui/screens/player/PlayerScreen.kt      | 215 ++++++++++++++--
 .../tv/ui/screens/player/PlayerViewModel.kt   | 170 ++++++++++++-
 .../tv/ui/screens/player/SubtitleAiModel.kt   |   2 +
 .../player/SubtitleTranslationService.kt      | 234 +++++++++++++++---
 .../tv/ui/screens/settings/SettingsScreen.kt  |  24 +-
 .../ui/screens/settings/SettingsViewModel.kt  |  12 +
 app/src/main/res/values-iw/strings.xml        |   2 +
 app/src/main/res/values/strings.xml           |   2 +
 docs/subtitle-auto-match.md                   |  65 ++++-
 11 files changed, 672 insertions(+), 64 deletions(-)

diff --git a/app/src/main/kotlin/com/arflix/tv/data/repository/CloudSyncRepository.kt b/app/src/main/kotlin/com/arflix/tv/data/repository/CloudSyncRepository.kt
index 18488300b..d63acb19d 100644
--- a/app/src/main/kotlin/com/arflix/tv/data/repository/CloudSyncRepository.kt
+++ b/app/src/main/kotlin/com/arflix/tv/data/repository/CloudSyncRepository.kt
@@ -353,6 +353,7 @@ class CloudSyncRepository @Inject constructor(
     private val subtitleAiEnabledKey = androidx.datastore.preferences.core.booleanPreferencesKey("subtitle_ai_enabled")
     private val subtitleAiAutoSelectKey = androidx.datastore.preferences.core.booleanPreferencesKey("subtitle_ai_auto_select")
     private val subtitleAiFindBestMatchKey = androidx.datastore.preferences.core.booleanPreferencesKey("subtitle_ai_find_best_match")
+    private val subtitlePreloadEnabledKey = androidx.datastore.preferences.core.booleanPreferencesKey("subtitle_preload_enabled")
     private val subtitleAiApiKeyKey = androidx.datastore.preferences.core.stringPreferencesKey("subtitle_ai_api_key")
     private val subtitleAiModelKey = androidx.datastore.preferences.core.stringPreferencesKey("subtitle_ai_model")
     private val subtitleRemoveHearingImpairedKey = androidx.datastore.preferences.core.booleanPreferencesKey("subtitle_remove_hearing_impaired")
@@ -491,6 +492,7 @@ class CloudSyncRepository @Inject constructor(
         root.put("subtitleAiEnabled", prefs[subtitleAiEnabledKey] ?: false)
         root.put("subtitleAiAutoSelect", prefs[subtitleAiAutoSelectKey] ?: false)
         root.put("subtitleAiFindBestMatch", prefs[subtitleAiFindBestMatchKey] ?: false)
+        root.put("subtitlePreloadEnabled", prefs[subtitlePreloadEnabledKey] ?: true)
         root.put("subtitleAiApiKey", prefs[subtitleAiApiKeyKey] ?: "")
         root.put("subtitleAiModel", prefs[subtitleAiModelKey] ?: "GROQ_LLAMA_70B")
         root.put("subtitleRemoveHearingImpaired", prefs[subtitleRemoveHearingImpairedKey] ?: true)
@@ -1230,6 +1232,12 @@ class CloudSyncRepository @Inject constructor(
                 prefs[subtitleAiEnabledKey] = root.optBoolean("subtitleAiEnabled", false)
                 prefs[subtitleAiAutoSelectKey] = root.optBoolean("subtitleAiAutoSelect", false)
                 prefs[subtitleAiFindBestMatchKey] = root.optBoolean("subtitleAiFindBestMatch", false)
+                // Only apply when the backup actually carries the field — backups pushed by app
+                // versions that predate the setting must not reset it (realtime sync pulls after
+                // EVERY push from any device, so one old-version device would keep wiping it).
+                if (root.has("subtitlePreloadEnabled")) {
+                    prefs[subtitlePreloadEnabledKey] = root.optBoolean("subtitlePreloadEnabled", false)
+                }
                 val apiKey = root.optString("subtitleAiApiKey", "")
                 if (apiKey.isNotBlank()) prefs[subtitleAiApiKeyKey] = apiKey
                 val model = root.optString("subtitleAiModel", "GROQ_LLAMA_70B")
diff --git a/app/src/main/kotlin/com/arflix/tv/server/AiKeyWebPage.kt b/app/src/main/kotlin/com/arflix/tv/server/AiKeyWebPage.kt
index 28ebd6b6f..bddd2476a 100644
--- a/app/src/main/kotlin/com/arflix/tv/server/AiKeyWebPage.kt
+++ b/app/src/main/kotlin/com/arflix/tv/server/AiKeyWebPage.kt
@@ -75,7 +75,7 @@ $sharedCss
   <a id="geminiLink" href="/gemini" class="provider-btn">
     <span class="badge badge-gemini">BETTER QUALITY</span>
     <span class="name">Google Gemini</span>
-    <span class="model">Gemini 2.5 Flash · Free tier available</span>
+    <span class="model">Gemini 3.5 Flash · Free tier available</span>
   </a>
 </div>
 <script>
diff --git a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerScreen.kt b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerScreen.kt
index 2c674d3c8..5fc99b7ee 100644
--- a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerScreen.kt
+++ b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerScreen.kt
@@ -88,6 +88,7 @@ import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberUpdatedState
 import androidx.compose.runtime.setValue
+import androidx.compose.runtime.snapshotFlow
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.geometry.Offset
@@ -163,6 +164,7 @@ import com.arflix.tv.ui.theme.TextSecondary
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withTimeoutOrNull
 import kotlinx.coroutines.Job
 import androidx.compose.runtime.rememberCoroutineScope
 import okhttp3.Cookie
@@ -485,6 +487,22 @@ fun PlayerScreen(
 
     // Track stream selection time (for future diagnostics)
     var streamSelectedTime by remember { mutableStateOf<Long?>(null) }
+    // Post-selection status for the loading overlay ("Loading subtitles…" during the preload
+    // gate, "Loading video stream…" while preparing). Overrides uiState.streamLoadPhase, which
+    // only covers source discovery and goes blank once a source is picked.
+    var startupPhase by remember { mutableStateOf<String?>(null) }
+    // Failover notice, displayed ON TOP of startupPhase for a fixed minimum time: a fast source
+    // switch (resolve can take <100ms) would otherwise overwrite it as an unreadable blink.
+    // Overlaying instead of delaying keeps the actual failover at full speed.
+    var switchNotice by remember { mutableStateOf<String?>(null) }
+    var switchNoticeUntilMs by remember { mutableLongStateOf(0L) }
+    LaunchedEffect(switchNoticeUntilMs) {
+        if (switchNotice != null) {
+            val remaining = switchNoticeUntilMs - System.currentTimeMillis()
+            if (remaining > 0) delay(remaining)
+            switchNotice = null
+        }
+    }
     var playbackIssueReported by remember { mutableStateOf(false) }
     var startupRecoverAttempted by remember { mutableStateOf(false) }
     var startupHardFailureReported by remember { mutableStateOf(false) }
@@ -679,6 +697,14 @@ fun PlayerScreen(
                 }
                 currentStreamIndex = nextIndex
                 triedStreamIndexes = triedStreamIndexes + nextIndex
+                val next = streams[nextIndex]
+                switchNotice = buildString {
+                    append("Source not starting — switching")
+                    val desc = listOf(next.quality, next.size).filter { it.isNotBlank() }.joinToString(" · ")
+                    if (desc.isNotBlank()) append(" ($desc)")
+                    append("…")
+                }
+                switchNoticeUntilMs = System.currentTimeMillis() + 2_500L
                 userSelectedSourceManually = false
                 playbackIssueReported = false
                 startupRecoverAttempted = false
@@ -793,6 +819,14 @@ fun PlayerScreen(
         DefaultMediaSourceFactory(context)
             .setDataSourceFactory(cacheDataSourceFactory)
     }
+    // "Preload Subtitles" mode: sidecar subtitle configs only merge through a
+    // DefaultMediaSourceFactory, but the cached one above would route heavy/debrid video through
+    // the disk cache (I/O bottleneck). This variant keeps file:// support for the local subtitle
+    // copies while streaming video uncached, like directProgressiveFactory.
+    val preloadMediaSourceFactory = remember(fileCapableDataSourceFactory) {
+        DefaultMediaSourceFactory(context)
+            .setDataSourceFactory(fileCapableDataSourceFactory)
+    }
 
     // ExoPlayer - tuned for both small and very large files. The byte cap scales
     // with the device heap so 4K/debrid streams get breathing room without pushing
@@ -1441,6 +1475,7 @@ fun PlayerScreen(
             val prepareStartMs = streamSelectedTime ?: System.currentTimeMillis()
             bufferingStartTime = null
             hasPlaybackStarted = false  // Reset for new stream
+            startupPhase = "Loading video stream…"
             firstVideoFrameRendered = false
             readyPlayingSinceMs = null
             playbackIssueReported = false
@@ -1505,25 +1540,68 @@ fun PlayerScreen(
             // Track when stream was selected
             // (Moved up before frame rate probe)
 
+            // "Preload Subtitles" mode: hold prepare until the ViewModel finished downloading the
+            // preferred-language subs to local files (or the gate times out), then side-load ALL
+            // of them into the initial MediaItem. Switching between them later is a pure track
+            // override — no MediaItem rebuild, no visible reload. Only local file:// copies are
+            // attached: the historical "never preload all subs" revert was about ExoPlayer eagerly
+            // fetching every REMOTE side-loaded config at prepare.
+            var preloadedSubtitleConfigs = emptyList<MediaItem.SubtitleConfiguration>()
+            if (latestUiState.subtitlePreloadEnabled) {
+                if (!latestUiState.subtitlePreloadComplete) {
+                    startupPhase = "Loading subtitles…"
+                }
+                val gateStartMs = System.currentTimeMillis()
+                val gateReady = withTimeoutOrNull(SUBTITLE_PRELOAD_GATE_TIMEOUT_MS) {
+                    snapshotFlow { latestUiState.subtitlePreloadComplete }.first { it }
+                } != null
+                preloadedSubtitleConfigs = buildExternalSubtitleConfigurations(
+                    latestUiState.preloadedSubtitles.filter { it.url.startsWith("file:") }
+                )
+                playbackStartupDiag(
+                    "subtitle preload gate ${if (gateReady) "ready" else "TIMEOUT"} " +
+                        "waitMs=${System.currentTimeMillis() - gateStartMs} attached=${preloadedSubtitleConfigs.size}"
+                )
+                // Startup watchdog bills elapsed time from streamSelectedTime — don't charge the
+                // gate to it, or slow subtitle addons would trigger source failover.
+                streamSelectedTime = System.currentTimeMillis()
+                startupRecoverAttempted = false
+            }
+
             // Only add the selected subtitle to ExoPlayer (not all 30+).
             // Loading all external subs slows down preparation and causes non-UTF8 subs to fail.
+            // (Preloaded LOCAL copies above are the exception — reading them at prepare is free.)
             val isHlsStream = isLikelyHlsPlaybackUrl(url, latestUiState.selectedStream)
+            val urlLower = url.lowercase()
+            val isDashStream = urlLower.contains(".mpd") || urlLower.contains("/dash") || urlLower.contains("format=dash")
             val mediaItemBuilder = MediaItem.Builder().setUri(Uri.parse(url))
             if (isHlsStream) {
                 mediaItemBuilder.setMimeType(MimeTypes.APPLICATION_M3U8)
             }
+            if (preloadedSubtitleConfigs.isNotEmpty()) {
+                mediaItemBuilder.setSubtitleConfigurations(preloadedSubtitleConfigs)
+                // DefaultMediaSourceFactory infers DASH from an explicit MIME type, not from the
+                // "/dash"/"format=dash" URL shapes the dedicated-factory routing recognizes.
+                if (isDashStream && !isHlsStream) {
+                    mediaItemBuilder.setMimeType(MimeTypes.APPLICATION_MPD)
+                }
+            }
             val mediaItem = mediaItemBuilder.build()
 
             // Use protocol-specific media source for faster startup:
             // - HLS: chunkless preparation enabled (saves 1-3s)
             // - DASH/Progressive: dedicated factories for optimal handling
-            val urlLower = url.lowercase()
             val isHeavy = isLikelyHeavyStream(latestUiState.selectedStream)
             val isRemoteHttp = urlLower.startsWith("http://") || urlLower.startsWith("https://")
             val mediaSource: MediaSource = when {
+                // Sidecar subtitle configs only merge through a DefaultMediaSourceFactory; the
+                // preload variant streams video uncached (like directProgressiveFactory) and
+                // resolves HLS/DASH from the MIME hints set above.
+                preloadedSubtitleConfigs.isNotEmpty() ->
+                    preloadMediaSourceFactory.createMediaSource(mediaItem)
                 isHlsStream ->
                     hlsFactory.createMediaSource(mediaItem)
-                urlLower.contains(".mpd") || urlLower.contains("/dash") || urlLower.contains("format=dash") ->
+                isDashStream ->
                     dashFactory.createMediaSource(mediaItem)
                 isHeavy || isRemoteHttp ->
                     // Bypass disk cache for large/debrid progressive streams to avoid I/O bottleneck
@@ -1547,12 +1625,15 @@ fun PlayerScreen(
             // No manual startup gate - trust the CDN/debrid while keeping enough safety margin.
             exoPlayer.playWhenReady = true
             exoPlayer.prepare()
+            startupPhase = "Starting playback…"
             playbackStartupDiag(
                 "prepare issued setupMs=${System.currentTimeMillis() - prepareStartMs} source=${uiState.selectedStream?.addonId}/${uiState.selectedStream?.quality}/${uiState.selectedStream?.size} host=${runCatching { Uri.parse(url).host }.getOrNull().orEmpty()}"
             )
 
             // Prefer currently selected subtitle language (if any), otherwise keep text disabled.
-            val subtitle = uiState.selectedSubtitle
+            // latestUiState, not the captured uiState: the preload gate above can wait several
+            // seconds, during which the auto-selection flow usually picks a subtitle.
+            val subtitle = latestUiState.selectedSubtitle
             if (subtitle != null) {
                 exoPlayer.trackSelectionParameters = exoPlayer.trackSelectionParameters
                     .buildUpon()
@@ -1652,11 +1733,60 @@ fun PlayerScreen(
             return@LaunchedEffect
         }
 
+        // External subtitle side-loaded at startup ("Preload Subtitles"): switching is just a
+        // track override — no MediaItem rebuild, no visible reload. This also catches the
+        // find-best-match winner: its localized file:// copy keeps the same provider|id-based
+        // track id as the attached remote entry (subtitleTrackId never hashes an id-carrying
+        // sub's URL).
+        if (latestUiState.subtitlePreloadEnabled) {
+            val targetTrackId = subtitleTrackId(subtitle)
+            repeat(2) { attempt ->
+                val groups = exoPlayer.currentTracks.groups
+                for (gi in groups.indices) {
+                    val group = groups[gi]
+                    if (group.type != C.TRACK_TYPE_TEXT) continue
+                    for (ti in 0 until group.length) {
+                        val fid = group.getTrackFormat(ti).id?.trim().orEmpty()
+                        val matches = fid.isNotBlank() &&
+                            (fid == targetTrackId || fid.substringAfterLast(':') == targetTrackId)
+                        if (matches) {
+                            exoPlayer.trackSelectionParameters = exoPlayer.trackSelectionParameters
+                                .buildUpon()
+                                .clearOverridesOfType(C.TRACK_TYPE_TEXT)
+                                // Explicit override — the preferred-language fallback would
+                                // silently select a DIFFERENT same-language attached track.
+                                .setPreferredTextLanguage(null)
+                                .setOverrideForType(
+                                    androidx.media3.common.TrackSelectionOverride(
+                                        group.mediaTrackGroup,
+                                        ti
+                                    )
+                                )
+                                .setTrackTypeDisabled(C.TRACK_TYPE_TEXT, false)
+                                .build()
+                            return@LaunchedEffect
+                        }
+                    }
+                }
+                // Track list can lag right after playback starts — one short retry before
+                // falling back to the rebuild path below.
+                if (attempt == 0) delay(400)
+            }
+        }
+
         // External subtitle: rebuild MediaItem with just this one subtitle
         if (subtitle.url.isNotBlank() && exoPlayer.playbackState != Player.STATE_IDLE) {
             val currentPosition = exoPlayer.currentPosition
             val wasPlaying = exoPlayer.isPlaying
-            val subtitleConfigs = buildExternalSubtitleConfigurations(listOf(subtitle))
+            // In preload mode keep the local preloaded tracks attached across the rebuild —
+            // otherwise the first non-attached pick would strip them and every later switch
+            // back would rebuild again.
+            val attachSubs = if (latestUiState.subtitlePreloadEnabled) {
+                latestUiState.preloadedSubtitles.filter { it.url.startsWith("file:") } + subtitle
+            } else {
+                listOf(subtitle)
+            }
+            val subtitleConfigs = buildExternalSubtitleConfigurations(attachSubs)
             val mediaItemBuilder = MediaItem.Builder()
                 .setUri(Uri.parse(url))
                 .setSubtitleConfigurations(subtitleConfigs)
@@ -1676,6 +1806,41 @@ fun PlayerScreen(
                 .setSelectUndeterminedTextLanguage(true)
                 .setTrackTypeDisabled(C.TRACK_TYPE_TEXT, false)
                 .build()
+
+            // With several same-language tracks attached (preload mode), the language preference
+            // above can land on the wrong one — pin the exact track once the rebuilt track list
+            // resolves. Language preference stays as the fallback if the config never loads.
+            if (subtitleConfigs.size > 1) {
+                val targetTrackId = subtitleTrackId(subtitle)
+                repeat(10) {
+                    delay(500)
+                    val groups = exoPlayer.currentTracks.groups
+                    for (gi in groups.indices) {
+                        val group = groups[gi]
+                        if (group.type != C.TRACK_TYPE_TEXT) continue
+                        for (ti in 0 until group.length) {
+                            val fid = group.getTrackFormat(ti).id?.trim().orEmpty()
+                            val matches = fid.isNotBlank() &&
+                                (fid == targetTrackId || fid.substringAfterLast(':') == targetTrackId)
+                            if (matches) {
+                                exoPlayer.trackSelectionParameters = exoPlayer.trackSelectionParameters
+                                    .buildUpon()
+                                    .clearOverridesOfType(C.TRACK_TYPE_TEXT)
+                                    .setPreferredTextLanguage(null)
+                                    .setOverrideForType(
+                                        androidx.media3.common.TrackSelectionOverride(
+                                            group.mediaTrackGroup,
+                                            ti
+                                        )
+                                    )
+                                    .setTrackTypeDisabled(C.TRACK_TYPE_TEXT, false)
+                                    .build()
+                                return@LaunchedEffect
+                            }
+                        }
+                    }
+                }
+            }
         }
     }
 
@@ -2784,7 +2949,14 @@ fun PlayerScreen(
                     logoUrl = uiState.logoUrl,
                     title = uiState.title,
                     progress = if (uiState.showLoadingStats) uiState.streamProgress else null,
-                    phaseLabel = if (uiState.showLoadingStats) uiState.streamLoadPhase else null
+                    // streamLoadPhase covers source discovery; startupPhase takes over from
+                    // stream selection ("Loading subtitles…"/"Loading video stream…") until the
+                    // first frame renders; switchNotice overlays both for 2.5s on failover.
+                    // Unlike the percentage ring, the phase text is not gated on
+                    // showLoadingStats — status feedback should always be visible.
+                    phaseLabel = switchNotice
+                        ?: (startupPhase.takeIf { uiState.selectedStreamUrl != null })
+                        ?: uiState.streamLoadPhase
                 )
             }
         }
@@ -3923,14 +4095,16 @@ private fun PulsingLogo(
                 style = ArflixTypography.sectionTitle.copy(fontSize = 22.sp, fontWeight = FontWeight.SemiBold),
                 color = Color.White
             )
-            if (!phaseLabel.isNullOrBlank()) {
-                Spacer(modifier = Modifier.height(6.dp))
-                Text(
-                    text = phaseLabel,
-                    style = ArflixTypography.caption,
-                    color = TextSecondary
-                )
-            }
+        }
+        // Independent of the progress ring: post-selection phases ("Loading video stream…",
+        // "Loading subtitles…") have no meaningful percentage but still need to show.
+        if (!phaseLabel.isNullOrBlank()) {
+            Spacer(modifier = Modifier.height(if (progress != null) 6.dp else 16.dp))
+            Text(
+                text = phaseLabel,
+                style = ArflixTypography.caption,
+                color = TextSecondary
+            )
         }
     }
 }
@@ -5094,9 +5268,17 @@ private fun detectAudioCodecLabel(codec: String?, trackLabel: String?): String?
     }
 }
 
+// Identity must survive URL swaps (remote → localized file:// copy), so it never hashes the URL
+// of an id-carrying sub. Provider-qualified because "Preload Subtitles" attaches many addons'
+// subs at once and bare numeric ids can collide across providers. '|' separator, never ':' —
+// ExoPlayer prefixes side-loaded format ids with "periodIndex:" and matching strips at the
+// last ':'.
 private fun subtitleTrackId(subtitle: Subtitle): String {
     val explicit = subtitle.id.trim()
-    if (explicit.isNotBlank()) return explicit
+    if (explicit.isNotBlank()) {
+        val provider = subtitle.provider.trim()
+        return if (provider.isBlank()) explicit else "$provider|$explicit"
+    }
 
     val normalizedUrl = subtitle.url.trim().ifBlank {
         "${subtitle.lang.trim().lowercase()}|${subtitle.label.trim().lowercase()}"
@@ -5105,6 +5287,11 @@ private fun subtitleTrackId(subtitle: Subtitle): String {
     return "ext_$stableHash"
 }
 
+// "Preload Subtitles" prepare gate: max time the initial prepare waits for the ViewModel to
+// finish downloading preferred-language subs. Below the player's hard startup timeout so a slow
+// subtitle addon can never trigger source failover (the gate also re-anchors the startup clock).
+private const val SUBTITLE_PRELOAD_GATE_TIMEOUT_MS = 20_000L
+
 private fun audioTrackKey(track: AudioTrackInfo): String {
     return listOf(
         track.index,
diff --git a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerViewModel.kt b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerViewModel.kt
index 2a819cb8c..58168fed1 100644
--- a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerViewModel.kt
+++ b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerViewModel.kt
@@ -65,6 +65,10 @@ private fun Addon.isVodStreamingAddon(): Boolean =
 
 private const val PLAYBACK_DIAGNOSTICS = true
 
+// "Preload Subtitles" mode: cap on how many preferred-language subs are downloaded and
+// side-loaded at startup (each becomes a MediaItem SubtitleConfiguration read at prepare).
+private const val MAX_PRELOAD_SUBS = 15
+
 private fun playbackDiag(message: String) {
     if (PLAYBACK_DIAGNOSTICS) {
         System.err.println("[PlaybackDiag] $message")
@@ -86,6 +90,16 @@ data class PlayerUiState(
     val streamSelectionNonce: Int = 0,
     val selectedSubtitle: Subtitle? = null,
     val subtitleSelectionNonce: Int = 0,
+    // "Preload Subtitles" mode: preferred-language addon subs downloaded to local files before
+    // playback so they can be side-loaded into the initial MediaItem — switching then needs only
+    // a track override, not a MediaItem rebuild (no visible video reload). Default ON.
+    val subtitlePreloadEnabled: Boolean = true,
+    // Localized (file://) copies ready to attach. Separate from [subtitles]: menu entries keep
+    // their remote URLs so scan/download flows are unaffected.
+    val preloadedSubtitles: List<Subtitle> = emptyList(),
+    // True once preloading for this video finished (even with zero results) — the prepare gate
+    // in PlayerScreen waits on this (with a timeout) before building the MediaItem.
+    val subtitlePreloadComplete: Boolean = false,
     val savedPosition: Long = 0,
     val preferredAudioLanguage: String = "en",
     val preferredSubtitleLang: String = "",
@@ -217,6 +231,9 @@ class PlayerViewModel @Inject constructor(
     // One auto-run of "find best match" per playback/stream — applyPreferredSubtitle re-runs on
     // every subtitle-list update and must not restart a completed scan.
     private var autoMatchAttempted = false
+    // "Preload Subtitles" mode (read once per video load, like the AI flags).
+    private var subtitlePreloadEnabled = false
+    private var subtitlePreloadJob: Job? = null
     private var aiApiKey = ""
     private var aiModel = SubtitleAiModel.GROQ_LLAMA_70B
     private var aiRemoveHearingImpaired = true
@@ -225,6 +242,7 @@ class PlayerViewModel @Inject constructor(
     private val aiEnabledKey = booleanPreferencesKey("subtitle_ai_enabled")
     private val aiAutoSelectKey = booleanPreferencesKey("subtitle_ai_auto_select")
     private val aiFindBestMatchKey = booleanPreferencesKey("subtitle_ai_find_best_match")
+    private val subtitlePreloadKey = booleanPreferencesKey("subtitle_preload_enabled")
     private val aiApiKeyKey = globalStringPreferencesKey("subtitle_ai_api_key")
     private val aiModelKey = globalStringPreferencesKey("subtitle_ai_model")
     private val aiRemoveHearingImpairedKey = booleanPreferencesKey("subtitle_remove_hearing_impaired")
@@ -251,7 +269,13 @@ class PlayerViewModel @Inject constructor(
     ).also { mgr ->
         mgr.onTranslatingChanged = { isTranslating -> _isTranslatingLive.value = isTranslating }
         mgr.onBatchResult = { success, errorMessage ->
-            if (!success && !aiErrorToastShown) {
+            // Content-policy blocks are not actionable (Gemini's non-configurable output filter
+            // on raw movie dialogue) and don't stop translation of other windows — the service
+            // already bisected the batch to salvage what it could. Don't consume the one toast
+            // per session on them; keep it for real errors (bad key, rate limit).
+            if (!success && errorMessage == TRANSLATION_ERROR_CONTENT_BLOCKED) {
+                android.util.Log.w("SubtitleTranslation", "batch content-blocked — toast suppressed")
+            } else if (!success && !aiErrorToastShown) {
                 aiErrorToastShown = true
                 val msg = when {
                     errorMessage == "API key missing" -> context.getString(R.string.player_ai_no_key)
@@ -434,6 +458,7 @@ class PlayerViewModel @Inject constructor(
         lastWatchHistorySavedPositionSeconds = -1L
         subtitleRefreshJob?.cancel()
         subtitleSelectionJob?.cancel()
+        subtitlePreloadJob?.cancel()
         // Cancel any in-flight "Find best match" scan from the previous title — otherwise it can
         // finish on this new session and select/restore a stale subtitle or poison the match cache
         // (its stream cache key resolves to the new stream). Same-VM path only, e.g. play-next.
@@ -509,6 +534,7 @@ class PlayerViewModel @Inject constructor(
             aiSubtitleEnabled = prefs[aiEnabledKey] ?: false
             aiSubtitleAutoSelect = prefs[aiAutoSelectKey] ?: false
             aiFindBestMatchFirst = prefs[aiFindBestMatchKey] ?: false
+            subtitlePreloadEnabled = prefs[subtitlePreloadKey] ?: true
             aiApiKey = prefs[aiApiKeyKey] ?: ""
             aiModel = runCatching {
                 SubtitleAiModel.valueOf(prefs[aiModelKey] ?: SubtitleAiModel.GROQ_LLAMA_70B.name)
@@ -539,7 +565,10 @@ class PlayerViewModel @Inject constructor(
                 subtitleOffset = subOffset,
                 autoPlayNext = autoPlayNext,
                 showLoadingStats = showLoadingStats,
-                volumeBoostDb = volumeBoostDb
+                volumeBoostDb = volumeBoostDb,
+                subtitlePreloadEnabled = subtitlePreloadEnabled,
+                // Nothing to preload without a preferred language — don't make the gate wait.
+                subtitlePreloadComplete = normalizeLanguage(preferredSub).isBlank()
             )
 
             // If stream URL provided, use it directly (except magnet links, which require resolution).
@@ -708,6 +737,7 @@ class PlayerViewModel @Inject constructor(
                             subtitles = mergedSubs,
                             isLoadingSubtitles = false
                         )
+                        preloadSubtitles(mergedSubs)
 
                         scheduleSubtitleSelection(currentOriginalLanguage)
                     } else {
@@ -719,6 +749,8 @@ class PlayerViewModel @Inject constructor(
                             "subtitle fetch skipped: no imdbId for $mediaType/$mediaId — scheduling selection with embedded-only"
                         )
                         _uiState.value = _uiState.value.copy(isLoadingSubtitles = false)
+                        // No addon subs will arrive — unblock the preload prepare gate.
+                        preloadSubtitles(emptyList())
                         scheduleSubtitleSelection(currentOriginalLanguage)
                     }
                 }
@@ -1058,6 +1090,7 @@ class PlayerViewModel @Inject constructor(
                         subtitles = mergedSubs,
                         isLoadingSubtitles = false
                     )
+                    preloadSubtitles(mergedSubs)
                     scheduleSubtitleSelection(currentOriginalLanguage)
                 }
 
@@ -2363,6 +2396,7 @@ class PlayerViewModel @Inject constructor(
                         }
                     )
                     _uiState.value = _uiState.value.copy(subtitles = merged)
+                    preloadSubtitles(merged)
 
                     scheduleSubtitleSelection(currentOriginalLanguage)
                 }
@@ -2518,6 +2552,19 @@ class PlayerViewModel @Inject constructor(
                 selectedSubtitle = resolvedSelected
             )
 
+            // Late AI-interim activation for a running scan. The preload gate defers prepare
+            // until the addon-subtitle fetch completes, so the scan now reliably STARTS before
+            // the player exposes any embedded track — runFindBestMatch then found no AI source
+            // and went silent, and autoMatchAttempted blocks any re-run (the pre-preload flow
+            // only worked because prepare raced ahead of the fetch). Join the interim as soon
+            // as an embedded source appears while the scan is still running.
+            if (_uiState.value.isFindingBestMatch && !_uiState.value.isAiTranslating &&
+                aiSubtitleEnabled && aiSubtitleAutoSelect &&
+                findAiSourceSubtitle(finalList) != null
+            ) {
+                activateAiTranslation()
+            }
+
             val currentSel = _uiState.value.selectedSubtitle
             val preferred = getDefaultSubtitle()
             val normalizedPref = normalizeLanguage(preferred)
@@ -2673,15 +2720,24 @@ class PlayerViewModel @Inject constructor(
         // AI activation is not a specific user track pick — a late embedded preferred-language
         // track may still displace it.
         userPickedSubtitle = false
+        // The silent-scan path never populates aiTargetLanguageName (it's set only when a source
+        // existed at scan start) — resolve from the preferred-language code so a late activation
+        // doesn't hand the manager a BLANK target (which silently translates to nothing).
         val targetLangName = _uiState.value.aiTargetLanguageName
+            .ifBlank { if (targetSubtitleLangCode.isNotBlank()) languageCodeToName(targetSubtitleLangCode) else "" }
         if (targetLangName.isNotBlank()) translationManager.targetLanguage = targetLangName
         translationManager.isEnabled = true
         translationManager.reset()
         aiErrorToastShown = false
+        android.util.Log.i(
+            "SubMatch",
+            "AI translation activated: source=${source.lang}/${source.label} target=$targetLangName"
+        )
         _uiState.value = _uiState.value.copy(
             selectedSubtitle = source,
             isAiTranslating = true,
             isAiAvailable = true,
+            aiTargetLanguageName = targetLangName,
             aiErrorToast = null
         )
     }
@@ -2954,11 +3010,31 @@ class PlayerViewModel @Inject constructor(
                 it.isEmbedded && it.id == referenceSub.id &&
                     it.groupIndex != null && it.trackIndex != null
             } ?: referenceSub
-            _uiState.value = _uiState.value.copy(
-                selectedSubtitle = refResolved,
-                isAiTranslating = false,
-                subtitleSelectionNonce = _uiState.value.subtitleSelectionNonce + 1
-            )
+            if (_uiState.value.isAiTranslating) {
+                // AI interim is running on a DIFFERENT source — with the preload gate this is
+                // the common case: activation happens before embedded tracks resolve, so the
+                // source is an external English sub. Killing the interim here (the historical
+                // behavior of this branch) is what made AI "never start" during scans. Instead,
+                // migrate the translation onto the reference: it's an embedded non-bitmap text
+                // track — precisely the preferred AI source — with strictly better (muxed)
+                // timing than the external sub.
+                android.util.Log.i(
+                    "SubMatch",
+                    "reference switch: migrating AI interim source ${aiSourceSubtitle?.label} -> ${refResolved.label}"
+                )
+                aiSourceSubtitle = refResolved
+                translationManager.reset()
+                _uiState.value = _uiState.value.copy(
+                    selectedSubtitle = refResolved,
+                    subtitleSelectionNonce = _uiState.value.subtitleSelectionNonce + 1
+                )
+            } else {
+                _uiState.value = _uiState.value.copy(
+                    selectedSubtitle = refResolved,
+                    isAiTranslating = false,
+                    subtitleSelectionNonce = _uiState.value.subtitleSelectionNonce + 1
+                )
+            }
         }
 
         // The reference-track selection propagates asynchronously (compose → track selector →
@@ -3030,7 +3106,16 @@ class PlayerViewModel @Inject constructor(
             // also cover a minimum stretch of the video.
             val span = if (refs.size >= 2) refs.last().second - refs.first().first else 0L
             val spanOk = span >= MATCH_MIN_REF_SPAN_MS
-            if (spanOk && refs.size >= MATCH_TARGET_REF_INTERVALS) break
+            // Target-reached needs BUFFERED quorum: realtime-dominated references carry render-lag
+            // skew and merged pseudo-cues that suppress well-synced subs (a verified-perfect sub
+            // scored 0.65 on buffered=2/9 refs from a sparse-dialogue recap, then 0.85 once
+            // buffered coverage existed — From S03E03, July 2026). Keep collecting instead of
+            // concluding from weak evidence; the accept breaks below stay reference-agnostic
+            // (a HIGH score is trustworthy on any reference) and the give-up timers still bound
+            // the scan.
+            if (spanOk && refs.size >= MATCH_TARGET_REF_INTERVALS &&
+                bufferedCount >= MATCH_MIN_BUFFERED_FOR_REJECT
+            ) break
             // Early accept: scoring is free, so score incrementally — once some candidate is
             // already clearly in sync there's no need to keep collecting up to the target.
             val bestNow = if (refs.size >= MATCH_EARLY_ACCEPT_REFS) {
@@ -3088,7 +3173,7 @@ class PlayerViewModel @Inject constructor(
             )
         }
 
-        return loaded.map { (sub, cues) ->
+        val results = loaded.map { (sub, cues) ->
             val s = SubtitleSyncMatcher.scoreByTiming(cues, refs)
             android.util.Log.i(
                 "SubMatch",
@@ -3097,6 +3182,18 @@ class PlayerViewModel @Inject constructor(
             )
             sub to s
         }
+        // A LOW score from a realtime-dominated reference (give-up exit without buffered quorum)
+        // is not evidence of a bad sub — report inconclusive instead of a confident
+        // "no well-synced subtitle (best N%)" reject. Accepts pass through unchanged.
+        val best = results.maxOfOrNull { it.second } ?: 0.0
+        if (best < MATCH_SUCCESS_THRESHOLD_TIMING && bufferedCount < MATCH_MIN_BUFFERED_FOR_REJECT) {
+            android.util.Log.i(
+                "SubMatch",
+                "verdict withheld: best=${"%.2f".format(best)} but buffered=$bufferedCount/${refs.size} — inconclusive"
+            )
+            return null
+        }
+        return results
     }
 
     /** Reference = AI hearing transcription (fallback when there's no built-in English track). */
@@ -3287,6 +3384,58 @@ class PlayerViewModel @Inject constructor(
         }.getOrDefault(sub)
     }
 
+    /**
+     * "Preload Subtitles" mode: download the preferred-language addon subtitles to local cache
+     * files (same UTF-8/gunzipped [localizeSubtitle] files the match scan serves) so PlayerScreen
+     * can side-load them ALL into the initial MediaItem — switching between them is then a track
+     * override with no MediaItem rebuild. The historical "never preload all subs" revert was about
+     * ExoPlayer eagerly fetching 30+ REMOTE configs at prepare; local files make that eager read
+     * free and encoding-safe. Incremental: re-invocations only download subs not yet localized.
+     * Every path ends with [PlayerUiState.subtitlePreloadComplete] = true so the prepare gate in
+     * PlayerScreen never waits on a dead job (it also has its own timeout).
+     */
+    private fun preloadSubtitles(subs: List<Subtitle>) {
+        if (!subtitlePreloadEnabled) return
+        val target = targetSubtitleLangCode
+        val alreadyPreloaded = _uiState.value.preloadedSubtitles
+            .map { "${it.provider}|${it.id}|${it.lang}" }
+            .toSet()
+        val candidates = if (target.isBlank()) emptyList() else subs
+            .filter { sub ->
+                !sub.isEmbedded && !sub.isBitmap && sub.url.isNotBlank() &&
+                    !sub.url.startsWith("file:") &&
+                    normalizeLanguage(sub.lang) == target &&
+                    "${sub.provider}|${sub.id}|${sub.lang}" !in alreadyPreloaded
+            }
+            .take(MAX_PRELOAD_SUBS)
+        if (candidates.isEmpty()) {
+            if (!_uiState.value.subtitlePreloadComplete) {
+                _uiState.value = _uiState.value.copy(subtitlePreloadComplete = true)
+            }
+            return
+        }
+        subtitlePreloadJob?.cancel()
+        subtitlePreloadJob = viewModelScope.launch {
+            val localized = candidates.map { sub ->
+                async(Dispatchers.IO) {
+                    SubtitleSyncMatcher.loadRaw(sub.url)
+                        ?.takeIf { it.isNotBlank() }
+                        ?.let { raw -> localizeSubtitle(sub, raw) }
+                        ?.takeIf { it.url.startsWith("file:") }
+                }
+            }.awaitAll().filterNotNull()
+            android.util.Log.d(
+                "SubMatch",
+                "preload done: ${localized.size}/${candidates.size} candidates localized (target=$target)"
+            )
+            _uiState.value = _uiState.value.copy(
+                preloadedSubtitles = (_uiState.value.preloadedSubtitles + localized)
+                    .distinctBy { "${it.provider}|${it.id}|${it.lang}" },
+                subtitlePreloadComplete = true
+            )
+        }
+    }
+
     private fun showMatchToast(message: String) {
         _uiState.value = _uiState.value.copy(matchToast = message)
     }
@@ -4084,6 +4233,9 @@ class PlayerViewModel @Inject constructor(
         private const val MATCH_FAST_ACCEPT_REFS = 5    // …with at least this many refs
         private const val MATCH_FAST_ACCEPT_SCORE = 0.85 // …scoring at least this
         private const val MATCH_MIN_REF_SPAN_MS = 30_000L // refs must cover this much video before any accept
+        // A REJECT verdict requires at least this many buffered (authored-timing) reference
+        // intervals — realtime-only references systematically under-score synced subs (§2 skew).
+        private const val MATCH_MIN_BUFFERED_FOR_REJECT = 4
         private const val MATCH_TRACK_SWITCH_SETTLE_MS = 1_500L // let the reference-track switch reach the renderer
         private const val MATCH_BUFFERED_REF_INTERVALS = 12  // max upcoming cues to read from the buffer per poll
         private const val MATCH_EMBEDDED_WAIT_MS = 8_000L    // grace period for async embedded tracks
diff --git a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/SubtitleAiModel.kt b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/SubtitleAiModel.kt
index a7119afd9..e75672cea 100644
--- a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/SubtitleAiModel.kt
+++ b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/SubtitleAiModel.kt
@@ -2,5 +2,7 @@ package com.arflix.tv.ui.screens.player
 
 enum class SubtitleAiModel {
     GROQ_LLAMA_70B,
+    // Now maps to gemini-3.5-flash (2.5 retired July 2026). Name kept: the enum value is
+    // persisted in DataStore and cloud backups — renaming breaks restore on other devices.
     GEMINI_FLASH_25
 }
diff --git a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/SubtitleTranslationService.kt b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/SubtitleTranslationService.kt
index b529b4674..ba8c259ef 100644
--- a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/SubtitleTranslationService.kt
+++ b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/SubtitleTranslationService.kt
@@ -21,9 +21,20 @@ data class TranslationResult(
     val errorMessage: String? = null
 )
 
+// Marker error for Gemini's non-configurable content-policy rejections (finishReason
+// PROHIBITED_CONTENT etc. — safetySettings BLOCK_NONE does NOT cover these). Blocked batches are
+// bisected so one flagged line doesn't lose the whole window, and the caller must not toast it:
+// it's not actionable and translation keeps working for everything else.
+const val TRANSLATION_ERROR_CONTENT_BLOCKED = "CONTENT_BLOCKED"
+
+private val BLOCKED_FINISH_REASONS = setOf(
+    "PROHIBITED_CONTENT", "SAFETY", "RECITATION", "BLOCKLIST", "SPII"
+)
+
 private const val GROQ_MODEL_ID = "llama-3.3-70b-versatile"
 private const val GROQ_URL = "https://api.groq.com/openai/v1/chat/completions"
-private const val GEMINI_MODEL_ID = "gemini-2.5-flash"
+// gemini-2.5-flash was retired by Google (HTTP 404 "no longer available", July 2026).
+private const val GEMINI_MODEL_ID = "gemini-3.5-flash"
 private const val GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models/$GEMINI_MODEL_ID:generateContent"
 
 class SubtitleTranslationService(
@@ -44,9 +55,21 @@ class SubtitleTranslationService(
 
         for (candidate in candidates) {
             try { return JSONArray(candidate) } catch (_: Exception) {}
+            // With responseMimeType=application/json the model sometimes wraps the array in an
+            // object (e.g. {"translations": [...]}) — unwrap a lone array-valued field.
+            try {
+                val obj = JSONObject(candidate)
+                val arrays = obj.keys().asSequence()
+                    .mapNotNull { key -> obj.optJSONArray(key) }
+                    .toList()
+                if (arrays.size == 1) return arrays[0]
+            } catch (_: Exception) {}
             val start = candidate.indexOf('[')
             val end = candidate.lastIndexOf(']')
-            if (start < 0 || end <= start) continue
+            if (start < 0 || end <= start) {
+                repairTruncatedArray(candidate)?.let { return it }
+                continue
+            }
             try {
                 return JSONArray(candidate.substring(start, end + 1))
             } catch (_: Exception) {}
@@ -54,15 +77,51 @@ class SubtitleTranslationService(
         return null
     }
 
+    /**
+     * Gemini's JSON mode intermittently truncates output at the very tail (finishReason STOP but
+     * the closing bracket — sometimes a trailing element — is missing). The translations
+     * themselves are intact, so re-terminate the array instead of failing the whole batch.
+     */
+    private fun repairTruncatedArray(text: String): JSONArray? {
+        val t = text.trim()
+        if (!t.startsWith("[") || t.endsWith("]")) return null
+        val lastQuote = t.lastIndexOf('"')
+        if (lastQuote <= 0) return null
+        // Try closing as-is, then after dropping a trailing partial element.
+        for (cut in listOf(t, t.substring(0, lastQuote + 1))) {
+            val trimmed = cut.trimEnd().trimEnd(',')
+            try { return JSONArray("$trimmed]") } catch (_: Exception) {}
+            try { return JSONArray("$trimmed\"]") } catch (_: Exception) {}
+        }
+        return null
+    }
+
     private fun buildSystemPrompt(targetLanguage: String, NL: String) =
         "You are a professional subtitle translator. Translate the following JSON array into natural $targetLanguage.\n" +
         "Rules:\n" +
-        "1. Return ONLY a valid JSON array.\n" +
-        "2. Keep the exact same order and element count.\n" +
-        "3. Preserve the '$NL' symbol exactly where it appears as a line break.\n" +
-        "4. Use informal, spoken $targetLanguage suitable for cinema."
+        "1. Return ONLY a valid JSON array of strings.\n" +
+        "2. Every input element starts with a numeric prefix like '7: ' — keep the EXACT same numeric prefix on the corresponding translated element. Never merge or split elements.\n" +
+        "3. Keep the exact same order and element count.\n" +
+        "4. Preserve the '$NL' symbol exactly where it appears as a line break.\n" +
+        "5. Use informal, spoken $targetLanguage suitable for cinema."
+
+    // The numeric prefix each translated element must carry back ("7: text" / tolerant of
+    // "7. text", "7 - text"). Alignment by index instead of array position: the model merging or
+    // splitting one subtitle line then costs only that line, not the whole window (line-count
+    // mismatches — 40→39, 19→20 — were the dominant translation failure on gemini-3.5-flash).
+    private val indexPrefixRegex = Regex("""^\s*(\d+)\s*[:.\-]\s*""")
+
+    private fun encodeIndexed(lines: List<String>, NL: String): JSONArray =
+        JSONArray(lines.mapIndexed { i, line -> "$i: ${line.replace("\n", NL)}" })
+
+    suspend fun translateBatch(lines: List<String>, targetLanguage: String): TranslationResult =
+        translateBatchInternal(lines, targetLanguage, depth = 0)
 
-    suspend fun translateBatch(lines: List<String>, targetLanguage: String): TranslationResult {
+    private suspend fun translateBatchInternal(
+        lines: List<String>,
+        targetLanguage: String,
+        depth: Int
+    ): TranslationResult {
         if (lines.isEmpty()) return TranslationResult(lines, true)
         val apiKey = apiKeyProvider()
         if (apiKey.isBlank()) {
@@ -70,16 +129,32 @@ class SubtitleTranslationService(
             return TranslationResult(lines, false, "API key missing")
         }
 
-        return when (modelProvider()) {
+        val result = when (modelProvider()) {
             SubtitleAiModel.GROQ_LLAMA_70B -> translateGroq(lines, targetLanguage, apiKey)
             SubtitleAiModel.GEMINI_FLASH_25 -> translateGemini(lines, targetLanguage, apiKey)
         }
+
+        // A content-policy block poisons the whole window because of (usually) one line.
+        // Bisect so the innocuous majority still gets translated; a line that stays blocked all
+        // the way down is shown in its original language. Depth cap keeps worst-case extra API
+        // calls bounded (window → halves → quarters).
+        if (!result.success &&
+            result.errorMessage == TRANSLATION_ERROR_CONTENT_BLOCKED &&
+            lines.size >= 2 && depth < 2
+        ) {
+            Log.w(TAG, "Content-blocked batch of ${lines.size} — bisecting (depth=$depth)")
+            val mid = lines.size / 2
+            val left = translateBatchInternal(lines.subList(0, mid), targetLanguage, depth + 1)
+            val right = translateBatchInternal(lines.subList(mid, lines.size), targetLanguage, depth + 1)
+            // Best-effort merge: failed halves already carry their original lines.
+            return TranslationResult(left.lines + right.lines, true)
+        }
+        return result
     }
 
     private suspend fun translateGroq(lines: List<String>, targetLanguage: String, apiKey: String): TranslationResult {
         val NL = "⏎"
-        val encoded = lines.map { it.replace("\n", NL) }
-        val inputArray = JSONArray(encoded)
+        val inputArray = encodeIndexed(lines, NL)
         val systemPrompt = buildSystemPrompt(targetLanguage, NL)
 
         val body = JSONObject().apply {
@@ -134,10 +209,14 @@ class SubtitleTranslationService(
         }
     }
 
-    private suspend fun translateGemini(lines: List<String>, targetLanguage: String, apiKey: String): TranslationResult {
+    private suspend fun translateGemini(
+        lines: List<String>,
+        targetLanguage: String,
+        apiKey: String,
+        attempt: Int = 0
+    ): TranslationResult {
         val NL = "⏎"
-        val encoded = lines.map { it.replace("\n", NL) }
-        val inputArray = JSONArray(encoded)
+        val inputArray = encodeIndexed(lines, NL)
         val systemPrompt = buildSystemPrompt(targetLanguage, NL)
 
         val body = JSONObject().apply {
@@ -159,9 +238,30 @@ class SubtitleTranslationService(
                 put("temperature", 0.1)
                 put("responseMimeType", "application/json")
                 put("thinkingConfig", JSONObject().apply {
-                    put("thinkingBudget", 0)
+                    // Subtitles need raw inference speed, not reasoning. Measured on
+                    // gemini-3.5-flash (July 2026): default = ~5s + 875 thought tokens per batch;
+                    // minimal = ~1.3s + 0. "thinkingLevel" is the Gemini 3.x field (the legacy
+                    // 2.5 "thinkingBudget: 0" still works there today, but is deprecated).
+                    put("thinkingLevel", "minimal")
                 })
             })
+            // Movie dialogue routinely contains violence/profanity/sexual references; default
+            // safety filters block such prompts outright (HTTP 200 with NO candidates — seen as
+            // "translation error" toasts at episode start on gemini-3.5-flash). We're translating
+            // the film's own subtitle text, not generating new content.
+            put("safetySettings", JSONArray().apply {
+                listOf(
+                    "HARM_CATEGORY_HARASSMENT",
+                    "HARM_CATEGORY_HATE_SPEECH",
+                    "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+                    "HARM_CATEGORY_DANGEROUS_CONTENT"
+                ).forEach { category ->
+                    put(JSONObject().apply {
+                        put("category", category)
+                        put("threshold", "BLOCK_NONE")
+                    })
+                }
+            })
         }
 
         val url = "$GEMINI_BASE_URL?key=$apiKey"
@@ -184,16 +284,55 @@ class SubtitleTranslationService(
                 }
 
                 val json = JSONObject(responseBody)
-                val rawText = json
-                    .getJSONArray("candidates")
-                    .getJSONObject(0)
-                    .getJSONObject("content")
-                    .getJSONArray("parts")
-                    .getJSONObject(0)
-                    .getString("text")
-                    .trim()
+                val candidates = json.optJSONArray("candidates")
+                if (candidates == null || candidates.length() == 0) {
+                    // HTTP 200 without candidates = prompt-level block (safety/recitation).
+                    val blockReason = json.optJSONObject("promptFeedback")
+                        ?.optString("blockReason").orEmpty()
+                    Log.e(TAG, "Gemini missing candidates (block=$blockReason): ${responseBody.take(400)}")
+                    return@withContext TranslationResult(
+                        lines, false,
+                        if (blockReason.isNotBlank()) TRANSLATION_ERROR_CONTENT_BLOCKED else "No candidates in response"
+                    )
+                }
+                val candidate = candidates.getJSONObject(0)
+                // Gemini 3.x can emit thought/thoughtSignature parts before the text — take
+                // every non-thought text part, not blindly parts[0].
+                val parts = candidate.optJSONObject("content")?.optJSONArray("parts")
+                val rawText = buildString {
+                    for (i in 0 until (parts?.length() ?: 0)) {
+                        val part = parts!!.getJSONObject(i)
+                        if (part.optBoolean("thought", false)) continue
+                        append(part.optString("text"))
+                    }
+                }.trim()
+                val finishReason = candidate.optString("finishReason")
+                if (rawText.isBlank()) {
+                    Log.e(TAG, "Gemini candidate has no text (finish=$finishReason): ${responseBody.take(400)}")
+                    return@withContext TranslationResult(
+                        lines, false,
+                        if (finishReason in BLOCKED_FINISH_REASONS) TRANSLATION_ERROR_CONTENT_BLOCKED
+                        else "Empty candidate (finish=$finishReason)"
+                    )
+                }
 
-                parseTranslationResult(lines, targetLanguage, rawText, NL)
+                val parsed = parseTranslationResult(lines, targetLanguage, rawText, NL)
+                if (!parsed.success && finishReason in BLOCKED_FINISH_REASONS) {
+                    // The policy filter can also cut generation mid-array: partial text +
+                    // blocked finishReason parses as garbage. Same treatment — bisect upstream.
+                    Log.e(TAG, "Gemini output truncated by policy (finish=$finishReason)")
+                    return@withContext TranslationResult(lines, false, TRANSLATION_ERROR_CONTENT_BLOCKED)
+                }
+                if (!parsed.success && attempt == 0) {
+                    // Intermittent JSON-mode malformation (e.g. tail truncation with STOP) —
+                    // one re-roll usually returns a clean array.
+                    Log.w(TAG, "Parse failed (${parsed.errorMessage}, finish=$finishReason) — retrying batch once")
+                    return@withContext translateGemini(lines, targetLanguage, apiKey, attempt = 1)
+                }
+                if (!parsed.success) {
+                    Log.e(TAG, "Parse failed after retry (finish=$finishReason) body=${responseBody.take(400)}")
+                }
+                parsed
             } catch (e: Exception) {
                 if (e is kotlinx.coroutines.CancellationException) throw e
 
@@ -204,17 +343,52 @@ class SubtitleTranslationService(
     }
 
     private fun parseTranslationResult(lines: List<String>, targetLanguage: String, rawText: String, NL: String): TranslationResult {
-        val resultArray = extractJsonArray(rawText)
-            ?: return TranslationResult(lines, false, "No valid JSON array in response")
+        var resultArray = extractJsonArray(rawText)
+        if (resultArray == null && lines.size == 1) {
+            // Single-line batches: the model often returns a bare JSON string (or plain text)
+            // instead of a one-element array — treat the whole payload as that one translation.
+            val single = runCatching { JSONArray("[$rawText]").getString(0) }.getOrNull()
+                ?: rawText.trim().trim('"')
+            if (single.isNotBlank()) resultArray = JSONArray(listOf(single))
+        }
+        if (resultArray == null) {
+            // The only failure path that carries no HTTP/finishReason context — always log the
+            // offending text or the toast is undiagnosable.
+            Log.e(TAG, "No JSON array in model output (sent ${lines.size} lines): ${rawText.take(300)}")
+            return TranslationResult(lines, false, "No valid JSON array in response")
+        }
 
-        if (resultArray.length() != lines.size) {
-            Log.w(TAG, "Line count mismatch: sent ${lines.size}, got ${resultArray.length()}")
-            return TranslationResult(lines, false, "Line count mismatch")
+        // Align by the numeric prefix, not array position — merges/splits then cost only the
+        // affected line (it stays in the original language) instead of failing the window.
+        val byIndex = HashMap<Int, String>()
+        for (i in 0 until resultArray.length()) {
+            val element = resultArray.optString(i) ?: continue
+            val match = indexPrefixRegex.find(element)
+            val key: Int
+            val value: String
+            if (match != null) {
+                key = match.groupValues[1].toIntOrNull() ?: continue
+                value = element.substring(match.range.last + 1)
+            } else if (resultArray.length() == lines.size) {
+                // Model dropped the prefixes but the count matches — positional fallback.
+                key = i
+                value = element
+            } else {
+                continue
+            }
+            if (!byIndex.containsKey(key)) byIndex[key] = value
+        }
+        if (byIndex.isEmpty()) {
+            Log.e(TAG, "No alignable lines (sent ${lines.size}, got ${resultArray.length()}): ${rawText.take(300)}")
+            return TranslationResult(lines, false, "No valid JSON array in response")
+        }
+        if (byIndex.size < lines.size) {
+            Log.w(TAG, "Partial alignment: ${byIndex.size}/${lines.size} lines translated")
         }
 
         val isRtl = RTL_LANGUAGES.contains(targetLanguage.lowercase())
-        val translated = List(resultArray.length()) { i ->
-            val line = resultArray.getString(i).replace(NL, "\n")
+        val translated = lines.indices.map { i ->
+            val line = byIndex[i]?.replace(NL, "\n") ?: return@map lines[i]
             if (isRtl) "‏$line‏" else line
         }
 
diff --git a/app/src/main/kotlin/com/arflix/tv/ui/screens/settings/SettingsScreen.kt b/app/src/main/kotlin/com/arflix/tv/ui/screens/settings/SettingsScreen.kt
index 6a32a1401..029c50aae 100644
--- a/app/src/main/kotlin/com/arflix/tv/ui/screens/settings/SettingsScreen.kt
+++ b/app/src/main/kotlin/com/arflix/tv/ui/screens/settings/SettingsScreen.kt
@@ -216,7 +216,7 @@ private val tvGeneralSectionIds = setOf(
 private fun tvGeneralRowsForSection(section: String): List<Int> {
     return when (section) {
         "language" -> listOf(0, 3)
-        "subtitles" -> listOf(1, 2, 38, 4, 5, 6, 7, 8, 9)
+        "subtitles" -> listOf(1, 2, 38, 39, 4, 5, 6, 7, 8, 9)
         "ai_subtitles" -> listOf(28, 29, 30, 31, 32, 33)
         "playback" -> listOf(10, 11, 12, 13, 14, 37, 34, 16, 15, 27)
         "appearance" -> listOf(17, 18, 20, 21, 24, 23, 22, 36)
@@ -904,6 +904,7 @@ fun SettingsScreen(
                                                 29 -> showAiModelDialog = true
                                                 30 -> viewModel.setSubtitleAiAutoSelect(!uiState.subtitleAiAutoSelect)
                                                 38 -> viewModel.setSubtitleAiFindBestMatch(!uiState.subtitleAiFindBestMatch)
+                                                39 -> viewModel.setSubtitlePreloadEnabled(!uiState.subtitlePreloadEnabled)
                                                 31 -> viewModel.setSubtitleRemoveHearingImpaired(!uiState.subtitleRemoveHearingImpaired)
                                                 32 -> showAiApiKeyDialog = true
                                                 33 -> viewModel.startAiKeyServer()
@@ -1332,6 +1333,7 @@ fun SettingsScreen(
                             subtitleAiEnabled = uiState.subtitleAiEnabled,
                             subtitleAiAutoSelect = uiState.subtitleAiAutoSelect,
                             subtitleAiFindBestMatch = uiState.subtitleAiFindBestMatch,
+                            subtitlePreloadEnabled = uiState.subtitlePreloadEnabled,
                             subtitleAiApiKey = uiState.subtitleAiApiKey,
                             subtitleAiModel = uiState.subtitleAiModel,
                             subtitleRemoveHearingImpaired = uiState.subtitleRemoveHearingImpaired,
@@ -1339,6 +1341,7 @@ fun SettingsScreen(
                             onSubtitleAiModelClick = { showAiModelDialog = true },
                             onSubtitleAiAutoSelectToggle = { viewModel.setSubtitleAiAutoSelect(it) },
                             onSubtitleAiFindBestMatchToggle = { viewModel.setSubtitleAiFindBestMatch(it) },
+                            onSubtitlePreloadToggle = { viewModel.setSubtitlePreloadEnabled(it) },
                             onSubtitleRemoveHearingImpairedToggle = { viewModel.setSubtitleRemoveHearingImpaired(it) },
                             onSubtitleAiApiKeyClick = { showAiApiKeyDialog = true },
                             onSubtitleAiQrClick = { viewModel.startAiKeyServer() },
@@ -3432,6 +3435,14 @@ private fun MobileSettingsMainPage(
                     isFocused = false,
                     onClick = { viewModel.setSubtitleAiFindBestMatch(!uiState.subtitleAiFindBestMatch) }
                 )
+                MobileSettingsRow(
+                    icon = Icons.Default.Subtitles,
+                    title = stringResource(R.string.subtitle_preload_title),
+                    subtitle = stringResource(R.string.subtitle_preload_desc),
+                    value = if (uiState.subtitlePreloadEnabled) "On" else "Off",
+                    isFocused = false,
+                    onClick = { viewModel.setSubtitlePreloadEnabled(!uiState.subtitlePreloadEnabled) }
+                )
                 MobileSettingsRow(
                     icon = Icons.Default.Subtitles,
                     title = stringResource(R.string.filter_subtitles),
@@ -3727,7 +3738,7 @@ private fun MobileSettingsSubPage(
                         subtitle = stringResource(R.string.ai_model_desc),
                         value = when (uiState.subtitleAiModel) {
                             com.arflix.tv.ui.screens.player.SubtitleAiModel.GROQ_LLAMA_70B -> "Groq - Llama 3.3 70B"
-                            com.arflix.tv.ui.screens.player.SubtitleAiModel.GEMINI_FLASH_25 -> "Google - Gemini 2.5 Flash"
+                            com.arflix.tv.ui.screens.player.SubtitleAiModel.GEMINI_FLASH_25 -> "Google - Gemini 3.5 Flash"
                         },
                         isFocused = false,
                         onClick = onSubtitleAiModelClick
@@ -4751,6 +4762,7 @@ private fun TvGeneralSettingsRows(
     subtitleAiEnabled: Boolean = false,
     subtitleAiAutoSelect: Boolean = false,
     subtitleAiFindBestMatch: Boolean = false,
+    subtitlePreloadEnabled: Boolean = false,
     subtitleAiApiKey: String = "",
     subtitleAiModel: com.arflix.tv.ui.screens.player.SubtitleAiModel = com.arflix.tv.ui.screens.player.SubtitleAiModel.GROQ_LLAMA_70B,
     subtitleRemoveHearingImpaired: Boolean = true,
@@ -4758,6 +4770,7 @@ private fun TvGeneralSettingsRows(
     onSubtitleAiModelClick: () -> Unit = {},
     onSubtitleAiAutoSelectToggle: (Boolean) -> Unit = {},
     onSubtitleAiFindBestMatchToggle: (Boolean) -> Unit = {},
+    onSubtitlePreloadToggle: (Boolean) -> Unit = {},
     onSubtitleRemoveHearingImpairedToggle: (Boolean) -> Unit = {},
     onSubtitleAiApiKeyClick: () -> Unit = {},
     onSubtitleAiQrClick: () -> Unit = {},
@@ -4857,7 +4870,7 @@ private fun TvGeneralSettingsRows(
                     subtitle = stringResource(R.string.ai_model_desc),
                     value = when (subtitleAiModel) {
                         com.arflix.tv.ui.screens.player.SubtitleAiModel.GROQ_LLAMA_70B -> "Groq - Llama 3.3 70B"
-                        com.arflix.tv.ui.screens.player.SubtitleAiModel.GEMINI_FLASH_25 -> "Google - Gemini 2.5 Flash"
+                        com.arflix.tv.ui.screens.player.SubtitleAiModel.GEMINI_FLASH_25 -> "Google - Gemini 3.5 Flash"
                     },
                     isFocused = focusedIndex == localIndex,
                     onClick = onSubtitleAiModelClick,
@@ -4866,6 +4879,7 @@ private fun TvGeneralSettingsRows(
                 30 -> SettingsToggleRow(stringResource(R.string.ai_auto_select_title), stringResource(R.string.ai_auto_select_desc), subtitleAiAutoSelect, focusedIndex == localIndex, onSubtitleAiAutoSelectToggle, Modifier.settingsFocusSlot(localIndex).alpha(if (subtitleAiEnabled) 1f else 0.4f))
                 // AI-independent: the timing-based match scan needs no API key.
                 38 -> SettingsToggleRow(stringResource(R.string.ai_find_best_match_title), stringResource(R.string.ai_find_best_match_desc), subtitleAiFindBestMatch, focusedIndex == localIndex, onSubtitleAiFindBestMatchToggle, Modifier.settingsFocusSlot(localIndex))
+                39 -> SettingsToggleRow(stringResource(R.string.subtitle_preload_title), stringResource(R.string.subtitle_preload_desc), subtitlePreloadEnabled, focusedIndex == localIndex, onSubtitlePreloadToggle, Modifier.settingsFocusSlot(localIndex))
                 31 -> SettingsToggleRow(stringResource(R.string.ai_remove_hi_title), stringResource(R.string.ai_remove_hi_desc), subtitleRemoveHearingImpaired, focusedIndex == localIndex, onSubtitleRemoveHearingImpairedToggle, Modifier.settingsFocusSlot(localIndex).alpha(if (subtitleAiEnabled) 1f else 0.4f))
                 32 -> SettingsRow(Icons.Default.VpnKey, stringResource(R.string.ai_api_key_title), stringResource(R.string.ai_api_key_desc), maskAiApiKey(subtitleAiApiKey, stringResource(R.string.ai_key_not_set)), focusedIndex == localIndex, onSubtitleAiApiKeyClick, Modifier.settingsFocusSlot(localIndex).alpha(if (subtitleAiEnabled) 1f else 0.4f))
                 33 -> SettingsRow(Icons.Default.QrCode, stringResource(R.string.ai_scan_qr_title), stringResource(R.string.ai_scan_qr_desc), "", focusedIndex == localIndex, onSubtitleAiQrClick, Modifier.settingsFocusSlot(localIndex).alpha(if (subtitleAiEnabled) 1f else 0.4f))
@@ -5310,7 +5324,7 @@ private fun GeneralSettings(
             subtitle = stringResource(R.string.ai_model_desc),
             value = when (subtitleAiModel) {
                 com.arflix.tv.ui.screens.player.SubtitleAiModel.GROQ_LLAMA_70B -> "Groq – Llama 3.3 70B"
-                com.arflix.tv.ui.screens.player.SubtitleAiModel.GEMINI_FLASH_25 -> "Google – Gemini 2.5 Flash"
+                com.arflix.tv.ui.screens.player.SubtitleAiModel.GEMINI_FLASH_25 -> "Google – Gemini 3.5 Flash"
             },
             isFocused = focusedIndex == 29,
             onClick = onSubtitleAiModelClick,
@@ -5392,7 +5406,7 @@ private fun AiModelDialog(
     val isMobile = LocalDeviceType.current.isTouchDevice()
     val options = listOf(
         Triple(com.arflix.tv.ui.screens.player.SubtitleAiModel.GROQ_LLAMA_70B, "Groq – Llama 3.3 70B", stringResource(R.string.ai_groq_model_note)),
-        Triple(com.arflix.tv.ui.screens.player.SubtitleAiModel.GEMINI_FLASH_25, "Google – Gemini 2.5 Flash", stringResource(R.string.ai_gemini_model_note))
+        Triple(com.arflix.tv.ui.screens.player.SubtitleAiModel.GEMINI_FLASH_25, "Google – Gemini 3.5 Flash", stringResource(R.string.ai_gemini_model_note))
     )
     BackHandler { onDismiss() }
     androidx.compose.ui.window.Dialog(onDismissRequest = onDismiss) {
diff --git a/app/src/main/kotlin/com/arflix/tv/ui/screens/settings/SettingsViewModel.kt b/app/src/main/kotlin/com/arflix/tv/ui/screens/settings/SettingsViewModel.kt
index d6dab3872..1350f0a0c 100644
--- a/app/src/main/kotlin/com/arflix/tv/ui/screens/settings/SettingsViewModel.kt
+++ b/app/src/main/kotlin/com/arflix/tv/ui/screens/settings/SettingsViewModel.kt
@@ -198,6 +198,7 @@ data class SettingsUiState(
     val subtitleAiEnabled: Boolean = false,
     val subtitleAiAutoSelect: Boolean = false,
     val subtitleAiFindBestMatch: Boolean = false,
+    val subtitlePreloadEnabled: Boolean = true,
     val subtitleAiApiKey: String = "",
     val subtitleAiModel: SubtitleAiModel = SubtitleAiModel.GROQ_LLAMA_70B,
     val subtitleRemoveHearingImpaired: Boolean = true,
@@ -288,6 +289,7 @@ class SettingsViewModel @Inject constructor(
     private val subtitleAiEnabledKey = booleanPreferencesKey("subtitle_ai_enabled")
     private val subtitleAiAutoSelectKey = booleanPreferencesKey("subtitle_ai_auto_select")
     private val subtitleAiFindBestMatchKey = booleanPreferencesKey("subtitle_ai_find_best_match")
+    private val subtitlePreloadEnabledKey = booleanPreferencesKey("subtitle_preload_enabled")
     private val subtitleAiApiKeyKey = stringPreferencesKey("subtitle_ai_api_key")
     private val subtitleAiModelKey = stringPreferencesKey("subtitle_ai_model")
     private val subtitleRemoveHearingImpairedKey = booleanPreferencesKey("subtitle_remove_hearing_impaired")
@@ -492,6 +494,7 @@ class SettingsViewModel @Inject constructor(
             val subtitleAiEnabled = prefs[subtitleAiEnabledKey] ?: false
             val subtitleAiAutoSelect = prefs[subtitleAiAutoSelectKey] ?: false
             val subtitleAiFindBestMatch = prefs[subtitleAiFindBestMatchKey] ?: false
+            val subtitlePreloadEnabled = prefs[subtitlePreloadEnabledKey] ?: true
             val subtitleAiApiKey = prefs[subtitleAiApiKeyKey] ?: ""
             val subtitleAiModel = runCatching {
                 SubtitleAiModel.valueOf(prefs[subtitleAiModelKey] ?: SubtitleAiModel.GROQ_LLAMA_70B.name)
@@ -562,6 +565,7 @@ class SettingsViewModel @Inject constructor(
                 subtitleAiEnabled = subtitleAiEnabled,
                 subtitleAiAutoSelect = subtitleAiAutoSelect,
                 subtitleAiFindBestMatch = subtitleAiFindBestMatch,
+                subtitlePreloadEnabled = subtitlePreloadEnabled,
                 subtitleAiApiKey = subtitleAiApiKey,
                 subtitleAiModel = subtitleAiModel,
                 subtitleRemoveHearingImpaired = subtitleRemoveHearingImpaired,
@@ -1310,6 +1314,14 @@ class SettingsViewModel @Inject constructor(
         }
     }
 
+    fun setSubtitlePreloadEnabled(enabled: Boolean) {
+        viewModelScope.launch {
+            context.settingsDataStore.edit { it[subtitlePreloadEnabledKey] = enabled }
+            _uiState.value = _uiState.value.copy(subtitlePreloadEnabled = enabled)
+            syncLocalStateToCloud(silent = true)
+        }
+    }
+
     fun setSubtitleRemoveHearingImpaired(enabled: Boolean) {
         viewModelScope.launch {
             context.settingsDataStore.edit { it[subtitleRemoveHearingImpairedKey] = enabled }
diff --git a/app/src/main/res/values-iw/strings.xml b/app/src/main/res/values-iw/strings.xml
index 8116ea887..df066c4e2 100644
--- a/app/src/main/res/values-iw/strings.xml
+++ b/app/src/main/res/values-iw/strings.xml
@@ -210,6 +210,8 @@
     <string name="ai_auto_select_desc">הפעל אוטומטית כאשר קיים תרגום מובנה כלשהו</string>
     <string name="ai_find_best_match_title">חיפוש אוטומטי של הכתובית המתאימה ביותר</string>
     <string name="ai_find_best_match_desc">בחירה אוטומטית של הכתובית המסונכרנת ביותר מההרחבות שלך</string>
+    <string name="subtitle_preload_title">טעינת כתוביות מראש</string>
+    <string name="subtitle_preload_desc">המתן לכתוביות לפני תחילת הווידאו כך שהחלפה ביניהן תהיה מיידית</string>
     <string name="ai_remove_hi_title">הסר טקסט למוגבלי שמיעה</string>
     <string name="ai_remove_hi_desc">הסר סימוני [סוגריים] למוגבלי שמיעה לפני תרגום</string>
     <string name="ai_api_key_title">מפתח API</string>
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index cff06215d..7cefa516a 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -237,6 +237,8 @@
     <string name="ai_auto_select_desc">Automatically activate AI when any built in language is available</string>
     <string name="ai_find_best_match_title">Auto Find Best Subtitle Match</string>
     <string name="ai_find_best_match_desc">Auto-pick the best-synced subtitle from your addons</string>
+    <string name="subtitle_preload_title">Preload Subtitles</string>
+    <string name="subtitle_preload_desc">Wait for subtitles before starting the video so switching them is instant</string>
     <string name="ai_remove_hi_title">Remove Hearing Impaired Text</string>
     <string name="ai_remove_hi_desc">Strip [bracketed] hearing-impaired markers before translation</string>
     <string name="ai_api_key_title">API Key</string>
diff --git a/docs/subtitle-auto-match.md b/docs/subtitle-auto-match.md
index 542a14abd..3c9637f2d 100644
--- a/docs/subtitle-auto-match.md
+++ b/docs/subtitle-auto-match.md
@@ -121,14 +121,19 @@ target-language candidates exist.
 
 | Condition | Values |
 |---|---|
-| Target reached | ≥ 8 intervals AND span ≥ 30s |
+| Target reached | ≥ 8 intervals AND span ≥ 30s **AND ≥ 4 buffered** |
 | Early accept | ≥ 4 intervals, span ≥ 30s, some candidate ≥ 0.8 |
 | Fast accept | ≥ 5 intervals, span ≥ 15s, some candidate ≥ 0.85 |
 | Give-up (no speech yet) | 4 min |
 | Give-up (stagnation) | 90s since last new interval (clock **frozen while paused**) |
 | Absolute ceiling | 10 min |
 
-Post-loop: `< 2` intervals or span `< 15s` ⇒ inconclusive (fall to ladder).
+Post-loop: `< 2` intervals or span `< 15s` ⇒ inconclusive (fall to ladder). Also inconclusive:
+best score `< 0.70` with `< 4` buffered intervals — a REJECT from a realtime-dominated reference
+is untrustworthy (July 2026, From S03E03: a verified-synced sub scored 0.65 on buffered=2/9 refs
+collected in a sparse-dialogue recap, then 0.85 for ALL candidates once buffered coverage
+existed). Accepts remain reference-agnostic — only the reject verdict needs buffered quorum
+(`MATCH_MIN_BUFFERED_FOR_REJECT = 4`).
 
 ### Scoring (`SubtitleSyncMatcher.scoreByTiming`) — HYBRID, calibrated
 
@@ -147,7 +152,9 @@ narrow — do not nudge thresholds or the metric without fresh A/B evidence.
 
 ## 3. Selection & the local-file trick
 
-Selecting an **external** subtitle rebuilds the MediaItem (re-prepare). Economics:
+Selecting an **external** subtitle rebuilds the MediaItem (re-prepare) — *unless* the track was
+side-loaded at startup by **Preload Subtitles** mode (see §3b), in which case selection is a pure
+`TrackSelectionOverride` with no rebuild. Economics of the rebuild path:
 - Video re-open: debrid streams are deliberately **not disk-cached** (I/O bottleneck) — usually
   fine, occasionally slow/stale.
 - Subtitle download during rebuild was the common stall (slow addon proxies) ⇒ matched subs are
@@ -156,8 +163,56 @@ Selecting an **external** subtitle rebuilds the MediaItem (re-prepare). Economic
   a `file://` copy (same id). The data source chain wraps OkHttp in `DefaultDataSource` for
   file support. The tracks-changed remap keeps `file:` selections as-is (would otherwise swap
   back to the remote URL and re-trigger a rebuild).
-- **Do NOT preload all subs into the MediaItem** — tried historically and reverted: ExoPlayer
-  eagerly downloads every side-loaded config at prepare (30+ requests), plus encoding issues.
+- **Do NOT preload all REMOTE subs into the MediaItem** — tried historically and reverted:
+  ExoPlayer eagerly downloads every side-loaded config at prepare (30+ requests), plus encoding
+  issues. Preload Subtitles mode (§3b) is the sanctioned exception because it attaches **local
+  file copies only** — the eager read is free and encoding is already normalized.
+
+## 3b. Preload Subtitles mode (July 2026)
+
+Opt-in setting **"Preload Subtitles"** (`subtitle_preload_enabled`, global, cloud-synced, row 39
+in Settings → Subtitles, default **off**). Modeled on NuvioTV's `AddonSubtitleStartupMode` but
+scoped to the preferred language and downloading files ourselves.
+
+Flow:
+1. `PlayerViewModel.preloadSubtitles()` runs after every addon-subtitle merge (all 3 fetch sites
+   + the no-imdbId branch): downloads preferred-language external subs (cap
+   `MAX_PRELOAD_SUBS = 15`) via `SubtitleSyncMatcher.loadRaw` → `localizeSubtitle` (same
+   `matched_subs/` files the scan serves) and publishes them as
+   `PlayerUiState.preloadedSubtitles` + `subtitlePreloadComplete` (always set, even on empty —
+   the gate must never hang; also pre-set when no preferred language).
+2. PlayerScreen's prepare effect **gates** the initial `setMediaSource` on
+   `subtitlePreloadComplete` (timeout 20s), attaches all `file://` configs, then **re-anchors
+   `streamSelectedTime` and clears `startupRecoverAttempted`** — otherwise a slow subtitle addon
+   would eat the startup watchdog budget and trigger source failover.
+3. Sidecar configs only merge through a `DefaultMediaSourceFactory`; the dedicated
+   `preloadMediaSourceFactory` streams video **uncached** (debrid I/O rule) while supporting
+   `file://` for the subs. HLS keeps working via the M3U8 mime hint (loses only chunkless prep);
+   DASH needs the explicit `APPLICATION_MPD` mime because DefaultMediaSourceFactory doesn't
+   recognize the "/dash"/"format=dash" URL shapes.
+4. Selection: the subtitle-switch effect first looks for an attached text track whose format id
+   matches `subtitleTrackId(subtitle)` and applies a `TrackSelectionOverride` (no rebuild). This
+   catches the **find-best-match winner** too: `subtitleTrackId` is provider|id-based (never a
+   URL hash for id-carrying subs), so the scan's localized `file://` copy resolves to the same
+   attached track. Non-attached picks fall back to the rebuild path, which in preload mode
+   re-attaches the preloaded set + the new sub and then pins the exact track by id (language
+   preference alone is ambiguous with several same-language tracks attached).
+- `subtitleTrackId` ids are provider-qualified with `|` — never `:`, because ExoPlayer prefixes
+  side-loaded format ids with `periodIndex:` and matching strips at the last `:`.
+- Mid-session source switches don't reset `subtitlePreloadComplete` — the files are per-title,
+  the gate passes instantly and the new MediaItem re-attaches the same copies.
+- ⚠ Ordering side effect: the gate guarantees the scan starts BEFORE the player exposes embedded
+  tracks (prepare waits for the very fetch that triggers selection). Two AI-interim fixes hang on
+  this (pre-preload both were masked because prepare raced ahead of the fetch):
+  1. No source at scan start → interim silently skipped and `autoMatchAttempted` blocks re-runs ⇒
+     late activation from `updatePlayerTextTracks` (scan running + auto-select + embedded source
+     just arrived). `activateAiTranslation` also resolves a blank `aiTargetLanguageName` from the
+     preferred-language code — the silent path never populated it, and a blank target made the
+     manager translate to nothing.
+  2. Interim activated early with an EXTERNAL English source → the scan's reference-track switch
+     (`scoreAgainstBuiltIn`) used to hard-set `isAiTranslating = false` when the AI source ≠
+     reference, killing the interim mid-scan. It now MIGRATES the interim onto the reference
+     (embedded non-bitmap = the preferred AI source) instead of disabling it.
 
 Subtitle MIME sniffing strips trailing slashes (`…/sub.vtt/?q=` is VTT — AIOStreams shape);
 default is SRT for extensionless URLs.

From cd22638ae134ed0091f42ce4bb6ba869a1a86d75 Mon Sep 17 00:00:00 2001
From: silentbil <silentbil@users.noreply.github.com>
Date: Fri, 10 Jul 2026 11:27:50 +0300
Subject: [PATCH 2/2] add timeout for preloading subs

---
 .../tv/data/repository/StreamRepository.kt    | 46 ++++++++++++++--
 .../tv/ui/screens/player/PlayerScreen.kt      | 52 +++++++++++++++----
 .../tv/ui/screens/player/PlayerViewModel.kt   | 28 +++++++++-
 docs/subtitle-auto-match.md                   | 14 +++--
 4 files changed, 118 insertions(+), 22 deletions(-)

diff --git a/app/src/main/kotlin/com/arflix/tv/data/repository/StreamRepository.kt b/app/src/main/kotlin/com/arflix/tv/data/repository/StreamRepository.kt
index f97888b2e..3fbde2f41 100644
--- a/app/src/main/kotlin/com/arflix/tv/data/repository/StreamRepository.kt
+++ b/app/src/main/kotlin/com/arflix/tv/data/repository/StreamRepository.kt
@@ -2711,12 +2711,22 @@ class StreamRepository @Inject constructor(
      * Fetch subtitles for the currently selected stream (important for OpenSubtitles matching).
      * Many subtitle providers (esp. OpenSubtitles) work best when `videoHash` and `videoSize` are provided.
      */
+    /**
+     * @param softDeadlineMs When set, don't let slow addons hold the merged list hostage: after
+     *   this long, harvest the addons that finished and CANCEL the rest (their subs are dropped
+     *   for this fetch). Used by the subtitle-preload prepare gate, where every extra second is
+     *   startup delay. Null = classic behavior (wait for all, each capped by [SUBTITLE_TIMEOUT_MS]).
+     * @param onPendingAddons Reports the names of addons still in flight whenever the set changes
+     *   (and finally an empty list) — surfaces WHICH addon is slow on the loading screen.
+     */
     suspend fun fetchSubtitlesForSelectedStream(
         mediaType: MediaType,
         imdbId: String,
         season: Int?,
         episode: Int?,
-        stream: StreamSource?
+        stream: StreamSource?,
+        softDeadlineMs: Long? = null,
+        onPendingAddons: ((List<String>) -> Unit)? = null
     ): List<Subtitle> = withContext(Dispatchers.IO) {
         val allAddons = installedAddons.first()
         // Include:
@@ -2760,8 +2770,8 @@ class StreamRepository @Inject constructor(
 
         // Query addons in parallel — with a generous timeout, sequential fetches would stack
         // each slow addon's latency onto the total.
-        subtitleAddons.map { addon ->
-            async {
+        val jobs = subtitleAddons.map { addon ->
+            addon.name to async {
                 suspend fun attempt(): List<Subtitle> = runCatching {
                     withTimeout(SUBTITLE_TIMEOUT_MS) {
                         val addonUrl = addon.url ?: return@withTimeout emptyList<Subtitle>()
@@ -2800,7 +2810,35 @@ class StreamRepository @Inject constructor(
                 }
                 subs
             }
-        }.awaitAll().flatten()
+        }
+
+        if (softDeadlineMs == null && onPendingAddons == null) {
+            return@withContext jobs.map { it.second }.awaitAll().flatten()
+        }
+
+        val deadlineAt = softDeadlineMs?.let { System.currentTimeMillis() + it }
+        var lastPending: List<String>? = null
+        while (true) {
+            val pending = jobs.filter { !it.second.isCompleted }.map { it.first }
+            if (pending != lastPending) {
+                lastPending = pending
+                onPendingAddons?.invoke(pending)
+            }
+            if (pending.isEmpty()) break
+            if (deadlineAt != null && System.currentTimeMillis() >= deadlineAt) {
+                Log.w(
+                    "StreamRepository",
+                    "subtitle fetch soft deadline (${softDeadlineMs}ms) — dropping slow addons: $pending"
+                )
+                jobs.forEach { (_, job) -> if (!job.isCompleted) job.cancel() }
+                break
+            }
+            delay(150)
+        }
+        onPendingAddons?.invoke(emptyList())
+        jobs.mapNotNull { (_, job) ->
+            if (job.isCompleted && !job.isCancelled) job.await() else null
+        }.flatten()
     }
 
     private fun buildSubtitlesUrl(
diff --git a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerScreen.kt b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerScreen.kt
index 5fc99b7ee..3243c397b 100644
--- a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerScreen.kt
+++ b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerScreen.kt
@@ -2956,6 +2956,16 @@ fun PlayerScreen(
                     // showLoadingStats — status feedback should always be visible.
                     phaseLabel = switchNotice
                         ?: (startupPhase.takeIf { uiState.selectedStreamUrl != null })
+                            ?.let { phase ->
+                                // Name the addons still being queried so a chronically slow one
+                                // identifies itself to the user ("Loading subtitles… (bla)").
+                                val pending = uiState.pendingSubtitleAddons
+                                if (phase.startsWith("Loading subtitles") && pending.isNotEmpty()) {
+                                    val shown = pending.take(2).joinToString(", ")
+                                    val more = pending.size - 2
+                                    "Loading subtitles… ($shown${if (more > 0) " +$more" else ""})"
+                                } else phase
+                            }
                         ?: uiState.streamLoadPhase
                 )
             }
@@ -3070,15 +3080,33 @@ fun PlayerScreen(
             )
         }
 
-        // "Find best match" status toast
+        // "Find best match" outcome — same top-center pill and spot as the scanning indicator
+        // above (a bottom toast would sit on the subtitles and interrupt watching).
         uiState.matchToast?.let { msg ->
-            Toast(
-                message = msg,
-                type = ToastType.INFO,
-                isVisible = true,
-                durationMs = 4000,
-                onDismiss = { viewModel.dismissMatchToast() }
-            )
+            LaunchedEffect(msg) {
+                delay(4000)
+                viewModel.dismissMatchToast()
+            }
+            androidx.compose.foundation.layout.Row(
+                modifier = Modifier
+                    .align(Alignment.TopCenter)
+                    // Slide below the scanning pill on the rare frames both are visible
+                    // (e.g. a remembered-match toast fired before the scan state cleared).
+                    .padding(top = if (hasPlaybackStarted && uiState.isFindingBestMatch) 60.dp else 16.dp)
+                    .background(
+                        color = androidx.compose.ui.graphics.Color.Black.copy(alpha = 0.72f),
+                        shape = RoundedCornerShape(20.dp)
+                    )
+                    .padding(horizontal = 16.dp, vertical = 8.dp)
+                    .zIndex(6f),
+                verticalAlignment = Alignment.CenterVertically
+            ) {
+                Text(
+                    text = msg,
+                    style = androidx.compose.material3.MaterialTheme.typography.labelLarge,
+                    color = androidx.compose.ui.graphics.Color.White.copy(alpha = 0.9f)
+                )
+            }
         }
 
         // Netflix-style Controls Overlay
@@ -5288,9 +5316,11 @@ private fun subtitleTrackId(subtitle: Subtitle): String {
 }
 
 // "Preload Subtitles" prepare gate: max time the initial prepare waits for the ViewModel to
-// finish downloading preferred-language subs. Below the player's hard startup timeout so a slow
-// subtitle addon can never trigger source failover (the gate also re-anchors the startup clock).
-private const val SUBTITLE_PRELOAD_GATE_TIMEOUT_MS = 20_000L
+// finish downloading preferred-language subs. The primary bound is the 10s addon-fetch soft
+// deadline (slow addons get dropped there); this cap only covers IMDb-id resolution plus the
+// file downloads on top of it, and stays below the player's hard startup timeout so a slow
+// subtitle pipeline can never trigger source failover (the gate also re-anchors the clock).
+private const val SUBTITLE_PRELOAD_GATE_TIMEOUT_MS = 14_000L
 
 private fun audioTrackKey(track: AudioTrackInfo): String {
     return listOf(
diff --git a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerViewModel.kt b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerViewModel.kt
index 58168fed1..85e0cba93 100644
--- a/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerViewModel.kt
+++ b/app/src/main/kotlin/com/arflix/tv/ui/screens/player/PlayerViewModel.kt
@@ -100,6 +100,9 @@ data class PlayerUiState(
     // True once preloading for this video finished (even with zero results) — the prepare gate
     // in PlayerScreen waits on this (with a timeout) before building the MediaItem.
     val subtitlePreloadComplete: Boolean = false,
+    // Addon names still being queried for subtitles (preload mode) — shown on the loading
+    // screen so a chronically slow addon identifies itself to the user.
+    val pendingSubtitleAddons: List<String> = emptyList(),
     val savedPosition: Long = 0,
     val preferredAudioLanguage: String = "en",
     val preferredSubtitleLang: String = "",
@@ -723,7 +726,9 @@ class PlayerViewModel @Inject constructor(
                                 imdbId = imdbId,
                                 season = seasonNumber,
                                 episode = episodeNumber,
-                                stream = null
+                                stream = null,
+                                softDeadlineMs = subtitleFetchSoftDeadline(),
+                                onPendingAddons = pendingSubtitleAddonsReporter()
                             )
                         }.getOrDefault(emptyList())
 
@@ -1076,7 +1081,9 @@ class PlayerViewModel @Inject constructor(
                             imdbId = effectiveStreamId,
                             season = seasonNumber,
                             episode = episodeNumber,
-                            stream = null
+                            stream = null,
+                            softDeadlineMs = subtitleFetchSoftDeadline(),
+                            onPendingAddons = pendingSubtitleAddonsReporter()
                         )
                     }.getOrDefault(emptyList())
 
@@ -3384,6 +3391,21 @@ class PlayerViewModel @Inject constructor(
         }.getOrDefault(sub)
     }
 
+    /**
+     * Preload mode only: cap the addon-list wait at 10s — completed addons are harvested, the
+     * stragglers are cancelled and DROPPED for this playback (user decision: a slow addon should
+     * cost its own subs, not everyone's startup time). Null (classic wait-for-all) when the mode
+     * is off: with no prepare gate there is nothing to hold up, so dropping subs buys nothing.
+     */
+    private fun subtitleFetchSoftDeadline(): Long? =
+        if (subtitlePreloadEnabled) SUBTITLE_FETCH_SOFT_DEADLINE_MS else null
+
+    /** Streams the names of still-pending subtitle addons to the loading screen (preload mode). */
+    private fun pendingSubtitleAddonsReporter(): ((List<String>) -> Unit)? =
+        if (!subtitlePreloadEnabled) null else { pending ->
+            _uiState.value = _uiState.value.copy(pendingSubtitleAddons = pending)
+        }
+
     /**
      * "Preload Subtitles" mode: download the preferred-language addon subtitles to local cache
      * files (same UTF-8/gunzipped [localizeSubtitle] files the match scan serves) so PlayerScreen
@@ -4236,6 +4258,8 @@ class PlayerViewModel @Inject constructor(
         // A REJECT verdict requires at least this many buffered (authored-timing) reference
         // intervals — realtime-only references systematically under-score synced subs (§2 skew).
         private const val MATCH_MIN_BUFFERED_FOR_REJECT = 4
+        // Preload mode: max wait for the addon subtitle lists before slow addons are dropped.
+        private const val SUBTITLE_FETCH_SOFT_DEADLINE_MS = 10_000L
         private const val MATCH_TRACK_SWITCH_SETTLE_MS = 1_500L // let the reference-track switch reach the renderer
         private const val MATCH_BUFFERED_REF_INTERVALS = 12  // max upcoming cues to read from the buffer per poll
         private const val MATCH_EMBEDDED_WAIT_MS = 8_000L    // grace period for async embedded tracks
diff --git a/docs/subtitle-auto-match.md b/docs/subtitle-auto-match.md
index 3c9637f2d..1435456ac 100644
--- a/docs/subtitle-auto-match.md
+++ b/docs/subtitle-auto-match.md
@@ -170,9 +170,9 @@ side-loaded at startup by **Preload Subtitles** mode (see §3b), in which case s
 
 ## 3b. Preload Subtitles mode (July 2026)
 
-Opt-in setting **"Preload Subtitles"** (`subtitle_preload_enabled`, global, cloud-synced, row 39
-in Settings → Subtitles, default **off**). Modeled on NuvioTV's `AddonSubtitleStartupMode` but
-scoped to the preferred language and downloading files ourselves.
+Setting **"Preload Subtitles"** (`subtitle_preload_enabled`, global, cloud-synced, row 39
+in Settings → Subtitles, default **ON** since July 2026). Modeled on NuvioTV's
+`AddonSubtitleStartupMode` but scoped to the preferred language and downloading files ourselves.
 
 Flow:
 1. `PlayerViewModel.preloadSubtitles()` runs after every addon-subtitle merge (all 3 fetch sites
@@ -182,9 +182,13 @@ Flow:
    `PlayerUiState.preloadedSubtitles` + `subtitlePreloadComplete` (always set, even on empty —
    the gate must never hang; also pre-set when no preferred language).
 2. PlayerScreen's prepare effect **gates** the initial `setMediaSource` on
-   `subtitlePreloadComplete` (timeout 20s), attaches all `file://` configs, then **re-anchors
+   `subtitlePreloadComplete` (cap 14s), attaches all `file://` configs, then **re-anchors
    `streamSelectedTime` and clears `startupRecoverAttempted`** — otherwise a slow subtitle addon
-   would eat the startup watchdog budget and trigger source failover.
+   would eat the startup watchdog budget and trigger source failover. The primary time bound is
+   upstream: in preload mode the addon-list fetch gets a **10s soft deadline**
+   (`fetchSubtitlesForSelectedStream(softDeadlineMs)`) — finished addons are harvested, slow ones
+   are cancelled and dropped for this playback, and the pending addon names stream to the loading
+   screen ("Loading subtitles… (addon)") so slow addons identify themselves to the user.
 3. Sidecar configs only merge through a `DefaultMediaSourceFactory`; the dedicated
    `preloadMediaSourceFactory` streams video **uncached** (debrid I/O rule) while supporting
    `file://` for the subs. HLS keeps working via the M3U8 mime hint (loses only chunkless prep);