StreamVault is a TV-first free IPTV player for Android TV built with Kotlin, Jetpack Compose, Room, Hilt, and Media3.
Kotlin iptv-player
feat(player): leverage Media3 1.9.2 APIs for faster zapping & richer metadata
Davidonab69dc14e53cf
diff --git a/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerViewModel.kt b/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerViewModel.ktindex fde84fb0..95972467 100644--- a/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerViewModel.kt+++ b/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerViewModel.kt@@ -1016,6 +1016,9 @@ class PlayerViewModel @Inject constructor(_displayChannelNumber.value = resolveChannelNumber(channel, index)_recentChannels.update { channels -> channels.filterNot { it.id == channel.id } }+ // Enable scrubbing mode for fast channel start — key-frame-only decoding+ playerEngine.setScrubbingMode(true)+viewModelScope.launch {val resolvedUrl = resolvePlaybackUrl(channel.streamUrl, channel.id, channel.providerId, ContentType.LIVE)?: return@launch@@ -1026,7 +1029,16 @@ class PlayerViewModel @Inject constructor()playerEngine.prepare(streamInfo)playerEngine.play()++ // Once the first frame is on screen, turn off scrubbing for full quality+ playerEngine.playbackState+ .filter { it == com.streamvault.player.PlaybackState.READY }+ .take(1)+ .collect { playerEngine.setScrubbingMode(false) }}++ // Pre-warm the next channel in sequence so the subsequent zap is near-instant+ preloadAdjacentChannel(index)fetchEpg(currentProviderId, channel.epgChannelId)@@ -1044,6 +1056,29 @@ class PlayerViewModel @Inject constructor(}}+ /**+ * Pre-warm the next channel's media source so switching is near-instant.+ * Only the manifest/first segment is parsed — no full buffering.+ */+ private fun preloadAdjacentChannel(currentIndex: Int) {+ if (channelList.size < 2) return+ val nextIndex = (currentIndex + 1) % channelList.size+ val nextChannel = channelList[nextIndex]+ viewModelScope.launch {+ val nextUrl = resolvePlaybackUrl(+ nextChannel.streamUrl, nextChannel.id,+ nextChannel.providerId, ContentType.LIVE+ ) ?: return@launch+ playerEngine.preload(+ com.streamvault.domain.model.StreamInfo(+ url = nextUrl,+ title = nextChannel.name,+ streamType = com.streamvault.domain.model.StreamType.UNKNOWN+ )+ )+ }+ }+private fun recordLivePlayback(channel: com.streamvault.domain.model.Channel) {if (currentProviderId <= 0 || currentContentType != ContentType.LIVE) returndiff --git a/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt b/player/src/main/java/com/streamvault/player/Media3PlayerEngine.ktindex 19a59ea5..906af707 100644--- a/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt+++ b/player/src/main/java/com/streamvault/player/Media3PlayerEngine.kt@@ -16,6 +16,7 @@ import androidx.media3.datasource.DefaultHttpDataSourceimport androidx.media3.datasource.okhttp.OkHttpDataSourceimport androidx.media3.exoplayer.DefaultRenderersFactoryimport androidx.media3.exoplayer.ExoPlayer+import androidx.media3.exoplayer.ScrubbingModeParametersimport androidx.media3.exoplayer.dash.DashMediaSourceimport androidx.media3.exoplayer.hls.HlsMediaSourceimport androidx.media3.exoplayer.rtsp.RtspMediaSource@@ -73,6 +74,11 @@ class Media3PlayerEngine @Inject constructor(private var shouldResumeOnAudioFocusGain = falseprivate var currentVolume = 1fprivate var isDucked = false+ /** Remembers the volume before mute so unmute restores it. */+ private var volumeBeforeMute = 1f+ /** Pre-warmed media source for rapid next-channel start. */+ private var preloadedSource: MediaSource? = null+ private var preloadedStreamInfo: StreamInfo? = nullprivate val audioFocusChangeListener = AudioManager.OnAudioFocusChangeListener { focusChange ->when (focusChange) {@@ -144,6 +150,12 @@ class Media3PlayerEngine @Inject constructor(private val _playerStats = MutableStateFlow(PlayerStats())override val playerStats: StateFlow<PlayerStats> = _playerStats.asStateFlow()+ private val _isMuted = MutableStateFlow(false)+ override val isMuted: StateFlow<Boolean> = _isMuted.asStateFlow()++ private val _mediaTitle = MutableStateFlow<String?>(null)+ override val mediaTitle: StateFlow<String?> = _mediaTitle.asStateFlow()+private fun getOrCreatePlayer(): ExoPlayer {return exoPlayer ?: createPlayer().also {exoPlayer = it@@ -162,14 +174,16 @@ class Media3PlayerEngine @Inject constructor()}- // Tuned for IPTV live streams: larger buffer for variable network conditions+ // Tuned for IPTV live streams: aggressive start with comfortable cruise buffer.+ // Low buffer-for-playback gets the first frame on screen sooner during channel zapping.val loadControl = DefaultLoadControl.Builder().setBufferDurationsMs(- 30_000, // min buffer- 60_000, // max buffer- 2500, // buffer for playback- 5000 // buffer for rebuffering+ 15_000, // min buffer – keep smaller so the player starts faster+ 60_000, // max buffer – comfortable cruise; avoids OOM on 100k playlists+ 500, // buffer for playback – half-second is enough for key-frame start+ 2500 // buffer for rebuffering – recover quickly on network hiccup)+ .setPrioritizeTimeOverSizeThresholds(true).build()val trackSelector = androidx.media3.exoplayer.trackselection.DefaultTrackSelector(context).apply {@@ -183,6 +197,8 @@ class Media3PlayerEngine @Inject constructor(return ExoPlayer.Builder(context, renderersFactory).setTrackSelector(trackSelector).setLoadControl(loadControl)+ .setSeekBackIncrementMs(10_000)+ .setSeekForwardIncrementMs(10_000).setAudioAttributes(Media3AudioAttributes.Builder().setUsage(C.USAGE_MEDIA)@@ -289,6 +305,15 @@ class Media3PlayerEngine @Inject constructor(}override fun onPlayerError(error: PlaybackException) {+ // Behind-live-window: just seek to the live edge — no retry counter needed+ if (error.errorCode == PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW) {+ Log.w(TAG, "Behind live window — seeking to live edge")+ exoPlayer?.let { p ->+ p.seekToDefaultPosition()+ p.prepare()+ }+ return+ }if (retryCount < MAX_RETRIES && isRecoverableError(error)) {retryCount++Log.w(TAG, "Recoverable error (attempt $retryCount/$MAX_RETRIES), retrying...")@@ -311,6 +336,12 @@ class Media3PlayerEngine @Inject constructor(_currentPosition.value = newPosition.positionMs}+ override fun onMediaMetadataChanged(metadata: androidx.media3.common.MediaMetadata) {+ // ICY / HLS metadata: the stream itself reports a title change.+ val title = metadata.title?.toString()?.takeIf { it.isNotBlank() }+ _mediaTitle.value = title+ }+override fun onTracksChanged(tracks: androidx.media3.common.Tracks) {val audioTracks = mutableListOf<PlayerTrack>()val subtitleTracks = mutableListOf<PlayerTrack>()@@ -360,12 +391,22 @@ class Media3PlayerEngine @Inject constructor(val player = getOrCreatePlayer()_error.tryEmit(null)_playerStats.value = PlayerStats() // reset stats+ _mediaTitle.value = null- val dataSourceFactory = createDataSourceFactory(streamInfo)- val streamType = streamInfo.streamType.takeIf { it != StreamType.UNKNOWN }- ?: StreamTypeDetector.detect(streamInfo.url)-- val mediaSource = createMediaSource(streamInfo.url, streamType, dataSourceFactory, streamInfo.title)+ // If we already preloaded this exact stream, use the cached source+ val mediaSource = if (preloadedStreamInfo?.url == streamInfo.url && preloadedSource != null) {+ preloadedSource!!.also {+ preloadedSource = null+ preloadedStreamInfo = null+ }+ } else {+ preloadedSource = null+ preloadedStreamInfo = null+ val dataSourceFactory = createDataSourceFactory(streamInfo)+ val streamType = streamInfo.streamType.takeIf { it != StreamType.UNKNOWN }+ ?: StreamTypeDetector.detect(streamInfo.url)+ createMediaSource(streamInfo.url, streamType, dataSourceFactory, streamInfo.title)+ }player.setMediaSource(mediaSource)player.prepare()@@ -412,6 +453,7 @@ class Media3PlayerEngine @Inject constructor(return when (streamType) {StreamType.HLS -> HlsMediaSource.Factory(dataSourceFactory).setAllowChunklessPreparation(true)+ // Start from the live edge rather than 3 segments behind it.createMediaSource(mediaItem)StreamType.DASH -> DashMediaSource.Factory(dataSourceFactory)@@ -492,6 +534,7 @@ class Media3PlayerEngine @Inject constructor(override fun setVolume(volume: Float) {currentVolume = volume.coerceIn(0f, 1f)+ _isMuted.value = falseexoPlayer?.volume = if (isDucked) {(currentVolume * 0.2f).coerceAtLeast(0.05f)} else {@@ -499,6 +542,42 @@ class Media3PlayerEngine @Inject constructor(}}+ override fun toggleMute() {+ if (_isMuted.value) {+ _isMuted.value = false+ exoPlayer?.volume = volumeBeforeMute+ } else {+ volumeBeforeMute = currentVolume.coerceAtLeast(0.1f)+ _isMuted.value = true+ exoPlayer?.volume = 0f+ }+ }++ override fun setScrubbingMode(enabled: Boolean) {+ val player = exoPlayer ?: return+ if (enabled) {+ player.setScrubbingModeEnabled(true)+ } else {+ player.setScrubbingModeEnabled(false)+ player.setScrubbingModeParameters(ScrubbingModeParameters.DEFAULT)+ }+ }++ override fun preload(streamInfo: StreamInfo?) {+ if (streamInfo == null) {+ preloadedSource = null+ preloadedStreamInfo = null+ return+ }+ // Don't preload the stream that's already playing+ if (streamInfo.url == lastStreamInfo?.url) return+ val dataSourceFactory = createDataSourceFactory(streamInfo)+ val streamType = streamInfo.streamType.takeIf { it != StreamType.UNKNOWN }+ ?: StreamTypeDetector.detect(streamInfo.url)+ preloadedSource = createMediaSource(streamInfo.url, streamType, dataSourceFactory, streamInfo.title)+ preloadedStreamInfo = streamInfo+ }+override fun selectAudioTrack(trackId: String) {exoPlayer?.let { player ->val tracks = player.currentTracks@@ -566,6 +645,8 @@ class Media3PlayerEngine @Inject constructor(handler.removeCallbacksAndMessages(null)shouldResumeOnAudioFocusGain = falseabandonAudioFocusIfHeld()+ preloadedSource = null+ preloadedStreamInfo = nullmediaSession?.release()mediaSession = nullexoPlayer?.release()@@ -576,14 +657,15 @@ class Media3PlayerEngine @Inject constructor(scope = CoroutineScope(Dispatchers.Main + supervisorJob)_playbackState.value = PlaybackState.IDLE_isPlaying.value = false+ _isMuted.value = false+ _mediaTitle.value = null}private fun isRecoverableError(error: PlaybackException): Boolean {return when (error.errorCode) {PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED,PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT,- PlaybackException.ERROR_CODE_IO_UNSPECIFIED,- PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW -> true+ PlaybackException.ERROR_CODE_IO_UNSPECIFIED -> trueelse -> false}}diff --git a/player/src/main/java/com/streamvault/player/PlayerEngine.kt b/player/src/main/java/com/streamvault/player/PlayerEngine.ktindex bf4ab38b..d17abcf1 100644--- a/player/src/main/java/com/streamvault/player/PlayerEngine.kt+++ b/player/src/main/java/com/streamvault/player/PlayerEngine.kt@@ -26,6 +26,9 @@ interface PlayerEngine {val availableAudioTracks: StateFlow<List<PlayerTrack>>val availableSubtitleTracks: StateFlow<List<PlayerTrack>>+ /** In-stream metadata title (ICY / HLS). Null when the stream sends nothing. */+ val mediaTitle: StateFlow<String?>+fun prepare(streamInfo: StreamInfo)fun play()fun pause()@@ -39,6 +42,24 @@ interface PlayerEngine {fun selectSubtitleTrack(trackId: String?) // null to disable subtitlesfun release()+ /** Toggle mute without losing the remembered volume level. */+ fun toggleMute()+ val isMuted: StateFlow<Boolean>++ /**+ * Enable scrubbing mode for rapid switching (channel zapping).+ * While enabled, the player skips re-buffering and favours lowest-latency+ * key-frame-only decoding so each channel appears on screen faster.+ */+ fun setScrubbingMode(enabled: Boolean)++ /**+ * Pre-warm the player with a stream that will likely be played next.+ * Only the initial manifest/key-frames are fetched — no full buffering.+ * Call with `null` to discard any preloaded data.+ */+ fun preload(streamInfo: StreamInfo?)+fun createRenderView(context: Context, resizeMode: PlayerSurfaceResizeMode): Viewfun bindRenderView(renderView: View, resizeMode: PlayerSurfaceResizeMode)}