Skip to content

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

feat(series): enhance series variant handling with error reporting and recovery options

David Nashash3f7b8d3b77cf
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 36175331..a3d6612a 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -18,6 +18,7 @@ All notable product changes are recorded in this document.
- Fixed missing episodes from providers that return nested episode arrays or season-keyed episode maps, which were previously skipped and left series with no episodes.
- Fixed episodes disappearing when an episode's optional metadata block arrived in an unexpected shape: the episode is now kept and only the metadata is skipped.
- Fixed series pages that stayed empty after a failed details request: a failure with no cached episodes now shows a localized error, and a series with no episodes shows a localized empty state.
+- Fixed grouped series with multiple versions: a failed version switch now keeps the current version on screen and reports the failure, the preferred version is saved only after it loads, and a series whose version fails to load now offers the other versions on the error screen.
- Fixed selected subtitles reverting to off by saving track details before track-list refreshes and keeping the player's active preference in sync with manual selections.
- Fixed a compile failure in the recording-by-time dialog that prevented the app from building after the recording scheduling update, which also blocked Settings backup export and import.
- Fixed audio stopping after a while.
diff --git a/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogPlatformPorts.kt b/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogPlatformPorts.kt
index 51c013a0..2a00e50d 100644
--- a/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogPlatformPorts.kt
+++ b/feature/catalog/src/main/java/com/streamvault/feature/catalog/api/CatalogPlatformPorts.kt
@@ -47,6 +47,7 @@ enum class CatalogMessage {
TraktFavoriteSyncFailed,
TraktRatingSaved,
TraktRatingFailed,
+ SeriesVariantLoadFailed,
}
sealed interface CatalogCastStartResult {
diff --git a/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/CatalogMessageText.kt b/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/CatalogMessageText.kt
index cb18d315..9980c07e 100644
--- a/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/CatalogMessageText.kt
+++ b/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/CatalogMessageText.kt
@@ -18,4 +18,5 @@ internal fun Context.catalogMessageText(message: CatalogMessage): String = when
CatalogMessage.TraktFavoriteSyncFailed -> getString(R.string.trakt_favorite_sync_failed)
CatalogMessage.TraktRatingSaved -> getString(R.string.trakt_rating_saved)
CatalogMessage.TraktRatingFailed -> getString(R.string.trakt_rating_failed)
+ CatalogMessage.SeriesVariantLoadFailed -> getString(R.string.series_episodes_load_failed)
}
diff --git a/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailScreen.kt b/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailScreen.kt
index bea9b1ea..28e303a5 100644
--- a/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailScreen.kt
+++ b/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailScreen.kt
@@ -134,20 +134,14 @@ fun SeriesDetailScreen(
}
if (series == null) {
- Box(
- modifier = Modifier
- .fillMaxSize()
- .background(AppColors.Canvas),
- contentAlignment = Alignment.Center
- ) {
- Text(
- text = when {
- uiState.detailsUnavailable -> stringResource(R.string.series_episodes_load_failed)
- else -> uiState.error ?: stringResource(R.string.series_not_found)
- },
- color = AppColors.Live
- )
- }
+ SeriesDetailsUnavailableContent(
+ message = when {
+ uiState.detailsUnavailable -> stringResource(R.string.series_episodes_load_failed)
+ else -> uiState.error ?: stringResource(R.string.series_not_found)
+ },
+ variants = uiState.availableVariants,
+ onSelectVariant = viewModel::selectSeriesVariant
+ )
return
}
@@ -199,6 +193,33 @@ fun SeriesDetailScreen(
}
}
+@Composable
+private fun SeriesDetailsUnavailableContent(
+ message: String,
+ variants: List<VodSeriesVariant>,
+ onSelectVariant: (Long) -> Unit
+) {
+ Box(
+ modifier = Modifier
+ .fillMaxSize()
+ .background(AppColors.Canvas),
+ contentAlignment = Alignment.Center
+ ) {
+ Column(
+ horizontalAlignment = Alignment.CenterHorizontally,
+ verticalArrangement = Arrangement.spacedBy(16.dp),
+ modifier = Modifier.padding(horizontal = 32.dp)
+ ) {
+ Text(message, color = AppColors.Live)
+ SeriesVersionSelector(
+ variants = variants,
+ selectedVariantId = -1L,
+ onSelectVariant = onSelectVariant
+ )
+ }
+ }
+}
+
@Composable
private fun SeriesDetailContent(
series: Series,
diff --git a/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailViewModel.kt b/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailViewModel.kt
index d8800846..0fc6f8c6 100644
--- a/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailViewModel.kt
+++ b/feature/catalog/src/main/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailViewModel.kt
@@ -23,6 +23,7 @@ import com.streamvault.domain.model.Result
import com.streamvault.domain.model.Season
import com.streamvault.domain.model.Series
import com.streamvault.domain.model.SeriesDetailPresentationHint
+import com.streamvault.domain.model.VodSeriesVariant
import com.streamvault.domain.repository.DownloadManager
import com.streamvault.domain.repository.ExternalRatingsRepository
import com.streamvault.domain.repository.FavoriteRepository
@@ -95,6 +96,7 @@ class SeriesDetailViewModel @Inject constructor(
private var providerDetailJob: Job? = null
private var unwatchedCountJob: Job? = null
+ private var activeProviderId: Long? = null
init {
observeCastPlaybackEvents()
@@ -110,7 +112,11 @@ class SeriesDetailViewModel @Inject constructor(
}
providerDetailJob = launch {
val effectiveProviderId = resolveEffectiveProviderId(provider.id)
- loadSeriesDetailsForProvider(effectiveProviderId, seriesId)
+ activeProviderId = effectiveProviderId
+ val result = loadSeriesDetailsForProvider(effectiveProviderId, seriesId)
+ if (result !is Result.Success) {
+ loadAvailableVariants(seriesId)
+ }
}
}
}
@@ -178,10 +184,12 @@ class SeriesDetailViewModel @Inject constructor(
?: fallbackProviderId
}
- private suspend fun loadSeriesDetailsForProvider(providerId: Long, requestedSeriesId: Long) {
- try {
- _uiState.update { it.copy(isLoading = true, error = null) }
-
+ private suspend fun loadSeriesDetailsForProvider(
+ providerId: Long,
+ requestedSeriesId: Long
+ ): Result<Series> {
+ _uiState.update { it.copy(isLoading = true, error = null) }
+ return try {
when (val result = seriesRepository.getSeriesDetails(providerId, requestedSeriesId, knownPresentationHint)) {
is Result.Success -> {
val isFavoriteDeferred = viewModelScope.async {
@@ -204,6 +212,7 @@ class SeriesDetailViewModel @Inject constructor(
}
refreshTraktWatchlist()
refreshTraktRatings()
+ result
}
is Result.Error -> {
_uiState.update {
@@ -213,9 +222,11 @@ class SeriesDetailViewModel @Inject constructor(
detailsUnavailable = result.exception is SeriesDetailsUnavailableException
)
}
+ result
}
is Result.Loading -> {
_uiState.update { it.copy(isLoading = true) }
+ result
}
}
} catch (e: Exception) {
@@ -226,17 +237,37 @@ class SeriesDetailViewModel @Inject constructor(
detailsUnavailable = true
)
}
+ Result.error(e.message ?: "Failed to load series details", e)
}
}
+ private suspend fun loadAvailableVariants(requestedSeriesId: Long) {
+ val variants = runCatching { seriesRepository.getSeriesVariants(requestedSeriesId) }
+ .getOrDefault(emptyList())
+ .filter { variant -> variant.rawSeriesId > 0L }
+ if (variants.isEmpty()) return
+ _uiState.update { it.copy(availableVariants = variants) }
+ }
+
fun selectSeriesVariant(rawSeriesId: Long) {
- val currentSeries = _uiState.value.series ?: return
- if (rawSeriesId <= 0L || rawSeriesId == currentSeries.id) return
+ val state = _uiState.value
+ val currentSeries = state.series
+ if (rawSeriesId <= 0L || rawSeriesId == currentSeries?.id || state.isLoading) return
viewModelScope.launch {
- currentSeries.logicalGroupId.takeIf { it.isNotBlank() }?.let { logicalGroupId ->
- preferencesRepository.setPreferredVodVariant(currentSeries.providerId, logicalGroupId, rawSeriesId)
+ val providerId = currentSeries?.providerId ?: activeProviderId ?: return@launch
+ when (val result = loadSeriesDetailsForProvider(providerId, rawSeriesId)) {
+ is Result.Success -> {
+ val logicalGroupId = result.data.logicalGroupId.takeIf { it.isNotBlank() }
+ ?: currentSeries?.logicalGroupId?.takeIf { it.isNotBlank() }
+ logicalGroupId?.let { groupId ->
+ preferencesRepository.setPreferredVodVariant(providerId, groupId, rawSeriesId)
+ }
+ }
+ is Result.Error -> if (currentSeries != null) {
+ _uiEvents.emit(CatalogUiEvent.ShowMessage(CatalogMessage.SeriesVariantLoadFailed))
+ }
+ is Result.Loading -> Unit
}
- loadSeriesDetailsForProvider(currentSeries.providerId, rawSeriesId)
}
}
@@ -491,6 +522,7 @@ data class SeriesDetailUiState(
val unwatchedEpisodeCount: Int = 0,
val error: String? = null,
val detailsUnavailable: Boolean = false,
+ val availableVariants: List<VodSeriesVariant> = emptyList(),
val isCasting: Boolean = false,
val isLoadingExternalRatings: Boolean = false,
val externalRatings: ExternalRatings = ExternalRatings.unavailable(),
diff --git a/feature/catalog/src/test/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailViewModelCastingTest.kt b/feature/catalog/src/test/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailViewModelCastingTest.kt
index 1986b8a6..05c49860 100644
--- a/feature/catalog/src/test/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailViewModelCastingTest.kt
+++ b/feature/catalog/src/test/java/com/streamvault/feature/catalog/presentation/series/SeriesDetailViewModelCastingTest.kt
@@ -21,6 +21,7 @@ import com.streamvault.domain.model.Result
import com.streamvault.domain.model.Season
import com.streamvault.domain.model.Series
import com.streamvault.domain.model.StreamInfo
+import com.streamvault.domain.model.VodSeriesVariant
import com.streamvault.domain.repository.DownloadManager
import com.streamvault.domain.repository.ExternalRatingsRepository
import com.streamvault.domain.repository.FavoriteRepository
@@ -56,6 +57,8 @@ import org.mockito.kotlin.any
import org.mockito.kotlin.anyOrNull
import org.mockito.kotlin.eq
import org.mockito.kotlin.mock
+import org.mockito.kotlin.never
+import org.mockito.kotlin.verify
import org.mockito.kotlin.whenever
class SeriesDetailViewModelCastingTest {
@@ -254,6 +257,102 @@ class SeriesDetailViewModelCastingTest {
}
}
+ @Test
+ fun `failed version switch keeps the current series and reports the failure`() = runBlocking {
+ val preferences = mock<PreferencesRepository>()
+ val current = series(episodes = listOf(episode(id = 21L))).copy(logicalGroupId = "group-1")
+ val variantId = 31L
+ val viewModel = createViewModel(
+ series = current,
+ variantSeriesId = variantId,
+ variantDetailsResult = Result.error("variant boom", SeriesDetailsUnavailableException("variant boom")),
+ preferencesRepository = preferences
+ )
+
+ try {
+ viewModel.uiState.first { it.series != null }
+ val event = async(start = CoroutineStart.UNDISPATCHED) { viewModel.uiEvents.first() }
+ viewModel.selectSeriesVariant(variantId)
+
+ assertThat(withTimeout(5_000L) { event.await() })
+ .isEqualTo(CatalogUiEvent.ShowMessage(CatalogMessage.SeriesVariantLoadFailed))
+ assertThat(viewModel.uiState.value.series?.id).isEqualTo(current.id)
+ assertThat(viewModel.uiState.value.detailsUnavailable).isTrue()
+ verify(preferences, never()).setPreferredVodVariant(any(), any(), any())
+ } finally {
+ viewModel.viewModelScope.cancel()
+ }
+ }
+
+ @Test
+ fun `successful version switch saves the preferred version`() = runBlocking {
+ val preferences = mock<PreferencesRepository>()
+ val current = series(episodes = listOf(episode(id = 21L))).copy(logicalGroupId = "group-1")
+ val variantId = 31L
+ val variant = series(episodes = listOf(episode(id = 41L)))
+ .copy(id = variantId, logicalGroupId = "group-1")
+ val viewModel = createViewModel(
+ series = current,
+ variantSeriesId = variantId,
+ variantDetailsResult = Result.success(variant),
+ preferencesRepository = preferences
+ )
+
+ try {
+ viewModel.uiState.first { it.series != null }
+ viewModel.selectSeriesVariant(variantId)
+
+ val state = withTimeout(5_000L) { viewModel.uiState.first { it.series?.id == variantId } }
+ assertThat(state.detailsUnavailable).isFalse()
+ verify(preferences).setPreferredVodVariant(eq(current.providerId), eq("group-1"), eq(variantId))
+ } finally {
+ viewModel.viewModelScope.cancel()
+ }
+ }
+
+ @Test
+ fun `first load failure exposes other versions for recovery`() = runBlocking {
+ val viewModel = createViewModel(
+ detailsResult = Result.error("boom", SeriesDetailsUnavailableException("boom")),
+ variants = listOf(variant(rawSeriesId = 31L), variant(rawSeriesId = 32L))
+ )
+
+ try {
+ val state = withTimeout(5_000L) { viewModel.uiState.first { it.availableVariants.isNotEmpty() } }
+
+ assertThat(state.series).isNull()
+ assertThat(state.availableVariants.map { it.rawSeriesId }).containsExactly(31L, 32L).inOrder()
+ } finally {
+ viewModel.viewModelScope.cancel()
+ }
+ }
+
+ @Test
+ fun `recovery pick loads the chosen version and saves it`() = runBlocking {
+ val preferences = mock<PreferencesRepository>()
+ val variantId = 31L
+ val recovered = series(episodes = listOf(episode(id = 41L)))
+ .copy(id = variantId, logicalGroupId = "group-1")
+ val viewModel = createViewModel(
+ detailsResult = Result.error("boom", SeriesDetailsUnavailableException("boom")),
+ variants = listOf(variant(rawSeriesId = variantId)),
+ variantSeriesId = variantId,
+ variantDetailsResult = Result.success(recovered),
+ preferencesRepository = preferences
+ )
+
+ try {
+ viewModel.uiState.first { it.availableVariants.isNotEmpty() }
+ viewModel.selectSeriesVariant(variantId)
+
+ val state = withTimeout(5_000L) { viewModel.uiState.first { it.series?.id == variantId } }
+ assertThat(state.detailsUnavailable).isFalse()
+ verify(preferences).setPreferredVodVariant(eq(1L), eq("group-1"), eq(variantId))
+ } finally {
+ viewModel.viewModelScope.cancel()
+ }
+ }
+
private suspend fun createViewModel(
series: Series = series(),
streamInfo: StreamInfo = StreamInfo(url = "https://example.test/episode.m3u8"),
@@ -261,6 +360,10 @@ class SeriesDetailViewModelCastingTest {
traktFavorites: TraktFavorites = com.streamvault.feature.catalog.presentation.NoopTraktFavorites(),
traktRatings: TraktRatings = com.streamvault.feature.catalog.presentation.NoopTraktRatings(),
detailsResult: Result<Series> = Result.success(series),
+ variantSeriesId: Long = series.id + 1L,
+ variantDetailsResult: Result<Series>? = null,
+ variants: List<VodSeriesVariant> = emptyList(),
+ preferencesRepository: PreferencesRepository = mock(),
): SeriesDetailViewModel {
val provider = Provider(
id = series.providerId,
@@ -278,11 +381,17 @@ class SeriesDetailViewModelCastingTest {
whenever(seriesRepository.getSeriesById(series.id)).thenReturn(series)
whenever(seriesRepository.getSeriesDetails(eq(provider.id), eq(series.id), anyOrNull()))
.thenReturn(detailsResult)
+ variantDetailsResult?.let { variantResult ->
+ whenever(seriesRepository.getSeriesDetails(eq(provider.id), eq(variantSeriesId), anyOrNull()))
+ .thenReturn(variantResult)
+ }
+ whenever(seriesRepository.getSeriesVariants(eq(series.id))).thenReturn(variants)
+ whenever(preferencesRepository.setPreferredVodVariant(any(), any(), any())).thenReturn(Unit)
whenever(seriesRepository.getEpisodeStreamInfo(any()))
.thenReturn(Result.success(streamInfo))
- whenever(favoriteRepository.isFavorite(eq(provider.id), eq(series.id), any()))
+ whenever(favoriteRepository.isFavorite(any(), any(), any()))
.thenReturn(false)
- whenever(playbackHistoryRepository.getUnwatchedCount(eq(provider.id), eq(series.id)))
+ whenever(playbackHistoryRepository.getUnwatchedCount(any(), any()))
.thenReturn(flowOf(0))
whenever(externalRatingsRepository.getRatings(any()))
.thenReturn(Result.success(ExternalRatings.unavailable()))
@@ -294,7 +403,7 @@ class SeriesDetailViewModelCastingTest {
playbackHistoryRepository = playbackHistoryRepository,
externalRatingsRepository = externalRatingsRepository,
favoriteRepository = favoriteRepository,
- preferencesRepository = mock<PreferencesRepository>(),
+ preferencesRepository = preferencesRepository,
streamPreparer = object : CatalogStreamPreparer {
override suspend fun prepare(streamInfo: StreamInfo): Result<StreamInfo> =
Result.success(streamInfo)
@@ -375,5 +484,21 @@ class SeriesDetailViewModelCastingTest {
seriesId = 30L,
watchProgress = watchProgress
)
+
+ fun variant(rawSeriesId: Long) = VodSeriesVariant(
+ rawSeriesId = rawSeriesId,
+ name = "Series",
+ seriesId = rawSeriesId,
+ providerSeriesId = rawSeriesId.toString(),
+ releaseDate = null,
+ tmdbId = null,
+ episodeRunTime = null,
+ rating = 0f,
+ lastModified = 0L,
+ qualityScore = 0,
+ recencyScore = 0L,
+ reliabilityScore = 0,
+ label = "Version $rawSeriesId"
+ )
}
}