Skip to content

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

feat: normalize Media3 VOD chapters

David Nashasha6783d6dd1a2
diff --git a/player/src/main/java/com/streamvault/player/ChapterMetadataMapper.kt b/player/src/main/java/com/streamvault/player/ChapterMetadataMapper.kt
new file mode 100644
index 00000000..182cf46a
--- /dev/null
+++ b/player/src/main/java/com/streamvault/player/ChapterMetadataMapper.kt
@@ -0,0 +1,65 @@
+@file:androidx.media3.common.util.UnstableApi
+
+package com.streamvault.player
+
+import androidx.media3.common.C
+import androidx.media3.common.Metadata
+import androidx.media3.extractor.metadata.Chapter
+
+internal fun mapChapterMetadata(
+ metadata: Metadata?,
+ windowOffsetMs: Long,
+ durationMs: Long
+): List<PlayerChapter> {
+ val candidates = metadata
+ ?.getEntriesOfType(Chapter::class.java)
+ .orEmpty()
+ .mapNotNull { chapter ->
+ if (chapter.isHidden || chapter.startTimeMs == C.TIME_UNSET) return@mapNotNull null
+
+ val startTimeMs = chapter.startTimeMs - windowOffsetMs
+ if (startTimeMs < 0L) return@mapNotNull null
+
+ val title = chapter.title?.value
+ ?.trim()
+ ?.takeIf(String::isNotEmpty)
+ ?: ""
+ val explicitEndTimeMs = chapter.endTimeMs
+ .takeUnless { it == C.TIME_UNSET }
+ ?.minus(windowOffsetMs)
+
+ ChapterCandidate(
+ title = title,
+ startTimeMs = startTimeMs,
+ explicitEndTimeMs = explicitEndTimeMs
+ )
+ }
+ .sortedWith(compareBy<ChapterCandidate> { it.startTimeMs }.thenBy { it.title })
+ .distinctBy { it.startTimeMs to it.title }
+
+ return candidates.mapIndexed { index, candidate ->
+ val nextStartTimeMs = candidates.getOrNull(index + 1)?.startTimeMs
+ val derivedEndTimeMs = candidate.explicitEndTimeMs
+ ?.takeIf { it > candidate.startTimeMs }
+ ?: nextStartTimeMs
+ ?: durationMs.takeIf { it > candidate.startTimeMs }
+ val endTimeMs = derivedEndTimeMs
+ ?.takeIf { it > candidate.startTimeMs }
+ ?.let { end ->
+ if (durationMs > candidate.startTimeMs) end.coerceAtMost(durationMs) else end
+ }
+
+ PlayerChapter(
+ index = index + 1,
+ title = candidate.title.ifBlank { "Chapter ${index + 1}" },
+ startTimeMs = candidate.startTimeMs,
+ endTimeMs = endTimeMs
+ )
+ }
+}
+
+private data class ChapterCandidate(
+ val title: String,
+ val startTimeMs: Long,
+ val explicitEndTimeMs: Long?
+)
diff --git a/player/src/main/java/com/streamvault/player/PlayerChapter.kt b/player/src/main/java/com/streamvault/player/PlayerChapter.kt
new file mode 100644
index 00000000..63400f4e
--- /dev/null
+++ b/player/src/main/java/com/streamvault/player/PlayerChapter.kt
@@ -0,0 +1,8 @@
+package com.streamvault.player
+
+data class PlayerChapter(
+ val index: Int,
+ val title: String,
+ val startTimeMs: Long,
+ val endTimeMs: Long?
+)
diff --git a/player/src/test/java/com/streamvault/player/ChapterMetadataMapperTest.kt b/player/src/test/java/com/streamvault/player/ChapterMetadataMapperTest.kt
new file mode 100644
index 00000000..68aaf988
--- /dev/null
+++ b/player/src/test/java/com/streamvault/player/ChapterMetadataMapperTest.kt
@@ -0,0 +1,80 @@
+package com.streamvault.player
+
+import androidx.media3.common.C
+import androidx.media3.common.Label
+import androidx.media3.common.Metadata
+import androidx.media3.extractor.metadata.Chapter
+import com.google.common.truth.Truth.assertThat
+import org.junit.Test
+
+class ChapterMetadataMapperTest {
+
+ @Test
+ fun `maps visible chapters into sorted window relative chapters`() {
+ val metadata = Metadata(
+ chapter(startMs = 12_000L, endMs = C.TIME_UNSET, title = "Second"),
+ chapter(startMs = 2_000L, endMs = 8_000L, title = "First"),
+ chapter(startMs = 20_000L, endMs = 30_000L, title = "Hidden", hidden = true)
+ )
+
+ val chapters = mapChapterMetadata(
+ metadata = metadata,
+ windowOffsetMs = 1_000L,
+ durationMs = 25_000L
+ )
+
+ assertThat(chapters).containsExactly(
+ PlayerChapter(index = 1, title = "First", startTimeMs = 1_000L, endTimeMs = 7_000L),
+ PlayerChapter(index = 2, title = "Second", startTimeMs = 11_000L, endTimeMs = 25_000L)
+ ).inOrder()
+ }
+
+ @Test
+ fun `derives missing end from the next chapter and duration`() {
+ val metadata = Metadata(
+ chapter(startMs = 0L, endMs = C.TIME_UNSET, title = null),
+ chapter(startMs = 10_000L, endMs = C.TIME_UNSET, title = "Final")
+ )
+
+ val chapters = mapChapterMetadata(metadata, windowOffsetMs = 0L, durationMs = 30_000L)
+
+ assertThat(chapters).containsExactly(
+ PlayerChapter(index = 1, title = "Chapter 1", startTimeMs = 0L, endTimeMs = 10_000L),
+ PlayerChapter(index = 2, title = "Final", startTimeMs = 10_000L, endTimeMs = 30_000L)
+ ).inOrder()
+ }
+
+ @Test
+ fun `ignores invalid entries and deduplicates repeated metadata`() {
+ val repeated = chapter(startMs = 5_000L, endMs = 9_000L, title = "Same")
+ val metadata = Metadata(
+ chapter(startMs = C.TIME_UNSET, endMs = C.TIME_UNSET, title = "Unset"),
+ chapter(startMs = -2_000L, endMs = 0L, title = "Negative"),
+ repeated,
+ repeated
+ )
+
+ val chapters = mapChapterMetadata(metadata, windowOffsetMs = 0L, durationMs = 20_000L)
+
+ assertThat(chapters).containsExactly(
+ PlayerChapter(index = 1, title = "Same", startTimeMs = 5_000L, endTimeMs = 9_000L)
+ )
+ }
+
+ @Test
+ fun `returns empty list without metadata`() {
+ assertThat(mapChapterMetadata(null, windowOffsetMs = 0L, durationMs = 20_000L)).isEmpty()
+ }
+
+ private fun chapter(
+ startMs: Long,
+ endMs: Long,
+ title: String?,
+ hidden: Boolean = false
+ ): Chapter = Chapter.Builder()
+ .setStartTimeMs(startMs)
+ .setEndTimeMs(endMs)
+ .setHidden(hidden)
+ .apply { title?.let { setTitle(Label(null, it)) } }
+ .build()
+}