reis-mobile 0.3.6 → 0.4.0

package/skills/android-leanback-to-compose-tv-migration/references/android/training/tv/playback/compose/index.md

@@ -0,0 +1,153 @@
+[Video](https://www.youtube.com/watch?v=_X4tswgV67Y)
+
+Compose for TV is the modern approach for building Android TV user
+interfaces. Compose for TV unlocks all the benefits of Android's
+Jetpack Compose for your TV apps, making building beautiful and functional UIs
+for your app much easier.
+
+Some specific benefits of using Compose for TV include the
+following:
+
+- **Flexibility**: Compose can be used to create any type of UI, from basic layouts to complex animations. Components work out of the box but can also be customized and styled to fit your app's needs.
+- **Simplified \& Accelerated Development**: Compose is compatible with existing code and enables developers to more efficiently build apps with less code.
+- **Intuitive**: Compose uses a declarative syntax that lets you to make changes to your UI, debug, understand and review your code.
+
+If you are unfamiliar with using the Jetpack Compose toolkit, check out the
+[Compose pathway](https://developer.android.com/courses/pathways/compose). Many of the development principles for mobile Compose
+apply to TV as well. See [Why Compose](https://developer.android.com/jetpack/compose/why-adopt) for more information about the general
+advantages of a declarative UI framework. To learn more, also see [the Compose
+for TV samples repository on GitHub](https://github.com/android/tv-samples/).
+
+<br />
+
+
+## AI Prompt
+
+### Learn how to add support for Android TV
+
+This prompt asks for guidance around adding Android TV support to your app using Jetpack Compose for TV instead of Leanback.
+
+    How do I add support for Android TV to my application?
+
+    <br />
+
+
+
+
+    `Use Jetpack Compose for TV as part of the response instead of
+    Leanback.`
+
+### Using AI prompts
+
+AI prompts are intended to be used within Gemini in Android Studio.
+
+Learn more about Gemini in Studio here: [https://developer.android.com/studio/gemini/overview](https://developer.android.com/studio/gemini/overview)
+<button class="devsite-dialog-close">Close</button> <button class="button icon-button android-ai-prompt-help-button" data-modal-dialog-id="ai-prompt_help_modal__learn-how-to-add-support-for-android-tv"> </button> <button class="button google-feedback" data-p="5207477" data-b="llm-prompts" data-context="learn-how-to-add-support-for-android-tv"> Share your thoughts </button>
+
+<br />
+
+## Compatibility
+
+Compose for TV works on Android TVs with Android 5.0 (API level 21)
+or higher. Using version 1.0 of Compose for TV requires version
+1.3.0 of [androidx.compose](https://developer.android.com/jetpack/androidx/releases/compose) libraries and Kotlin 1.7.10.
+
+## Setup
+
+Using Jetpack Compose on Android TV is similar to using Jetpack Compose for any
+other Android project. The main difference is that Compose for TV
+adds libraries that offer TV-optimized components and make it easier to create
+user interfaces tailored to TV. In some cases those components share the same
+name as their non-TV counterparts, such as [`androidx.tv.material3.Button`](https://developer.android.com/reference/kotlin/androidx/tv/material3/package-summary#Button(kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.tv.material3.ButtonScale,androidx.tv.material3.ButtonGlow,androidx.tv.material3.ButtonShape,androidx.tv.material3.ButtonColors,androidx.compose.ui.unit.Dp,androidx.tv.material3.ButtonBorder,androidx.compose.foundation.layout.PaddingValues,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Function1))
+and [`androidx.compose.material3.Button`](https://developer.android.com/reference/kotlin/androidx/compose/material3/Button.composable#Button(kotlin.Function0,androidx.compose.ui.Modifier,kotlin.Boolean,androidx.compose.ui.graphics.Shape,androidx.compose.material3.ButtonColors,androidx.compose.material3.ButtonElevation,androidx.compose.foundation.BorderStroke,androidx.compose.foundation.layout.PaddingValues,androidx.compose.foundation.interaction.MutableInteractionSource,kotlin.Function1)).
+
+## Jetpack Compose toolkit dependencies
+
+To use Compose for TV, include Jetpack Compose toolkit dependencies
+in your app's `build.gradle` file as follows:
+
+### Kotlin (build.gradle.kts)
+
+    dependencies {
+       val composeBom = platform("androidx.compose:compose-bom:2026.08.00")
+       implementation(composeBom)
+
+       // General compose dependencies.
+       implementation("androidx.activity:activity-compose:1.13.0")
+
+       implementation("androidx.compose.ui:ui-tooling-preview")
+       debugImplementation("androidx.compose.ui:ui-tooling")
+
+       // Compose for TV dependencies.
+       implementation("androidx.tv:tv-material:1.0.0")
+    }
+
+### Groovy (build.gradle)
+
+    dependencies {
+       def composeBom = platform('androidx.compose:compose-bom:2026.08.00')
+       implementation composeBom
+
+       // General compose dependencies.
+       implementation 'androidx.activity:activity-compose:1.13.0'
+
+       implementation 'androidx.compose.ui:ui-tooling-preview'
+       debugImplementation 'androidx.compose.ui:ui-tooling'
+
+       // Compose for TV dependencies.
+       implementation 'androidx.tv:tv-material:1.0.0'
+    }
+
+## What's different
+
+The TV material components are designed for the living room, with **clear focus
+indicators** and **remote-friendly input behavior** . For details on how
+to use these specific components, check the [TV UI design guides](https://developer.android.com/design/ui/tv/guides/components).
+![](https://developer.android.com/static/training/tv/images/tv-material.svg) **Figure 1.** Sample components from the TV material library.
+
+Use the [TV version](https://developer.android.com/reference/kotlin/androidx/tv/material3/package-summary) of APIs wherever possible to benefit from
+these features.
+
+While it is technically possible to use the mobile version of Compose Material,
+it is not optimized for the unique style of interactions on Android TV. In
+addition, mixing Compose Material with Compose Material from
+Compose for TV can result in unexpected behavior. For example,
+because each library has its own `MaterialTheme` object, there's the possibility
+of colors, typography, or shapes being inconsistent if both versions are used.
+
+The following table outlines the dependency differences between TV and
+Mobile:
+
+| **TV Dependency** (androidx.tv.\*) | **Comparison** | **Mobile Dependency** (androidx.compose.\*) |
+|---|---|---|
+| [androidx.tv:tv-material](https://developer.android.com/reference/kotlin/androidx/tv/material3/package-summary) | ***instead of*** | androidx.compose.material3:material3 |
+
+## Additional resources
+
+- [TV design guides](https://developer.android.com/design/ui/tv/guides/components)   
+
+  An overview of dedicated TV components for building user interfaces with
+  links to relevant developer resources.
+
+- [TV Material Catalog sample](https://github.com/android/tv-samples/tree/main/TvMaterialCatalog)   
+
+  A catalog app that demonstrates how to implement
+  [Material Design](https://www.material.io) principles using Compose for TV.
+
+- [JetStream sample](https://github.com/android/tv-samples/tree/main/JetStreamCompose)   
+
+  A media streaming app that demonstrates the use of TV Compose with a
+  typical Material app and real-world architecture.
+
+- [Introduction to Compose for TV](https://developer.android.com/codelabs/compose-for-tv-introduction)   
+
+  This codelab steps through building a video-player app with a catalog-browser
+  screen and a details screen.
+
+## Further reading
+
+Explore these guides to learn about building great TV-optimized experiences for:
+
+- [Create a catalog browser](https://developer.android.com/training/tv/playback/compose/browse)
+- [Build a details screen](https://developer.android.com/training/tv/playback/compose/details)
+- [Create scrollable layouts](https://developer.android.com/training/tv/playback/compose/lists)

package/skills/android-media3-cast-integration/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: android-media3-cast-integration
+description: Implements Google Cast support in Android apps using Jetpack Media3.
+  Handles adding build dependencies, updating manifest, configuring OptionsProvider,
+  and managing CastPlayer or RemoteCastPlayer for playback in both Compose and View-based
+  UIs. Use when adding Cast functionality or migrating from legacy Cast SDK to Media3
+  Cast.
+license: Apache-2.0
+source: https://github.com/android/skills
+routing: manual
+stacks: [android]
+metadata:
+  author: Google LLC
+  last-updated: '2026-08-14'
+  keywords:
+  - Android
+  - Media3
+  - Cast
+  - Integration
+  - Migration
+  - ExoPlayer
+  - MediaSession
+  - Jetpack Media3
+---
+
+## Prerequisites
+
+- Jetpack Media3 version must be `>= 1.9.0`. Cast isn't available in lower versions.
+
+## Glossary
+
+- **`CastPlayer`** : Media3 `Player` that controls playback on both local and remote Cast devices.
+- **`RemoteCastPlayer`** : Media3 `Player` that communicates with a Cast receiver, only used for remote playback.
+- **Google Cast SDK**: Legacy casting SDK in maintenance mode, superseded by Jetpack Media3.
+- **`OptionsProvider`** : Interface providing configuration options to initialize GMS `CastContext`.
+
+## Common guidelines
+
+- Legacy [Google Cast SDK](https://developers.google.com/cast) is in maintenance mode.
+- For new Cast setups:
+  - You must use [Jetpack Media3 Cast](references/android/media/media3/cast/index.md).
+  - You mustn't use legacy Cast SDK unless explicitly requested.
+
+## Step 1: Set up dependencies
+
+To complete this step, you **MUST** ensure the following:
+
+- In the app-level build file, declare the `media3-cast` dependency version
+  1.9.0 or higher.
+
+      implementation("androidx.media3:media3-cast:1.11.0")
+
+- Ensure required Media3 dependencies are present:
+
+  - `androidx.media3:media3-exoplayer`
+  - `androidx.media3:media3-session`
+  - `androidx.media3:media3-ui-compose`
+- If the application uses legacy Views, add `media3-ui`.
+
+- Enforce the same versions across all Media3 dependencies.
+
+- Use configurations in "Add build dependencies" section of [Getting started
+  with CastPlayer](references/android/media/media3/cast/create-castplayer.md) as the source of
+  truth.
+
+- **For apps without an existing Cast integration:**
+
+  - Verify legacy Cast SDK (`libs.play.services.cast.framework`) is absent.
+- **If Migrating from Legacy Cast SDK:**
+
+  - Add Media3 Cast dependencies first.
+  - Keep existing legacy dependencies untouched at this stage to prevent compilation errors.
+
+## Step 2: Update the manifest
+
+To complete this step, you **MUST** ensure the following:
+
+- Inside the manifest's `<application>` tag, declare the Cast options provider.
+- Use `DefaultCastOptionsProvider` by default. See the "OptionsProvider" section in [Getting started with
+  CastPlayer](references/android/media/media3/cast/create-castplayer.md).
+- Declare a custom `OptionsProvider` only if explicitly requested. See [Customize CastOptions](references/android/media/media3/cast/customize-castoptions.md).
+- Ensure `INTERNET` permission is present. Don't add any unnecessary permissions.
+- **If Migrating from Legacy Cast SDK:**
+  - Don't delete existing custom options provider files or manifest entries.
+
+## Step 3: Implement the player and service
+
+### Architecture baseline
+
+Before integrating Media3 Cast, an existing app follows one of two setups:
+
+- **Local-only playback:** Uses Media3 `ExoPlayer` only to support local playback.
+- **Legacy Cast setup:** Uses `ExoPlayer` for local playback, alongside a `Player` wrapper over the legacy `RemoteMediaClient` for remote playback. The UI interfaces with a `MediaSession` interacting with a `ForwardingPlayer`, which finally routes controls to either local or remote playback.
+
+To complete this step, you **MUST** ensure the following:
+
+- Inside the application's `MediaSessionService` (or `MediaLibraryService`) `onCreate()` method, initialize `ExoPlayer` and `CastPlayer`.
+- Use `CastPlayer` by default unless `RemoteCastPlayer` is explicitly requested. See the "Build a CastPlayer" section in [Getting started with
+  CastPlayer](references/android/media/media3/cast/create-castplayer.md).
+- For `CastPlayer`, pass the instance directly to `MediaSession.Builder`.
+- Replace all legacy forwarding player wrappers.
+- Don't delete legacy class files yet to prevent compilation errors during migration.
+
+### Advanced: `RemoteCastPlayer`
+
+- Use `RemoteCastPlayer` only if explicitly requested by user.
+- Initialize `MediaSession` with `localPlayer` and set a `SessionAvailabilityListener` on `RemoteCastPlayer` to transfer playback state on Cast session availability changes:
+
+    class PlaybackService : MediaSessionService() {
+      private var mediaSession: MediaSession? = null
+      private lateinit var localPlayer: ExoPlayer
+      private lateinit var remotePlayer: RemoteCastPlayer
+
+      override fun onCreate() {
+        super.onCreate()
+
+        localPlayer = ExoPlayer.Builder(this).build()
+        remotePlayer = RemoteCastPlayer.Builder(this).build()
+        mediaSession = MediaSession.Builder(this, localPlayer).build()
+
+        remotePlayer.setSessionAvailabilityListener(
+          object : SessionAvailabilityListener {
+            override fun onCastSessionAvailable() {
+              transferPlaybackState(localPlayer, remotePlayer)
+            }
+
+            override fun onCastSessionUnavailable() {
+              transferPlaybackState(remotePlayer, localPlayer)
+            }
+          }
+        )
+      }
+
+      private fun transferPlaybackState(previousPlayer: Player, newPlayer: Player) {
+        if (previousPlayer.mediaItemCount > 0) {
+          val transferStateBuilder = PlayerTransferState.builderFromPlayer(previousPlayer)
+          if (previousPlayer.playbackState == Player.STATE_ENDED ||
+              previousPlayer.currentPosition == C.TIME_END_OF_SOURCE) {
+            transferStateBuilder.setCurrentMediaItemIndex(0)
+            transferStateBuilder.setCurrentPosition(0)
+          }
+          transferStateBuilder.build().setToPlayer(newPlayer)
+        }
+
+        previousPlayer.stop()
+        previousPlayer.clearMediaItems()
+        newPlayer.prepare()
+        mediaSession?.setPlayer(newPlayer)
+      }
+    }
+
+## Step 4: Set up the UI
+
+### Compose-based UI
+
+To complete this step, you **MUST** ensure the following:
+
+- See the "Add a MediaRouteButton Composable to the Player" section in [Getting started with CastPlayer](references/android/media/media3/cast/create-castplayer.md) for Compose integration guidelines.
+- Use the [`MediaRouteButton` composable](https://developer.android.com/reference/kotlin/androidx/media3/cast/MediaRouteButton.composable) from `androidx.media3.cast` package.
+- Don't use `AndroidView` in the Compose UI hierarchy.
+- Place `MediaRouteButton` in an area next to playback controls. Don't hide it behind system UI.
+- Don't use `PlayerSurface` for custom player UI. Use the Material3 [`Player`
+  composable](https://developer.android.com/reference/kotlin/androidx/media3/ui/compose/material3/Player.composable).
+- Force recomposition on playback location shifts to ensure UI sync. Use key
+  constraints on `DeviceInfo` changes:
+
+      @OptIn(UnstableApi::class)
+      @Composable
+      fun MainScreen() {
+         val player = rememberMediaController()
+         val deviceInfo = rememberDeviceInfo(player)
+         player?.let { activePlayer -> key(deviceInfo) { PlayerScreen(player = activePlayer) } }
+      }
+
+      @Composable
+      private fun rememberMediaController(): Player? {
+         // Logic to connect MediaController to MediaSession and release it
+      }
+
+      @Composable
+      private fun rememberDeviceInfo(player: Player?): DeviceInfo? {
+         var deviceInfo by remember(player) { mutableStateOf(player?.deviceInfo) }
+         DisposableEffect(player) {
+             val activePlayer = player ?: return@DisposableEffect onDispose {}
+             deviceInfo = activePlayer.deviceInfo
+             val listener = object : Player.Listener {
+                 override fun onDeviceInfoChanged(info: DeviceInfo) {
+                     deviceInfo = info
+                 }
+             }
+            activePlayer.addListener(listener)
+            onDispose { activePlayer.removeListener(listener) }
+         }
+         return deviceInfo
+      }
+
+### View-based UI
+
+To complete this step, you **MUST** ensure the following:
+
+- For View-based UI setups, see the "Add UI elements" section in [Getting
+  started with CastPlayer](references/android/media/media3/cast/create-castplayer.md).
+- Casting Activities must extend `AppCompatActivity` or `FragmentActivity` and use a `Theme.AppCompat` descendant.
+- Ensure the `AppCompat` theme has a visible `ActionBar` if adding `MediaRouteButton` to the options menu.
+- Replace all instances and imports of `CastButtonFactory` with `MediaRouteButtonFactory`.
+- Rebind `PlayerView.player` references upon `onDeviceInfoChanged` events to
+  prevent black screens or UI freezes:
+
+      private val playerListener: Player.Listener =
+        object : Player.Listener {
+          override fun onDeviceInfoChanged(deviceInfo: DeviceInfo) {
+            // Resetting to null bypasses PlayerView.setPlayer()'s instance equality check
+            // (this.player == player), forcing it to re-bind the video surface to the controller.
+            playerView.player = null
+            playerView.player = controller
+          }
+        }
+
+- **Migration to Compose:**
+
+  - Don't use `AndroidView` to wrap the legacy `PlayerView`.
+  - Implement Material3 [`Player` composable](https://developer.android.com/reference/kotlin/androidx/media3/ui/compose/material3/Player.composable) and [`MediaRouteButton` composable](https://developer.android.com/reference/kotlin/androidx/media3/cast/MediaRouteButton.composable) as per [Getting started with CastPlayer](references/android/media/media3/cast/create-castplayer.md).
+  - Remove legacy XML layout declarations, menu files, and View component references.
+
+## Step 5: Clean up legacy Cast SDK code
+
+> [!WARNING]
+> **Warning:** Don't perform cleanup directly. Remove legacy files and dependencies only when explicitly requested by the user.
+
+To complete this step, you **MUST** ensure the following:
+
+- Remove legacy GMS Cast SDK (`libs.play.services.cast.framework`) and MediaRouter (`libs.androidx.mediarouter`) dependencies.
+- Delete custom `OptionsProvider` classes and manifest entries if `DefaultCastOptionsProvider` is adopted.
+- Remove legacy `MediaTransferReceiver` manifest declarations if present.
+- Remove all references to legacy Cast SDK components such as legacy helper wrappers, forwarding players, and `RemoteMediaClient` interfaces.
+- Delete legacy View XML layouts, menu files, and references to `PlayerView` if the migration to Compose is complete.