Add suport for local playback in CastPlayer

AquilesCanta · copybara-github · commit bb105d3f9163 · 2025-07-08T11:31:58.000-07:00
API users can access the new functionality by creating a CastPlayer
instance using the new builder. Existing constructors keep their
previous behavior.

The new functionality to handle both Cast and local playback
simultaneously is implemented by CastPlayerImpl, which delegates
playback to a local player or a RemoteCastPlayer instance, depending
on the availability of a CastSession.

PiperOrigin-RevId: 780647424
diff --git a/RELEASENOTES.md b/RELEASENOTES.md
@@ -64,6 +64,11 @@
 *   MIDI extension:
 *   Leanback extension:
 *   Cast extension:
+    *   Add `CastPlayer.Builder`, which enables `CastPlayer` to do both local
+        and Cast playback. To keep the old `CastPlayer` behavior of supporting
+        only Cast playback, you can use `RemoteCastPlayer`. The pre-existing
+        `CastPlayer` constructors keep their old behavior, but are deprecated in
+        favour of using the `CastPlayer` or `RemoteCastPlayer` builders instead.
 *   Test Utilities:
 *   Remove deprecated symbols:
 
diff --git a/libraries/cast/build.gradle b/libraries/cast/build.gradle
@@ -27,6 +27,7 @@ dependencies {
     api 'com.google.android.gms:play-services-cast-framework:21.5.0'
     implementation 'androidx.annotation:annotation:' + androidxAnnotationVersion
     api project(modulePrefix + 'lib-common')
+    api project(modulePrefix + 'lib-exoplayer')
     compileOnly 'com.google.errorprone:error_prone_annotations:' + errorProneVersion
     compileOnly 'org.checkerframework:checker-qual:' + checkerframeworkVersion
     compileOnly 'org.jetbrains.kotlin:kotlin-annotations-jvm:' + kotlinAnnotationsVersion
diff --git a/libraries/cast/src/main/java/androidx/media3/cast/CastPlayer.java b/libraries/cast/src/main/java/androidx/media3/cast/CastPlayer.java
@@ -15,6 +15,8 @@
  */
 package androidx.media3.cast;
 
+import static androidx.media3.common.util.Assertions.checkNotNull;
+
 import android.content.Context;
 import androidx.annotation.IntRange;
 import androidx.annotation.Nullable;
@@ -23,19 +25,154 @@
 import androidx.media3.common.ForwardingPlayer;
 import androidx.media3.common.MediaItem;
 import androidx.media3.common.Player;
+import androidx.media3.common.PlayerTransferState;
+import androidx.media3.common.util.Assertions;
 import androidx.media3.common.util.UnstableApi;
+import androidx.media3.exoplayer.ExoPlayer;
 import com.google.android.gms.cast.framework.CastContext;
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
 
 /**
- * {@link Player} implementation that communicates with a Cast receiver app.
+ * {@link Player} implementation that can control playback both on the local device, and on a remote
+ * Cast device.
+ *
+ * <p>See {@link RemoteCastPlayer} for a {@link Player} that only supports playback on Cast
+ * receivers.
+ *
+ * <p>This class works by delegating playback to a dedicated player depending on Cast session
+ * availability. When a Cast session becomes available or unavailable, the following steps take
+ * place:
  *
- * <p>This class is a passthrough wrapper of {@link RemoteCastPlayer}.
+ * <ul>
+ *   <li>The new active player is a {@link RemoteCastPlayer} if a Cast session is active, or the
+ *       {@link Builder#setLocalPlayer local player} otherwise.
+ *   <li>A customizable {@link TransferCallback} receives both players to transfer state across
+ *       players.
+ *   <li>The inactive player is {@link Player#stop() stopped}.
+ * </ul>
  */
-// TODO: b/419816002 - Deprecate constructors in this class and update javadocs once
-// RemoteCastPlayer has a Builder, and this class is able to support local playback.
 @UnstableApi
 public final class CastPlayer extends ForwardingPlayer {
 
+  /**
+   * Callback for moving state across players when transferring playback upon Cast session
+   * availability changes.
+   */
+  public interface TransferCallback {
+
+    TransferCallback DEFAULT =
+        (sourcePlayer, targetPlayer) ->
+            PlayerTransferState.fromPlayer(sourcePlayer).setToPlayer(targetPlayer);
+
+    /**
+     * Called immediately before changing the active {@link Player}, with the intended use of
+     * transferring playback state.
+     *
+     * @param sourcePlayer The {@link Player} from which playback is transferring, from which to
+     *     fetch the state.
+     * @param targetPlayer The {@link Player} to which playback is transferring, to populate with
+     *     state.
+     * @see PlayerTransferState
+     */
+    void transferState(Player sourcePlayer, Player targetPlayer);
+  }
+
+  /** Builder for {@link CastPlayer}. */
+  public static final class Builder {
+
+    private final Context context;
+    private TransferCallback transferCallback;
+    private @MonotonicNonNull Player localPlayer;
+    private @MonotonicNonNull RemoteCastPlayer remotePlayer;
+    private boolean buildCalled;
+
+    /**
+     * Creates a builder.
+     *
+     * <p>The builder uses the following default values:
+     *
+     * <ul>
+     *   <li>{@link TransferCallback}: {@link TransferCallback#DEFAULT}.
+     *   <li>{@link RemoteCastPlayer}: {@link RemoteCastPlayer new
+     *       RemoteCastPlayer.Builder(context).build()}.
+     *   <li>{@link #setLocalPlayer}: {@link ExoPlayer new ExoPlayer.Builder(context).build()}.
+     * </ul>
+     *
+     * @param context A {@link Context}.
+     */
+    public Builder(Context context) {
+      this.context = checkNotNull(context);
+      transferCallback = TransferCallback.DEFAULT;
+    }
+
+    /**
+     * Sets the {@link TransferCallback} to call when the active player changes.
+     *
+     * @param transferCallback A {@link TransferCallback}.
+     * @return This builder.
+     * @throws IllegalStateException If {@link #build()} has already been called on this builder
+     *     instance.
+     */
+    @CanIgnoreReturnValue
+    public Builder setTransferCallback(TransferCallback transferCallback) {
+      Assertions.checkState(!buildCalled);
+      this.transferCallback = checkNotNull(transferCallback);
+      return this;
+    }
+
+    /**
+     * Sets the {@link Player} to use for local playback.
+     *
+     * @param localPlayer A {@link Player}.
+     * @return This builder.
+     * @throws IllegalStateException If {@link #build()} has already been called on this builder
+     *     instance.
+     */
+    @CanIgnoreReturnValue
+    public Builder setLocalPlayer(Player localPlayer) {
+      Assertions.checkState(!buildCalled);
+      this.localPlayer = checkNotNull(localPlayer);
+      return this;
+    }
+
+    /**
+     * Sets the {@link RemoteCastPlayer} to use for remote playback.
+     *
+     * @param remotePlayer A {@link RemoteCastPlayer}.
+     * @return This builder.
+     * @throws IllegalStateException If {@link #build()} has already been called on this builder
+     *     instance.
+     */
+    @CanIgnoreReturnValue
+    public Builder setRemotePlayer(RemoteCastPlayer remotePlayer) {
+      Assertions.checkState(!buildCalled);
+      this.remotePlayer = checkNotNull(remotePlayer);
+      return this;
+    }
+
+    /**
+     * Creates and returns the new {@link CastPlayerImpl} instance.
+     *
+     * @throws IllegalStateException If this method has already been called on this instance.
+     */
+    public CastPlayer build() {
+      Assertions.checkState(!buildCalled);
+      buildCalled = true;
+      if (localPlayer == null) {
+        localPlayer = new ExoPlayer.Builder(context).build();
+      }
+      if (remotePlayer == null) {
+        remotePlayer = new RemoteCastPlayer.Builder(context).build();
+      }
+      Player initialActivePlayer =
+          remotePlayer.isCastSessionAvailable() ? remotePlayer : localPlayer;
+      CastPlayerImpl castPlayerImpl =
+          new CastPlayerImpl(localPlayer, remotePlayer, initialActivePlayer, transferCallback);
+      return new CastPlayer(castPlayerImpl, remotePlayer);
+    }
+  }
+
   /** Same as {@link RemoteCastPlayer#DEVICE_INFO_REMOTE_EMPTY}. */
   public static final DeviceInfo DEVICE_INFO_REMOTE_EMPTY =
       RemoteCastPlayer.DEVICE_INFO_REMOTE_EMPTY;
@@ -65,7 +202,11 @@ public CastPlayer(CastContext castContext) {
    *
    * @param castContext The context from which the cast session is obtained.
    * @param mediaItemConverter The {@link MediaItemConverter} to use.
+   * @deprecated Use {@link RemoteCastPlayer.Builder} to create a {@link Player} for playback
+   *     exclusively on Cast receivers, or {@link Builder} for a {@link Player} that works both on
+   *     Cast receivers and locally.
    */
+  @Deprecated
   public CastPlayer(CastContext castContext, MediaItemConverter mediaItemConverter) {
     this(
         castContext,
@@ -83,7 +224,11 @@ public CastPlayer(CastContext castContext, MediaItemConverter mediaItemConverter
    * @param seekForwardIncrementMs The {@link #seekForward()} increment, in milliseconds.
    * @throws IllegalArgumentException If {@code seekBackIncrementMs} or {@code
    *     seekForwardIncrementMs} is non-positive.
+   * @deprecated Use {@link RemoteCastPlayer.Builder} to create a {@link Player} for playback
+   *     exclusively on Cast receivers, or {@link Builder} for a {@link Player} that works both on
+   *     Cast receivers and locally.
    */
+  @Deprecated
   public CastPlayer(
       CastContext castContext,
       MediaItemConverter mediaItemConverter,
@@ -112,7 +257,11 @@ public CastPlayer(
    * @throws IllegalArgumentException If {@code seekBackIncrementMs} or {@code
    *     seekForwardIncrementMs} is non-positive, or if {@code maxSeekToPreviousPositionMs} is
    *     negative.
+   * @deprecated Use {@link RemoteCastPlayer.Builder} to create a {@link Player} for playback
+   *     exclusively on Cast receivers, or {@link Builder} for a {@link Player} that works both on
+   *     Cast receivers and locally.
    */
+  @Deprecated
   public CastPlayer(
       @Nullable Context context,
       CastContext castContext,
@@ -135,7 +284,18 @@ private CastPlayer(RemoteCastPlayer remoteCastPlayer) {
     this.remoteCastPlayer = remoteCastPlayer;
   }
 
-  /** Returns whether a cast session is available. */
+  private CastPlayer(CastPlayerImpl castPlayerImpl, RemoteCastPlayer remoteCastPlayer) {
+    super(castPlayerImpl);
+    this.remoteCastPlayer = remoteCastPlayer;
+  }
+
+  /**
+   * Returns whether a cast session is available.
+   *
+   * @deprecated Use {@link #getDeviceInfo()} instead, and check for {@link
+   *     DeviceInfo#PLAYBACK_TYPE_REMOTE}.
+   */
+  @Deprecated
   public boolean isCastSessionAvailable() {
     return remoteCastPlayer.isCastSessionAvailable();
   }
@@ -144,7 +304,10 @@ public boolean isCastSessionAvailable() {
    * Sets a listener for updates on the cast session availability.
    *
    * @param listener The {@link SessionAvailabilityListener}, or null to clear the listener.
+   * @deprecated Use {@link androidx.media3.common.Player.Listener#onDeviceInfoChanged} instead, and
+   *     check for {@link DeviceInfo#PLAYBACK_TYPE_REMOTE}.
    */
+  @Deprecated
   public void setSessionAvailabilityListener(@Nullable SessionAvailabilityListener listener) {
     remoteCastPlayer.setSessionAvailabilityListener(listener);
   }
diff --git a/libraries/cast/src/main/java/androidx/media3/cast/CastPlayerImpl.java b/libraries/cast/src/main/java/androidx/media3/cast/CastPlayerImpl.java
@@ -0,0 +1,103 @@
+/*
+ * Copyright 2025 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package androidx.media3.cast;
+
+import androidx.media3.common.ForwardingSimpleBasePlayer;
+import androidx.media3.common.Player;
+import com.google.common.util.concurrent.Futures;
+import com.google.common.util.concurrent.ListenableFuture;
+
+/**
+ * Contains the implementation details of {@link CastPlayer}, when created using {@link
+ * CastPlayer.Builder}.
+ *
+ * <p>When created using the constructors, {@link CastPlayer} behaves as a thin wrapper of {@link
+ * RemoteCastPlayer}, for API backwards compatibility. When created using {@link
+ * CastPlayer.Builder}, {@link CastPlayer} will wrap this class instead, making it support both
+ * local and remote playback, unlike {@link RemoteCastPlayer}, which supports only remote playback.
+ */
+/* package */ final class CastPlayerImpl extends ForwardingSimpleBasePlayer {
+
+  private final Player localPlayer;
+  private final RemoteCastPlayer remotePlayer;
+  private final CastPlayer.TransferCallback transferCallback;
+  private final SessionAvailabilityListener sessionAvailabilityListener;
+
+  public CastPlayerImpl(
+      Player localPlayer,
+      RemoteCastPlayer remotePlayer,
+      Player initialActivePlayer,
+      CastPlayer.TransferCallback transferCallback) {
+    super(initialActivePlayer);
+    this.localPlayer = localPlayer;
+    this.remotePlayer = remotePlayer;
+    this.transferCallback = transferCallback;
+    sessionAvailabilityListener = new SessionAvailabilityListenerImpl();
+    remotePlayer.setInternalSessionAvailabilityListener(sessionAvailabilityListener);
+  }
+
+  private void updateActivePlayer() {
+    Player previousPlayer = getPlayer();
+    Player newPlayer = remotePlayer.isCastSessionAvailable() ? remotePlayer : localPlayer;
+    if (previousPlayer == newPlayer) {
+      return;
+    }
+    transferCallback.transferState(previousPlayer, newPlayer);
+    previousPlayer.stop();
+    setPlayer(newPlayer);
+  }
+
+  // SimpleBasePlayer implementation.
+
+  @Override
+  protected State getState() {
+    State currentState = super.getState();
+    Commands availableCommands = currentState.availableCommands;
+    if (!availableCommands.contains(COMMAND_RELEASE)) {
+      // This player implementation supports release regardless of the forwarded Player, but we only
+      // recreate the state when necessary. So as to avoid unnecessarily recreating the state object
+      // every time.
+      Commands newCommands = availableCommands.buildUpon().add(COMMAND_RELEASE).build();
+      currentState = currentState.buildUpon().setAvailableCommands(newCommands).build();
+    }
+    return currentState;
+  }
+
+  @Override
+  protected ListenableFuture<?> handleRelease() {
+    remotePlayer.release();
+    remotePlayer.setInternalSessionAvailabilityListener(null);
+    if (localPlayer.isCommandAvailable(COMMAND_RELEASE)) {
+      localPlayer.release();
+    }
+    return Futures.immediateVoidFuture();
+  }
+
+  // Internal classes.
+
+  private class SessionAvailabilityListenerImpl implements SessionAvailabilityListener {
+
+    @Override
+    public void onCastSessionAvailable() {
+      updateActivePlayer();
+    }
+
+    @Override
+    public void onCastSessionUnavailable() {
+      updateActivePlayer();
+    }
+  }
+}
diff --git a/libraries/cast/src/main/java/androidx/media3/cast/RemoteCastPlayer.java b/libraries/cast/src/main/java/androidx/media3/cast/RemoteCastPlayer.java
diff --git a/libraries/cast/src/test/java/androidx/media3/cast/CastPlayerTest.java b/libraries/cast/src/test/java/androidx/media3/cast/CastPlayerTest.java
