Skip to content

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

feat: upgrade Media3 to 1.11.0

David Nashash45ba7735d69e
diff --git a/app/build.gradle.kts b/app/build.gradle.kts
index 963991ed..70ccbfc5 100644
--- a/app/build.gradle.kts
+++ b/app/build.gradle.kts
@@ -479,7 +479,7 @@ dependencies {
implementation(libs.media3.exoplayer.rtsp)
implementation(libs.media3.datasource.okhttp)
implementation(libs.media3.ui)
- implementation(files("../player/libs/media3-decoder-ffmpeg-1.9.2.aar"))
+ implementation(files("../player/libs/media3-decoder-ffmpeg-1.11.0.aar"))
// Room
implementation(libs.room.runtime)
diff --git a/docs/FFMPEG-LGPL-NOTICE.md b/docs/FFMPEG-LGPL-NOTICE.md
index 0645186d..f15b9e12 100644
--- a/docs/FFMPEG-LGPL-NOTICE.md
+++ b/docs/FFMPEG-LGPL-NOTICE.md
@@ -5,7 +5,7 @@ StreamVault distributes a bundled Media3 FFmpeg audio decoder artifact built for
Distribution rules for this repo:
- Do not enable GPL or nonfree FFmpeg components in the bundled artifact.
-- Keep the build provenance recorded in `player/libs/media3-decoder-ffmpeg-1.9.2.properties`.
+- Keep the build provenance recorded in `player/libs/media3-decoder-ffmpeg-1.11.0.properties`.
- Preserve rebuild instructions so recipients can replace or relink the shipped decoder artifact if required by the applicable LGPL obligations.
Operationally, this repo treats the FFmpeg AAR as a versioned bundled dependency rather than rebuilding it in CI.
diff --git a/docs/FFMPEG.md b/docs/FFMPEG.md
index 42603867..9d65b173 100644
--- a/docs/FFMPEG.md
+++ b/docs/FFMPEG.md
@@ -5,7 +5,7 @@ StreamVault bundles the Media3 FFmpeg audio decoder artifact for unsupported IPT
Current product scope:
- Audio fallback only
-- Media3 version: `1.9.2`
+- Media3 version: `1.11.0`
- Supported ABIs: `arm64-v8a`, `armeabi-v7a`
- Enabled decoders: `ac3`, `eac3`, `dca`, `mp2`, `mp3`, `truehd`
- License target: LGPL-compatible build only
@@ -17,7 +17,7 @@ Important product notes:
Refresh procedure:
-1. Rebuild the AndroidX FFmpeg decoder against Media3 `1.9.2`.
-2. Replace `player/libs/media3-decoder-ffmpeg-1.9.2.aar`.
-3. Update `player/libs/media3-decoder-ffmpeg-1.9.2.properties` if provenance changes.
+1. Rebuild the AndroidX FFmpeg decoder against Media3 `1.11.0`.
+2. Replace `player/libs/media3-decoder-ffmpeg-1.11.0.aar`.
+3. Update `player/libs/media3-decoder-ffmpeg-1.11.0.properties` if provenance changes.
4. Run `:player:verifyLocalFfmpegArtifact` and the player/app test builds.
diff --git a/docs/superpowers/plans/2026-09-11-preferred-text-language.md b/docs/superpowers/plans/2026-09-11-preferred-text-language.md
new file mode 100644
index 00000000..65095b3c
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-11-preferred-text-language.md
@@ -0,0 +1,178 @@
+# Preferred Subtitle-Language Auto-Selection Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task with verification checkpoints.
+
+**Goal:** Use Media3 1.11's stable text-language selection parameters as the automatic fallback for a saved VOD subtitle-language preference while preserving StreamVault's existing per-title track ID/label overrides and disabled-subtitle behavior.
+
+**Architecture:** Keep `VodTrackPreferences` and `VodTrackPreferenceResolver` as the app-owned persistence and exact-track layer. Add a small pure policy that translates the saved subtitle preference into Media3 text parameters (`preferredTextLanguage`, `selectTextByDefault`, and text enabled/disabled), then apply that policy when the player initializes and when VOD preferences are applied. No new UI or persistence schema is needed because develop already provides the subtitle preference picker and storage.
+
+**Tech Stack:** Kotlin, Media3 1.11 `TrackSelectionParameters.Builder`, JUnit/Truth, existing Android player module.
+
+**Spec:** `docs/upgrade.txt`, section “Media3 1.10.x findings” → “Existing app functions worth evaluating against 1.10 APIs” (preferred subtitle-language selection).
+
+## Global Constraints
+
+- Preserve explicit disabled-subtitle choices.
+- Preserve exact saved track ID/label matching and language-family fallback.
+- Do not enable subtitles for live playback when no VOD preference is supplied.
+- Do not add a new dependency or expose Media3 types through `:feature:playback`.
+- Keep external subtitle loading and the existing subtitle picker behavior unchanged.
+
+---
+
+### Task 1: Define the Media3 text-selection policy
+
+**Files:**
+- Create: `player/src/main/java/com/streamvault/player/tracks/PreferredTextTrackPolicy.kt`
+- Test: `player/src/test/java/com/streamvault/player/tracks/PreferredTextTrackPolicyTest.kt`
+
+**Interfaces:**
+- Consumes: nullable `VodTrackPreferences`.
+- Produces: an internal immutable policy containing `preferredLanguageTag: String?`, `selectTextByDefault: Boolean`, and `textDisabled: Boolean`.
+
+- [x] **Step 1: Write the failing tests**
+
+Cover these exact cases:
+
+```kotlin
+@Test
+fun `no VOD preference keeps text disabled`() {
+ assertThat(resolvePreferredTextTrackPolicy(null)).isEqualTo(
+ PreferredTextTrackPolicy(preferredLanguageTag = null, selectTextByDefault = false, textDisabled = true)
+ )
+}
+
+@Test
+fun `saved subtitle language enables Media3 automatic text selection`() {
+ val preferences = VodTrackPreferences(
+ subtitle = VodTrackPreference(language = "en-US", label = "English")
+ )
+
+ assertThat(resolvePreferredTextTrackPolicy(preferences)).isEqualTo(
+ PreferredTextTrackPolicy(preferredLanguageTag = "en-US", selectTextByDefault = true, textDisabled = false)
+ )
+}
+
+@Test
+fun `explicitly disabled subtitles stay disabled`() {
+ val preferences = VodTrackPreferences(
+ subtitle = VodTrackPreference(language = "en", disabled = true)
+ )
+
+ assertThat(resolvePreferredTextTrackPolicy(preferences)).isEqualTo(
+ PreferredTextTrackPolicy(preferredLanguageTag = null, selectTextByDefault = false, textDisabled = true)
+ )
+}
+
+@Test
+fun `label-only preference waits for the app-owned exact-track override`() {
+ val preferences = VodTrackPreferences(
+ subtitle = VodTrackPreference(label = "Commentary")
+ )
+
+ assertThat(resolvePreferredTextTrackPolicy(preferences)).isEqualTo(
+ PreferredTextTrackPolicy(preferredLanguageTag = null, selectTextByDefault = false, textDisabled = true)
+ )
+}
+```
+
+- [x] **Step 2: Run the policy test and verify it fails**
+
+Run:
+
+```text
+.\gradlew.bat :player:testDebugUnitTest --tests com.streamvault.player.tracks.PreferredTextTrackPolicyTest --no-daemon
+```
+
+Expected: compilation failure because `PreferredTextTrackPolicy` and `resolvePreferredTextTrackPolicy` do not exist yet.
+
+- [x] **Step 3: Implement the minimal policy**
+
+Normalize blank language values to `null`. Return disabled text unless the subtitle preference exists, is not disabled, and contains a nonblank language. Do not infer a language from the label; the existing resolver owns that exact-match behavior.
+
+- [x] **Step 4: Run the policy test and verify it passes**
+
+Run the same Gradle command and expect all four tests to pass.
+
+### Task 2: Apply the policy without changing custom precedence
+
+**Files:**
+- Modify: `player/src/main/java/com/streamvault/player/tracks/PlayerTrackController.kt`
+- Test: `player/src/test/java/com/streamvault/player/tracks/PlayerTrackControllerSelectionTest.kt`
+
+**Interfaces:**
+- Consumes: `resolvePreferredTextTrackPolicy(vodTrackPreferences)` from Task 1.
+- Produces: Media3 parameters with preferred text language only as fallback; `TrackSelectionOverride` remains authoritative when a saved track resolves.
+
+- [x] **Step 1: Write the failing controller-policy assertions**
+
+Add pure assertions around the policy-to-parameter decisions (without constructing a real player): a language preference must enable automatic text selection, a disabled preference must disable text, and a missing preference must remain disabled. Keep exact track resolver tests unchanged.
+
+- [x] **Step 2: Run the focused controller tests and verify the new assertions fail**
+
+Run:
+
+```text
+.\gradlew.bat :player:testDebugUnitTest --tests com.streamvault.player.tracks.PlayerTrackControllerSelectionTest --no-daemon
+```
+
+Expected: the new assertions fail before the controller applies the Media3 policy.
+
+- [x] **Step 3: Apply Media3 parameters**
+
+In `applyInitialParameters`, after clearing text overrides, apply:
+
+```kotlin
+val textPolicy = resolvePreferredTextTrackPolicy(vodTrackPreferences)
+setPreferredTextLanguage(textPolicy.preferredLanguageTag)
+setSelectTextByDefault(textPolicy.selectTextByDefault)
+setTrackTypeDisabled(C.TRACK_TYPE_TEXT, textPolicy.textDisabled)
+```
+
+In `applyVodTrackPreferences`, apply the same preferred-language/default flags before the existing subtitle branch. Preserve the existing branch that resolves ID/language/label and installs an override; preserve its behavior of disabling text when an explicitly saved language/track cannot be resolved. This keeps the Media3 preference from selecting an arbitrary language when the app-owned preference has no match.
+
+- [x] **Step 4: Run focused tests and verify they pass**
+
+Run the policy and controller tests together:
+
+```text
+.\gradlew.bat :player:testDebugUnitTest --tests com.streamvault.player.tracks.PreferredTextTrackPolicyTest --tests com.streamvault.player.tracks.PlayerTrackControllerSelectionTest --no-daemon
+```
+
+### Task 3: Update the audit and run integration verification
+
+**Files:**
+- Modify: `docs/upgrade.txt`
+
+- [x] **Step 1: Mark the preferred subtitle-language item complete**
+
+Change the 1.10 “Preferred subtitle-language selection” item from `ADD` to `DONE`, explain that Media3 text parameters are now the automatic language fallback, and retain the custom persisted ID/label resolver for precedence and provider compatibility. Remove it from the remaining backlog.
+
+- [x] **Step 2: Refresh the code graph**
+
+Run:
+
+```text
+graphify update .
+```
+
+- [x] **Step 3: Run the combined verification**
+
+Run:
+
+```text
+.\gradlew.bat :player:testDebugUnitTest :feature:playback:testDebugUnitTest :app:assembleDebug --no-daemon
+```
+
+Expected: build success, zero failures/errors in player and playback tests, and the existing feature-playback boundary check remains successful.
+
+- [x] **Step 4: Check the final diff**
+
+Run:
+
+```text
+git diff --check
+git diff --name-only --diff-filter=U
+```
+
+Expected: no whitespace errors and no unmerged paths.
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index 624fb117..131c9605 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -16,7 +16,7 @@ profileinstaller = "1.4.1"
startup-runtime = "1.1.1"
errorprone-annotations = "2.36.0"
tracing = "1.2.0"
-media3 = "1.9.2"
+media3 = "1.11.0"
room = "2.8.4"
hilt = "2.56.2"
hilt-navigation-compose = "1.3.0"
diff --git a/player/build.gradle.kts b/player/build.gradle.kts
index 30721cdb..cf82c465 100644
--- a/player/build.gradle.kts
+++ b/player/build.gradle.kts
@@ -35,8 +35,8 @@ abstract class VerifyLocalFfmpegArtifactTask : DefaultTask() {
manifestFile.inputStream().use(::load)
}
- check(manifest.getProperty("media3Version") == "1.9.2") {
- "FFmpeg artifact must use Media3 version 1.9.2"
+ check(manifest.getProperty("media3Version") == "1.11.0") {
+ "FFmpeg artifact must use Media3 version 1.11.0"
}
val aarEntries = ZipFile(aarFile).use { zipFile ->
@@ -174,8 +174,8 @@ val verifyLocalFfmpegArtifact = tasks.register<VerifyLocalFfmpegArtifactTask>("v
group = "verification"
description = "Verifies the bundled Media3 FFmpeg artifact, metadata, and supported ABIs."
- ffmpegAarFile.set(layout.projectDirectory.file("libs/media3-decoder-ffmpeg-1.9.2.aar"))
- ffmpegManifestFile.set(layout.projectDirectory.file("libs/media3-decoder-ffmpeg-1.9.2.properties"))
+ ffmpegAarFile.set(layout.projectDirectory.file("libs/media3-decoder-ffmpeg-1.11.0.aar"))
+ ffmpegManifestFile.set(layout.projectDirectory.file("libs/media3-decoder-ffmpeg-1.11.0.properties"))
}
tasks.named("preBuild").configure {
diff --git a/player/libs/README.md b/player/libs/README.md
index 68590e7e..018358a5 100644
--- a/player/libs/README.md
+++ b/player/libs/README.md
@@ -4,14 +4,18 @@ This directory holds the bundled Media3 FFmpeg decoder artifact used by StreamVa
Bundled artifact:
-- `media3-decoder-ffmpeg-1.9.2.aar`
+- `media3-decoder-ffmpeg-1.11.0.aar`
Build provenance for the checked-in artifact:
-- Upstream source: `androidx/media` `release` branch
-- Upstream commit used here: `5fb3064497`
-- Media3 version match: `1.9.2`
+- Upstream source: `androidx/media` tag `1.11.0`
+- Upstream commit used here: `2bc207851df311340767e913931ca7b28cab1794`
+- Media3 version match: `1.11.0`
- FFmpeg recommendation from upstream README: `release/6.0`
+- FFmpeg commit used here: `ba69be84a1ceabfb39127831ad8da0fd7cb471f3`
+- Android NDK used for FFmpeg: `26.1.10909125` (upstream-tested r26b toolchain)
+- Android NDK used to link the AAR JNI wrapper: `28.2.13676358` (Media3 1.11.0 build default)
+- AAR SHA-256: `2D617618E39C58DF6FDB2B8B7DC493029CD7BFADF2325B0DA2A8D0476615F31A`
- Supported ABIs: `arm64-v8a`, `armeabi-v7a`
- Enabled decoders: `ac3`, `eac3`, `dca`, `mp2`, `mp3`, `truehd`
- License target: LGPL-compatible build only; do not enable GPL/nonfree codecs
diff --git a/player/libs/media3-decoder-ffmpeg-1.11.0.aar b/player/libs/media3-decoder-ffmpeg-1.11.0.aar
new file mode 100644
index 00000000..509b688e
Binary files /dev/null and b/player/libs/media3-decoder-ffmpeg-1.11.0.aar differ
diff --git a/player/libs/media3-decoder-ffmpeg-1.11.0.properties b/player/libs/media3-decoder-ffmpeg-1.11.0.properties
new file mode 100644
index 00000000..248d5761
--- /dev/null
+++ b/player/libs/media3-decoder-ffmpeg-1.11.0.properties
@@ -0,0 +1,11 @@
+media3Version=1.11.0
+androidxCommit=2bc207851df311340767e913931ca7b28cab1794
+androidxBranch=tag/1.11.0
+ffmpegBranch=release/6.0
+ffmpegCommit=ba69be84a1ceabfb39127831ad8da0fd7cb471f3
+enabledDecoders=ac3,eac3,dca,mp2,mp3,truehd
+supportedAbis=arm64-v8a,armeabi-v7a
+licenseMode=LGPL-compatible
+ffmpegNdkVersion=26.1.10909125
+aarNdkVersion=28.2.13676358
+sha256=2D617618E39C58DF6FDB2B8B7DC493029CD7BFADF2325B0DA2A8D0476615F31A
diff --git a/player/libs/media3-decoder-ffmpeg-1.9.2.aar b/player/libs/media3-decoder-ffmpeg-1.9.2.aar
deleted file mode 100644
index f0486fa5..00000000
Binary files a/player/libs/media3-decoder-ffmpeg-1.9.2.aar and /dev/null differ
diff --git a/player/libs/media3-decoder-ffmpeg-1.9.2.properties b/player/libs/media3-decoder-ffmpeg-1.9.2.properties
deleted file mode 100644
index c1c8e258..00000000
--- a/player/libs/media3-decoder-ffmpeg-1.9.2.properties
+++ /dev/null
@@ -1,7 +0,0 @@
-media3Version=1.9.2
-androidxCommit=5fb3064497
-androidxBranch=release
-ffmpegBranch=release/6.0
-enabledDecoders=ac3,eac3,dca,mp2,mp3,truehd
-supportedAbis=arm64-v8a,armeabi-v7a
-licenseMode=LGPL-compatible
diff --git a/player/src/main/java/com/streamvault/player/ExternalSubtitlePlayback.kt b/player/src/main/java/com/streamvault/player/ExternalSubtitlePlayback.kt
index 438539a7..c3283cad 100644
--- a/player/src/main/java/com/streamvault/player/ExternalSubtitlePlayback.kt
+++ b/player/src/main/java/com/streamvault/player/ExternalSubtitlePlayback.kt
@@ -1,7 +1,20 @@
package com.streamvault.player
+import android.net.Uri
import androidx.media3.common.C
+import androidx.media3.common.Format
+import androidx.media3.common.MediaItem
+import androidx.media3.common.MimeTypes
import androidx.media3.common.TrackSelectionParameters
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DataSpec
+import androidx.media3.extractor.ExtractorsFactory
+import androidx.media3.extractor.text.DefaultSubtitleParserFactory
+import androidx.media3.extractor.text.SubtitleExtractor
+import androidx.media3.exoplayer.source.MediaSource
+import androidx.media3.exoplayer.source.ProgressiveMediaSource
+import java.io.IOException
internal data class ExternalSubtitlePlaybackTransition(
val resumePositionMs: Long,
@@ -21,3 +34,73 @@ internal fun TrackSelectionParameters.withExternalSubtitleEnabled(): TrackSelect
.clearOverridesOfType(C.TRACK_TYPE_TEXT)
.setTrackTypeDisabled(C.TRACK_TYPE_TEXT, false)
.build()
+
+internal fun buildExternalSubtitleConfiguration(
+ subtitleUri: Uri,
+ language: String
+): MediaItem.SubtitleConfiguration = MediaItem.SubtitleConfiguration.Builder(subtitleUri)
+ .setMimeType(MimeTypes.APPLICATION_SUBRIP)
+ .setLanguage(language)
+ .setSelectionFlags(C.SELECTION_FLAG_DEFAULT)
+ .build()
+
+@UnstableApi
+internal fun buildExternalSubtitleMediaSource(
+ dataSourceFactory: DataSource.Factory,
+ configuration: MediaItem.SubtitleConfiguration
+): MediaSource {
+ val format = Format.Builder()
+ .setSampleMimeType(configuration.mimeType)
+ .setLanguage(configuration.language)
+ .setSelectionFlags(configuration.selectionFlags)
+ .setRoleFlags(configuration.roleFlags)
+ .setLabel(configuration.label)
+ .setId(configuration.id)
+ .build()
+ val subtitleParserFactory = DefaultSubtitleParserFactory()
+ require(subtitleParserFactory.supportsFormat(format)) {
+ "Unsupported external subtitle format: ${configuration.mimeType}"
+ }
+ val extractorsFactory = ExtractorsFactory {
+ arrayOf(SubtitleExtractor(subtitleParserFactory.create(format), format))
+ }
+ return ProgressiveMediaSource.Factory(
+ optionalExternalSubtitleDataSourceFactory(dataSourceFactory),
+ extractorsFactory
+ )
+ .createMediaSource(MediaItem.fromUri(configuration.uri))
+}
+
+@UnstableApi
+internal fun optionalExternalSubtitleDataSourceFactory(
+ delegateFactory: DataSource.Factory
+): DataSource.Factory = DataSource.Factory {
+ OptionalExternalSubtitleDataSource(delegateFactory.createDataSource())
+}
+
+@UnstableApi
+private class OptionalExternalSubtitleDataSource(
+ private val delegate: DataSource
+) : DataSource by delegate {
+ private var reachedOptionalEnd = false
+
+ override fun open(dataSpec: DataSpec): Long {
+ reachedOptionalEnd = false
+ return try {
+ delegate.open(dataSpec)
+ } catch (_: IOException) {
+ reachedOptionalEnd = true
+ 0L
+ }
+ }
+
+ override fun read(buffer: ByteArray, offset: Int, length: Int): Int {
+ if (reachedOptionalEnd) return C.RESULT_END_OF_INPUT
+ return try {
+ delegate.read(buffer, offset, length)
+ } catch (_: IOException) {
+ reachedOptionalEnd = true
+ C.RESULT_END_OF_INPUT
+ }
+ }
+}
diff --git a/player/src/main/java/com/streamvault/player/playback/CodecPreference.kt b/player/src/main/java/com/streamvault/player/playback/CodecPreference.kt
index 5b7b4929..649b615c 100644
--- a/player/src/main/java/com/streamvault/player/playback/CodecPreference.kt
+++ b/player/src/main/java/com/streamvault/player/playback/CodecPreference.kt
@@ -1,6 +1,8 @@
package com.streamvault.player.playback
+import androidx.media3.common.Format
import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.DecoderReuseEvaluation
import androidx.media3.exoplayer.mediacodec.MediaCodecInfo
import androidx.media3.exoplayer.mediacodec.MediaCodecSelector
import com.streamvault.domain.model.DecoderMode
@@ -19,6 +21,18 @@ internal fun shouldUseManagedCodecSelector(
decoderPolicy: ActiveDecoderPolicy
): Boolean = requestedMode != DecoderMode.AUTO && decoderPolicy != ActiveDecoderPolicy.AUTO
+internal fun buildDecoderReuseWorkaroundEvaluation(
+ decoderName: String,
+ oldFormat: Format,
+ newFormat: Format
+): DecoderReuseEvaluation = DecoderReuseEvaluation(
+ decoderName,
+ oldFormat,
+ newFormat,
+ DecoderReuseEvaluation.REUSE_RESULT_NO,
+ DecoderReuseEvaluation.DISCARD_REASON_MAX_INPUT_SIZE_EXCEEDED
+)
+
internal data class PlaybackRendererPlan(
val useAudioVideoSyncSink: Boolean,
val useVideoRendererWorkaround: Boolean,
diff --git a/player/src/main/java/com/streamvault/player/playback/InitialBitratePolicy.kt b/player/src/main/java/com/streamvault/player/playback/InitialBitratePolicy.kt
new file mode 100644
index 00000000..f3580bc2
--- /dev/null
+++ b/player/src/main/java/com/streamvault/player/playback/InitialBitratePolicy.kt
@@ -0,0 +1,49 @@
+package com.streamvault.player.playback
+
+import androidx.media3.common.C
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.upstream.DefaultBandwidthMeter
+
+/**
+ * Chooses a conservative estimate for the first adaptive-track selection.
+ *
+ * Media3 normally has a network-type estimate, but a player recreation would otherwise lose the
+ * estimate observed by this app's previous player. Reusing the latest provider estimate at 75%
+ * gives the next selection a useful head start without immediately selecting the top rendition.
+ */
+@UnstableApi
+class InitialBitratePolicy(
+ private val recentEstimateProvider: () -> Long = { 0L }
+) : DefaultBandwidthMeter.InitialBitrateSupplier {
+
+ override fun getInitialBitrateEstimate(networkType: Int): Long = estimate(
+ networkType = networkType,
+ recentEstimateBps = recentEstimateProvider()
+ )
+
+ companion object {
+ private const val RECENT_ESTIMATE_NUMERATOR = 3L
+ private const val RECENT_ESTIMATE_DENOMINATOR = 4L
+ private const val MIN_STARTUP_ESTIMATE_BPS = 250_000L
+ private const val MAX_STARTUP_ESTIMATE_BPS = 8_000_000L
+
+ fun estimate(networkType: Int, recentEstimateBps: Long): Long {
+ val recentEstimate = recentEstimateBps.takeIf { it > 0L }
+ ?: return defaultEstimateFor(networkType)
+
+ return (recentEstimate * RECENT_ESTIMATE_NUMERATOR / RECENT_ESTIMATE_DENOMINATOR)
+ .coerceIn(MIN_STARTUP_ESTIMATE_BPS, MAX_STARTUP_ESTIMATE_BPS)
+ }
+
+ private fun defaultEstimateFor(networkType: Int): Long = when (networkType) {
+ C.NETWORK_TYPE_WIFI,
+ C.NETWORK_TYPE_ETHERNET -> DefaultBandwidthMeter.DEFAULT_INITIAL_BITRATE_ESTIMATES_WIFI.first()
+ C.NETWORK_TYPE_2G -> DefaultBandwidthMeter.DEFAULT_INITIAL_BITRATE_ESTIMATES_2G.first()
+ C.NETWORK_TYPE_3G -> DefaultBandwidthMeter.DEFAULT_INITIAL_BITRATE_ESTIMATES_3G.first()
+ C.NETWORK_TYPE_4G -> DefaultBandwidthMeter.DEFAULT_INITIAL_BITRATE_ESTIMATES_4G.first()
+ C.NETWORK_TYPE_5G_NSA -> DefaultBandwidthMeter.DEFAULT_INITIAL_BITRATE_ESTIMATES_5G_NSA.first()
+ C.NETWORK_TYPE_5G_SA -> DefaultBandwidthMeter.DEFAULT_INITIAL_BITRATE_ESTIMATES_5G_SA.first()
+ else -> DefaultBandwidthMeter.DEFAULT_INITIAL_BITRATE_ESTIMATE
+ }
+ }
+}
diff --git a/player/src/main/java/com/streamvault/player/playback/LiveAudioTapAudioSink.kt b/player/src/main/java/com/streamvault/player/playback/LiveAudioTapAudioSink.kt
index 206133fa..b2d5450e 100644
--- a/player/src/main/java/com/streamvault/player/playback/LiveAudioTapAudioSink.kt
+++ b/player/src/main/java/com/streamvault/player/playback/LiveAudioTapAudioSink.kt
@@ -25,11 +25,12 @@ internal class LiveAudioTapAudioSink(
private var channelCount: Int = Format.NO_VALUE
private var encoding: Int = C.ENCODING_INVALID
- override fun configure(inputFormat: Format, specifiedBufferSize: Int, outputChannels: IntArray?) {
+ override fun configure(audioSinkConfig: AudioSink.AudioSinkConfig) {
+ val inputFormat = audioSinkConfig.format
sampleRate = inputFormat.sampleRate
channelCount = inputFormat.channelCount
encoding = inputFormat.pcmEncoding
- delegate.configure(inputFormat, specifiedBufferSize, outputChannels)
+ delegate.configure(audioSinkConfig)
}
override fun handleBuffer(
diff --git a/player/src/main/java/com/streamvault/player/playback/PlayerDataSourceFactoryProvider.kt b/player/src/main/java/com/streamvault/player/playback/PlayerDataSourceFactoryProvider.kt
index b470bd74..f5909590 100644
--- a/player/src/main/java/com/streamvault/player/playback/PlayerDataSourceFactoryProvider.kt
+++ b/player/src/main/java/com/streamvault/player/playback/PlayerDataSourceFactoryProvider.kt
@@ -27,7 +27,9 @@ class PlayerDataSourceFactoryProvider(
private val context: Context,
private val baseClient: OkHttpClient,
/** Receives byte counts for foreground (non-preload) playback; used for measured bitrate stats. */
- private val transferListener: TransferListener? = null
+ private val transferListener: TransferListener? = null,
+ /** Receives the same foreground transfers for Media3's adaptive bandwidth estimate. */
+ private val additionalTransferListener: TransferListener? = null
) {
private companion object {
private const val TAG = "PlayerDataSource"
@@ -111,8 +113,8 @@ class PlayerDataSourceFactoryProvider(
}
}
val defaultFactory = DefaultDataSource.Factory(context, upstreamFactory)
- if (!preload && transferListener != null) {
- defaultFactory.setTransferListener(transferListener)
+ if (!preload) {
+ playbackTransferListener()?.let(defaultFactory::setTransferListener)
}
val factory = if (shouldWrapDataSourceReadStats(resolvedStreamType)) {
PlayerDataSourceReadStatsFactory(
@@ -126,6 +128,12 @@ class PlayerDataSourceFactoryProvider(
return profile to factory
}
+ private fun playbackTransferListener(): TransferListener? = when {
+ transferListener == null -> additionalTransferListener
+ additionalTransferListener == null -> transferListener
+ else -> CompositeTransferListener(transferListener, additionalTransferListener)
+ }
+
internal fun clientCacheSizeForTests(): Int = clientsByKey.size()
private fun logRequestShape(
@@ -166,6 +174,43 @@ class PlayerDataSourceFactoryProvider(
}
}
+private class CompositeTransferListener(
+ private vararg val listeners: TransferListener
+) : TransferListener {
+ override fun onTransferInitializing(
+ source: DataSource,
+ dataSpec: androidx.media3.datasource.DataSpec,
+ isNetwork: Boolean
+ ) {
+ listeners.forEach { it.onTransferInitializing(source, dataSpec, isNetwork) }
+ }
+
+ override fun onTransferStart(
+ source: DataSource,
+ dataSpec: androidx.media3.datasource.DataSpec,
+ isNetwork: Boolean
+ ) {
+ listeners.forEach { it.onTransferStart(source, dataSpec, isNetwork) }
+ }
+
+ override fun onBytesTransferred(
+ source: DataSource,
+ dataSpec: androidx.media3.datasource.DataSpec,
+ isNetwork: Boolean,
+ bytesTransferred: Int
+ ) {
+ listeners.forEach { it.onBytesTransferred(source, dataSpec, isNetwork, bytesTransferred) }
+ }
+
+ override fun onTransferEnd(
+ source: DataSource,
+ dataSpec: androidx.media3.datasource.DataSpec,
+ isNetwork: Boolean
+ ) {
+ listeners.forEach { it.onTransferEnd(source, dataSpec, isNetwork) }
+ }
+}
+
internal fun effectivePlaybackRequestProperties(
headers: Map<String, String>,
userAgent: String?
diff --git a/player/src/main/java/com/streamvault/player/playback/PlayerMediaSourceFactory.kt b/player/src/main/java/com/streamvault/player/playback/PlayerMediaSourceFactory.kt
index f514eb92..7956635d 100644
--- a/player/src/main/java/com/streamvault/player/playback/PlayerMediaSourceFactory.kt
+++ b/player/src/main/java/com/streamvault/player/playback/PlayerMediaSourceFactory.kt
@@ -39,6 +39,7 @@ private val TS_SUBTITLE_FORMATS: List<Format> = listOf(
internal fun liveMpegTsExtractorsFactory(): DefaultExtractorsFactory =
DefaultExtractorsFactory()
+ .setDisableArtworkMetadata(true)
// Xtream live ".ts" URLs are raw transport streams, not HLS segments. The HLS
// mode path is more permissive about segment continuity, but it also enables
// HLS-specific extractor behavior that does not match direct long-lived TS input.
@@ -96,19 +97,16 @@ class PlayerMediaSourceFactory(
.setLoadErrorHandlingPolicy(retryPolicy)
.createMediaSource(mediaItem)
- resolvedStreamType == ResolvedStreamType.PROGRESSIVE -> ProgressiveMediaSource.Factory(dataSourceFactory)
+ resolvedStreamType == ResolvedStreamType.PROGRESSIVE -> ProgressiveMediaSource.Factory(
+ dataSourceFactory,
+ playbackExtractorsFactory()
+ )
.setLoadErrorHandlingPolicy(retryPolicy)
.createMediaSource(mediaItem)
else -> DefaultMediaSourceFactory(
dataSourceFactory,
- DefaultExtractorsFactory()
- .setTsExtractorFlags(
- DefaultTsPayloadReaderFactory.FLAG_DETECT_ACCESS_UNITS
- or DefaultTsPayloadReaderFactory.FLAG_ALLOW_NON_IDR_KEYFRAMES
- or DefaultTsPayloadReaderFactory.FLAG_IGNORE_SPLICE_INFO_STREAM
- )
- .setTsSubtitleFormats(TS_SUBTITLE_FORMATS)
+ playbackExtractorsFactory()
)
.setLoadErrorHandlingPolicy(retryPolicy)
.createMediaSource(mediaItem)
@@ -161,3 +159,13 @@ class PlayerMediaSourceFactory(
private const val TAG = "PlayerMediaSourceFactory"
}
}
+
+private fun playbackExtractorsFactory(): DefaultExtractorsFactory =
+ DefaultExtractorsFactory()
+ .setDisableArtworkMetadata(true)
+ .setTsExtractorFlags(
+ DefaultTsPayloadReaderFactory.FLAG_DETECT_ACCESS_UNITS
+ or DefaultTsPayloadReaderFactory.FLAG_ALLOW_NON_IDR_KEYFRAMES
+ or DefaultTsPayloadReaderFactory.FLAG_IGNORE_SPLICE_INFO_STREAM
+ )
+ .setTsSubtitleFormats(TS_SUBTITLE_FORMATS)
diff --git a/player/src/main/java/com/streamvault/player/tracks/PlayerTrackController.kt b/player/src/main/java/com/streamvault/player/tracks/PlayerTrackController.kt
index c5a0d324..33639bbd 100644
--- a/player/src/main/java/com/streamvault/player/tracks/PlayerTrackController.kt
+++ b/player/src/main/java/com/streamvault/player/tracks/PlayerTrackController.kt
@@ -50,10 +50,10 @@ class PlayerTrackController(
.clearOverridesOfType(C.TRACK_TYPE_TEXT)
.clearOverridesOfType(C.TRACK_TYPE_VIDEO)
.setTrackTypeDisabled(C.TRACK_TYPE_AUDIO, false)
- .setTrackTypeDisabled(C.TRACK_TYPE_TEXT, true)
.setTrackTypeDisabled(C.TRACK_TYPE_VIDEO, false)
.setPreferredAudioLanguage(preferredAudioLanguageTag)
- .setViewportSizeToPhysicalDisplaySize(context, true)
+ .applyPreferredTextTrackPolicy(resolvePreferredTextTrackPolicy(vodTrackPreferences))
+ .setViewportSizeToPhysicalDisplaySize(true)
.apply {
resolvedMaxVideoHeightForCurrentNetwork(constrainResolutionForMultiView)?.let { maxHeight ->
setMaxVideoSize(Int.MAX_VALUE, maxHeight)
@@ -69,7 +69,9 @@ class PlayerTrackController(
fun applyVodTrackPreferences(player: ExoPlayer) {
val preferences = vodTrackPreferences ?: return
- val builder = player.trackSelectionParameters.buildUpon()
+ val builder = player.trackSelectionParameters
+ .buildUpon()
+ .applyPreferredTextTrackPolicy(resolvePreferredTextTrackPolicy(preferences))
preferences.audio?.let { preference ->
val selected = resolvePreferredPlayerTrack(preference, _availableAudioTracks.value)
diff --git a/player/src/main/java/com/streamvault/player/tracks/PreferredTextTrackPolicy.kt b/player/src/main/java/com/streamvault/player/tracks/PreferredTextTrackPolicy.kt
new file mode 100644
index 00000000..2894c2be
--- /dev/null
+++ b/player/src/main/java/com/streamvault/player/tracks/PreferredTextTrackPolicy.kt
@@ -0,0 +1,36 @@
+package com.streamvault.player.tracks
+
+import androidx.media3.common.C
+import androidx.media3.common.TrackSelectionParameters
+import com.streamvault.domain.settings.VodTrackPreferences
+
+internal data class PreferredTextTrackPolicy(
+ val preferredLanguageTag: String?,
+ val selectTextByDefault: Boolean,
+ val textDisabled: Boolean
+)
+
+internal fun resolvePreferredTextTrackPolicy(
+ preferences: VodTrackPreferences?
+): PreferredTextTrackPolicy {
+ val subtitlePreference = preferences?.subtitle
+ ?.takeUnless { it.disabled }
+ val languageTag = subtitlePreference?.language
+ ?.trim()
+ ?.replace('_', '-')
+ ?.takeIf(String::isNotBlank)
+
+ return PreferredTextTrackPolicy(
+ preferredLanguageTag = languageTag,
+ selectTextByDefault = languageTag != null,
+ textDisabled = languageTag == null
+ )
+}
+
+internal fun TrackSelectionParameters.Builder.applyPreferredTextTrackPolicy(
+ policy: PreferredTextTrackPolicy
+): TrackSelectionParameters.Builder = apply {
+ setPreferredTextLanguage(policy.preferredLanguageTag)
+ setSelectTextByDefault(policy.selectTextByDefault)
+ setTrackTypeDisabled(C.TRACK_TYPE_TEXT, policy.textDisabled)
+}
diff --git a/player/src/test/java/com/streamvault/player/ExternalSubtitlePlaybackTest.kt b/player/src/test/java/com/streamvault/player/ExternalSubtitlePlaybackTest.kt
index 538c2fd1..54879a4d 100644
--- a/player/src/test/java/com/streamvault/player/ExternalSubtitlePlaybackTest.kt
+++ b/player/src/test/java/com/streamvault/player/ExternalSubtitlePlaybackTest.kt
@@ -1,10 +1,21 @@
package com.streamvault.player
+import android.net.Uri
import androidx.media3.common.C
+import androidx.media3.common.MimeTypes
import androidx.media3.common.TrackSelectionParameters
+import androidx.media3.datasource.ByteArrayDataSource
+import androidx.media3.datasource.DataSource
+import androidx.media3.datasource.DataSpec
+import androidx.media3.datasource.TransferListener
+import androidx.media3.exoplayer.source.ProgressiveMediaSource
import com.google.common.truth.Truth.assertThat
+import java.io.IOException
import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+@RunWith(RobolectricTestRunner::class)
class ExternalSubtitlePlaybackTest {
@Test
@@ -29,4 +40,73 @@ class ExternalSubtitlePlaybackTest {
assertThat(subtitleEnabledParameters.disabledTrackTypes).doesNotContain(C.TRACK_TYPE_TEXT)
}
+
+ @Test
+ fun `external subtitle configuration preserves language and uses subrip`() {
+ val configuration = buildExternalSubtitleConfiguration(
+ subtitleUri = Uri.parse("https://example.test/subtitles/episode.srt"),
+ language = "he"
+ )
+
+ assertThat(configuration.uri.toString()).isEqualTo("https://example.test/subtitles/episode.srt")
+ assertThat(configuration.mimeType).isEqualTo(MimeTypes.APPLICATION_SUBRIP)
+ assertThat(configuration.language).isEqualTo("he")
+ assertThat(configuration.selectionFlags).isEqualTo(C.SELECTION_FLAG_DEFAULT)
+ }
+
+ @Test
+ fun `external subtitles use extraction based progressive media source`() {
+ val configuration = buildExternalSubtitleConfiguration(
+ subtitleUri = Uri.parse("https://example.test/subtitles/episode.srt"),
+ language = "en"
+ )
+ val dataSourceFactory = DataSource.Factory { ByteArrayDataSource(byteArrayOf()) }
+
+ val source = buildExternalSubtitleMediaSource(dataSourceFactory, configuration)
+
+ assertThat(source).isInstanceOf(ProgressiveMediaSource::class.java)
+ }
+
+ @Test
+ fun `external subtitle data source treats open failure as empty optional content`() {
+ var closed = false
+ val failingFactory = DataSource.Factory {
+ object : DataSource {
+ override fun addTransferListener(transferListener: TransferListener) = Unit
+ override fun open(dataSpec: DataSpec): Long = throw IOException("missing subtitle")
+ override fun read(buffer: ByteArray, offset: Int, length: Int): Int =
+ error("read must not reach failed delegate")
+ override fun getUri(): Uri? = null
+ override fun close() {
+ closed = true
+ }
+ }
+ }
+ val source = optionalExternalSubtitleDataSourceFactory(failingFactory).createDataSource()
+ val dataSpec = DataSpec(Uri.parse("https://example.test/missing.srt"))
+
+ assertThat(source.open(dataSpec)).isEqualTo(0L)
+ assertThat(source.read(ByteArray(8), 0, 8)).isEqualTo(C.RESULT_END_OF_INPUT)
+ source.close()
+
+ assertThat(closed).isTrue()
+ }
+
+ @Test
+ fun `external subtitle data source treats read failure as optional end of input`() {
+ val failingFactory = DataSource.Factory {
+ object : DataSource {
+ override fun addTransferListener(transferListener: TransferListener) = Unit
+ override fun open(dataSpec: DataSpec): Long = C.LENGTH_UNSET.toLong()
+ override fun read(buffer: ByteArray, offset: Int, length: Int): Int =
+ throw IOException("subtitle connection interrupted")
+ override fun getUri(): Uri? = null
+ override fun close() = Unit
+ }
+ }
+ val source = optionalExternalSubtitleDataSourceFactory(failingFactory).createDataSource()
+ source.open(DataSpec(Uri.parse("https://example.test/interrupted.srt")))
+
+ assertThat(source.read(ByteArray(8), 0, 8)).isEqualTo(C.RESULT_END_OF_INPUT)
+ }
}
diff --git a/player/src/test/java/com/streamvault/player/playback/InitialBitratePolicyTest.kt b/player/src/test/java/com/streamvault/player/playback/InitialBitratePolicyTest.kt
new file mode 100644
index 00000000..ce98be1a
--- /dev/null
+++ b/player/src/test/java/com/streamvault/player/playback/InitialBitratePolicyTest.kt
@@ -0,0 +1,34 @@
+package com.streamvault.player.playback
+
+import androidx.media3.common.C
+import com.google.common.truth.Truth.assertThat
+import org.junit.Test
+
+class InitialBitratePolicyTest {
+
+ @Test
+ fun `network fallback follows the connection class`() {
+ assertThat(InitialBitratePolicy.estimate(C.NETWORK_TYPE_WIFI, recentEstimateBps = 0L))
+ .isEqualTo(4_300_000L)
+ assertThat(InitialBitratePolicy.estimate(C.NETWORK_TYPE_4G, recentEstimateBps = 0L))
+ .isEqualTo(2_500_000L)
+ assertThat(InitialBitratePolicy.estimate(C.NETWORK_TYPE_2G, recentEstimateBps = 0L))
+ .isEqualTo(1_500_000L)
+ assertThat(InitialBitratePolicy.estimate(C.NETWORK_TYPE_UNKNOWN, recentEstimateBps = 0L))
+ .isEqualTo(1_000_000L)
+ }
+
+ @Test
+ fun `recent bandwidth is discounted before being used for startup`() {
+ assertThat(InitialBitratePolicy.estimate(C.NETWORK_TYPE_WIFI, recentEstimateBps = 4_000_000L))
+ .isEqualTo(3_000_000L)
+ }
+
+ @Test
+ fun `recent bandwidth is bounded to avoid an aggressive first selection`() {
+ assertThat(InitialBitratePolicy.estimate(C.NETWORK_TYPE_WIFI, recentEstimateBps = 100_000L))
+ .isEqualTo(250_000L)
+ assertThat(InitialBitratePolicy.estimate(C.NETWORK_TYPE_WIFI, recentEstimateBps = 20_000_000L))
+ .isEqualTo(8_000_000L)
+ }
+}
diff --git a/player/src/test/java/com/streamvault/player/playback/LiveAudioTapAudioSinkTest.kt b/player/src/test/java/com/streamvault/player/playback/LiveAudioTapAudioSinkTest.kt
new file mode 100644
index 00000000..aa49f77b
--- /dev/null
+++ b/player/src/test/java/com/streamvault/player/playback/LiveAudioTapAudioSinkTest.kt
@@ -0,0 +1,69 @@
+package com.streamvault.player.playback
+
+import androidx.media3.common.C
+import androidx.media3.common.Format
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.audio.AudioSink
+import com.google.common.truth.Truth.assertThat
+import com.streamvault.player.LiveAudioPcmBuffer
+import com.streamvault.player.LiveAudioTap
+import java.lang.reflect.Proxy
+import java.nio.ByteBuffer
+import org.junit.Test
+
+@UnstableApi
+class LiveAudioTapAudioSinkTest {
+
+ @Test
+ fun `new audio sink configuration reaches delegate and configures pcm tap metadata`() {
+ var delegatedConfig: AudioSink.AudioSinkConfig? = null
+ val tappedBuffers = mutableListOf<LiveAudioPcmBuffer>()
+ val delegate = Proxy.newProxyInstance(
+ AudioSink::class.java.classLoader,
+ arrayOf(AudioSink::class.java)
+ ) { _, method, arguments ->
+ when (method.name) {
+ "configure" -> {
+ if (arguments?.size == 1) {
+ delegatedConfig = arguments.single() as AudioSink.AudioSinkConfig
+ }
+ Unit
+ }
+ "handleBuffer" -> {
+ val buffer = arguments?.get(0) as ByteBuffer
+ buffer.position(buffer.limit())
+ true
+ }
+ "toString" -> "FakeAudioSink"
+ else -> defaultValue(method.returnType)
+ }
+ } as AudioSink
+ val sink = LiveAudioTapAudioSink(delegate) { LiveAudioTap(tappedBuffers::add) }
+ val format = Format.Builder()
+ .setSampleMimeType("audio/raw")
+ .setSampleRate(48_000)
+ .setChannelCount(2)
+ .setPcmEncoding(C.ENCODING_PCM_16BIT)
+ .build()
+ val config = AudioSink.AudioSinkConfig.Builder(format).build()
+
+ sink.configure(config)
+ sink.handleBuffer(ByteBuffer.wrap(byteArrayOf(1, 2, 3, 4)), 250_000L, 1)
+
+ assertThat(delegatedConfig).isSameInstanceAs(config)
+ assertThat(tappedBuffers).hasSize(1)
+ assertThat(tappedBuffers.single().sampleRate).isEqualTo(48_000)
+ assertThat(tappedBuffers.single().channelCount).isEqualTo(2)
+ assertThat(tappedBuffers.single().data).isEqualTo(byteArrayOf(1, 2, 3, 4))
+ }
+
+ private fun defaultValue(type: Class<*>): Any? = when (type) {
+ java.lang.Boolean.TYPE -> false
+ java.lang.Integer.TYPE -> 0
+ java.lang.Long.TYPE -> 0L
+ java.lang.Float.TYPE -> 0f
+ java.lang.Double.TYPE -> 0.0
+ java.lang.Void.TYPE -> Unit
+ else -> null
+ }
+}
diff --git a/player/src/test/java/com/streamvault/player/playback/PlaybackCodecSelectorTest.kt b/player/src/test/java/com/streamvault/player/playback/PlaybackCodecSelectorTest.kt
index d9b1b4cb..3d433075 100644
--- a/player/src/test/java/com/streamvault/player/playback/PlaybackCodecSelectorTest.kt
+++ b/player/src/test/java/com/streamvault/player/playback/PlaybackCodecSelectorTest.kt
@@ -1,11 +1,16 @@
package com.streamvault.player.playback
+import androidx.media3.common.Format
import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.DecoderReuseEvaluation
import com.google.common.truth.Truth.assertThat
import com.streamvault.domain.model.DecoderMode
import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
@UnstableApi
+@RunWith(RobolectricTestRunner::class)
class PlaybackCodecSelectorTest {
@Test
@@ -117,6 +122,23 @@ class PlaybackCodecSelectorTest {
)
}
+ @Test
+ fun `decoder reuse workaround forces codec recreation for format changes`() {
+ val oldFormat = Format.Builder().setSampleMimeType("video/avc").setWidth(1280).build()
+ val newFormat = Format.Builder().setSampleMimeType("video/avc").setWidth(1920).build()
+
+ val evaluation = buildDecoderReuseWorkaroundEvaluation(
+ decoderName = "OMX.vendor.avc.decoder",
+ oldFormat = oldFormat,
+ newFormat = newFormat
+ )
+
+ assertThat(evaluation.decoderName).isEqualTo("OMX.vendor.avc.decoder")
+ assertThat(evaluation.result).isEqualTo(DecoderReuseEvaluation.REUSE_RESULT_NO)
+ assertThat(evaluation.discardReasons)
+ .isEqualTo(DecoderReuseEvaluation.DISCARD_REASON_MAX_INPUT_SIZE_EXCEEDED)
+ }
+
@Test
fun `explicit hardware uses managed codec selector`() {
val plan = buildPlaybackRendererPlan(
diff --git a/player/src/test/java/com/streamvault/player/tracks/PreferredTextTrackPolicyTest.kt b/player/src/test/java/com/streamvault/player/tracks/PreferredTextTrackPolicyTest.kt
new file mode 100644
index 00000000..7d802717
--- /dev/null
+++ b/player/src/test/java/com/streamvault/player/tracks/PreferredTextTrackPolicyTest.kt
@@ -0,0 +1,104 @@
+package com.streamvault.player.tracks
+
+import androidx.media3.common.C
+import androidx.media3.common.TrackSelectionParameters
+import com.google.common.truth.Truth.assertThat
+import com.streamvault.domain.settings.VodTrackPreference
+import com.streamvault.domain.settings.VodTrackPreferences
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+
+@RunWith(RobolectricTestRunner::class)
+class PreferredTextTrackPolicyTest {
+
+ @Test
+ fun `no VOD preference keeps text disabled`() {
+ assertThat(resolvePreferredTextTrackPolicy(null)).isEqualTo(
+ PreferredTextTrackPolicy(
+ preferredLanguageTag = null,
+ selectTextByDefault = false,
+ textDisabled = true
+ )
+ )
+ }
+
+ @Test
+ fun `saved subtitle language enables Media3 automatic text selection`() {
+ val preferences = VodTrackPreferences(
+ subtitle = VodTrackPreference(language = "en-US", label = "English")
+ )
+
+ assertThat(resolvePreferredTextTrackPolicy(preferences)).isEqualTo(
+ PreferredTextTrackPolicy(
+ preferredLanguageTag = "en-US",
+ selectTextByDefault = true,
+ textDisabled = false
+ )
+ )
+ }
+
+ @Test
+ fun `explicitly disabled subtitles stay disabled`() {
+ val preferences = VodTrackPreferences(
+ subtitle = VodTrackPreference(language = "en", disabled = true)
+ )
+
+ assertThat(resolvePreferredTextTrackPolicy(preferences)).isEqualTo(
+ PreferredTextTrackPolicy(
+ preferredLanguageTag = null,
+ selectTextByDefault = false,
+ textDisabled = true
+ )
+ )
+ }
+
+ @Test
+ fun `label-only preference waits for the app-owned exact-track override`() {
+ val preferences = VodTrackPreferences(
+ subtitle = VodTrackPreference(label = "Commentary")
+ )
+
+ assertThat(resolvePreferredTextTrackPolicy(preferences)).isEqualTo(
+ PreferredTextTrackPolicy(
+ preferredLanguageTag = null,
+ selectTextByDefault = false,
+ textDisabled = true
+ )
+ )
+ }
+
+ @Test
+ fun `media3 parameters enable the preferred text language`() {
+ val parameters = TrackSelectionParameters.Builder()
+ .applyPreferredTextTrackPolicy(
+ PreferredTextTrackPolicy(
+ preferredLanguageTag = "en-US",
+ selectTextByDefault = true,
+ textDisabled = false
+ )
+ )
+ .build()
+
+ assertThat(parameters.preferredTextLanguages).containsExactly("en-us")
+ assertThat(parameters.selectTextByDefault).isTrue()
+ assertThat(parameters.disabledTrackTypes).doesNotContain(C.TRACK_TYPE_TEXT)
+ }
+
+ @Test
+ fun `media3 parameters disable text when no automatic language is available`() {
+ val parameters = TrackSelectionParameters.Builder()
+ .applyPreferredTextTrackPolicy(
+ PreferredTextTrackPolicy(
+ preferredLanguageTag = null,
+ selectTextByDefault = false,
+ textDisabled = true
+ )
+ )
+ .build()
+
+ assertThat(parameters.preferredTextLanguages).isEmpty()
+ assertThat(parameters.selectTextByDefault).isFalse()
+ assertThat(parameters.disabledTrackTypes).contains(C.TRACK_TYPE_TEXT)
+ }
+}