OPTI-1528: handle CC prefix for CEA text tracks on Player API below 11th release

app/src/main/java/com/theoplayer/android/ui/demo/Streams.kt

@@ -41,7 +41,14 @@ val streams by lazy {
                 TypedSource.Builder("https://livesim.dashif.org/livesim/testpic_2s/Manifest.mpd")
                     .build()
             ).build()
-        )
+        ),
+        Stream(
+            title = "Test card (with CEA tracks)",
+            source = SourceDescription.Builder(
+                TypedSource.Builder("https://livesim2.dashif.org/vod/testpic_2s/cea608.mpd")
+                    .build()
+            ).build()
+        ),
     )
 }
 

gradle/libs.versions.toml

@@ -10,13 +10,14 @@ activity-compose = "1.10.1"
 appcompat = "1.7.1"
 compose-bom = "2025.08.01"
 junit4 = "4.13.2"
+mockk = "1.14.9"
 playServices-castFramework = "21.5.0"
 ui-test-junit4 = "1.9.0" # ...not in BOM for some reason?
 androidx-junit = "1.3.0"
 androidx-espresso = "3.7.0"
 androidx-mediarouter = "1.8.1"
 dokka = "2.0.0"
-theoplayer = { prefer="10.11.0", strictly = "[7.6.0, 11.0)" }
+theoplayer = { prefer="10.13.0", strictly = "[7.6.0, 11.0)" }
 
 [libraries]
 androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }
@@ -35,6 +36,7 @@ androidx-compose-ui-toolingPreview = { group = "androidx.compose.ui", name = "ui
 androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "androidx-junit" }
 androidx-espresso = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "androidx-espresso" }
 androidx-mediarouter = { group = "androidx.mediarouter", name = "mediarouter", version.ref = "androidx-mediarouter" }
+mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
 playServices-castFramework = { group = "com.google.android.gms", name = "play-services-cast-framework", version.ref = "playServices-castFramework" }
 gradle-plugin = { group = "com.android.tools.build", name = "gradle", version.ref = "gradle" }
 dokka-base = { group = "org.jetbrains.dokka", name = "dokka-base", version.ref = "dokka" }

ui/build.gradle.kts

@@ -78,7 +78,9 @@ dependencies {
     implementation(libs.androidx.compose.ui.toolingPreview)
     implementation(libs.androidx.compose.material3)
     implementation(libs.androidx.compose.material.iconsExtended)
+
     testImplementation(libs.junit4)
+    testImplementation(libs.mockk)
     androidTestImplementation(libs.androidx.junit)
     androidTestImplementation(libs.androidx.espresso)
     androidTestImplementation(libs.androidx.compose.ui.testJunit4)

ui/src/main/java/com/theoplayer/android/ui/AudioTrackList.kt

@@ -29,7 +29,7 @@ fun AudioTrackList(
         ) {
             val audioTrack = audioTracks[it]
             ListItem(
-                headlineContent = { Text(text = formatTrackLabel(audioTrack)) },
+                headlineContent = { Text(text = rememberTrackLabel(audioTrack)) },
                 leadingContent = {
                     RadioButton(
                         selected = (activeAudioTrack == audioTrack),

ui/src/main/java/com/theoplayer/android/ui/Helper.kt

@@ -1,9 +1,11 @@
 package com.theoplayer.android.ui
 
+import android.content.res.Resources
 import androidx.compose.runtime.Composable
-import androidx.compose.ui.res.stringResource
+import androidx.compose.runtime.remember
+import androidx.compose.ui.platform.LocalResources
 import com.theoplayer.android.api.player.track.Track
-import java.util.Locale
+import com.theoplayer.android.ui.util.constructLabel
 import kotlin.math.absoluteValue
 
 /**
@@ -63,19 +65,9 @@ fun formatTime(time: Double, guide: Double = 0.0, preferNegative: Boolean = fals
  * @param track the media track or text track
  */
 @Composable
-fun formatTrackLabel(track: Track): String {
-    val label = track.label
-    if (!label.isNullOrEmpty()) {
-        return label
-    }
-    val languageCode = track.language
-    if (!languageCode.isNullOrEmpty()) {
-        val locale = Locale.forLanguageTag(languageCode)
-        val languageName = locale.getDisplayName(locale)
-        if (languageName.isNotEmpty()) {
-            return languageName
-        }
-        return languageCode
-    }
-    return stringResource(R.string.theoplayer_ui_track_unknown)
-}
+fun rememberTrackLabel(
+    track: Track,
+    resources: Resources = LocalResources.current,
+): String = remember(key1 = track.id, key2 = track.uid) {
+    constructLabel(track) ?: resources.getString(R.string.theoplayer_ui_track_unknown)
+}

ui/src/main/java/com/theoplayer/android/ui/LanguageMenu.kt

@@ -86,7 +86,7 @@ fun MenuScope.LanguageMenuCompact() {
                 ) {
                     Text(
                         modifier = Modifier.weight(1f),
-                        text = player?.activeAudioTrack?.let { formatTrackLabel(it) }
+                        text = player?.activeAudioTrack?.let { rememberTrackLabel(it) }
                             ?: stringResource(
                                 R.string.theoplayer_ui_audio_none
                             ),
@@ -115,7 +115,7 @@ fun MenuScope.LanguageMenuCompact() {
                 ) {
                     Text(
                         modifier = Modifier.weight(1f),
-                        text = player?.activeSubtitleTrack?.let { formatTrackLabel(it) } ?: stringResource(
+                        text = player?.activeSubtitleTrack?.let { rememberTrackLabel(it) } ?: stringResource(
                             R.string.theoplayer_ui_subtitles_off
                         ),
                         textAlign = TextAlign.Center

ui/src/main/java/com/theoplayer/android/ui/SubtitleTrackList.kt

@@ -45,7 +45,7 @@ fun SubtitleTrackList(
         ) {
             val audioTrack = subtitleTracks[it]
             ListItem(
-                headlineContent = { Text(text = formatTrackLabel(audioTrack)) },
+                headlineContent = { Text(text = rememberTrackLabel(audioTrack)) },
                 leadingContent = {
                     RadioButton(
                         selected = (activeSubtitleTrack == audioTrack),

ui/src/main/java/com/theoplayer/android/ui/util/CeaUtil.kt

@@ -0,0 +1,45 @@
+package com.theoplayer.android.ui.util
+
+import androidx.annotation.CheckResult
+import androidx.annotation.IntRange
+
+private val CEA_FORMATTING_REGEX = "^CC(\\d+)$".toRegex()
+
+/**
+ * Checks whether a provided label is CEA-608 or CEA-708 formed.
+ */
+@CheckResult
+internal fun isLabelCeaFormatted(label: String?): Boolean {
+    if (label.isNullOrEmpty()) {
+        return false
+    }
+
+    val matchResult = CEA_FORMATTING_REGEX.find(label) ?: return false
+    val groupValues = matchResult.groupValues
+    // There is one group we want to match with the channel number.
+    if (groupValues.size != 2) {
+        return false
+    }
+
+    val rawChannelNumber = groupValues[1]
+    val channelNumber = rawChannelNumber.toIntOrNull()
+    return !rawChannelNumber.startsWith("0") && channelNumber in 1..63
+}
+
+/**
+ * Creates a text track label for CEA-608 and CEA-708 formats.
+ *
+ * @return an optional string composed of a [channelNumber] and a prepended
+ * "CC" suffix, or `null` if the channel number is invalid.
+ */
+@CheckResult
+internal fun getLabelForChannelNumber(
+    @IntRange(from = 0L, to = 63L) channelNumber: Int,
+): String? {
+    // CEA-608 only supports channel numbers in [1, 4],
+    // while CEA-708 support service numbers in [1, 63].
+    if (channelNumber !in 1..63) {
+        return null
+    }
+    return "CC${channelNumber}"
+}

ui/src/main/java/com/theoplayer/android/ui/util/Compat.kt

@@ -0,0 +1,32 @@
+package com.theoplayer.android.ui.util
+
+import androidx.annotation.DoNotInline
+import com.theoplayer.android.api.player.track.texttrack.TextTrack
+
+/**
+ * Returns [TextTrack.getCaptionChannel], if available.
+ */
+internal val TextTrack.captionChannelCompat: Int?
+    get() {
+        // TextTrack.getCaptionChannel was added in THEOplayer 10.13.0.
+        return if (THEOplayerGlobalExt.version >= version1013) {
+            TheoPlayer1013Impl.getTextTrackCaptionChannel(this)
+        } else null
+    }
+
+private val version1013 = Version(major = 10, minor = 13, patchAndPrerelease = "0")
+
+/**
+ * This class must be loaded **only** with THEOplayer 10.13.0 or higher.
+ *
+ * This uses the same pattern as AndroidX AppCompat,
+ * see e.g. [androidx.appcompat.app.AppCompatDelegate.Api33Impl]
+ * and the docs about [API-specific implementations](https://github.com/androidx/androidx/blob/androidx-main/docs/api_guidelines/compat.md#delegating-to-api-specific-implementations-delegating-to-api-specific-implementations)
+ * and [static shims](https://github.com/androidx/androidx/blob/androidx-main/docs/api_guidelines/platform_compat.md#static-shims-ex-viewcompat-static-shim).
+ */
+private class TheoPlayer1013Impl private constructor() {
+    companion object {
+        @DoNotInline
+        fun getTextTrackCaptionChannel(track: TextTrack): Int? = track.captionChannel
+    }
+}

ui/src/main/java/com/theoplayer/android/ui/util/TrackExts.kt

@@ -0,0 +1,88 @@
+package com.theoplayer.android.ui.util
+
+import androidx.annotation.CheckResult
+import com.theoplayer.android.api.player.track.Track
+import com.theoplayer.android.api.player.track.texttrack.TextTrack
+import com.theoplayer.android.api.player.track.texttrack.TextTrackType
+import java.util.Locale
+
+private const val LANGUAGE_UNDEFINED = "und"
+
+/**
+ * Returns a name for the [Track.language] in the
+ * [Locale.Category.DISPLAY] locale that is appropriate
+ * for display to the user.
+ * If such conversion is not possible, for instance
+ * when [Track.language] is `null`, blank, or `"und"`,
+ * returns `null`.
+ */
+@get:CheckResult
+internal val Track.localizedLanguageName: String?
+    get() {
+        val languageCode = this.language
+            ?.takeUnless { it.isBlank() || it == LANGUAGE_UNDEFINED }
+            ?: return null
+        val locale = Locale.forLanguageTag(languageCode)
+        val localisedLanguage: String? = locale.getDisplayName(locale)
+        return localisedLanguage?.takeUnless { it.isBlank() }
+    }
+
+/**
+ * Constructs a label for the given [Track] instance.
+ * The method works slightly different for different player version.
+ *
+ * On version 10 and below the logic checks the following and condition
+ * and the first not `null` entry from the list:
+ * 1. Track label if is not a language code
+ * or a CEA-prefixed string.
+ * 2. Track language display name
+ * 3. Track caption channel if a text CEA-608 track
+ * 4. Track label if was either a language code or a CEA-prefixed string
+ *
+ * If none of the above is satisfied, returns `null`.
+ *
+ * On version 11 and later the logic has slightly changed as
+ * the player no longer constructs the [Track.getLabel] internally:
+ * 1. Track label
+ * 2. Track language display name
+ * 3. Track caption channel
+ */
+internal fun constructLabel(
+    track: Track,
+): String? {
+    val label: String? = if (
+        (track is TextTrack) &&
+        THEOplayerGlobalExt.version.major < 11 &&
+        (isLabelCeaFormatted(track.label) || (track.label != null && track.language == track.label))
+    ) {
+        // If we are below 11th major release
+        // and the label is CEA-formatted we
+        // can safely assume it was the last resort
+        // option to produce a meaningful label, given
+        // we cannot localize the language code in the player.
+        null
+    } else {
+        // With 11 release, the player will no longer
+        // prefix text tracks with "CC" for CEA-608 and CEA-708,
+        // if [Track.label] is `null`.
+        track.label
+    }
+
+    if (!label.isNullOrBlank()) {
+        return label
+    }
+
+    track.localizedLanguageName?.let { return it }
+
+    if ((track is TextTrack) && track.type == TextTrackType.CEA608) {
+        track.captionChannelCompat
+            ?.let { getLabelForChannelNumber(it) }
+            ?.let { return it }
+
+        track.label
+            ?.takeUnless { it.isBlank() }
+            ?.let { return it }
+    }
+
+    return null
+}

ui/src/main/java/com/theoplayer/android/ui/util/VersionUtil.kt

@@ -0,0 +1,62 @@
+package com.theoplayer.android.ui.util
+
+import com.theoplayer.android.api.THEOplayerGlobal
+
+private const val VERSION_DELIMITER = '.'
+
+/**
+ * A [semver](https://semver.org/) version.
+ */
+internal data class Version(
+    /**
+     * The major version.
+     */
+    val major: Int,
+    /**
+     * The minor version.
+     */
+    val minor: Int,
+    /**
+     * The patch (and prerelease) version.
+     */
+    val patchAndPrerelease: String,
+) : Comparable<Version> {
+    override fun toString() = buildString {
+        append(major)
+        append(VERSION_DELIMITER)
+        append(minor)
+        append(VERSION_DELIMITER)
+        append(patchAndPrerelease)
+    }
+
+    override fun compareTo(other: Version): Int {
+        return compareBy<Version> { it.major }
+            .thenBy { it.minor }
+            .thenBy { it.patchAndPrerelease }
+            .compare(this, other)
+    }
+
+    companion object {
+        fun parse(version: String): Version {
+            try {
+                val versionParts = version.split(VERSION_DELIMITER, limit = 3)
+                require(versionParts.size == 3)
+                val (major, minor, patchAndPrerelease) = versionParts
+                return Version(
+                    major = major.toInt(),
+                    minor = minor.toInt(),
+                    patchAndPrerelease = patchAndPrerelease
+                )
+            } catch (e: IllegalArgumentException) {
+                throw IllegalArgumentException("Invalid version", e)
+            }
+        }
+    }
+}
+
+internal object THEOplayerGlobalExt {
+    /**
+     * Returns the version of THEOplayer, as a [Version].
+     */
+    val version: Version by lazy { Version.parse(THEOplayerGlobal.getVersion()) }
+}