Skip to content

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

docs: add Compose Reduction Baseline documentation for Phase 0 UI architecture and performance metrics

David Nashash78cb7a561ae3
diff --git a/app/build.gradle.kts b/app/build.gradle.kts
index e98d7087..837327c5 100644
--- a/app/build.gradle.kts
+++ b/app/build.gradle.kts
@@ -159,6 +159,15 @@ kotlin {
}
}
+// Diagnostic-only output for the Compose reduction work. These reports are
+// build artifacts and are intentionally not committed. They expose unstable
+// parameters, restartable/skippable composables, and large generated groups
+// before we change UI state ownership or module boundaries.
+composeCompiler {
+ reportsDestination = layout.buildDirectory.dir("reports/compose-compiler")
+ metricsDestination = layout.buildDirectory.dir("reports/compose-compiler")
+}
+
kover {
currentProject {
createVariant("ci") {
diff --git a/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerControlsOverlayHost.kt b/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerControlsOverlayHost.kt
new file mode 100644
index 00000000..78767304
--- /dev/null
+++ b/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerControlsOverlayHost.kt
@@ -0,0 +1,144 @@
+package com.streamvault.app.ui.screens.player
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.focus.FocusRequester
+import androidx.lifecycle.compose.collectAsStateWithLifecycle
+import com.streamvault.app.ui.screens.player.overlay.PlayerControlsOverlay
+import com.streamvault.domain.model.Channel
+import com.streamvault.domain.model.Program
+import com.streamvault.player.PlayerEngine
+
+/**
+ * Owns the player controls' high-frequency transport state at the overlay boundary.
+ *
+ * Keeping position and duration collection here prevents the screen coordinator from
+ * also owning the controls' realtime state while we continue decomposing PlayerScreen.
+ */
+@Composable
+internal fun PlayerControlsOverlayHost(
+ playerEngine: PlayerEngine,
+ visible: Boolean,
+ title: String,
+ contentType: String,
+ isCatchUpPlayback: Boolean = false,
+ isPlaying: Boolean,
+ currentProgram: Program?,
+ currentChannel: Channel?,
+ currentChannelName: String?,
+ displayChannelNumber: Int,
+ aspectRatioLabel: String,
+ subtitleTrackCount: Int,
+ liveTranslationAvailable: Boolean,
+ audioTrackCount: Int,
+ videoQualityCount: Int,
+ currentRecordingStatus: com.streamvault.domain.model.RecordingStatus?,
+ isMuted: Boolean,
+ playbackSpeed: Float,
+ mediaTitle: String?,
+ sleepTimerUiState: SleepTimerUiState,
+ timeshiftUiState: PlayerTimeshiftUiState,
+ playButtonFocusRequester: FocusRequester,
+ quickActionsFocusRequester: FocusRequester,
+ modifier: Modifier = Modifier,
+ onClose: () -> Unit,
+ onTogglePlayPause: () -> Unit,
+ onSeekBackward: () -> Unit,
+ onSeekForward: () -> Unit,
+ onRestartProgram: () -> Unit,
+ onOpenArchive: () -> Unit,
+ onStartRecording: () -> Unit,
+ onStopRecording: () -> Unit,
+ onScheduleRecording: () -> Unit,
+ onScheduleDailyRecording: () -> Unit,
+ onScheduleWeeklyRecording: () -> Unit,
+ onToggleAspectRatio: () -> Unit,
+ onOpenSubtitleTracks: () -> Unit,
+ onOpenAudioTracks: () -> Unit,
+ onOpenVideoTracks: () -> Unit,
+ onOpenPlaybackSpeed: () -> Unit,
+ onOpenStopPlaybackTimer: () -> Unit,
+ onOpenIdleStandbyTimer: () -> Unit,
+ onOpenAudioVideoSync: () -> Unit,
+ audioVideoSyncEnabled: Boolean,
+ showEpisodesAction: Boolean,
+ onOpenEpisodes: () -> Unit,
+ onOpenSplitScreen: () -> Unit,
+ onEnterPictureInPicture: () -> Unit,
+ onToggleMute: () -> Unit,
+ isCastConnected: Boolean,
+ onCast: () -> Unit,
+ onStopCasting: () -> Unit,
+ onSeekToLiveEdge: () -> Unit,
+ onSeekToPosition: (Long) -> Unit,
+ onSetScrubbingMode: (Boolean) -> Unit,
+ seekPreview: SeekPreviewState,
+ onSeekPreviewPositionChanged: (Long?) -> Unit,
+ onUserInteraction: () -> Unit
+) {
+ val currentPosition by playerEngine.currentPosition.collectAsStateWithLifecycle()
+ val duration by playerEngine.duration.collectAsStateWithLifecycle()
+
+ PlayerControlsOverlay(
+ visible = visible,
+ title = title,
+ contentType = contentType,
+ isCatchUpPlayback = isCatchUpPlayback,
+ isPlaying = isPlaying,
+ currentProgram = currentProgram,
+ currentChannel = currentChannel,
+ currentChannelName = currentChannelName,
+ displayChannelNumber = displayChannelNumber,
+ currentPosition = currentPosition,
+ duration = duration,
+ aspectRatioLabel = aspectRatioLabel,
+ subtitleTrackCount = subtitleTrackCount,
+ liveTranslationAvailable = liveTranslationAvailable,
+ audioTrackCount = audioTrackCount,
+ videoQualityCount = videoQualityCount,
+ currentRecordingStatus = currentRecordingStatus,
+ isMuted = isMuted,
+ playbackSpeed = playbackSpeed,
+ mediaTitle = mediaTitle,
+ sleepTimerUiState = sleepTimerUiState,
+ timeshiftUiState = timeshiftUiState,
+ playButtonFocusRequester = playButtonFocusRequester,
+ quickActionsFocusRequester = quickActionsFocusRequester,
+ modifier = modifier,
+ onClose = onClose,
+ onTogglePlayPause = onTogglePlayPause,
+ onSeekBackward = onSeekBackward,
+ onSeekForward = onSeekForward,
+ onRestartProgram = onRestartProgram,
+ onOpenArchive = onOpenArchive,
+ onStartRecording = onStartRecording,
+ onStopRecording = onStopRecording,
+ onScheduleRecording = onScheduleRecording,
+ onScheduleDailyRecording = onScheduleDailyRecording,
+ onScheduleWeeklyRecording = onScheduleWeeklyRecording,
+ onToggleAspectRatio = onToggleAspectRatio,
+ onOpenSubtitleTracks = onOpenSubtitleTracks,
+ onOpenAudioTracks = onOpenAudioTracks,
+ onOpenVideoTracks = onOpenVideoTracks,
+ onOpenPlaybackSpeed = onOpenPlaybackSpeed,
+ onOpenStopPlaybackTimer = onOpenStopPlaybackTimer,
+ onOpenIdleStandbyTimer = onOpenIdleStandbyTimer,
+ onOpenAudioVideoSync = onOpenAudioVideoSync,
+ audioVideoSyncEnabled = audioVideoSyncEnabled,
+ showEpisodesAction = showEpisodesAction,
+ onOpenEpisodes = onOpenEpisodes,
+ onOpenSplitScreen = onOpenSplitScreen,
+ onEnterPictureInPicture = onEnterPictureInPicture,
+ onToggleMute = onToggleMute,
+ isCastConnected = isCastConnected,
+ onCast = onCast,
+ onStopCasting = onStopCasting,
+ onSeekToLiveEdge = onSeekToLiveEdge,
+ onSeekToPosition = onSeekToPosition,
+ onSetScrubbingMode = onSetScrubbingMode,
+ seekPreview = seekPreview,
+ onSeekPreviewPositionChanged = onSeekPreviewPositionChanged,
+ onUserInteraction = onUserInteraction
+ )
+}
diff --git a/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerScreen.kt b/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerScreen.kt
index 930a16a9..3b04b945 100644
--- a/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerScreen.kt
+++ b/app/src/main/java/com/streamvault/app/ui/screens/player/PlayerScreen.kt
@@ -93,7 +93,6 @@ import com.streamvault.app.ui.screens.player.overlay.PlayerEpisodeSelectionDialo
import com.streamvault.app.ui.screens.player.overlay.PlayerResumePrompt
import com.streamvault.app.ui.screens.player.overlay.PlayerTrackSelectionDialog
import com.streamvault.app.ui.screens.player.overlay.PlayerAspectRatioToast
-import com.streamvault.app.ui.screens.player.overlay.PlayerControlsOverlay
import com.streamvault.app.ui.screens.player.overlay.PlayerNumericInputOverlay
import com.streamvault.app.ui.screens.player.overlay.PlayerResolutionBadge
import com.streamvault.app.ui.screens.player.overlay.PlayerAudioVideoOffsetDialog
@@ -1426,133 +1425,6 @@ private fun buildResolutionBadgeLabel(
}
}
-@Composable
-private fun PlayerControlsOverlayHost(
- playerEngine: PlayerEngine,
- visible: Boolean,
- title: String,
- contentType: String,
- isCatchUpPlayback: Boolean = false,
- isPlaying: Boolean,
- currentProgram: Program?,
- currentChannel: Channel?,
- currentChannelName: String?,
- displayChannelNumber: Int,
- aspectRatioLabel: String,
- subtitleTrackCount: Int,
- liveTranslationAvailable: Boolean,
- audioTrackCount: Int,
- videoQualityCount: Int,
- currentRecordingStatus: com.streamvault.domain.model.RecordingStatus?,
- isMuted: Boolean,
- playbackSpeed: Float,
- mediaTitle: String?,
- sleepTimerUiState: SleepTimerUiState,
- timeshiftUiState: PlayerTimeshiftUiState,
- playButtonFocusRequester: FocusRequester,
- quickActionsFocusRequester: FocusRequester,
- modifier: Modifier = Modifier,
- onClose: () -> Unit,
- onTogglePlayPause: () -> Unit,
- onSeekBackward: () -> Unit,
- onSeekForward: () -> Unit,
- onRestartProgram: () -> Unit,
- onOpenArchive: () -> Unit,
- onStartRecording: () -> Unit,
- onStopRecording: () -> Unit,
- onScheduleRecording: () -> Unit,
- onScheduleDailyRecording: () -> Unit,
- onScheduleWeeklyRecording: () -> Unit,
- onToggleAspectRatio: () -> Unit,
- onOpenSubtitleTracks: () -> Unit,
- onOpenAudioTracks: () -> Unit,
- onOpenVideoTracks: () -> Unit,
- onOpenPlaybackSpeed: () -> Unit,
- onOpenStopPlaybackTimer: () -> Unit,
- onOpenIdleStandbyTimer: () -> Unit,
- onOpenAudioVideoSync: () -> Unit,
- audioVideoSyncEnabled: Boolean,
- showEpisodesAction: Boolean,
- onOpenEpisodes: () -> Unit,
- onOpenSplitScreen: () -> Unit,
- onEnterPictureInPicture: () -> Unit,
- onToggleMute: () -> Unit,
- isCastConnected: Boolean,
- onCast: () -> Unit,
- onStopCasting: () -> Unit,
- onSeekToLiveEdge: () -> Unit,
- onSeekToPosition: (Long) -> Unit,
- onSetScrubbingMode: (Boolean) -> Unit,
- seekPreview: SeekPreviewState,
- onSeekPreviewPositionChanged: (Long?) -> Unit,
- onUserInteraction: () -> Unit
-) {
- val currentPosition by playerEngine.currentPosition.collectAsStateWithLifecycle()
- val duration by playerEngine.duration.collectAsStateWithLifecycle()
-
- PlayerControlsOverlay(
- visible = visible,
- title = title,
- contentType = contentType,
- isCatchUpPlayback = isCatchUpPlayback,
- isPlaying = isPlaying,
- currentProgram = currentProgram,
- currentChannel = currentChannel,
- currentChannelName = currentChannelName,
- displayChannelNumber = displayChannelNumber,
- currentPosition = currentPosition,
- duration = duration,
- aspectRatioLabel = aspectRatioLabel,
- subtitleTrackCount = subtitleTrackCount,
- liveTranslationAvailable = liveTranslationAvailable,
- audioTrackCount = audioTrackCount,
- videoQualityCount = videoQualityCount,
- currentRecordingStatus = currentRecordingStatus,
- isMuted = isMuted,
- playbackSpeed = playbackSpeed,
- mediaTitle = mediaTitle,
- sleepTimerUiState = sleepTimerUiState,
- timeshiftUiState = timeshiftUiState,
- playButtonFocusRequester = playButtonFocusRequester,
- quickActionsFocusRequester = quickActionsFocusRequester,
- modifier = modifier,
- onClose = onClose,
- onTogglePlayPause = onTogglePlayPause,
- onSeekBackward = onSeekBackward,
- onSeekForward = onSeekForward,
- onRestartProgram = onRestartProgram,
- onOpenArchive = onOpenArchive,
- onStartRecording = onStartRecording,
- onStopRecording = onStopRecording,
- onScheduleRecording = onScheduleRecording,
- onScheduleDailyRecording = onScheduleDailyRecording,
- onScheduleWeeklyRecording = onScheduleWeeklyRecording,
- onToggleAspectRatio = onToggleAspectRatio,
- onOpenSubtitleTracks = onOpenSubtitleTracks,
- onOpenAudioTracks = onOpenAudioTracks,
- onOpenVideoTracks = onOpenVideoTracks,
- onOpenPlaybackSpeed = onOpenPlaybackSpeed,
- onOpenStopPlaybackTimer = onOpenStopPlaybackTimer,
- onOpenIdleStandbyTimer = onOpenIdleStandbyTimer,
- onOpenAudioVideoSync = onOpenAudioVideoSync,
- audioVideoSyncEnabled = audioVideoSyncEnabled,
- showEpisodesAction = showEpisodesAction,
- onOpenEpisodes = onOpenEpisodes,
- onOpenSplitScreen = onOpenSplitScreen,
- onEnterPictureInPicture = onEnterPictureInPicture,
- onToggleMute = onToggleMute,
- isCastConnected = isCastConnected,
- onCast = onCast,
- onStopCasting = onStopCasting,
- onSeekToLiveEdge = onSeekToLiveEdge,
- onSeekToPosition = onSeekToPosition,
- onSetScrubbingMode = onSetScrubbingMode,
- seekPreview = seekPreview,
- onSeekPreviewPositionChanged = onSeekPreviewPositionChanged,
- onUserInteraction = onUserInteraction
- )
-}
-
private tailrec fun android.content.Context.findMainActivity(): MainActivity? = when (this) {
is MainActivity -> this
is android.content.ContextWrapper -> baseContext.findMainActivity()
diff --git a/app/src/test/java/com/streamvault/app/ui/screens/home/HomeViewModelTest.kt b/app/src/test/java/com/streamvault/app/ui/screens/home/HomeViewModelTest.kt
index 1eb18fa1..1e064b2b 100644
--- a/app/src/test/java/com/streamvault/app/ui/screens/home/HomeViewModelTest.kt
+++ b/app/src/test/java/com/streamvault/app/ui/screens/home/HomeViewModelTest.kt
@@ -51,6 +51,7 @@ class HomeViewModelTest {
private val preferencesRepository: PreferencesRepository = mock()
private val epgRepository: EpgRepository = mock()
private val playbackHistoryRepository: PlaybackHistoryRepository = mock()
+ private val m3uClassificationRepository: M3uClassificationRepository = mock()
private val getCustomCategories: GetCustomCategories = mock()
private val unlockParentalCategory: UnlockParentalCategory = mock()
private val parentalControlManager: ParentalControlManager = mock()
@@ -137,6 +138,7 @@ class HomeViewModelTest {
preferencesRepository = preferencesRepository,
epgRepository = epgRepository,
playbackHistoryRepository = playbackHistoryRepository,
+ m3uClassificationRepository = m3uClassificationRepository,
getCustomCategories = getCustomCategories,
unlockParentalCategory = unlockParentalCategory,
parentalControlManager = parentalControlManager,
diff --git a/docs/COMPOSE_REDUCTION_AND_UI_ARCHITECTURE_PLAN.md b/docs/COMPOSE_REDUCTION_AND_UI_ARCHITECTURE_PLAN.md
new file mode 100644
index 00000000..c64ddc23
--- /dev/null
+++ b/docs/COMPOSE_REDUCTION_AND_UI_ARCHITECTURE_PLAN.md
@@ -0,0 +1,1123 @@
+# Compose Reduction and UI Architecture Modernization Plan
+
+Status: In progress
+Owner: Unassigned
+Created: 2026-08-15
+Scope: Android application UI, navigation, build structure, and UI-facing module boundaries
+
+## Current execution state
+
+Phase 0 is partially complete. The build and Compose compiler baseline is recorded in [`COMPOSE_REDUCTION_BASELINE.md`](COMPOSE_REDUCTION_BASELINE.md), and the Compose compiler diagnostic outputs are now generated under `app/build/reports/compose-compiler/`.
+
+The first Phase 1 refactor has also started: `PlayerControlsOverlayHost` was moved out of `PlayerScreen.kt` into its own file without changing its parameters, callbacks, routes, or playback behavior. This reduced `PlayerScreen.kt` from 1,561 to 1,432 lines. `:app:compileDebugKotlin` passes after the extraction.
+
+The full `:app:testDebugUnitTest` task now passes after the test fixture was updated to provide the already-required `m3uClassificationRepository` mock. No production behavior was changed; existing coroutine opt-in warnings remain.
+
+## 1. Executive summary
+
+StreamVault should reduce Compose by making it an intentional UI technology choice instead of the default location for all application behavior. Compose should remain the primary technology for dynamic, focus-heavy TV experiences such as Live TV, EPG, playback overlays, media shelves, and MultiView. Form-heavy and mostly static surfaces such as provider setup, settings, backup/import, and simple onboarding should be evaluated for classic Views after their state and navigation boundaries are cleaned up.
+
+The largest gains will not come from mechanically converting composables to XML. They will come from:
+
+1. Moving UI code out of the monolithic `:app` compilation unit into a small number of feature modules.
+2. Separating route/state ownership from pure rendering.
+3. Preventing frequently changing state from invalidating entire screens.
+4. Removing data-layer and Media3 implementation details from presentation code.
+5. Keeping shared UI APIs small and stable.
+6. Measuring build and runtime behavior before and after every migration phase.
+
+The recommended end state is a hybrid UI architecture with five to seven feature modules, a stable `:core:ui` module, feature-owned navigation registration, and explicit UI technology decisions per feature.
+
+## 2. Current-state assessment
+
+The following measurements were taken from the repository on 2026-08-15. They are architectural indicators, not performance benchmarks.
+
+| Area | Current observation | Architectural effect |
+|---|---:|---|
+| `app/src/main` | Approximately 296 Kotlin files and 88,885 lines | Most application-facing changes converge on one Android module |
+| Compose footprint | Approximately 458 composable functions | Compose compilation and presentation behavior are concentrated in `:app` |
+| UI screens | Approximately 69,741 lines and 360 composables below `ui/screens` | Features are organized by package but not isolated at the build boundary |
+| `ProviderSetupScreen.kt` | 3,651 lines and 32 composables | Provider forms, Android file operations, pairing, draft state, and dialogs share one file |
+| `PlayerScreen.kt` | 1,561 lines and approximately 57 `collectAsState*` calls | Independent state streams can invalidate a very broad composition scope |
+| `AppNavigation.kt` | 1,108 lines | Route declaration, startup resolution, navigation policy, and feature wiring are centralized |
+| Player overlay package | Approximately 6,284 lines and 47 composables | Playback UI is partially decomposed by file but still coordinated through a large root screen |
+| Settings package | Approximately 19,318 lines and 127 composables | Settings has become a large sub-application inside `:app` |
+| Shared card ticker | Each `ChannelCard` collects the same 30-second ticker | Every visible card owns a subscription and participates in periodic recomposition |
+
+The graph report also identifies the following highly connected hubs:
+
+- `SettingsViewModel`: 172 edges.
+- `Media3PlayerEngine`: 111 edges.
+- `TvClickableSurface()`: 91 edges.
+
+High connectivity is not automatically a defect. It does indicate that changes to these APIs can affect many features and that their responsibilities should be deliberately constrained.
+
+### 2.1 Build-time causes
+
+The likely build-time contributors are:
+
+- Nearly all Compose UI lives in `:app`, so incremental isolation stops at the file level rather than the feature-module level.
+- `:app` owns navigation, feature screens, Hilt wiring, services, Cast integration, TV input, update handling, and UI.
+- Large source files create expensive invalidation and analysis units for Kotlin and the Compose compiler.
+- `:app` directly declares Compose Material 3, TV Material, Media3, Room, Retrofit, OkHttp, WorkManager, Cast, and other dependencies.
+- Hilt and KSP also run in the same module that contains the largest Kotlin/Compose source set.
+- Shared UI code currently imports app navigation, `MainActivity`, domain models, and concrete application concerns, which makes extraction harder.
+
+The existing Gradle profile showing an up-to-date `assembleDebug` in roughly four seconds is not a useful compilation baseline because `compileDebugKotlin` was up-to-date. Phase 0 must establish clean, warm, and realistic incremental measurements.
+
+### 2.2 Runtime causes
+
+The likely runtime contributors are:
+
+- Broad state observation at screen roots, particularly in `PlayerScreen`.
+- Large UI state objects that contain many lists and maps with uncertain Compose stability.
+- Frequent player state changes mixed with infrequent metadata and dialog state.
+- Repeated state collectors inside list items.
+- Complex TV focus, pointer, key, animation, image, and overlay behavior sharing the same composition scopes.
+- Feature screens that combine rendering, file I/O launchers, navigation policy, lifecycle handling, local draft state, and ViewModel events.
+- Potentially unnecessary use of both Material 3 and TV Material components in the same presentation layer.
+
+These are hypotheses until Phase 0 records traces and benchmark results.
+
+## 3. Goals
+
+### 3.1 Primary goals
+
+- Reduce incremental build time for changes isolated to one UI feature.
+- Reduce broad and unnecessary recomposition on low-powered TV devices.
+- Make state ownership and navigation ownership obvious from the directory structure.
+- Allow selected features to use classic Views without forcing the entire application to use one UI toolkit.
+- Keep Live TV and player behavior unchanged during architectural migration.
+- Reduce direct dependencies from presentation code to `data` implementation types and concrete Media3 classes.
+- Make feature code independently testable.
+- Preserve TV remote focus, accessibility, RTL, phone, tablet, and TV behavior.
+
+### 3.2 Secondary goals
+
+- Reduce large source files to reviewable units.
+- Reduce `:app` to the Android composition root.
+- Standardize design-system and interaction primitives.
+- Make Compose compiler stability and recomposition reports part of performance work.
+- Prepare for baseline profiles and macrobenchmarks.
+
+### 3.3 Goal priority and timing
+
+| Goal | When | How we know it is working |
+|---|---|---|
+| Preserve current UI and playback behavior during structural changes | Every phase | Existing tests pass; manual smoke tests pass; player validation shows no new errors, stuckness, or focus regressions |
+| Make state, rendering, and platform responsibilities easier to locate | Phase 1 | Large screens are split into focused files with explicit route/screen/state boundaries |
+| Reduce unnecessary recomposition in confirmed hotspots | Phase 2 | Compose reports and runtime traces show fewer invalidated scopes or lower frame cost |
+| Improve incremental build isolation | Phases 3–6 | Feature-only edits recompile fewer tasks and meet the baseline-relative build target |
+| Use Compose or Views intentionally per feature | Phases 5–6 | Each candidate has a measured maintenance/runtime reason, not a toolkit preference |
+| Reduce `:app` coupling and direct implementation dependencies | Phases 3–7 | Feature modules depend on contracts and `:app` becomes primarily the composition root |
+
+The first active goal is structural safety: complete the player decomposition while preserving behavior. Performance targets are later goals until runtime and repeated build measurements confirm the hotspots.
+
+### 3.4 Non-goals
+
+- Rewriting the entire UI in XML.
+- Changing the product design during the architecture migration.
+- Replacing Navigation Compose immediately.
+- Replacing Hilt, Room, Media3, or the domain/data architecture.
+- Creating one Gradle module per screen.
+- Annotating mutable or uncertain models as `@Stable` or `@Immutable` merely to silence Compose diagnostics.
+- Combining architecture work with playback recovery policy changes.
+
+## 4. Architecture principles
+
+1. Feature ownership comes before toolkit ownership. A feature owns its screens, state, actions, components, tests, and resources.
+2. Routes collect state; screens render state. Android integration and ViewModels stay at the route boundary.
+3. Frequently changing state belongs near the leaf that renders it.
+4. Shared UI must be generic. `:core:ui` must not import app routes, `MainActivity`, DAOs, provider implementations, or concrete Media3 engines.
+5. Features depend on contracts, not implementations. Presentation should prefer domain/use-case interfaces and player API abstractions.
+6. Module boundaries should reflect meaningful team and rebuild boundaries, not individual files.
+7. Each phase must preserve behavior and have a rollback point.
+8. Runtime changes are validated in release-like builds on representative low-powered devices.
+9. Player architecture changes require full live playback validation, not launch-only validation.
+
+## 5. Target module architecture
+
+```text
+:app
+ MainActivity
+ StreamVaultApp
+ root Hilt composition
+ root navigation host
+ platform services
+ deep-link and external-intent dispatch
+
+:domain
+ business models
+ repository contracts
+ use cases
+ platform-independent policies
+
+:data
+ Room
+ network providers
+ repository implementations
+ sync
+ DataStore and encrypted preferences implementations
+
+:player
+ player API
+ Media3 implementation
+ playback policies
+ timeshift
+ surface/view binding
+
+:core:ui
+ theme and design tokens
+ generic TV focus and input primitives
+ generic cards, dialogs, loading, and empty states
+ image-loading wrappers
+ adaptive screen primitives
+
+:core:navigation
+ typed destination contracts
+ common navigation request models
+ no screen implementations
+
+:feature:live
+ Live TV browsing
+ channel/category UI
+ EPG and guide
+ preview UI
+
+:feature:catalog
+ dashboard media shelves
+ movies
+ series
+ VOD
+ favorites
+ search
+
+:feature:playback
+ Player route and screen
+ player controls and overlays
+ player dialogs
+ MultiView presentation
+
+:feature:provider
+ provider setup and editing
+ import and pairing presentation
+
+:feature:settings
+ settings
+ parental controls
+ backup/restore presentation
+
+:feature:system
+ welcome
+ downloads
+ plugin management UI
+```
+
+The final module count can be adjusted after measuring Gradle configuration and clean-build effects. `:feature:system` can remain in `:app` initially if its size does not justify extraction.
+
+### 5.1 Dependency direction
+
+```text
+ +----------------+
+ | :app |
+ +--------+-------+
+ |
+ +-------------------+-------------------+
+ | | |
+ +------v------+ +-----v------+ +-----v------+
+ | :feature:* | | :core:ui | | :core:nav |
+ +------+------+ +-----+------+ +-----+------+
+ | | |
+ +-------------------+-------------------+
+ |
+ +--------v-------+
+ | :domain |
+ +--------+-------+
+ ^
+ +-------------+-------------+
+ | |
+ +------+-+ +----+----+
+ | :data | | :player |
+ +--------+ +---------+
+```
+
+Practical dependency rules:
+
+- `:app` may depend on every feature because it is the composition root.
+- Feature modules may depend on `:core:ui`, `:core:navigation`, `:domain`, and explicitly approved API modules.
+- Feature modules should not depend on another feature's implementation.
+- Feature-to-feature navigation uses destination contracts and callbacks.
+- `:data` and `:player` must not depend on feature modules or `:core:ui`.
+- `:core:ui` must not depend on `:app`, `:data`, or feature modules.
+- A temporary feature-to-`:data` dependency may be allowed during extraction, but it must be tracked and removed before that feature's migration is considered complete.
+
+### 5.2 Why feature modules improve builds
+
+Moving code into modules means a player UI edit recompiles `:feature:playback` and its downstream consumer rather than the complete UI source set. This primarily improves incremental builds. It may make clean builds slightly slower because there are more Gradle tasks, so clean-build time is a guardrail rather than the main success metric.
+
+The shared modules must remain small and stable. A frequently edited `:core:ui` module would invalidate every feature and erase much of the incremental-build benefit.
+
+## 6. UI technology strategy
+
+Compose should be selected where its declarative state, TV focus APIs, animation, and dynamic layout provide a clear benefit.
+
+| Feature or surface | Initial technology decision | Reason |
+|---|---|---|
+| Live TV browser | Keep Compose | Dynamic lists, focus, preview, overlays, adaptive modes |
+| EPG | Keep Compose | Custom grid behavior, time-based rendering, focus, dynamic loading |
+| Player overlays | Keep Compose | Layered visibility, state-driven controls, TV input and focus |
+| Player video surface | Keep View/Media3 surface behind an interop boundary | Video rendering should remain outside Compose drawing |
+| MultiView | Keep Compose initially | Dynamic slot layout and state-driven controls |
+| Dashboard/media shelves | Keep Compose | Lazy media rows and adaptive content |
+| Movies/series/VOD | Keep Compose initially | Shared media components and dynamic catalog lists |
+| Provider setup | Evaluate classic Views after state extraction | Large form, many text fields, launchers, imports, and provider-specific sections |
+| Settings | Evaluate classic Views after feature extraction | Form/list-heavy, mostly static, high source volume |
+| Backup/import | Strong candidate for Views or DialogFragment | Platform document contracts and form-like flow |
+| Welcome/onboarding | Either toolkit | Small surface; choose based on maintenance cost |
+| Plugin management | Keep current implementation until measured | No evidence yet that toolkit choice is the bottleneck |
+
+### 6.1 Decision gate for converting a feature to Views
+
+A feature should move from Compose to Views only when all of the following are true:
+
+- Its Route/Screen and state boundaries are already clean.
+- A benchmark or trace shows meaningful composition, layout, allocation, or interaction cost.
+- The feature is mostly static or form-based.
+- TV focus and accessibility behavior can be preserved or improved.
+- The conversion removes Compose from the feature module or substantially reduces a hot composition tree.
+- The additional interop/navigation complexity is acceptable.
+
+Using `AndroidView` around an entire XML screen is not considered a complete Compose reduction. It may reduce the internal composition tree, but it retains a Compose host and introduces an interop boundary. A Views-only feature should preferably use a Fragment or Activity entry point with ViewBinding and an explicit result/navigation contract.
+
+## 7. Standard feature hierarchy
+
+Each feature should use a predictable presentation structure:
+
+```text
+feature/<name>/src/main/java/com/streamvault/feature/<name>/
+ navigation/
+ <Feature>Destination.kt
+ <Feature>NavGraph.kt
+
+ presentation/
+ <Feature>Route.kt
+ <Feature>Screen.kt
+ <Feature>UiState.kt
+ <Feature>Action.kt
+ <Feature>Effect.kt
+ <Feature>ViewModel.kt
+
+ components/
+ dialogs/
+ model/
+
+ domain/ # optional feature-local orchestration
+ resources/
+```
+
+### 7.1 Route responsibility
+
+The route may:
+
+- Obtain a ViewModel.
+- Collect lifecycle-aware state.
+- Translate navigation callbacks.
+- Observe one-shot effects.
+- Register Activity Result contracts.
+- Access Android-only services when they cannot be behind an interface.
+
+The route should not contain substantial layout code.
+
+### 7.2 Screen responsibility
+
+The screen should:
+
+- Accept immutable state and event callbacks.
+- Render the feature.
+- Be previewable and testable without Hilt.
+- Avoid repositories, DAOs, concrete player engines, and direct navigation-controller calls.
+- Avoid launching business work directly.
+
+### 7.3 State frequency boundaries
+
+State should be grouped by update frequency and consumer:
+
+```text
+FeatureRouteState infrequent route/identity/loading changes
+FeatureContentState content data and selection changes
+FeatureOverlayState dialogs, panels, transient interaction state
+FeatureRealtimeState position, progress, clock, diagnostics
+```
+
+Do not combine a one-second playback position with large channel lists and infrequently changing metadata in a single root state object.
+
+### 7.4 Event pattern
+
+Prefer a small event surface over dozens of unrelated lambdas when a feature has many actions:
+
+```kotlin
+sealed interface PlayerAction {
+ data object TogglePlayback : PlayerAction
+ data object OpenChannels : PlayerAction
+ data class SelectChannel(val channelId: Long) : PlayerAction
+ data class SeekTo(val positionMs: Long) : PlayerAction
+}
+
+@Composable
+fun PlayerScreen(
+ state: PlayerScreenState,
+ onAction: (PlayerAction) -> Unit,
+ modifier: Modifier = Modifier,
+)
+```
+
+Do not force every small component to understand the feature-wide action type. Translate feature actions into narrow callbacks at section boundaries when that produces a clearer component API.
+
+## 8. Detailed refactoring plans
+
+### 8.1 Root application and navigation
+
+Current concern: `AppNavigation` owns startup routing, external requests, destination resolution, route argument parsing, and every feature's callback wiring.
+
+Target structure:
+
+```text
+app/navigation/
+ AppNavHost.kt
+ AppNavigator.kt
+ AppStartupCoordinator.kt
+ ExternalNavigationCoordinator.kt
+ TopLevelNavigationPolicy.kt
+
+feature/*/navigation/
+ LiveNavGraph.kt
+ CatalogNavGraph.kt
+ PlaybackNavGraph.kt
+ ProviderNavGraph.kt
+ SettingsNavGraph.kt
+```
+
+`AppNavHost` should read like a registry:
+
+```kotlin
+NavHost(...) {
+ welcomeGraph(...)
+ providerGraph(...)
+ liveGraph(...)
+ catalogGraph(...)
+ playbackGraph(...)
+ settingsGraph(...)
+}
+```
+
+Actions:
+
+- Move pure route construction and parsing into typed destination contracts.
+- Move startup landing resolution out of the composable into a coordinator or ViewModel.
+- Keep the `NavController` in `:app`.
+- Pass navigation callbacks into feature graph registration.
+- Avoid passing `MainActivity` into shared UI or feature screens.
+- Expose explicit platform capabilities, such as PiP, through small interfaces.
+
+### 8.2 Core UI and AppShell
+
+Current concern: `AppShell` contains reusable visual structures but also imports app routes, `MainActivity`, and app-specific navigation behavior.
+
+Split it into:
+
+```text
+:core:ui
+ AppScreenScaffold
+ AppScreenHeader
+ NavigationRailVisuals
+ TopBarVisuals
+ Focus primitives
+ Generic destination item model
+
+:app or :core:navigation
+ destination list resolution
+ current route mapping
+ navigation callbacks
+ activity/platform actions
+```
+
+The generic destination model should contain only rendering information and a stable ID. It should not contain a `NavController` or app repository.
+
+Design-system rules:
+
+- Feature code should use StreamVault wrappers for common surfaces, text, buttons, dialogs, focus indication, and spacing.
+- Raw Material 3 and TV Material usage should be limited to `:core:ui` unless a feature needs a specialized primitive.
+- Do not make a single universal component with dozens of optional parameters.
+- Keep focus behavior explicit and testable.
+
+### 8.3 Player
+
+Current concern: `PlayerScreen` observes many flows at the root and owns lifecycle, PiP, window flags, key handling, overlay focus, preparation, dialogs, player controls, and navigation.
+
+Target composition:
+
+```text
+PlayerRoute
+ PlayerLifecycleHost
+ PlayerScreen
+ PlayerVideoSurface
+ PlayerInputHost
+ PlayerOverlayHost
+ PlayerTransportRoute
+ PlayerLiveOverlayRoute
+ PlayerDialogHost
+ PlayerNoticeHost
+ PlayerDiagnosticsRoute
+```
+
+Recommended state groups:
+
+- `PlayerSessionState`: identity, content type, title, current media/channel/episode.
+- `PlayerPlaybackState`: ready/buffering/error/playing, video format, engine identity.
+- `PlayerControlsState`: visibility, mute, speed, aspect ratio, tracks, timers.
+- `PlayerLiveState`: channel/category/EPG overlays and numeric input.
+- `PlayerDialogState`: one sealed representation of the active modal instead of many booleans.
+- `PlayerRealtimeState`: position, duration, seek preview, and diagnostics.
+
+Specific actions:
+
+- Keep `currentPosition` and `duration` collection inside transport controls.
+- Collect diagnostics only while diagnostics are visible; the current conditional collection is a pattern to preserve.
+- Replace many dialog booleans with a sealed `PlayerModal` where modal states are mutually exclusive.
+- Move root key handling into a dedicated, testable input policy that returns actions.
+- Move PiP and window-flag behavior behind a platform interface owned by the route.
+- Keep player preparation keyed by a stable preparation identity.
+- Stop casting `PlayerEngine` to `Media3PlayerEngine` from presentation code; expose required capabilities through the player API.
+- Keep player surface creation and binding in `:player`.
+- Preserve all recovery, timeshift, and live transport policies during UI refactoring.
+
+Player acceptance checks are defined in Section 12 and include the project's long-duration live playback validation.
+
+### 8.4 Provider setup
+
+Current concern: `ProviderSetupScreen` owns more than 20 local draft fields, file import and cleanup, QR generation, Android launchers, protocol-specific forms, advanced Stalker options, pairing, sync progress, and dialogs.
+
+Target files:
+
+```text
+provider/presentation/
+ ProviderSetupRoute.kt
+ ProviderSetupScreen.kt
+ ProviderSetupUiState.kt
+ ProviderSetupAction.kt
+ ProviderSetupEffect.kt
+ ProviderSetupViewModel.kt
+
+ forms/
+ M3uProviderForm.kt
+ XtreamProviderForm.kt
+ StalkerProviderForm.kt
+ JellyfinProviderForm.kt
+ ProviderAdvancedOptions.kt
+
+ import/
+ ProviderImportCoordinator.kt
+ ProviderImportDialogs.kt
+ ProviderFileImport.kt
+
+ pairing/
+ ProviderPairingCard.kt
+ ProviderPairingUiModel.kt
+
+ components/
+ ProviderTextField.kt
+ ProviderSourceSelector.kt
+ ProviderPolicyOption.kt
+```
+
+Specific actions:
+
+- Move the provider draft into the ViewModel, backed by `SavedStateHandle` where process restoration matters.
+- Keep only transient visual state in `rememberSaveable`, such as the currently expanded section.
+- Move file copy/cleanup and QR generation out of the composable file.
+- Use provider-specific draft models rather than one flat list of unrelated strings.
+- Convert data-layer Stalker configuration types to feature/domain UI models at the route/ViewModel boundary.
+- Keep Activity Result launchers in `ProviderSetupRoute` and communicate results through actions.
+- Split create, edit, import, pairing, and sync-result behavior into explicit states.
+- After decomposition, benchmark a Compose implementation against a ViewBinding implementation before choosing a final toolkit.
+
+### 8.5 Settings
+
+Current concern: settings presentation and `SettingsViewModel` are major graph hubs, and several settings files directly use DAOs, DataStore implementation types, and operational data entities.
+
+Target structure:
+
+```text
+settings/presentation/
+ SettingsRoute.kt
+ SettingsScreen.kt
+ SettingsSection.kt
+ SettingsAction.kt
+ SettingsEffect.kt
+
+ sections/
+ GeneralSettings.kt
+ PlaybackSettings.kt
+ LiveTvSettings.kt
+ GuideSettings.kt
+ RecordingSettings.kt
+ ProviderSettings.kt
+ BackupSettings.kt
+ AboutSettings.kt
+
+ dialogs/
+ backup/
+ parental/
+```
+
+Specific actions:
+
+- Split the ViewModel by responsibility or introduce focused coordinators/use cases.
+- Replace direct DAO dependencies with domain-level query/command contracts.
+- Replace concrete `PreferencesRepository` use in presentation-facing classes with an application settings contract.
+- Keep backup file launchers and platform directory interactions at the route/platform boundary.
+- Define a stable row model for list-based settings if a classic `RecyclerView` implementation is evaluated.
+- Keep each settings section independently testable.
+
+### 8.6 Live TV and EPG
+
+Current concern: Live TV and EPG are naturally complex and should not be rewritten merely to reduce Compose count.
+
+Specific actions:
+
+- Keep Compose.
+- Split dialog ownership from the main screen state.
+- Keep preview player state isolated from channel/category list state.
+- Ensure all lazy items have stable keys and useful `contentType` values.
+- Avoid rebuilding provider lookup maps and filtered collections in composition.
+- Expose only visible-window data where possible.
+- Ensure time ticker changes invalidate only current-program/progress elements.
+- Keep focus restoration and remote input policies in dedicated helpers with tests.
+- Benchmark channel navigation, category switching, EPG horizontal movement, and preview start/stop.
+
+### 8.7 Catalog, favorites, and search
+
+Specific actions:
+
+- Consolidate shared movie/series/VOD browsing behavior behind feature-local presentation models.
+- Keep shared media cards in `:core:ui` only when they are genuinely feature-neutral.
+- Keep feature-specific card decorations and actions inside `:feature:catalog`.
+- Move filtering, ranking, grouping, and sort construction out of composables.
+- Ensure list instances are reused when content has not changed.
+- Use paging/windowed loading where lists are too large to materialize at once.
+- Standardize media item keys across combined-provider variants.
+
+## 9. Compose runtime rules
+
+These rules should be documented and enforced during the migration:
+
+- Collect state at the lowest practical owner.
+- Use `collectAsStateWithLifecycle` for UI-observed flows.
+- Do not create one collector per list item for shared state.
+- Use stable keys for every dynamic lazy item.
+- Add `contentType` to mixed lazy lists and grids.
+- Perform sorting, grouping, and large map creation outside composition.
+- Use `remember` for expensive pure derivations whose keys are correct.
+- Use `derivedStateOf` only when it reduces invalidations; do not use it as decoration.
+- Keep high-frequency reads in drawing/layout lambdas or leaf composables when possible.
+- Prefer immutable feature UI models.
+- Use immutable collections when they materially improve stability and allocation behavior.
+- Apply `@Immutable` only when every exposed property is deeply immutable by contract.
+- Avoid passing mutable collections into composables.
+- Avoid broad `CompositionLocal` state for feature data.
+- Avoid unnecessary animations on reduced-motion or constrained-device paths.
+- Do not load full-resolution artwork when the rendered size is small.
+- Keep image requests stable and sized to the display target.
+- Treat focus state as local visual state unless the feature needs to restore it across navigation.
+
+## 10. Build performance plan
+
+### 10.1 Establish scenarios
+
+Measure at least these scenarios:
+
+1. Clean `assembleDebug`.
+2. Warm no-change `assembleDebug`.
+3. Incremental change to a player composable.
+4. Incremental change to a settings composable.
+5. Incremental change to `:core:ui`.
+6. Incremental change to a domain model used by several features.
+7. Unit-test compilation for a single feature.
+8. Release or beta compilation for representative CI behavior.
+
+Use Gradle Profiler for repeatable incremental scenarios when practical. Record median and p95 across multiple runs rather than one result.
+
+### 10.2 Compose compiler reports
+
+Add reports for Compose modules during the diagnostic phase:
+
+```kotlin
+composeCompiler {
+ reportsDestination = layout.buildDirectory.dir("compose_compiler")
+ metricsDestination = layout.buildDirectory.dir("compose_compiler")
+}
+```
+
+Reports should remain build artifacts unless a small summarized baseline is intentionally committed. Review:
+
+- Restartable versus skippable composables.
+- Unstable parameter types.
+- Large generated composable groups.
+- Feature models that force unnecessary invalidation.
+
+### 10.3 Gradle structure
+
+- Introduce convention plugins for Android library, Compose feature, and non-Compose feature configuration after two feature modules prove the desired pattern.
+- Keep annotation processors and KSP only in modules that need them.
+- Use `implementation` by default; use `api` only for deliberate public contracts.
+- Keep module public APIs small to minimize downstream recompilation.
+- Preserve configuration-cache compatibility.
+- Avoid dynamic dependency versions.
+- Audit direct `:app` dependencies after feature extraction.
+
+### 10.4 Dependency cleanup candidates
+
+- Remove direct Media3 dependencies from `:app` after all direct Media3 use is behind `:player` APIs.
+- Remove direct Room/Retrofit/OkHttp dependencies from UI feature modules.
+- Evaluate replacing `material-icons-extended` with a small set of vector resources or core icons.
+- Centralize and audit regular Material 3 versus TV Material usage.
+- Keep debug-only tooling and LeakCanary out of release dependency graphs.
+- Compare APK and dex composition before and after dependency cleanup; do not assume source dependency removal equals packaged size reduction.
+
+## 11. Phased delivery plan
+
+Every phase should be independently mergeable. Avoid a long-running branch that moves all features at once.
+
+### Phase 0 - Baseline and guardrails
+
+Purpose: establish evidence and prevent regressions.
+
+Deliverables:
+
+- Build benchmark scenarios and recorded baseline.
+- Compose compiler reports for `:app`.
+- A `:benchmark` or equivalent Macrobenchmark module plan, followed by implementation.
+- Runtime traces for startup, dashboard scroll, Live TV navigation, EPG navigation, player controls, and settings.
+- Representative device matrix.
+- Baseline APK/dex and memory measurements.
+
+Exit criteria:
+
+- Results are reproducible across at least five warm/incremental runs and three runtime iterations per scenario.
+- Debug-only Compose overhead is not used to judge release runtime.
+- The team agrees on baseline-relative targets in Section 13.
+
+### Phase 1 - Source decomposition without behavior change
+
+Purpose: make later changes reviewable and lower merge risk.
+
+Deliverables:
+
+- Split `ProviderSetupScreen.kt` into provider-specific forms, dialogs, import helpers, and components.
+- Split `PlayerScreen.kt` into lifecycle, input, overlay host, and modal host files.
+- Split `AppNavigation.kt` into startup/external navigation policy and graph registration files.
+- Keep packages and Gradle modules unchanged.
+- Add or move tests around extracted pure policies.
+
+Exit criteria:
+
+- No intended UI behavior change.
+- Screenshots/golden tests remain equivalent.
+- Existing unit and instrumentation suites pass.
+- Live TV validation passes if player composition or lifecycle code moved.
+
+### Phase 2 - Runtime state isolation
+
+Purpose: reduce broad recomposition before modularization.
+
+Deliverables:
+
+- Player state grouped by consumer and frequency.
+- Position/duration state isolated to transport controls.
+- Player modal state represented explicitly.
+- Shared channel ticker ownership reduced.
+- Stable keys and `contentType` audited for hot lazy lists.
+- Large UI models audited with Compose compiler reports.
+- Recomposition traces compared to Phase 0.
+
+Exit criteria:
+
+- No increase in player errors or stuck playback.
+- Measurable reduction in recomposed scopes or frame cost on at least one identified hot flow.
+- No material regression on reference devices.
+
+### Phase 3 - Core UI boundary
+
+Purpose: create a stable reusable presentation foundation.
+
+Deliverables:
+
+- Add `:core:ui`.
+- Move theme, design tokens, generic focus/input primitives, and truly generic components.
+- Separate `AppShell` visuals from app navigation and activity behavior.
+- Establish dependency rules with a build-time or static check where practical.
+
+Exit criteria:
+
+- `:core:ui` does not depend on `:app`, `:data`, or feature implementations.
+- A core UI change intentionally recompiles dependents; a feature UI change does not recompile unrelated features.
+- Golden coverage exists for critical shared TV components.
+
+### Phase 4 - Navigation contracts
+
+Purpose: allow feature extraction without central navigation growth.
+
+Deliverables:
+
+- Add `:core:navigation` if typed contracts justify a separate module.
+- Extract typed destinations and player navigation requests.
+- Add `NavGraphBuilder` registration extensions per feature area.
+- Move startup and external navigation orchestration out of the root composable.
+
+Exit criteria:
+
+- `AppNavHost` is primarily a graph registry.
+- Features do not access the root `NavController` directly.
+- Deep links, startup player requests, return routes, and external navigation are covered by tests.
+
+### Phase 5 - Feature module extraction
+
+Recommended extraction order:
+
+1. `:feature:playback` because it has the highest runtime and state-isolation value.
+2. `:feature:provider` because it has the largest composable source file and a clear boundary.
+3. `:feature:settings` because it is large and highly connected.
+4. `:feature:live` because Live TV and EPG share player-preview and channel concepts.
+5. `:feature:catalog` because movies, series, VOD, favorites, and search share media UI.
+6. `:feature:system` only if measurement shows value.
+
+For each module:
+
+- Move source, resources, tests, and Hilt bindings needed by the feature.
+- Expose only route registration and destination contracts.
+- Remove app-package imports from feature implementation.
+- Track temporary `:data` implementation dependencies.
+- Measure feature edit build time before and after extraction.
+
+Exit criteria:
+
+- A change inside one feature does not recompile unrelated feature source.
+- Feature tests can run independently.
+- `:app` contains orchestration and platform entry points, not feature presentation implementations.
+
+### Phase 6 - Optional Views migrations
+
+Purpose: reduce Compose where evidence and maintenance characteristics support it.
+
+Candidate order:
+
+1. Backup/import flows.
+2. Provider setup forms.
+3. Settings sections.
+4. Simple onboarding.
+
+For each candidate, build a small benchmarkable vertical slice first. Compare:
+
+- Initial render and interaction frame time.
+- Memory and allocations.
+- TV focus behavior.
+- Accessibility.
+- Source complexity and testability.
+- Incremental build impact.
+- Navigation/interoperability cost.
+
+Exit criteria:
+
+- Conversion demonstrates a measurable benefit or a clear maintenance win.
+- Converted modules omit the Compose plugin when they contain no Compose code.
+- The change does not create a fragile Compose/View navigation boundary.
+
+### Phase 7 - Dependency and API cleanup
+
+Purpose: finish the architecture rather than leaving transitional dependencies permanent.
+
+Deliverables:
+
+- Domain-facing settings/preferences contracts.
+- Player capability API without presentation casts to `Media3PlayerEngine`.
+- Provider setup UI models without direct Stalker implementation types.
+- Removal of unused direct dependencies from `:app` and feature modules.
+- Final package and naming cleanup.
+- Updated architecture documentation and diagrams.
+
+Exit criteria:
+
+- No presentation package imports DAOs or remote provider implementation classes.
+- Concrete Media3 use is confined to player/platform implementation code.
+- Temporary migration dependencies are removed or explicitly documented with owners.
+
+## 12. Validation strategy
+
+### 12.1 Build validation
+
+Record for every architectural phase:
+
+- Clean build median and p95.
+- Warm no-change build median.
+- Incremental feature-edit build median and p95.
+- Kotlin compilation and KSP task durations.
+- Number of tasks executed versus up-to-date/from-cache.
+- Gradle configuration time.
+- CI build duration when available.
+
+Do not compare one clean build against one warm build.
+
+### 12.2 Runtime benchmark flows
+
+Benchmark at least:
+
+- Cold startup to welcome/home content.
+- Warm startup to the configured landing destination.
+- Dashboard vertical and horizontal scrolling.
+- Live TV category change and repeated channel focus movement.
+- Live preview start, stop, and replacement.
+- EPG horizontal time movement and vertical channel movement.
+- Player controls open/close.
+- Player channel list and EPG overlay navigation.
+- Repeated channel zapping.
+- MultiView open, focus movement, and slot replacement.
+- Provider setup typing and provider-tab switching.
+- Settings scrolling and dialog opening.
+
+Collect:
+
+- Frame timing and jank.
+- Main-thread slices in Perfetto.
+- Composition/recomposition traces where available.
+- Java/Kotlin allocations.
+- PSS and heap behavior on constrained devices.
+- Time to initial display and time to fully drawn.
+
+### 12.3 Device matrix
+
+At minimum:
+
+- A constrained Android TV/Google TV class device.
+- A Fire TV class device when available.
+- The Television 1080p emulator used by existing tests.
+- A phone/tablet reference device if those form factors remain supported.
+- One modern high-performance device as a regression control.
+
+### 12.4 Player and Live TV validation
+
+Any phase that changes player composition, lifecycle, state collection, surface ownership, navigation, or overlays must use the repository's full live playback protocol:
+
+- Validate more than one live channel.
+- Capture at a 2-second cadence.
+- Capture at least 45 screenshots for about 90 seconds; prefer 61 screenshots for about two minutes.
+- Confirm changing screenshot hashes through the full window.
+- Confirm the media session remains `PLAYING` with `error=null`.
+- Check logs for fatal player errors, stuck-player timeout, and unintended MPEG-TS fallback.
+- Record HLS prepare/read/first-frame or expected recovery evidence.
+- Report channel names, screenshot count, interval, unique hash count, media-session result, and log findings.
+
+Build success, installation, launch, or a single screenshot is not sufficient player validation.
+
+### 12.5 Functional regression coverage
+
+- Navigation and deep links.
+- Startup landing preference.
+- Provider create/edit/import.
+- Backup and restore.
+- TV remote focus and back behavior.
+- Mouse and touch behavior.
+- RTL layout and navigation.
+- Reduced motion.
+- Accessibility labels and focus order.
+- PiP.
+- Cast.
+- TV input and recommendations.
+- Parental controls.
+- Playback recovery and timeshift.
+
+## 13. Success metrics
+
+Phase 0 should produce the final approved numbers. The following are initial target ranges, all relative to the recorded baseline:
+
+| Metric | Initial target | Guardrail |
+|---|---:|---:|
+| Incremental build after feature-only UI edit | At least 25% faster | Must not regress |
+| Incremental unit-test compile for extracted feature | At least 20% faster | Must not regress |
+| Clean debug build | Improvement is optional | No more than 10% slower without documented reason |
+| Warm no-change build | Maintain or improve | No more than 10% slower |
+| Slow/janky frames in selected hot flows | At least 20% reduction where a hotspot is confirmed | No regression on other benchmark flows |
+| Player controls open latency | At least 10% improvement if currently measurable | No visible focus delay |
+| Startup time | Maintain or improve during structural phases | No more than 5% regression |
+| Memory during Live TV/player | Maintain or improve | No sustained growth or new leak |
+| Player stability | Equivalent or better | Zero new fatal/stuck/fallback regressions |
+| `:app` presentation source | Majority moved to feature modules | `:app` must not regain feature implementations |
+
+Targets should be revised if Phase 0 shows measurement noise larger than the proposed improvement.
+
+## 14. Proposed pull-request sequence
+
+This sequence keeps reviews focused and creates rollback points:
+
+1. Add build/runtime benchmark infrastructure and capture baseline.
+2. Add Compose compiler report configuration and stability audit notes.
+3. Extract pure player input/modal policies with tests.
+4. Split `PlayerScreen` files without behavior changes.
+5. Isolate player real-time state and validate Live TV fully.
+6. Split provider setup files without behavior changes.
+7. Move provider draft and import behavior to explicit route/ViewModel state.
+8. Add `:core:ui` and move only theme/design/focus primitives.
+9. Separate AppShell visuals from navigation and activity dependencies.
+10. Split navigation policy and feature graph registration.
+11. Extract `:feature:playback`.
+12. Extract `:feature:provider`.
+13. Extract `:feature:settings`.
+14. Extract `:feature:live`.
+15. Extract `:feature:catalog`.
+16. Run Views proof of concept for backup/import or one provider form.
+17. Make toolkit decision per candidate feature.
+18. Remove transitional data/player implementation dependencies.
+19. Final performance report and architecture documentation update.
+
+Large moves should use history-preserving file moves where possible. Mechanical moves and behavior changes should be separate PRs.
+
+## 15. Risks and mitigations
+
+| Risk | Mitigation |
+|---|---|
+| Feature modules increase clean-build task overhead | Optimize for incremental builds, keep module count modest, measure clean-build guardrail |
+| Core UI becomes a new god module | Keep it generic, small, stable, and dependency-restricted |
+| Moving state changes behavior | First extract files without behavior changes; then change state ownership with tests |
+| Player refactor introduces playback regressions | Separate UI architecture from recovery policy; use full multi-channel long-duration validation |
+| Compose/View interop complicates navigation | Convert only after a vertical-slice proof and explicit navigation contract |
+| `@Immutable` hides mutable behavior | Annotate only deeply immutable contracts and validate with compiler reports/tests |
+| Feature extraction exposes too many APIs | Default to internal visibility and expose route registration plus small contracts |
+| Temporary feature-to-data dependencies become permanent | Track them in the migration PR and require removal in Phase 7 |
+| Golden tests become brittle during file moves | Preserve semantics and test tags; avoid visual changes in structural PRs |
+| Long-running refactor causes merge conflicts | Use small sequential PRs and move one feature at a time |
+
+## 16. Rollback strategy
+
+- Every PR must compile and pass its scoped validation independently.
+- Preserve old route entry points until a feature module is fully wired and tested.
+- For state isolation, keep adapters that can map old ViewModel flows into the new state model during transition.
+- For Views experiments, keep the existing Compose destination behind a debug or development switch until the comparison is complete.
+- Do not delete the original implementation in the same commit that introduces an unvalidated replacement.
+- Playback policy and recovery code must remain unchanged during presentation-only refactors unless a separate bug-fix scope explicitly authorizes it.
+
+## 17. Definition of done
+
+The modernization is complete when:
+
+- `:app` is primarily the platform and navigation composition root.
+- Major UI areas are isolated in a small number of feature modules.
+- Route, Screen, UiState, Action, and Effect responsibilities are consistently applied.
+- Player high-frequency state is isolated from infrequently changing screen state.
+- Provider setup no longer owns a flat collection of draft fields and platform work inside one composable.
+- Settings presentation does not directly depend on DAOs or concrete data implementations.
+- Feature presentation does not cast to `Media3PlayerEngine`.
+- `:core:ui` is generic and stable.
+- Navigation is registered per feature and the root nav host is readable.
+- Compose remains where it provides clear product value.
+- Views are used only where measurement or maintenance evidence supports them.
+- Incremental build targets are met or documented with evidence.
+- Runtime benchmark flows show no regressions and confirmed hotspots improve.
+- Full Live TV/player validation passes after all playback-facing phases.
+- Documentation and graph output reflect the final architecture.
+
+## 18. Immediate next actions
+
+- [ ] Approve this plan's target module grouping.
+- [ ] Assign an owner for Phase 0 measurements.
+- [x] Capture initial clean-task-graph and warm Gradle baselines. See `docs/COMPOSE_REDUCTION_BASELINE.md`.
+- [x] Add Compose compiler reports and inspect player/provider stability output. See `docs/COMPOSE_REDUCTION_BASELINE.md`.
+- [x] Complete the first no-behavior-change slice by extracting `PlayerControlsOverlayHost`.
+- [ ] Run a manual app smoke test for player launch, controls, remote/back handling, seeking, and overlay actions.
+- [ ] Run full multi-channel Live TV validation before marking the player phase complete.
+- [ ] Add or define the Macrobenchmark module and constrained-device benchmark flows.
+- [ ] Create the first no-behavior-change PR for `PlayerScreen` decomposition.
+- [ ] Create the second no-behavior-change PR for `ProviderSetupScreen` decomposition.
+- [ ] Revisit the initial success targets after baseline data is available.
+
+## Appendix A - Initial file mapping
+
+The following is a proposed migration map. Exact names may change during implementation.
+
+| Current file or package | Proposed destination |
+|---|---|
+| `MainActivity.kt` | `:app` |
+| `navigation/AppNavigation.kt` | `:app` plus feature `navigation/*NavGraph.kt` files |
+| `ui/theme` | `:core:ui` |
+| `ui/design` | `:core:ui` |
+| Generic parts of `ui/interaction` | `:core:ui` |
+| Generic parts of `ui/components` | `:core:ui` |
+| App-specific parts of `ui/components/shell` | `:app` or feature navigation shell |
+| `ui/screens/player` | `:feature:playback` |
+| `ui/screens/multiview` | `:feature:playback` |
+| `ui/screens/provider` | `:feature:provider` |
+| `ui/screens/settings` | `:feature:settings` |
+| `ui/screens/home` | `:feature:live` |
+| `ui/screens/epg` | `:feature:live` |
+| `ui/screens/movies` | `:feature:catalog` |
+| `ui/screens/series` | `:feature:catalog` |
+| `ui/screens/vod` | `:feature:catalog` |
+| `ui/screens/favorites` | `:feature:catalog` |
+| `ui/screens/search` | `:feature:catalog` |
+| `ui/screens/dashboard` | `:feature:catalog` initially; reconsider if it becomes an app-level aggregator |
+| `ui/screens/welcome` | `:feature:system` or `:app` initially |
+| `ui/screens/downloads` | `:feature:system` or dedicated feature if it grows |
+| `ui/screens/plugins` | `:feature:system` or dedicated feature if plugin UI grows |
+
+## Appendix B - Suggested local commands
+
+Examples use PowerShell from the repository root.
+
+Build profile:
+
+```powershell
+.\gradlew.bat --stop
+.\gradlew.bat clean :app:assembleDebug --profile --no-daemon
+.\gradlew.bat :app:assembleDebug --profile
+```
+
+Focused checks during early source decomposition:
+
+```powershell
+.\gradlew.bat :app:compileDebugKotlin
+.\gradlew.bat :app:testDebugUnitTest
+.\gradlew.bat :app:lintDebug
+```
+
+After feature extraction, run the feature's checks directly before the app integration checks:
+
+```powershell
+.\gradlew.bat :feature:playback:compileDebugKotlin
+.\gradlew.bat :feature:playback:testDebugUnitTest
+.\gradlew.bat :app:assembleDebug
+```
+
+After modifying code files, refresh the repository graph:
+
+```powershell
+graphify update .
+```
+
+## Appendix C - Architecture review checklist
+
+Use this checklist for every migrated feature:
+
+- [ ] The feature has one clear Route entry point.
+- [ ] The Screen can render without Hilt or a `NavController`.
+- [ ] UI state is immutable by contract.
+- [ ] High-frequency state is isolated near its consumer.
+- [ ] Lazy collections use stable keys.
+- [ ] Mixed lazy content uses `contentType`.
+- [ ] Business sorting/filtering is outside composition.
+- [ ] Android launchers and platform services are at the route boundary.
+- [ ] No DAO or remote implementation type appears in presentation APIs.
+- [ ] No concrete Media3 engine cast appears in presentation code.
+- [ ] Shared components are truly generic before moving to `:core:ui`.
+- [ ] Navigation is expressed through callbacks or destination contracts.
+- [ ] Focus, accessibility, RTL, touch, mouse, and remote behavior are tested.
+- [ ] Build impact is measured.
+- [ ] Runtime impact is measured for hot flows.
+- [ ] Player-facing changes pass full live playback validation.
diff --git a/docs/COMPOSE_REDUCTION_BASELINE.md b/docs/COMPOSE_REDUCTION_BASELINE.md
new file mode 100644
index 00000000..3cb0810b
--- /dev/null
+++ b/docs/COMPOSE_REDUCTION_BASELINE.md
@@ -0,0 +1,111 @@
+# Compose Reduction Baseline
+
+Date: 2026-08-15
+Repository state: existing user changes in `gradle.properties` and `player/build.gradle.kts` were preserved
+Purpose: Phase 0 baseline for UI architecture and Compose reduction work
+
+## Execution update
+
+The first behavior-preserving decomposition has been applied: `PlayerControlsOverlayHost` now lives in `app/src/main/java/com/streamvault/app/ui/screens/player/PlayerControlsOverlayHost.kt`, while its inputs, callbacks, and `PlayerControlsOverlay` wiring remain unchanged. `PlayerScreen.kt` decreased from 1,561 to 1,432 lines.
+
+Verification after the extraction:
+
+- `:app:compileDebugKotlin` — passed.
+- `graphify update .` — passed; graph refreshed to 12,893 nodes and 24,601 edges.
+- `:app:testDebugUnitTest` — passed after the test fixture was updated to provide the already-required `m3uClassificationRepository` mock. Existing coroutine opt-in warnings remain.
+
+This document records the first build and Compose compiler measurements before any feature UI refactoring. The numbers are directional until repeated with Gradle Profiler and runtime benchmarks.
+
+## Build baseline
+
+| Scenario | Result | Cache/task details |
+|---|---:|---|
+| `clean :app:assembleDebug --profile --no-daemon` | 2m15.47s | 93 actionable tasks; 40 executed; 53 from cache; configuration cache stored |
+| Warm `:app:assembleDebug --profile --no-daemon` | 36.264s | 89 actionable tasks; 1 executed; 88 up-to-date; configuration cache reused |
+| `:app:compileDebugKotlin --profile --no-daemon` | 33s command duration | 49 actionable tasks; 1 executed; 48 up-to-date |
+| Forced `:app:compileDebugKotlin --rerun-tasks` | Incomplete after 184s timeout | Compose reports were emitted; duration is not a valid benchmark |
+
+The clean command still reused Gradle/build-cache outputs for several compilation tasks. It should therefore be described as a clean task-graph run with cache reuse, not a fully uncached machine build.
+
+The warm command includes the cost of starting a single-use Gradle process because `--no-daemon` was used. Future comparisons should include both a normal developer-daemon scenario and a CI-style no-daemon scenario.
+
+## Packaging snapshot
+
+| Artifact | Size |
+|---|---:|
+| `app/build/outputs/apk/debug/app-debug.apk` | 50,778,921 bytes |
+
+This is a debug APK and is not an install-size or release-size target. A release APK and per-ABI/package analysis should be added before dependency cleanup.
+
+## Compose compiler snapshot
+
+Reports were generated under `app/build/reports/compose-compiler/` using the diagnostic configuration added to [`app/build.gradle.kts`](../app/build.gradle.kts).
+
+| Metric | Value |
+|---|---:|
+| Generated composables | 2,273 |
+| Restartable composables | 2,240 |
+| Skippable composables | 1,243 |
+| Known unstable arguments | 1,060 |
+| Inferred unstable classes | 156 of 268 analyzed classes |
+| Memoized lambdas | 3,070 |
+| Compose feature flags | Strong skipping, intrinsic remember, optimized non-skipping groups, pausable composition |
+
+The generated composable count is larger than the source-level `@Composable` count because the compiler report also includes generated and nested composable groups/lambdas.
+
+## First findings
+
+### Shared media components
+
+- `ChannelCard` receives an unstable `Channel`.
+- `MovieCard` receives an unstable `Movie`.
+- `SeriesCard` receives an unstable `Series`.
+- `CategoryRow` receives an unstable `List<T>`.
+- `ChannelCard` also observes the shared 30-second progress ticker from inside each card.
+
+Initial implication: do not immediately annotate domain models as stable. Introduce feature-facing immutable UI models where the rendering contract is smaller and genuinely immutable. Revisit ticker ownership after runtime tracing.
+
+### Player
+
+- `PlayerScreen` itself is restartable/skippable, but its root ViewModel exposes a large state surface.
+- `PlayerControlsOverlay` receives unstable `Program` and `Channel` values in addition to realtime position/duration.
+- `PlayerRenderView` receives the player abstraction and should remain isolated from the rest of the composition.
+
+Initial implication: split player state by frequency and consumer before changing player module boundaries. Position, duration, and seek preview should remain in the transport subtree. Live channel/EPG state should remain in the live overlay subtree.
+
+### Provider setup
+
+- `ProviderSetupScreen` receives an unstable ViewModel and owns many local draft values.
+- `ProviderSetupCompletionLayer` receives unstable provider state, sets, and file values.
+
+Initial implication: extract provider-specific form models and move persistent draft ownership toward the ViewModel. Keep launcher callbacks at the route boundary.
+
+### Settings and navigation
+
+- `SettingsScreen` receives an unstable ViewModel and passes unstable settings state into dialog/overlay hosts.
+- `AppNavigation` receives an unstable `MainActivity` object containing repositories, managers, and mutable flows.
+
+Initial implication: root navigation should receive small platform capability interfaces and navigation state rather than a concrete activity. Settings should eventually depend on use-case/contracts instead of concrete DAOs and preference implementations.
+
+## Baseline limitations
+
+The following are still required before performance targets are finalized:
+
+- Repeated Gradle Profiler incremental scenarios.
+- Compose recomposition tracing for player, Live TV, EPG, dashboard, and settings.
+- Macrobenchmark or equivalent startup/interaction measurements.
+- At least one constrained TV device and one phone/tablet reference device.
+- Release/beta APK size and per-ABI analysis.
+- Long-duration Live TV validation before and after player-facing changes.
+
+## Immediate next implementation
+
+The first behavior-preserving UI change should be player source decomposition and state-boundary preparation:
+
+1. **Complete for this slice:** split the controls overlay host out of `PlayerScreen.kt`.
+2. **Next:** split lifecycle, input, transport-host, and modal-host code from `PlayerScreen.kt`.
+3. Keep the same ViewModel, routes, callbacks, and playback policies.
+4. Run the existing player tests and full Live TV validation.
+5. Compare the Compose compiler report and runtime trace with this baseline.
+
+The next candidate is provider setup decomposition, followed by feature-module extraction once the internal boundaries are stable.
diff --git a/gradle.properties b/gradle.properties
index d7181061..c3c20c96 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -1,4 +1,7 @@
org.gradle.jvmargs=-Xmx4096m -Dfile.encoding=UTF-8
+org.gradle.caching=true
+org.gradle.configuration-cache=true
+org.gradle.parallel=true
android.useAndroidX=true
android.nonTransitiveRClass=true
kotlin.code.style=official
diff --git a/player/build.gradle.kts b/player/build.gradle.kts
index 2b874d33..4e2bc98c 100644
--- a/player/build.gradle.kts
+++ b/player/build.gradle.kts
@@ -1,4 +1,13 @@
+import java.io.ByteArrayInputStream
import java.util.Properties
+import java.util.zip.ZipFile
+import java.util.zip.ZipInputStream
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.TaskAction
plugins {
alias(libs.plugins.android.library)
@@ -8,6 +17,120 @@ plugins {
alias(libs.plugins.kover)
}
+abstract class VerifyLocalFfmpegArtifactTask : DefaultTask() {
+ @get:InputFile
+ @get:PathSensitive(PathSensitivity.RELATIVE)
+ abstract val ffmpegAarFile: RegularFileProperty
+
+ @get:InputFile
+ @get:PathSensitive(PathSensitivity.RELATIVE)
+ abstract val ffmpegManifestFile: RegularFileProperty
+
+ @TaskAction
+ fun verify() {
+ val aarFile = ffmpegAarFile.get().asFile
+ val manifestFile = ffmpegManifestFile.get().asFile
+ val manifest = Properties().apply {
+ manifestFile.inputStream().use(::load)
+ }
+
+ check(manifest.getProperty("media3Version") == "1.9.2") {
+ "FFmpeg artifact must use Media3 version 1.9.2"
+ }
+
+ val aarEntries = ZipFile(aarFile).use { zipFile ->
+ zipFile.entries().asSequence()
+ .filterNot { it.isDirectory }
+ .map { it.name }
+ .toSet()
+ }
+ listOf("jni/arm64-v8a/", "jni/armeabi-v7a/").forEach { abiPrefix ->
+ check(aarEntries.any { it.startsWith(abiPrefix) && it.endsWith(".so") }) {
+ "FFmpeg artifact is missing a native library under $abiPrefix"
+ }
+ }
+
+ val classesJarBytes = readZipEntry(aarFile, "classes.jar")
+ val classEntries = zipEntryNames(classesJarBytes)
+ listOf(
+ "androidx/media3/decoder/ffmpeg/FfmpegLibrary.class",
+ "androidx/media3/decoder/ffmpeg/FfmpegAudioRenderer.class"
+ ).forEach { requiredClass ->
+ check(requiredClass in classEntries) {
+ "FFmpeg artifact is missing required class $requiredClass"
+ }
+ }
+
+ val enabledDecoders = manifest.getProperty("enabledDecoders")
+ .split(',')
+ .map(String::trim)
+ .filter(String::isNotEmpty)
+ .toSet()
+ check("mp2" in enabledDecoders) {
+ "FFmpeg artifact must include the mp2 decoder for MPEG layer II audio streams"
+ }
+
+ val ffmpegLibraryClassText = zipEntryBytes(
+ classesJarBytes,
+ "androidx/media3/decoder/ffmpeg/FfmpegLibrary.class"
+ ).toString(Charsets.ISO_8859_1)
+ check("audio/mpeg-L2" in ffmpegLibraryClassText) {
+ "FFmpeg FfmpegLibrary must expose audio/mpeg-L2 MIME type for MPEG layer II audio"
+ }
+
+ ZipFile(aarFile).use { zipFile ->
+ zipFile.entries().asSequence()
+ .filter { entry ->
+ !entry.isDirectory &&
+ entry.name.startsWith("jni/") &&
+ entry.name.endsWith("/libffmpegJNI.so")
+ }
+ .forEach { nativeLibrary ->
+ val nativeLibraryText = zipFile.getInputStream(nativeLibrary).use { input ->
+ input.readBytes().toString(Charsets.ISO_8859_1)
+ }
+ check("ff_mp2_decoder" in nativeLibraryText) {
+ "FFmpeg native library is missing the mp2 decoder: ${nativeLibrary.name}"
+ }
+ }
+ }
+ }
+
+ private fun readZipEntry(zipFile: java.io.File, entryName: String): ByteArray =
+ ZipFile(zipFile).use { archive ->
+ val entry = archive.getEntry(entryName)
+ ?: error("FFmpeg artifact is missing $entryName")
+ archive.getInputStream(entry).use { it.readBytes() }
+ }
+
+ private fun zipEntryNames(zipBytes: ByteArray): Set<String> {
+ val names = mutableSetOf<String>()
+ ZipInputStream(ByteArrayInputStream(zipBytes)).use { zipInput ->
+ var entry = zipInput.nextEntry
+ while (entry != null) {
+ names += entry.name
+ entry = zipInput.nextEntry
+ }
+ }
+ return names
+ }
+
+ private fun zipEntryBytes(zipBytes: ByteArray, entryName: String): ByteArray {
+ var bytes: ByteArray? = null
+ ZipInputStream(ByteArrayInputStream(zipBytes)).use { zipInput ->
+ var entry = zipInput.nextEntry
+ while (entry != null) {
+ if (entry.name == entryName) {
+ bytes = zipInput.readBytes()
+ break
+ }
+ entry = zipInput.nextEntry
+ }
+ }
+ return bytes ?: error("FFmpeg classes.jar is missing $entryName")
+ }
+}
+
android {
namespace = "com.streamvault.player"
compileSdk = 36
@@ -42,76 +165,12 @@ kover {
}
}
-val ffmpegAarFile = layout.projectDirectory.file("libs/media3-decoder-ffmpeg-1.9.2.aar").asFile
-val ffmpegManifestFile = layout.projectDirectory.file("libs/media3-decoder-ffmpeg-1.9.2.properties").asFile
-
-val verifyLocalFfmpegArtifact by tasks.registering {
+val verifyLocalFfmpegArtifact = tasks.register<VerifyLocalFfmpegArtifactTask>("verifyLocalFfmpegArtifact") {
group = "verification"
description = "Verifies the bundled Media3 FFmpeg artifact, metadata, and supported ABIs."
- inputs.file(ffmpegAarFile)
- inputs.file(ffmpegManifestFile)
-
- doLast {
- check(ffmpegAarFile.isFile) {
- "Required FFmpeg artifact missing: ${ffmpegAarFile.absolutePath}"
- }
- check(ffmpegManifestFile.isFile) {
- "Required FFmpeg manifest missing: ${ffmpegManifestFile.absolutePath}"
- }
-
- val manifest = Properties().apply {
- ffmpegManifestFile.inputStream().use(::load)
- }
- check(manifest.getProperty("media3Version") == "1.9.2") {
- "FFmpeg manifest media3Version must be 1.9.2"
- }
-
- val aarEntries = zipTree(ffmpegAarFile).files.map { it.invariantSeparatorsPath }
- listOf("jni/arm64-v8a/", "jni/armeabi-v7a/").forEach { abiPrefix ->
- check(aarEntries.any { it.contains(abiPrefix) && it.endsWith(".so") }) {
- "FFmpeg artifact is missing native libraries under $abiPrefix"
- }
- }
-
- val classesJar = zipTree(ffmpegAarFile).matching { include("classes.jar") }.singleFile
- val classEntries = zipTree(classesJar).files.map { it.invariantSeparatorsPath }
- listOf(
- "androidx/media3/decoder/ffmpeg/FfmpegLibrary.class",
- "androidx/media3/decoder/ffmpeg/FfmpegAudioRenderer.class"
- ).forEach { requiredClass ->
- check(classEntries.any { it.endsWith(requiredClass) }) {
- "FFmpeg artifact is missing required class $requiredClass"
- }
- }
-
- val enabledDecoders = manifest.getProperty("enabledDecoders")
- .split(',')
- .map(String::trim)
- .filter(String::isNotEmpty)
- .toSet()
- check("mp2" in enabledDecoders) {
- "FFmpeg artifact must include the mp2 decoder for MPEG layer II audio streams"
- }
-
- val ffmpegLibraryClass = zipTree(classesJar)
- .matching { include("androidx/media3/decoder/ffmpeg/FfmpegLibrary.class") }
- .singleFile
- val ffmpegLibraryClassText = ffmpegLibraryClass.readBytes().toString(Charsets.ISO_8859_1)
- check("audio/mpeg-L2" in ffmpegLibraryClassText) {
- "FFmpeg FfmpegLibrary must expose audio/mpeg-L2 MIME type for MPEG layer II audio"
- }
-
- zipTree(ffmpegAarFile)
- .matching { include("jni/*/libffmpegJNI.so") }
- .files
- .forEach { nativeLibrary ->
- val nativeLibraryText = nativeLibrary.readBytes().toString(Charsets.ISO_8859_1)
- check("ff_mp2_decoder" in nativeLibraryText) {
- "FFmpeg native library is missing the mp2 decoder: ${nativeLibrary.name}"
- }
- }
- }
+ ffmpegAarFile.set(layout.projectDirectory.file("libs/media3-decoder-ffmpeg-1.9.2.aar"))
+ ffmpegManifestFile.set(layout.projectDirectory.file("libs/media3-decoder-ffmpeg-1.9.2.properties"))
}
tasks.named("preBuild").configure {