Skip to content

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

feat: Implement self-heal for Xtream series with zero episodes, preserving local episode sets during re-hydration

David Nashashf3696d91ff81
diff --git a/data/src/main/java/com/streamvault/data/repository/SeriesRepositoryImpl.kt b/data/src/main/java/com/streamvault/data/repository/SeriesRepositoryImpl.kt
index 99ad7326..127f88f4 100644
--- a/data/src/main/java/com/streamvault/data/repository/SeriesRepositoryImpl.kt
+++ b/data/src/main/java/com/streamvault/data/repository/SeriesRepositoryImpl.kt
@@ -484,7 +484,10 @@ class SeriesRepositoryImpl @Inject constructor(
}
if (provider.type == ProviderType.XTREAM_CODES && seriesEntity.hasFreshXtreamDetails()) {
- return Result.success(attachSeriesPresentation(buildSeriesWithPersistedEpisodes(seriesEntity), knownPresentation))
+ val localSeries = buildSeriesWithPersistedEpisodes(seriesEntity)
+ if (localSeries.seasons.any { season -> season.episodes.isNotEmpty() }) {
+ return Result.success(attachSeriesPresentation(localSeries, knownPresentation))
+ }
}
if (provider.type == ProviderType.STALKER_PORTAL && seriesEntity.hasFreshStalkerDetails()) {
val localSeries = buildSeriesWithPersistedEpisodes(seriesEntity)
@@ -544,7 +547,8 @@ class SeriesRepositoryImpl @Inject constructor(
is Result.Success -> {
val remoteSeries = remoteResult.data
val hasRemoteEpisodes = remoteSeries.seasons.any { season -> season.episodes.isNotEmpty() }
- val hasPersistedEpisodes = episodeDao.getBySeriesSync(seriesEntity.id).isNotEmpty()
+ val persistedEpisodesBefore = episodeDao.getBySeriesSync(seriesEntity.id)
+ val hasPersistedEpisodes = persistedEpisodesBefore.isNotEmpty()
val updatedSeries = seriesEntity.copy(
name = remoteSeries.name.ifBlank { seriesEntity.name },
@@ -612,7 +616,10 @@ class SeriesRepositoryImpl @Inject constructor(
}
}
- if (episodesToPersist.isNotEmpty()) {
+ val adoptRemoteEpisodes = episodesToPersist.isNotEmpty() &&
+ (persistedEpisodesBefore.isEmpty() || episodesToPersist.size >= persistedEpisodesBefore.size)
+
+ if (adoptRemoteEpisodes) {
episodeDao.replaceAll(seriesEntity.id, providerId, episodesToPersist)
}
@@ -623,7 +630,7 @@ class SeriesRepositoryImpl @Inject constructor(
}
val remoteSeasonMetadataByNumber = remoteSeries.seasons.associateBy { it.seasonNumber }
- val mergedSeasons = if (remoteSeries.seasons.any { it.episodes.isNotEmpty() }) {
+ val mergedSeasons = if (adoptRemoteEpisodes) {
remoteSeries.seasons
.sortedBy { it.seasonNumber }
.map { remoteSeason ->
diff --git a/data/src/test/java/com/streamvault/data/repository/SeriesRepositoryImplTest.kt b/data/src/test/java/com/streamvault/data/repository/SeriesRepositoryImplTest.kt
index 9a01da0f..23ebdf82 100644
--- a/data/src/test/java/com/streamvault/data/repository/SeriesRepositoryImplTest.kt
+++ b/data/src/test/java/com/streamvault/data/repository/SeriesRepositoryImplTest.kt
@@ -230,7 +230,19 @@ class SeriesRepositoryImplTest {
status = ProviderStatus.ACTIVE
)
)
- whenever(episodeDao.getBySeriesSync(99L)).thenReturn(emptyList())
+ whenever(episodeDao.getBySeriesSync(99L)).thenReturn(
+ listOf(
+ EpisodeBrowseEntity(
+ id = 1L,
+ episodeId = 301L,
+ title = "Episode 1",
+ episodeNumber = 1,
+ seasonNumber = 1,
+ seriesId = 99L,
+ providerId = 7L
+ )
+ )
+ )
val result = createRepository().getSeriesDetails(7L, 99L)
@@ -239,6 +251,37 @@ class SeriesRepositoryImplTest {
verify(xtreamContentIndexDao, never()).markDetailHydrated(any(), any(), any(), any(), anyOrNull(), any())
}
+ @Test
+ fun `getSeriesDetails rehydrates fresh xtream series that lost its episodes`() = runTest {
+ val hydratedAt = System.currentTimeMillis()
+ val seriesEntity = SeriesEntity(
+ id = 99L,
+ seriesId = 301L,
+ name = "Cached Series",
+ providerId = 7L,
+ cacheState = "DETAIL_HYDRATED",
+ detailHydratedAt = hydratedAt
+ )
+ whenever(seriesDao.getById(99L)).thenReturn(seriesEntity)
+ stubProvider(
+ Provider(
+ id = 7L,
+ name = "Xtream",
+ type = ProviderType.XTREAM_CODES,
+ serverUrl = "http://example.com",
+ username = "user",
+ password = "pass",
+ status = ProviderStatus.ACTIVE
+ )
+ )
+ whenever(episodeDao.getBySeriesSync(99L)).thenReturn(emptyList())
+
+ createRepository().getSeriesDetails(7L, 99L)
+
+ verify(seriesCatalogSource).hydrateSeries(any(), any())
+ verify(xtreamContentIndexDao).markDetailHydrated(any(), any(), any(), any(), anyOrNull(), any())
+ }
+
@Test
fun `getSeriesDetails with duplicate handling uses narrow tmdb candidates instead of full provider scan`() = runTest {
val hydratedAt = System.currentTimeMillis()
@@ -886,6 +929,85 @@ class SeriesRepositoryImplTest {
assertThat(series.seasons.first().episodes.map { it.title }).containsExactly("Pilot")
}
+ @Test
+ fun `getSeriesDetails keeps persisted episodes when remote returns a partial set`() = runTest {
+ whenever(preferencesRepository.xtreamBase64TextCompatibility).thenReturn(flowOf(false))
+ val seriesEntity = SeriesEntity(
+ id = 15L,
+ seriesId = 301L,
+ name = "Stored Series",
+ providerId = 7L
+ )
+ whenever(seriesDao.getById(15L)).thenReturn(seriesEntity)
+ stubProvider(
+ Provider(
+ id = 7L,
+ name = "Xtream",
+ type = ProviderType.XTREAM_CODES,
+ serverUrl = "http://example.com",
+ username = "user",
+ password = "pass",
+ status = ProviderStatus.ACTIVE
+ )
+ )
+ whenever(episodeDao.getBySeriesSync(15L)).thenReturn(
+ listOf(
+ EpisodeBrowseEntity(
+ id = 1L,
+ episodeId = 7001L,
+ title = "Episode 1",
+ episodeNumber = 1,
+ seasonNumber = 1,
+ seriesId = 15L,
+ providerId = 7L
+ ),
+ EpisodeBrowseEntity(
+ id = 2L,
+ episodeId = 7002L,
+ title = "Episode 2",
+ episodeNumber = 2,
+ seasonNumber = 1,
+ seriesId = 15L,
+ providerId = 7L
+ )
+ )
+ )
+ whenever(seriesCatalogSource.hydrateSeries(any(), any())).thenReturn(
+ Result.success(
+ Series(
+ id = 15L,
+ name = "Stored Series",
+ providerId = 7L,
+ seriesId = 301L,
+ seasons = listOf(
+ Season(
+ seasonNumber = 1,
+ episodes = listOf(
+ Episode(
+ id = 0L,
+ episodeId = 7001L,
+ title = "Episode 1",
+ episodeNumber = 1,
+ seasonNumber = 1,
+ seriesId = 15L,
+ providerId = 7L
+ )
+ ),
+ episodeCount = 1
+ )
+ )
+ )
+ )
+ )
+
+ val result = createRepository().getSeriesDetails(7L, 15L)
+
+ assertThat(result).isInstanceOf(com.streamvault.domain.model.Result.Success::class.java)
+ val series = (result as com.streamvault.domain.model.Result.Success).data
+ assertThat(series.seasons.flatMap { it.episodes }.map { it.title }).containsExactly("Episode 1", "Episode 2")
+ verify(episodeDao, never()).replaceAll(any(), any(), any())
+ }
+
@Test
fun `getSeriesDetails uses provider series id for stalker details`() = runTest {
val seriesEntity = SeriesEntity(
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 040d256d..4f3f3f19 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -17,6 +17,8 @@ All notable product changes are recorded in this document.
- Added VOD category pinning for Movies and Series, with pin-first browsing, Android TV pin controls, and pinned category content shelves on the Home dashboard.
- Added measured frame-rate and stream-bitrate diagnostics for IPTV playback, including MPEG-TS streams that omit these values from their metadata.
- Added portal-backed Stalker VOD search with mixed movie/series results, persisted result IDs, paging, parental/hidden-category filtering, and a Browsing setting to disable it.
+- Added a Media3 `FrameExtractor` pilot for supported VOD seek thumbnails, while retaining `MediaMetadataRetriever` as a fallback for unsupported or failed sources.
+- Added bounded VOD and episode sliding-window preloading for current and adjacent series or catch-up items, with lifecycle cleanup, stale-session protection, and direct-playback fallback; ordinary live playback remains on its existing path.
### Fixed
@@ -32,6 +34,7 @@ All notable product changes are recorded in this document.
- Fixed Stalker VOD category layout drift by retargeting stale stored category types before synchronization instead of forcing an unnecessary catalog re-download.
- Fixed Stalker guide synchronization continuing through dead per-channel EPG endpoints after both bulk and first per-channel responses are confirmed empty.
- Fixed Stalker channel logos returned as bare or portal-relative paths by resolving them against the portal logo directory, including channels imported before the fix.
+- Fixed Xtream series showing an empty episode list after re-entering: a hydrated series whose local episodes went missing is now re-fetched, and re-hydration no longer replaces a larger cached episode set with a smaller, partially re-scraped provider response.
### Changed
@@ -43,6 +46,7 @@ All notable product changes are recorded in this document.
- Inherited compatibility improvements for HLS Content Steering, DASH/HLS metadata, AV1 and Dolby Vision, VVC, Matroska, and MP4 formats when supported by the device.
- Reduced unnecessary artwork metadata extraction during playback to lower memory use on TV devices.
- Improved Android TV navigation, focus handling, and Back-button behavior across Live TV, player controls, provider setup, and Settings.
+- Redesigned the VOD playback controls UI, including the control layout, actions, and navigation behavior.
- Improved playback quick-action readability by using shared theme-aware content colors across focused and unfocused controls, keeping contrast consistent across all playback buttons.
- Improved Live TV control reliability, including timeshift seeking and rewind interactions.
- Improved reliability when configuring providers, importing settings, and preserving playback preferences.
diff --git a/docs/superpowers/plans/2026-09-14-xtream-series-zero-episodes-self-heal.md b/docs/superpowers/plans/2026-09-14-xtream-series-zero-episodes-self-heal.md
new file mode 100644
index 00000000..84551801
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-14-xtream-series-zero-episodes-self-heal.md
@@ -0,0 +1,158 @@
+# Xtream Series Zero-Episode Self-Heal Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Prevent an Xtream series from showing an empty episode list after a user re-enters it. Two complementary guards make the detail path self-heal: (1) a freshly-hydrated Xtream series whose local episodes have vanished is re-fetched instead of returning an empty cache, and (2) re-hydration never replaces a larger local episode set with a smaller (partial) remote set.
+
+**Architecture:** Keep all changes inside `SeriesRepositoryImpl.getSeriesDetails`. Fix 1 mirrors the existing Stalker "impossible state" self-repair (`SeriesRepositoryImpl.kt:489-500`) for the Xtream branch. Fix 2 computes a single `adoptRemoteEpisodes` decision and uses it both to gate the destructive `episodeDao.replaceAll` call and to select which season set is shown, so the UI and the persisted rows stay consistent.
+
+**Tech Stack:** Kotlin, Kotlin Coroutines, Room, Mockito-Kotlin, Truth, Gradle.
+
+**Spec:** `docs/superpowers/specs/2026-09-14-xtream-series-zero-episodes-self-heal-design.md`
+
+## Global Constraints
+
+- Preserve the `SeriesRepository` interface and the Room schema.
+- No change to `EpisodeDao.replaceAll` or any DAO signature; the guards live in the repository layer.
+- A genuinely empty series (provider returns no episodes and none are persisted) must still show as empty and remain `SUMMARY_ONLY`; do not loop re-fetching it on every open.
+- The provider-empty case (e.g. series 10588) must be unchanged: single variant, no episodes server-side, stays `SUMMARY_ONLY`.
+- Healthy series (fresh + episodes present, or remote superset) keep their existing behavior exactly.
+- Foreign-key enforcement is OFF in this app (`onDelete = CASCADE` on `episodes` never fires); do not rely on cascade semantics.
+- Run `graphify update .` after production code files are modified.
+
+---
+
+## File Map
+
+| File | Responsibility |
+| --- | --- |
+| `data/src/main/java/com/streamvault/data/repository/SeriesRepositoryImpl.kt` | Add the Xtream fresh-but-empty guard and the non-destructive episode-adoption decision. |
+| `data/src/test/java/com/streamvault/data/repository/SeriesRepositoryImplTest.kt` | Add tests for the fresh-but-empty re-hydration path and the partial-set preservation path; adjust the existing fresh-cache test to carry episodes. |
+
+## Interfaces Produced for Later Tasks
+
+No new public interface is introduced. The only contract change is the internal decision variable `adoptRemoteEpisodes`, which is private to `getSeriesDetails`.
+
+---
+
+### Task 1: Self-heal a fresh Xtream series whose episodes vanished
+
+**Files:**
+
+- Modify: `data/src/main/java/com/streamvault/data/repository/SeriesRepositoryImpl.kt:486-488`
+- Modify: `data/src/test/java/com/streamvault/data/repository/SeriesRepositoryImplTest.kt`
+
+- [ ] **Step 1: Add a failing test for the fresh-but-empty re-hydration.**
+
+Add `getSeriesDetails rehydrates fresh xtream series that lost its episodes`: a `DETAIL_HYDRATED` series with a recent `detailHydratedAt` and an empty `episodeDao.getBySeriesSync`, then assert `seriesCatalogSource.hydrateSeries` and `xtreamContentIndexDao.markDetailHydrated` are invoked (i.e. the detail path fell through to re-hydration instead of returning the empty cache).
+
+- [ ] **Step 2: Guard the existing fresh-cache test so it still means "fresh with episodes".**
+
+In `getSeriesDetails uses fresh xtream hydrated cache without refetching`, change the empty `episodeDao.getBySeriesSync` stub to return a single `EpisodeBrowseEntity` so the test keeps asserting that a fresh series *with* episodes does not refetch.
+
+- [ ] **Step 3: Implement the Xtream fresh-but-empty guard.**
+
+Replace the unconditional early return in the Xtream branch with the Stalker-style check:
+
+~~~kotlin
+if (provider.type == ProviderType.XTREAM_CODES && seriesEntity.hasFreshXtreamDetails()) {
+ val localSeries = buildSeriesWithPersistedEpisodes(seriesEntity)
+ if (localSeries.seasons.any { season -> season.episodes.isNotEmpty() }) {
+ return Result.success(attachSeriesPresentation(localSeries, knownPresentation))
+ }
+}
+~~~
+
+- [ ] **Step 4: Run the focused repository tests.**
+
+~~~powershell
+.\gradlew.bat :data:testDebugUnitTest --tests "com.streamvault.data.repository.SeriesRepositoryImplTest"
+~~~
+
+Expected: the new test and the adjusted fresh-cache test pass.
+
+### Task 2: Never shrink the episode set during re-hydration
+
+**Files:**
+
+- Modify: `data/src/main/java/com/streamvault/data/repository/SeriesRepositoryImpl.kt:546-547,615-617,626`
+- Modify: `data/src/test/java/com/streamvault/data/repository/SeriesRepositoryImplTest.kt`
+
+- [ ] **Step 1: Add a failing test for partial remote sets.**
+
+Add `getSeriesDetails keeps persisted episodes when remote returns a partial set`: a non-fresh Xtream series (or `SUMMARY_ONLY`) with two persisted episodes whose `hydrateSeries` returns one episode, then assert the result still shows the persisted (larger) episode set and `episodeDao.replaceAll` is not called.
+
+- [ ] **Step 2: Capture the persisted episode list once.**
+
+Change the `hasPersistedEpisodes` lookup to retain the list so the count can be compared:
+
+~~~kotlin
+val persistedEpisodesBefore = episodeDao.getBySeriesSync(seriesEntity.id)
+val hasPersistedEpisodes = persistedEpisodesBefore.isNotEmpty()
+~~~
+
+- [ ] **Step 3: Gate `replaceAll` behind a superset decision.**
+
+Replace the existing `if (episodesToPersist.isNotEmpty())` guard:
+
+~~~kotlin
+val adoptRemoteEpisodes = episodesToPersist.isNotEmpty() &&
+ (persistedEpisodesBefore.isEmpty() || episodesToPersist.size >= persistedEpisodesBefore.size)
+if (adoptRemoteEpisodes) {
+ episodeDao.replaceAll(seriesEntity.id, providerId, episodesToPersist)
+}
+~~~
+
+- [ ] **Step 4: Use the same decision when merging seasons.**
+
+Change the first `mergedSeasons` branch condition from `remoteSeries.seasons.any { it.episodes.isNotEmpty() }` to `adoptRemoteEpisodes` so the displayed seasons match what was persisted.
+
+- [ ] **Step 5: Run the focused repository tests.**
+
+~~~powershell
+.\gradlew.bat :data:testDebugUnitTest --tests "com.streamvault.data.repository.SeriesRepositoryImplTest"
+~~~
+
+Expected: the partial-set test passes and the existing "remote only has season metadata" test (which relies on persisted episodes being kept) still passes.
+
+### Task 3: Full Regression and Graph Update
+
+**Files:**
+
+- Modify: none unless a test identifies a regression in `SeriesRepositoryImpl.kt`.
+
+- [ ] **Step 1: Run the data module unit tests.**
+
+~~~powershell
+.\gradlew.bat :data:testDebugUnitTest
+~~~
+
+Expected: PASS with no series sync or repository regressions.
+
+- [ ] **Step 2: Update graphify after the production change.**
+
+~~~powershell
+graphify update .
+~~~
+
+Expected: the graph updates successfully. If the CLI is unavailable, record the limitation and continue with the verified Gradle results.
+
+- [ ] **Step 3: Inspect the worktree.**
+
+~~~powershell
+git status --short
+git diff --check
+~~~
+
+Expected: only the two intended files are modified; no whitespace errors; pre-existing `docs/CHANGELOG.md`/`docs/upgrade.txt` changes remain unstaged and untouched.
+
+## Self-Review Checklist
+
+- [ ] Fix 1 mirrors the existing Stalker self-repair and only fires for a fresh Xtream series with zero persisted episodes.
+- [ ] Fix 2 never reduces the locally persisted episode count; a partial remote response keeps the larger local set.
+- [ ] Genuinely empty series still resolve to `SUMMARY_ONLY` and are not refetched in a loop.
+- [ ] Healthy series (fresh + episodes, or remote superset) are behaviorally unchanged.
+- [ ] No DAO signatures or Room schema changes.
+- [ ] Test commands use the repository's Gradle module name (`:data`) and the existing test class.
+- [ ] `graphify update .` is run after production files change.
+- [ ] `docs/CHANGELOG.md` and `docs/upgrade.txt` remain untouched and unstaged.
diff --git a/docs/superpowers/specs/2026-09-14-xtream-series-zero-episodes-self-heal-design.md b/docs/superpowers/specs/2026-09-14-xtream-series-zero-episodes-self-heal-design.md
new file mode 100644
index 00000000..cf9c3634
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-14-xtream-series-zero-episodes-self-heal-design.md
@@ -0,0 +1,44 @@
+# Xtream Series Zero-Episode Self-Heal — Design
+
+## Problem
+
+An Xtream provider can leave a series showing "Season N with 0 episodes" after a user re-enters it. Two distinct local states produce this symptom:
+
+1. **Fresh-but-empty**: the `series` row still reports `cache_state = DETAIL_HYDRATED` with a recent `detail_hydrated_at`, but the `episodes` rows are gone. `getSeriesDetails` trusts `hasFreshXtreamDetails()` and returns the empty persisted set without re-fetching.
+2. **Partial re-scrape**: re-hydration returns a smaller (or remapped) episode set than what is already persisted, and `episodeDao.replaceAll` blindly deletes the larger local set.
+
+Both cases were investigated against provider `line.dndnscloud.ru`. Foreign-key enforcement is OFF in this app (Room 2.8.4 does not call `setForeignKeyConstraintsEnabled`, and the app never does), so `onDelete = CASCADE` never fires; the loss is via `EpisodeDao.replaceAll` or the fresh-cache early return, not cascade.
+
+## Design
+
+All changes are contained in `SeriesRepositoryImpl.getSeriesDetails`.
+
+### Fix 1 — fresh-but-empty self-heal
+
+The Xtream branch currently returns unconditionally when the row is fresh. Mirror the existing Stalker "impossible state" guard: only return the cached seasons when they actually contain episodes; otherwise fall through to the normal re-hydration path.
+
+### Fix 2 — non-destructive episode adoption
+
+Compute one boolean used in two places:
+
+```
+adoptRemoteEpisodes = remoteEpisodes.nonEmpty && (persisted.isEmpty() || remoteEpisodes.size >= persisted.size)
+```
+
+- `true` → persist the remote set (`replaceAll`) and render the remote seasons.
+- `false` → keep the persisted set and render it; a partial/remapped response never shrinks the library.
+
+This preserves the existing "empty remote keeps persisted episodes" behavior (which is currently handled implicitly) and extends it to the "partial remote" case.
+
+## Non-goals
+
+- No sibling/variant redirect (opening a same-TMDB sibling that has episodes) — left for a follow-up if the fresh-but-empty guard does not cover the observed symptom.
+- No DAO or schema change.
+- No change to how a genuinely empty series is represented (`SUMMARY_ONLY`, season shells rendered from provider metadata).
+
+## Test coverage
+
+- Fresh Xtream series + zero persisted episodes → re-hydrates.
+- Fresh Xtream series + episodes present → no re-fetch (existing behavior preserved).
+- Non-fresh series + partial remote set → persisted (larger) set is kept, `replaceAll` not called.
+- Existing "remote returns only season metadata keeps persisted episodes" test must remain green.
diff --git a/docs/upgrade.txt b/docs/upgrade.txt
deleted file mode 100644
index 7f0d7857..00000000
--- a/docs/upgrade.txt
+++ /dev/null
@@ -1,96 +0,0 @@
-# Media3 1.9 -> 1.11 upgrade audit
-
-This audit covers the complete jump from the app's previous Media3 1.9.2
-dependencies through Media3 1.10.x and 1.11.0. Items are classified as:
-
-- DONE: implemented in this worktree.
-- AUTOMATIC: provided by the Media3 upgrade; no app code is required.
-- ADD: a worthwhile app capability or targeted improvement that is not yet implemented.
-- NOT NEEDED: technically available, but not a fit for StreamVault's current architecture.
-- WATCH: useful only if future telemetry or product requirements justify it.
-
-Primary source: https://developer.android.com/jetpack/androidx/releases/media3
-
-## Work already completed in this worktree
-
-These items are complete and should not remain in the pending migration list:
-
-- DONE - Upgraded all Maven Media3 dependencies from 1.9.2 to 1.11.0.
-- DONE - Replaced the bundled FFmpeg decoder AAR with the matching Media3 1.11.0 artifact, including checksum and ABI/decoder verification.
-- DONE - Replaced the legacy `SingleSampleMediaSource` external-subtitle path with `MediaItem.SubtitleConfiguration` plus extraction-based subtitle loading. Optional subtitle I/O failures remain non-fatal to video playback.
-- DONE - Migrated the custom PCM tap to `AudioSink.AudioSinkConfig`, preserving audio format, timeline/period context, and tap behavior.
-- DONE - Migrated the custom video renderer construction to `MediaCodecVideoRenderer.Builder`, preserving the decoder-reuse workaround.
-- DONE - Migrated `setViewportSizeToPhysicalDisplaySize` to the current API.
-- DONE - Enabled `DefaultExtractorsFactory.setDisableArtworkMetadata(true)` for playback extractors to reduce unnecessary cover-art memory use on TV devices.
-- DONE - Added regression/unit coverage for external subtitles, audio-sink configuration, decoder reuse, and the FFmpeg artifact.
-
-## Media3 1.10.x findings
-
-### Automatic benefits already received by upgrading to 1.11.0
-
-- AUTOMATIC - `ProgressiveMediaSource` timeline propagation fix. The app uses progressive sources for VOD and side-loaded subtitles, so the fix is inherited without an app change.
-- AUTOMATIC - Decoder-error recovery/prewarming fixes, AV1 Dolby Vision initialization fixes, codec-reuse improvements, RTSP packet parsing fixes, HLS fallback/`EXT-X-MAP` fixes, DASH seek/timeline fixes, and audio-output retry improvements.
-- AUTOMATIC - Dynamic video scheduling introduced in 1.10 and enabled by default at the ExoPlayer level in 1.11. No explicit opt-in is required for the current player.
-- AUTOMATIC - VobSub cue-duration handling and 1.11 TTML parser fixes. These improve subtitle timing/availability but are not a guaranteed fix for the reported subtitle-freeze issue.
-- AUTOMATIC - HLS redundant-location fallback, HLS `QUERYPARAM`/`X-PLAYOUT-LIMIT` handling, HLS ID3 metadata-track exposure, and DASH CEA caption grouping/location fallback.
-- AUTOMATIC - Dolby Vision Profile 10, VVC container parsing, larger MP4 `uuid` boxes, and other extractor/codec compatibility fixes where the device decoder supports the format.
-- AUTOMATIC - Media3 1.10's stable track-selection preferences and Media3 1.11's continued track-selection fixes are available to the existing `PlayerTrackController`.
-
-### Existing app functions worth evaluating against 1.10 APIs
-
-- DONE - Preferred subtitle-language selection. Media3 text-selection parameters now use the saved VOD subtitle language as the automatic fallback (`preferredTextLanguage` plus `selectTextByDefault`), while the app-owned persisted track ID/label resolver remains authoritative when it can match a track and explicit disabled choices remain disabled.
-- ADD - Media3 `FrameExtractor` pilot for VOD seek thumbnails. Media3 1.10 moved this API to the `media3-inspector-frame` module. The current `SeekThumbnailProvider` uses Android `MediaMetadataRetriever`, can block on remote URLs, and excludes HLS/DASH. Pilot implementation is now behind the existing provider interface: Media3 is first for supported non-live, non-DRM VOD, with the current provider retained as a fallback. Player/feature tests, the dependency boundary, app Hilt wiring, and a debug APK build pass. Emulator smoke playback remains healthy, but the controlled device/content latency matrix is still pending; do not remove the legacy implementation yet.
-- WATCH - `DefaultPreloadManager.Builder.setDataSourceFactory`. This is useful only if the app adopts Media3's preload manager; it allows the app's custom headers, timeouts, and proxy behavior to be reused by preloading.
-
-### 1.10 APIs that should not replace current code
-
-- NOT NEEDED - `Player.mute()`/`unmute()`. They became stable in 1.10, but the app's `PlayerAudioFocusController` preserves volume, coordinates focus/ducking, and exposes state; replacing it would lose behavior.
-- NOT NEEDED - Media3 Compose `Player`, `ProgressSlider`, and playback-speed composables. StreamVault has custom TV/DPAD controls, overlays, subtitle styling, surfaces, and a `PlayerEngine` boundary that intentionally hides Media3 from `:feature:playback`.
-- NOT NEEDED - `RemoteCastPlayer.Builder.setTrackSelector`. StreamVault uses the Google Cast SDK directly through `CastManager`, not Media3 `CastPlayer`.
-- NOT NEEDED - Transformer, IMA, IAMF, Lottie-effect, widget, download, and muxer additions. The app does not currently use those Media3 product areas.
-
-## Media3 1.11.0 findings
-
-### Automatic benefits already received
-
-- AUTOMATIC - ExoPlayer concurrency, codec operating-rate, codec-flush, audio-session, scrubbing, and dynamic-scheduling fixes.
-- AUTOMATIC - `DefaultLoadControl` low-memory protection, audio-renderer underrun grace period, fixed PCM buffer sizing, explicit decoder channel-mask handling, and MPEG-TS DTS-HD/DTS Express extraction fixes.
-- AUTOMATIC - TTML region/style cue fixes, improved MP4/Matroska chapter parsing, fragmented-MP4 `mfra` seeking, Matroska ALAC/color/chapter handling, and MPEG-TS last-frame handling.
-- AUTOMATIC - HLS Content Steering/Pathway Cloning support and HLS `SCORE` parsing into `Format.selectionPriority`. No app code is required for manifests that provide these features.
-- AUTOMATIC - Safer default `MediaSession` controller access and the 1.11 session-threading/deadlock fixes. The app creates a basic `MediaSession` without a custom callback, so there is no `onConnect` migration to perform.
-- AUTOMATIC - `Format.channelMask` and the corresponding audio-channel configuration logic. The custom audio sink now receives the richer `AudioSinkConfig`.
-
-### Worth adding as new capabilities or targeted improvements
-
-- DONE (P1) - VOD chapter navigation. Media3 `Chapter` metadata is normalized into the player boundary, exposed as chapter state, and surfaced in the new video-first VOD overlay with timeline markers, chapter sheet selection, and previous/next chapter actions. Live and catch-up overlays remain on their existing path; chapter actions are hidden while Cast is connected.
-- DONE - Adaptive startup bitrate. `DefaultBandwidthMeter.InitialBitrateSupplier` now uses Media3's network-class defaults when no history exists, or a discounted/capped estimate from the previous provider measurement when the player is recreated. The bandwidth meter is wired into the existing foreground data-source transfer listener and resets on network changes; user quality settings are unchanged.
-- ADD (P2) - VOD/episode sliding-window preloading — IMPLEMENTED PILOT. `DefaultPreloadManager` with `SimpleRankingDataComparator` now manages a maximum of three current/adjacent series-episode or catch-up candidates. Candidates use the app's preload-scoped data source path, preserve resolved provider metadata, skip live/DRM/expired/unsupported entries, and fall back to direct playback on a miss. The feature layer refreshes after `READY` and asynchronous episode/channel context resolution, fingerprints unchanged windows, guards stale sessions, and keeps the existing legacy single-item path for ordinary live zapping and recovery. Player/feature/app unit tests, the feature boundary check, and a debug APK build pass. The real-device/content latency, request-shape, lifecycle, and foreground-transfer-accounting matrix is still pending; do not remove the legacy path until that gate passes.
-- WATCH (P2) - Custom adaptive variant ordering. Media3 now exposes `Format.selectionPriority` and `AdaptiveTrackSelection.Factory.setTrackFormatComparator`. The default HLS `SCORE` mapping is already automatic; add a custom comparator only after telemetry shows provider scores or user quality preferences need different ordering.
-- WATCH (P3) - Explicit per-stream media progression. `ExoPlayer.Builder.enablePerStreamMediaProgression()` can reduce transitions between queued short items, but the app normally replaces one media source at a time rather than playing a Media3 playlist. Do not enable it globally yet.
-
-### 1.11 capabilities not suitable for the current app
-
-- NOT NEEDED - Media3 Compose `PlayerDefaults`, control slots, `MiniController`, `PlayerPool`, and Compose state holders. These would duplicate StreamVault's custom player UI and lifecycle rather than extend it.
-- NOT NEEDED - `media3-datasource-ktor`. The player depends on custom OkHttp headers, TLS policy, proxy behavior, timeouts, and transfer accounting; switching stacks provides no feature benefit.
-- NOT NEEDED - `CastParams`/SystemUI Output Switcher migration for now. It would require moving or bridging the existing Google Cast implementation to Media3 Cast and would create a large parallel playback path.
-- NOT NEEDED - HAGC/Eclipsa timed HDR metadata. It targets progressive media on API 37+ devices and has no current product requirement; the project currently compiles against API 36.
-- NOT NEEDED - Ogg/WAV muxers, track-reference muxing, Transformer, IMA, and other authoring APIs. StreamVault is a playback application.
-
-## Subtitle-freeze relevance
-
-The upgrade includes automatic subtitle-parser improvements from both 1.10 and 1.11, and the external subtitle path is DONE above. There is still no Media3 1.10/1.11 switch that guarantees recovery from a frozen embedded subtitle track. Embedded-subtitle behavior remains unverified on the affected device/content and should be instrumented separately if the report persists.
-
-## Remaining implementation backlog
-
-1. Design and test VOD-only sliding-window preloading before replacing the current single-source preload path.
-2. Keep custom variant ordering and Media3 Cast migration as telemetry-driven follow-ups, not automatic parts of the 1.11 upgrade.
-
-## Verification status for the completed migration
-
-- 414 player/playback unit tests passed (239 in `:player`, 175 in `:feature:playback`).
-- The adaptive startup bitrate policy unit tests pass, including network fallbacks, discounted history, and safety bounds.
-- Debug APK assembled successfully.
-- FFmpeg AAR checksum matched its manifest.
-- Targeted deprecated usages: zero.
-- Independent review: no critical or important issues after the subtitle-path fix.
-- DONE - Repository-wide `testDebugUnitTest` task passed successfully across all modules (270 actionable tasks, zero test failures).