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

CHANGELOG.md

@@ -9,6 +9,10 @@
 > - 🏠 Internal
 > - 💅 Polish
 
+## Unreleased
+
+* 🐛 The language menu now prefers to show CEA-608/708 closed caption tracks with their localized language name (if available) instead of their language code (e.g. "en") or channel number (e.g. "CC1"). ([#84](https://github.com/THEOplayer/android-ui/pull/84))
+
 ## v1.13.3 (2026-03-23)
 
 * 🐛 Changed the minimum supported THEOplayer version to 7.6.0. ([#85](https://github.com/THEOplayer/android-ui/pull/85))

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,15 @@ activity-compose = "1.13.0"
 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.+", strictly = "[7.6.0, 11.0)" }
+theoplayer-compile = { prefer = "10.+", strictly = "[10.13.0, 11.0)" }
 theoplayer-min = { strictly = "7.6.0" }
 core = "1.18.0"
 core-pip = "1.0.0-alpha02"
@@ -46,12 +48,14 @@ dokka-base = { group = "org.jetbrains.dokka", name = "dokka-base", version.ref =
 dokka-plugin = { group = "org.jetbrains.dokka", name = "android-documentation-plugin", version.ref = "dokka" }
 kotlin-gradle-plugin = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
 junit4 = { group = "junit", name = "junit", version.ref = "junit4" }
+mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
 theoplayer = { group = "com.theoplayer.theoplayer-sdk-android", name = "core", version.ref = "theoplayer" }
 theoplayer-ads-ima = { group = "com.theoplayer.theoplayer-sdk-android", name = "integration-ads-ima", version.ref = "theoplayer" }
 theoplayer-cast = { group = "com.theoplayer.theoplayer-sdk-android", name = "integration-cast", version.ref = "theoplayer" }
 theoplayer-min = { group = "com.theoplayer.theoplayer-sdk-android", name = "core", version.ref = "theoplayer-min" }
 theoplayer-min-ads-ima = { group = "com.theoplayer.theoplayer-sdk-android", name = "integration-ads-ima", version.ref = "theoplayer-min" }
 theoplayer-min-cast = { group = "com.theoplayer.theoplayer-sdk-android", name = "integration-cast", version.ref = "theoplayer-min" }
+theoplayer-compile = { group = "com.theoplayer.theoplayer-sdk-android", name = "core", version.ref = "theoplayer-compile" }
 
 [plugins]
 android-application = { id = "com.android.application", version.ref = "gradle" }

ui/build.gradle.kts

@@ -78,14 +78,18 @@ 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)
     debugImplementation(libs.androidx.compose.ui.tooling)
     debugImplementation(libs.androidx.compose.ui.testManifest)
 
+    compileOnly(libs.theoplayer.compile)
     api(libs.theoplayer)
+    testImplementation(libs.theoplayer)
 
     dokkaPlugin(libs.dokka.plugin)
 }

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

@@ -1,9 +1,12 @@
 package com.theoplayer.android.ui
 
 import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
 import androidx.compose.ui.res.stringResource
 import com.theoplayer.android.api.player.track.Track
-import java.util.Locale
+import com.theoplayer.android.api.player.track.mediatrack.MediaTrack
+import com.theoplayer.android.api.player.track.texttrack.TextTrack
+import com.theoplayer.android.ui.util.constructLabel
 import kotlin.math.absoluteValue
 
 /**
@@ -64,18 +67,33 @@ fun formatTime(time: Double, guide: Double = 0.0, preferNegative: Boolean = fals
  */
 @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 remember(track.id, track.uid) {
+        when (track) {
+            is TextTrack -> constructLabel(track)
+            is MediaTrack<*> -> constructLabel(track)
+            else -> null
         }
-        return languageCode
-    }
-    return stringResource(R.string.theoplayer_ui_track_unknown)
-}
+    } ?: stringResource(R.string.theoplayer_ui_track_unknown)
+}
+
+/**
+ * Return a human-readable label for the given media track.
+ *
+ * @param track the media track
+ */
+@Composable
+fun formatTrackLabel(track: MediaTrack<*>): String {
+    return remember(track.id, track.uid) { constructLabel(track) }
+        ?: stringResource(R.string.theoplayer_ui_track_unknown)
+}
+
+/**
+ * Return a human-readable label for the given text track.
+ *
+ * @param track the text track
+ */
+@Composable
+fun formatTrackLabel(track: TextTrack): String {
+    return remember(track.id, track.uid) { constructLabel(track) }
+        ?: stringResource(R.string.theoplayer_ui_track_unknown)
+}

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

@@ -43,17 +43,17 @@ fun SubtitleTrackList(
             count = subtitleTracks.size,
             key = { subtitleTracks[it].uid }
         ) {
-            val audioTrack = subtitleTracks[it]
+            val subtitleTrack = subtitleTracks[it]
             ListItem(
-                headlineContent = { Text(text = formatTrackLabel(audioTrack)) },
+                headlineContent = { Text(text = formatTrackLabel(subtitleTrack)) },
                 leadingContent = {
                     RadioButton(
-                        selected = (activeSubtitleTrack == audioTrack),
+                        selected = (activeSubtitleTrack == subtitleTrack),
                         onClick = null
                     )
                 },
                 modifier = Modifier.clickable(onClick = {
-                    player?.activeSubtitleTrack = audioTrack
+                    player?.activeSubtitleTrack = subtitleTrack
                     onClick?.let { it() }
                 })
             )

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,98 @@
+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.mediatrack.MediaTrack
+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 = locale.getDisplayName(locale).orEmpty()
+        return localisedLanguage.takeUnless { it.isBlank() }
+    }
+
+/**
+ * Constructs a label for the given [MediaTrack] instance.
+ *
+ * This returns the first non-empty entry from the list:
+ * 1. Track label
+ * 2. Track language display name
+ */
+internal fun constructLabel(track: MediaTrack<*>): String? {
+    return track.label?.takeUnless { it.isBlank() }
+        ?: track.localizedLanguageName
+}
+
+/**
+ * Constructs a label for the given [TextTrack] 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: TextTrack): String? {
+    val label: String? = if (
+        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.type == TextTrackType.CEA608) {
+        track.captionChannelCompat
+            ?.let { getLabelForChannelNumber(it) }
+            ?.let { return it }
+
+        track.label
+            ?.takeUnless { it.isBlank() }
+            ?.let { return it }
+    }
+
+    return null
+}