Skip to content

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

fix: TextureView green screen + settings exit button + welcome screen focus

David Nashasha5e7f5d4a8d9
diff --git a/app/src/main/java/com/streamvault/app/ui/components/shell/AppShell.kt b/app/src/main/java/com/streamvault/app/ui/components/shell/AppShell.kt
index e9dfa8e2..4a45b8a8 100644
--- a/app/src/main/java/com/streamvault/app/ui/components/shell/AppShell.kt
+++ b/app/src/main/java/com/streamvault/app/ui/components/shell/AppShell.kt
@@ -24,6 +24,7 @@ import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.foundation.horizontalScroll
import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ExitToApp
import androidx.compose.material.icons.filled.Home
import androidx.compose.material.icons.filled.Info
import androidx.compose.material.icons.filled.Menu
@@ -74,6 +75,7 @@ import com.streamvault.app.ui.design.AppMotion
import com.streamvault.app.ui.design.FocusSpec
import com.streamvault.app.ui.interaction.mouseClickable
import com.streamvault.app.ui.interaction.rememberTvInteractionSounds
+import com.streamvault.app.ui.interaction.TvIconButton
import com.streamvault.app.ui.design.LocalAppShapes
import com.streamvault.app.ui.design.LocalAppSpacing
@@ -94,6 +96,7 @@ fun AppScreenScaffold(
compactHeader: Boolean = false,
showScreenHeader: Boolean = true,
header: (@Composable ColumnScope.() -> Unit)? = null,
+ topBarActions: (@Composable RowScope.() -> Unit)? = null,
contentPadding: PaddingValues = PaddingValues(),
content: @Composable ColumnScope.() -> Unit
) {
@@ -169,6 +172,7 @@ fun AppScreenScaffold(
TopNavigationBar(
currentRoute = currentRoute,
onNavigate = onNavigate,
+ actions = topBarActions,
modifier = Modifier.fillMaxWidth()
)
Spacer(modifier = Modifier.height(10.dp))
@@ -243,6 +247,7 @@ fun AppScreenHeader(
private fun TopNavigationBar(
currentRoute: String,
onNavigate: (String) -> Unit,
+ actions: (@Composable RowScope.() -> Unit)? = null,
modifier: Modifier = Modifier
) {
val items = remember { buildDestinationItems() }
@@ -297,10 +302,47 @@ private fun TopNavigationBar(
)
}
}
+ if (actions != null) {
+ Row(
+ horizontalArrangement = Arrangement.spacedBy(6.dp),
+ verticalAlignment = Alignment.CenterVertically,
+ content = actions
+ )
+ }
}
}
}
+@Composable
+fun AppTopBarCloseAction(
+ onClick: () -> Unit,
+ modifier: Modifier = Modifier,
+ contentDescription: String = stringResource(R.string.settings_close_app)
+) {
+ TvIconButton(
+ onClick = onClick,
+ modifier = modifier,
+ colors = androidx.tv.material3.IconButtonDefaults.colors(
+ containerColor = Color.Transparent,
+ focusedContainerColor = AppColors.SurfaceEmphasis,
+ contentColor = AppColors.TextSecondary,
+ focusedContentColor = AppColors.TextPrimary
+ ),
+ border = androidx.tv.material3.IconButtonDefaults.border(
+ focusedBorder = Border(
+ border = BorderStroke(FocusSpec.BorderWidth, AppColors.Focus),
+ shape = RoundedCornerShape(14.dp)
+ )
+ )
+ ) {
+ Icon(
+ imageVector = Icons.AutoMirrored.Filled.ExitToApp,
+ contentDescription = contentDescription,
+ modifier = Modifier.size(18.dp)
+ )
+ }
+}
+
@Composable
private fun TopNavigationButton(
label: String,
diff --git a/app/src/main/java/com/streamvault/app/ui/screens/settings/SettingsScreen.kt b/app/src/main/java/com/streamvault/app/ui/screens/settings/SettingsScreen.kt
index 26a5330e..4a091390 100644
--- a/app/src/main/java/com/streamvault/app/ui/screens/settings/SettingsScreen.kt
+++ b/app/src/main/java/com/streamvault/app/ui/screens/settings/SettingsScreen.kt
@@ -22,6 +22,7 @@ import androidx.documentfile.provider.DocumentFile
import com.streamvault.app.backup.BackupFileBridge
import com.streamvault.app.diagnostics.CrashReportStore
import com.streamvault.app.util.OfficialBuildVerifier
+import com.streamvault.app.ui.components.shell.AppTopBarCloseAction
import com.streamvault.app.ui.components.shell.AppNavigationChrome
import com.streamvault.app.ui.components.shell.AppScreenScaffold
import com.streamvault.app.ui.theme.*
@@ -157,7 +158,12 @@ fun SettingsScreen(
subtitle = stringResource(R.string.settings_providers_subtitle),
navigationChrome = AppNavigationChrome.TopBar,
compactHeader = true,
- showScreenHeader = false
+ showScreenHeader = false,
+ topBarActions = {
+ AppTopBarCloseAction(
+ onClick = { mainActivity?.finishAffinity() }
+ )
+ }
) {
Row(modifier = Modifier.fillMaxSize()) {
SettingsNavigationRail(
diff --git a/app/src/main/java/com/streamvault/app/ui/screens/welcome/WelcomeScreen.kt b/app/src/main/java/com/streamvault/app/ui/screens/welcome/WelcomeScreen.kt
index 33b6b4bb..8536fb5a 100644
--- a/app/src/main/java/com/streamvault/app/ui/screens/welcome/WelcomeScreen.kt
+++ b/app/src/main/java/com/streamvault/app/ui/screens/welcome/WelcomeScreen.kt
@@ -302,7 +302,7 @@ private fun WelcomeStartCard(
modifier = Modifier.weight(1f),
colors = ButtonDefaults.colors(
containerColor = AppColors.SurfaceElevated,
- focusedContainerColor = AppColors.BrandMuted,
+ focusedContainerColor = Color.White,
contentColor = AppColors.TextPrimary
)
) {
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index a90bae45..6e8f42bd 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -523,6 +523,7 @@
<string name="settings_surface_auto">Auto</string>
<string name="settings_surface_surface_view">SurfaceView</string>
<string name="settings_surface_texture_view">TextureView</string>
+ <string name="settings_close_app">Close app</string>
<string name="settings_select_decoder_mode">Select Decoder Mode</string>
<string name="settings_buffer_duration">Buffer Duration</string>
<string name="settings_buffer_5s">5 seconds</string>
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index abef5030..7bbfe1cc 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -6,39 +6,41 @@ All notable product changes are recorded in this document.
### Added
-- Added audio decoder name to player diagnostics so FFmpeg-backed playback can be confirmed from the overlay.
-- Added FFmpeg artifact verification in the player build, plus bundled provenance and LGPL notice docs.
-- Added expert playback settings for audio output policy and persistent compatibility memory.
-- Added richer playback diagnostics for FFmpeg availability/version, audio path classification, and compatibility decision source.
-- Added APK companion plugin support with discovery, activation, capability sync, and plugin provider integration.
-- Added plugin installation from APK URL and local file picker, plus automatic detection of compatible plugins installed manually by the user.
-- Added a host-rendered plugin configuration schema so plugins can expose StreamVault-native settings screens, persisted values, validation, and plugin actions over IPC.
-- Added native Activity plugin configuration mode so rich plugin UIs can open from StreamVault with their own visual and interaction model.
-- Added a welcome-screen "Set up later" option so first-time users can enter the app and reach Settings before adding a provider.
-- Added Google Drive backup sync support with sign-in/out, push/pull actions, last-sync status in Settings, onboarding import-from-Drive progress flow, and private Drive credential sync so imported providers can restore saved usernames/passwords.
-- Added Live TV quick-filter management for hidden categories and hidden channels, including restore dialogs and channel-level hide actions from the home screen dialogs.
-- Added opt-in developer onboarding seeding from `local.properties` (Xtream + M3U) in debug builds, with a versioned `local.properties.example` template and `docs/DEV_SEEDING.md` guide.
-- Added real-time first-boot library sync progress on the welcome screen (Live/VOD/Series section state, determinate/indeterminate progress bar, current label, and indexed-items counter) powered by a typed sync progress bus.
+- Added close app icon, top right corner in settings tab.
+- Added audio decoder names to player diagnostics.
+- Added FFmpeg artifact verification plus provenance and LGPL docs.
+- Added advanced playback settings for audio output and compatibility memory.
+- Added richer FFmpeg and compatibility diagnostics.
+- Added APK companion plugin discovery, activation, and provider integration.
+- Added plugin installation from APK URLs and local files, plus auto-detection of compatible installed plugins.
+- Added host-rendered plugin settings screens with persisted values, validation, and plugin actions.
+- Added native Activity-based plugin configuration for richer plugin UIs.
+- Added a welcome-screen `Set up later` option.
+- Added Google Drive backup sync, onboarding import, and credential restore.
+- Added Live TV quick-filter management for hidden categories and channels.
+- Added opt-in debug onboarding seeding from `local.properties` with docs and template updates.
+- Added real-time first-boot library sync progress on the welcome screen.
### Changed
-- Updated the Plugins screen with compact StreamVault-styled controls and a dedicated blocks icon distinct from Settings.
-- Documented the plugin API, manifest metadata, installation model, IPC contract, host-rendered configuration schema, native Activity configuration mode, and visual integration guidance.
-- Clarified the Google Drive maintainer setup guide around the `drive.appdata` scope and the Testing-to-Production consent-screen flip for public rollout.
+- Refreshed the Plugins screen with denser StreamVault-styled controls and a dedicated icon.
+- Expanded plugin API docs for manifests, installation, IPC, configuration, and UI integration.
+- Clarified the Google Drive maintainer guide for `drive.appdata` and production rollout.
### Fixed
-- Fixed unsupported audio codec playback fallback by bundling Media3 FFmpeg decoder support for `AC-3`, `E-AC-3`, `DTS`, `MP2`, and `TrueHD` streams.
-- Fixed streams with unsupported audio codecs not retrying in software when FFmpeg support is available; the player now performs one automatic fallback retry.
-- Fixed software navigation bars cutting into the app on devices such as Nexus 5X by reapplying immersive fullscreen mode when the app resumes or regains focus.
-- Fixed touch/mouse activation behavior for TV controls used by plugin management on non-TV devices.
-- Fixed `TvClickableSurface` / `TvIconButton` long-click handling so home-screen category and channel actions keep their press-and-hold behavior.
-- Fixed series detail screens missing the favorite heart action; series info pages now match movies with add/remove favorite support directly from the detail view.
-- Fixed Xtream series detail pages sometimes showing no seasons or episodes when providers returned season metadata without inline episode rows; cached episodes are now preserved and metadata-only season payloads no longer render as empty detail screens.
-- Fixed Xtream live sync category requests stalling for several minutes near the end of large provider imports; segmented catalog calls now use shorter cancellable transport timeouts and timeout handling now surfaces as normal request failures instead of hanging the sync.
-- Fixed VOD category shelves and category browse ordering in both classic and modern views to sort by provider-added time instead of release metadata.
-- Fixed Stalker VOD category filtering drifting or appearing empty when filtered portal responses omit item category metadata; requested category context is now preserved during category hydration.
-- Fixed backup export/import to preserve hidden live categories and hidden channels preferences.
+- Fixed unsupported audio playback by bundling Media3 FFmpeg decoders for `AC-3`, `E-AC-3`, `DTS`, `MP2`, and `TrueHD`.
+- Fixed unsupported audio streams not retrying once in software when FFmpeg is available.
+- Fixed explicit `TextureView` live playback getting stuck on green or corrupted frames before first video render.
+- Fixed software nav bars overlapping the app on devices like Nexus 5X.
+- Fixed touch and mouse activation for TV plugin controls on non-TV devices.
+- Fixed `TvClickableSurface` and `TvIconButton` long-press behavior for home-screen actions.
+- Fixed missing favorite actions on series detail screens.
+- Fixed Xtream series detail pages rendering empty when only metadata-only season payloads were returned.
+- Fixed Xtream live sync category requests hanging near the end of large imports.
+- Fixed VOD category ordering to sort by provider-added time.
+- Fixed Stalker VOD category filtering drifting when portal responses omitted category metadata.
+- Fixed backup export and import to preserve hidden live categories and channels.
---
diff --git a/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt b/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt
index ff5164db..6b24a9de 100644
--- a/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt
+++ b/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt
@@ -169,6 +169,7 @@ class Media3PlayerEngine @Inject constructor(
private var currentRetryPolicy: PlayerRetryPolicy? = null
private var currentRetryContext: PlaybackRetryContext? = null
private var playbackStarted = false
+ private var hasRenderedFirstVideoFrame = false
private var prepareStartMs = 0L
private var retryAttempt = 0
private var retryJob: Job? = null
@@ -722,6 +723,7 @@ class Media3PlayerEngine @Inject constructor(
currentRetryPolicy = null
currentRetryContext = null
playbackStarted = false
+ hasRenderedFirstVideoFrame = false
retryAttempt = 0
_retryStatus.value = null
_playbackState.value = PlaybackState.IDLE
@@ -783,6 +785,7 @@ class Media3PlayerEngine @Inject constructor(
}
lastMediaId = mediaId
playbackStarted = false
+ hasRenderedFirstVideoFrame = false
prepareStartMs = System.currentTimeMillis()
audioCodecUnsupportedReported = false
pendingLearnedAudioFallback = null
@@ -1170,6 +1173,7 @@ class Media3PlayerEngine @Inject constructor(
output: Any,
renderTimeMs: Long
) {
+ hasRenderedFirstVideoFrame = true
if (prepareStartMs > 0L) {
val ttff = System.currentTimeMillis() - prepareStartMs
_playerStats.value = _playerStats.value.copy(ttffMs = ttff)
@@ -1576,20 +1580,20 @@ class Media3PlayerEngine @Inject constructor(
}
private fun shouldFallbackTextureViewBeforeFirstFrame(stats: PlayerStats): Boolean {
- if (_renderSurfaceType.value != PlayerRenderSurfaceType.TEXTURE_VIEW) return false
- if (sessionSurfaceModeOverride == PlayerSurfaceMode.SURFACE_VIEW) return false
- if (textureViewSessionFallbackAttempted) return false
- if (lastStreamInfo == null) return false
- if (playbackStarted) return false
- if (!isCurrentStreamLive()) return false
- val state = _playbackState.value
- if (state != PlaybackState.READY && state != PlaybackState.BUFFERING) return false
- if (System.currentTimeMillis() - prepareStartMs < TEXTURE_VIEW_STARTUP_TIMEOUT_MS) return false
- if (state == PlaybackState.BUFFERING && stats.bufferedDurationMs < TEXTURE_VIEW_BUFFERED_STARTUP_THRESHOLD_MS) {
- return false
- }
- if (selectedVideoDecoderName == "Unknown" && state != PlaybackState.READY) return false
- return true
+ return shouldFallbackTextureViewWithoutFirstFrame(
+ renderSurfaceType = _renderSurfaceType.value,
+ sessionSurfaceModeOverride = sessionSurfaceModeOverride,
+ fallbackAttempted = textureViewSessionFallbackAttempted,
+ hasStreamInfo = lastStreamInfo != null,
+ hasRenderedFirstVideoFrame = hasRenderedFirstVideoFrame,
+ isCurrentStreamLive = isCurrentStreamLive(),
+ playbackState = _playbackState.value,
+ elapsedSincePrepareMs = System.currentTimeMillis() - prepareStartMs,
+ startupTimeoutMs = TEXTURE_VIEW_STARTUP_TIMEOUT_MS,
+ bufferedDurationMs = stats.bufferedDurationMs,
+ bufferedStartupThresholdMs = TEXTURE_VIEW_BUFFERED_STARTUP_THRESHOLD_MS,
+ selectedVideoDecoderName = selectedVideoDecoderName
+ )
}
private fun fallbackTextureViewSurface(reason: String) {
diff --git a/player/src/main/java/com/streamvault/player/TextureViewFallbackPolicy.kt b/player/src/main/java/com/streamvault/player/TextureViewFallbackPolicy.kt
new file mode 100644
index 00000000..f4b2dee3
--- /dev/null
+++ b/player/src/main/java/com/streamvault/player/TextureViewFallbackPolicy.kt
@@ -0,0 +1,34 @@
+package com.streamvault.player
+
+import com.streamvault.domain.model.PlayerSurfaceMode
+
+private const val UNKNOWN_DECODER_NAME = "Unknown"
+
+internal fun shouldFallbackTextureViewWithoutFirstFrame(
+ renderSurfaceType: PlayerRenderSurfaceType,
+ sessionSurfaceModeOverride: PlayerSurfaceMode?,
+ fallbackAttempted: Boolean,
+ hasStreamInfo: Boolean,
+ hasRenderedFirstVideoFrame: Boolean,
+ isCurrentStreamLive: Boolean,
+ playbackState: PlaybackState,
+ elapsedSincePrepareMs: Long,
+ startupTimeoutMs: Long,
+ bufferedDurationMs: Long,
+ bufferedStartupThresholdMs: Long,
+ selectedVideoDecoderName: String
+): Boolean {
+ if (renderSurfaceType != PlayerRenderSurfaceType.TEXTURE_VIEW) return false
+ if (sessionSurfaceModeOverride == PlayerSurfaceMode.SURFACE_VIEW) return false
+ if (fallbackAttempted) return false
+ if (!hasStreamInfo) return false
+ if (hasRenderedFirstVideoFrame) return false
+ if (!isCurrentStreamLive) return false
+ if (playbackState != PlaybackState.READY && playbackState != PlaybackState.BUFFERING) return false
+ if (elapsedSincePrepareMs < startupTimeoutMs) return false
+ if (playbackState == PlaybackState.BUFFERING && bufferedDurationMs < bufferedStartupThresholdMs) {
+ return false
+ }
+ if (selectedVideoDecoderName == UNKNOWN_DECODER_NAME && playbackState != PlaybackState.READY) return false
+ return true
+}
\ No newline at end of file
diff --git a/player/src/test/java/com/streamvault/player/TextureViewFallbackPolicyTest.kt b/player/src/test/java/com/streamvault/player/TextureViewFallbackPolicyTest.kt
new file mode 100644
index 00000000..692214a0
--- /dev/null
+++ b/player/src/test/java/com/streamvault/player/TextureViewFallbackPolicyTest.kt
@@ -0,0 +1,88 @@
+package com.streamvault.player
+
+import com.google.common.truth.Truth.assertThat
+import com.streamvault.domain.model.PlayerSurfaceMode
+import org.junit.Test
+
+class TextureViewFallbackPolicyTest {
+
+ @Test
+ fun `ready texture view without first frame still falls back after timeout`() {
+ val shouldFallback = shouldFallbackTextureViewWithoutFirstFrame(
+ renderSurfaceType = PlayerRenderSurfaceType.TEXTURE_VIEW,
+ sessionSurfaceModeOverride = null,
+ fallbackAttempted = false,
+ hasStreamInfo = true,
+ hasRenderedFirstVideoFrame = false,
+ isCurrentStreamLive = true,
+ playbackState = PlaybackState.READY,
+ elapsedSincePrepareMs = 9_500L,
+ startupTimeoutMs = 9_000L,
+ bufferedDurationMs = 0L,
+ bufferedStartupThresholdMs = 4_000L,
+ selectedVideoDecoderName = "OMX.amlogic.mpeg2.decoder"
+ )
+
+ assertThat(shouldFallback).isTrue()
+ }
+
+ @Test
+ fun `texture view does not fall back after first frame renders`() {
+ val shouldFallback = shouldFallbackTextureViewWithoutFirstFrame(
+ renderSurfaceType = PlayerRenderSurfaceType.TEXTURE_VIEW,
+ sessionSurfaceModeOverride = null,
+ fallbackAttempted = false,
+ hasStreamInfo = true,
+ hasRenderedFirstVideoFrame = true,
+ isCurrentStreamLive = true,
+ playbackState = PlaybackState.READY,
+ elapsedSincePrepareMs = 9_500L,
+ startupTimeoutMs = 9_000L,
+ bufferedDurationMs = 0L,
+ bufferedStartupThresholdMs = 4_000L,
+ selectedVideoDecoderName = "OMX.amlogic.mpeg2.decoder"
+ )
+
+ assertThat(shouldFallback).isFalse()
+ }
+
+ @Test
+ fun `texture view buffering waits for enough buffered data`() {
+ val shouldFallback = shouldFallbackTextureViewWithoutFirstFrame(
+ renderSurfaceType = PlayerRenderSurfaceType.TEXTURE_VIEW,
+ sessionSurfaceModeOverride = null,
+ fallbackAttempted = false,
+ hasStreamInfo = true,
+ hasRenderedFirstVideoFrame = false,
+ isCurrentStreamLive = true,
+ playbackState = PlaybackState.BUFFERING,
+ elapsedSincePrepareMs = 9_500L,
+ startupTimeoutMs = 9_000L,
+ bufferedDurationMs = 1_500L,
+ bufferedStartupThresholdMs = 4_000L,
+ selectedVideoDecoderName = "OMX.amlogic.mpeg2.decoder"
+ )
+
+ assertThat(shouldFallback).isFalse()
+ }
+
+ @Test
+ fun `surface view override suppresses texture view fallback`() {
+ val shouldFallback = shouldFallbackTextureViewWithoutFirstFrame(
+ renderSurfaceType = PlayerRenderSurfaceType.TEXTURE_VIEW,
+ sessionSurfaceModeOverride = PlayerSurfaceMode.SURFACE_VIEW,
+ fallbackAttempted = false,
+ hasStreamInfo = true,
+ hasRenderedFirstVideoFrame = false,
+ isCurrentStreamLive = true,
+ playbackState = PlaybackState.READY,
+ elapsedSincePrepareMs = 9_500L,
+ startupTimeoutMs = 9_000L,
+ bufferedDurationMs = 0L,
+ bufferedStartupThresholdMs = 4_000L,
+ selectedVideoDecoderName = "OMX.amlogic.mpeg2.decoder"
+ )
+
+ assertThat(shouldFallback).isFalse()
+ }
+}
\ No newline at end of file