media3-cast-integration

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 is in maintenance mode.
For new Cast setups:
- You must use Jetpack Media3 Cast.
- 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.10.1")
```

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 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.
Declare a custom
```
OptionsProvider
```
only if explicitly requested. See Customize CastOptions.
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.
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

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 for Compose integration guidelines.
Use the
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
.

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.
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
  and
  MediaRouteButton
  composable
  as per Getting started with CastPlayer.
- 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.

media3-cast-integration

NPX Install

Tags

SKILL.md Content

Prerequisites

Glossary

Common guidelines

Step 1: Set up dependencies

Step 2: Update the manifest

Step 3: Implement the player and service

Architecture baseline

Advanced:
`RemoteCastPlayer`

Step 4: Set up the UI

Compose-based UI

View-based UI

Step 5: Clean up legacy Cast SDK code