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 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