StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.
Kotlin iptv-player
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.ktindex 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.dataval 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.ktindex 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())+ }+@Testfun `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())+ }+@Testfun `getSeriesDetails uses provider series id for stalker details`() = runTest {val seriesEntity = SeriesEntity(diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.txtdeleted file mode 100644index 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).