Extend Player interface, overloading 4 device-volume methods with flags

Previously, ExoPlayerImpl had volume flags hardcoded to SHOW_UI, but now the developer can choose what happens on volume change. The old methods have been deprecated.

PiperOrigin-RevId: 523974358

Author: oceanjules

extensions/cast/build.gradle

@@ -14,7 +14,7 @@
 apply from: "$gradle.ext.exoplayerSettingsDir/common_library_config.gradle"
 
 dependencies {
-    api 'com.google.android.gms:play-services-cast-framework:21.2.0'
+    api 'com.google.android.gms:play-services-cast-framework:21.3.0'
     implementation 'androidx.annotation:annotation:' + androidxAnnotationVersion
     implementation project(modulePrefix + 'library-common')
     compileOnly 'org.checkerframework:checker-qual:' + checkerframeworkVersion

extensions/cast/src/main/java/com/google/android/exoplayer2/ext/cast/CastPlayer.java

@@ -753,22 +753,50 @@ public boolean isDeviceMuted() {
     return false;
   }
 
-  /** This method is not supported and does nothing. */
+  /**
+   * @deprecated Use {@link #setDeviceVolume(int, int)} instead.
+   */
+  @Deprecated
   @Override
   public void setDeviceVolume(int volume) {}
 
   /** This method is not supported and does nothing. */
   @Override
+  public void setDeviceVolume(int volume, @C.VolumeFlags int flags) {}
+
+  /**
+   * @deprecated Use {@link #increaseDeviceVolume(int)} instead.
+   */
+  @Deprecated
+  @Override
   public void increaseDeviceVolume() {}
 
   /** This method is not supported and does nothing. */
   @Override
+  public void increaseDeviceVolume(@C.VolumeFlags int flags) {}
+
+  /**
+   * @deprecated Use {@link #decreaseDeviceVolume(int)} instead.
+   */
+  @Deprecated
+  @Override
   public void decreaseDeviceVolume() {}
 
   /** This method is not supported and does nothing. */
   @Override
+  public void decreaseDeviceVolume(@C.VolumeFlags int flags) {}
+
+  /**
+   * @deprecated Use {@link #setDeviceMuted(boolean, int)} instead.
+   */
+  @Deprecated
+  @Override
   public void setDeviceMuted(boolean muted) {}
 
+  /** This method is not supported and does nothing. */
+  @Override
+  public void setDeviceMuted(boolean muted, @C.VolumeFlags int flags) {}
+
   // Internal methods.
 
   // Call deprecated callbacks.

library/common/src/main/java/com/google/android/exoplayer2/C.java

@@ -404,6 +404,37 @@ private C() {}
   /** The default stream type used by audio renderers. Equal to {@link #STREAM_TYPE_MUSIC}. */
   public static final int STREAM_TYPE_DEFAULT = STREAM_TYPE_MUSIC;
 
+  /**
+   * Volume flags to be used when setting or adjusting device volume. The value can be either 0 or a
+   * combination of the following flags: {@link #VOLUME_FLAG_SHOW_UI}, {@link
+   * #VOLUME_FLAG_ALLOW_RINGER_MODES}, {@link #VOLUME_FLAG_PLAY_SOUND}, {@link
+   * #VOLUME_FLAG_REMOVE_SOUND_AND_VIBRATE}, {@link #VOLUME_FLAG_VIBRATE}.
+   */
+  @Documented
+  @Retention(RetentionPolicy.SOURCE)
+  @Target({TYPE_USE})
+  @IntDef(
+      flag = true,
+      value = {
+        VOLUME_FLAG_SHOW_UI,
+        VOLUME_FLAG_ALLOW_RINGER_MODES,
+        VOLUME_FLAG_PLAY_SOUND,
+        VOLUME_FLAG_REMOVE_SOUND_AND_VIBRATE,
+        VOLUME_FLAG_VIBRATE,
+      })
+  public @interface VolumeFlags {}
+  /** See {@link AudioManager#FLAG_SHOW_UI}. */
+  public static final int VOLUME_FLAG_SHOW_UI = AudioManager.FLAG_SHOW_UI;
+  /** See {@link AudioManager#FLAG_ALLOW_RINGER_MODES}. */
+  public static final int VOLUME_FLAG_ALLOW_RINGER_MODES = AudioManager.FLAG_ALLOW_RINGER_MODES;
+  /** See {@link AudioManager#FLAG_PLAY_SOUND}. */
+  public static final int VOLUME_FLAG_PLAY_SOUND = AudioManager.FLAG_PLAY_SOUND;
+  /** See {@link AudioManager#FLAG_REMOVE_SOUND_AND_VIBRATE}. */
+  public static final int VOLUME_FLAG_REMOVE_SOUND_AND_VIBRATE =
+      AudioManager.FLAG_REMOVE_SOUND_AND_VIBRATE;
+  /** See {@link AudioManager#FLAG_VIBRATE}. */
+  public static final int VOLUME_FLAG_VIBRATE = AudioManager.FLAG_VIBRATE;
+
   /**
    * Content types for audio attributes. One of:
    *

library/common/src/main/java/com/google/android/exoplayer2/ForwardingPlayer.java

@@ -848,30 +848,66 @@ public boolean isDeviceMuted() {
     return player.isDeviceMuted();
   }
 
-  /** Calls {@link Player#setDeviceVolume(int)} on the delegate. */
+  /**
+   * @deprecated Use {@link #setDeviceVolume(int, int)} instead.
+   */
+  @Deprecated
   @Override
   public void setDeviceVolume(int volume) {
     player.setDeviceVolume(volume);
   }
 
-  /** Calls {@link Player#increaseDeviceVolume()} on the delegate. */
+  /** Calls {@link Player#setDeviceVolume(int, int)} on the delegate. */
+  @Override
+  public void setDeviceVolume(int volume, @C.VolumeFlags int flags) {
+    player.setDeviceVolume(volume, flags);
+  }
+
+  /**
+   * @deprecated Use {@link #increaseDeviceVolume(int)} instead.
+   */
+  @Deprecated
   @Override
   public void increaseDeviceVolume() {
     player.increaseDeviceVolume();
   }
 
-  /** Calls {@link Player#decreaseDeviceVolume()} on the delegate. */
+  /** Calls {@link Player#increaseDeviceVolume(int)} on the delegate. */
+  @Override
+  public void increaseDeviceVolume(@C.VolumeFlags int flags) {
+    player.increaseDeviceVolume(flags);
+  }
+
+  /**
+   * @deprecated Use {@link #decreaseDeviceVolume(int)} instead.
+   */
+  @Deprecated
   @Override
   public void decreaseDeviceVolume() {
     player.decreaseDeviceVolume();
   }
 
-  /** Calls {@link Player#setDeviceMuted(boolean)} on the delegate. */
+  /** Calls {@link Player#decreaseDeviceVolume(int)} on the delegate. */
+  @Override
+  public void decreaseDeviceVolume(@C.VolumeFlags int flags) {
+    player.decreaseDeviceVolume(flags);
+  }
+
+  /**
+   * @deprecated Use {@link #setDeviceMuted(boolean, int)} instead.
+   */
+  @Deprecated
   @Override
   public void setDeviceMuted(boolean muted) {
     player.setDeviceMuted(muted);
   }
 
+  /** Calls {@link Player#setDeviceMuted(boolean, int)} on the delegate. */
+  @Override
+  public void setDeviceMuted(boolean muted, @C.VolumeFlags int flags) {
+    player.setDeviceMuted(muted, flags);
+  }
+
   /** Returns the {@link Player} to which operations are forwarded. */
   public Player getWrappedPlayer() {
     return player;

library/common/src/main/java/com/google/android/exoplayer2/Player.java

@@ -378,7 +378,9 @@ public static final class Builder {
         COMMAND_GET_DEVICE_VOLUME,
         COMMAND_SET_VOLUME,
         COMMAND_SET_DEVICE_VOLUME,
+        COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS,
         COMMAND_ADJUST_DEVICE_VOLUME,
+        COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS,
         COMMAND_SET_VIDEO_SURFACE,
         COMMAND_GET_TEXT,
         COMMAND_SET_TRACK_SELECTION_PARAMETERS,
@@ -1426,7 +1428,9 @@ default void onMetadata(Metadata metadata) {}
    *   <li>{@link #COMMAND_GET_DEVICE_VOLUME}
    *   <li>{@link #COMMAND_SET_VOLUME}
    *   <li>{@link #COMMAND_SET_DEVICE_VOLUME}
+   *   <li>{@link #COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS}
    *   <li>{@link #COMMAND_ADJUST_DEVICE_VOLUME}
+   *   <li>{@link #COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS}
    *   <li>{@link #COMMAND_SET_VIDEO_SURFACE}
    *   <li>{@link #COMMAND_GET_TEXT}
    *   <li>{@link #COMMAND_SET_TRACK_SELECTION_PARAMETERS}
@@ -1470,7 +1474,9 @@ default void onMetadata(Metadata metadata) {}
     COMMAND_GET_DEVICE_VOLUME,
     COMMAND_SET_VOLUME,
     COMMAND_SET_DEVICE_VOLUME,
+    COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS,
     COMMAND_ADJUST_DEVICE_VOLUME,
+    COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS,
     COMMAND_SET_VIDEO_SURFACE,
     COMMAND_GET_TEXT,
     COMMAND_SET_TRACK_SELECTION_PARAMETERS,
@@ -1776,27 +1782,36 @@ default void onMetadata(Metadata metadata) {}
    * #isCommandAvailable(int) available}.
    */
   int COMMAND_SET_VOLUME = 24;
+
+  /**
+   * @deprecated Use {@link #COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS} instead.
+   */
+  @Deprecated int COMMAND_SET_DEVICE_VOLUME = 25;
   /**
-   * Command to set the device volume.
+   * Command to set the device volume with volume flags.
    *
-   * <p>The {@link #setDeviceVolume(int)} method must only be called if this command is {@linkplain
-   * #isCommandAvailable(int) available}.
+   * <p>The {@link #setDeviceVolume(int, int)} method must only be called if this command is
+   * {@linkplain #isCommandAvailable(int) available}.
    */
-  int COMMAND_SET_DEVICE_VOLUME = 25;
+  int COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS = 33;
 
   /**
-   * Command to increase and decrease the device volume and mute it.
+   * @deprecated Use {@link #COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS} instead.
+   */
+  @Deprecated int COMMAND_ADJUST_DEVICE_VOLUME = 26;
+  /**
+   * Command to increase and decrease the device volume and mute it with volume flags.
    *
    * <p>The following methods must only be called if this command is {@linkplain
    * #isCommandAvailable(int) available}:
    *
    * <ul>
-   *   <li>{@link #increaseDeviceVolume()}
-   *   <li>{@link #decreaseDeviceVolume()}
-   *   <li>{@link #setDeviceMuted(boolean)}
+   *   <li>{@link #increaseDeviceVolume(int)}
+   *   <li>{@link #decreaseDeviceVolume(int)}
+   *   <li>{@link #setDeviceMuted(boolean, int)}
    * </ul>
    */
-  int COMMAND_ADJUST_DEVICE_VOLUME = 26;
+  int COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS = 34;
 
   /**
    * Command to set and clear the surface on which to render the video.
@@ -3067,36 +3082,68 @@ default void onMetadata(Metadata metadata) {}
   boolean isDeviceMuted();
 
   /**
-   * Sets the volume of the device.
+   * @deprecated Use {@link #setDeviceVolume(int, int)} instead.
+   */
+  @Deprecated
+  void setDeviceVolume(@IntRange(from = 0) int volume);
+
+  /**
+   * Sets the volume of the device with volume flags.
    *
-   * <p>This method must only be called if {@link #COMMAND_SET_DEVICE_VOLUME} is {@linkplain
-   * #getAvailableCommands() available}.
+   * <p>This method must only be called if {@link #COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS} is
+   * {@linkplain #getAvailableCommands() available}.
    *
    * @param volume The volume to set.
+   * @param flags Either 0 or a bitwise combination of one or more {@link C.VolumeFlags}.
    */
-  void setDeviceVolume(@IntRange(from = 0) int volume);
+  void setDeviceVolume(@IntRange(from = 0) int volume, int flags);
+
+  /**
+   * @deprecated Use {@link #increaseDeviceVolume(int)} instead.
+   */
+  @Deprecated
+  void increaseDeviceVolume();
 
   /**
    * Increases the volume of the device.
    *
-   * <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME} is {@linkplain
-   * #getAvailableCommands() available}.
+   * <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS} is
+   * {@linkplain #getAvailableCommands() available}.
+   *
+   * @param flags Either 0 or a bitwise combination of one or more {@link C.VolumeFlags}.
    */
-  void increaseDeviceVolume();
+  void increaseDeviceVolume(@C.VolumeFlags int flags);
+
+  /**
+   * @deprecated Use {@link #decreaseDeviceVolume(int)} instead.
+   */
+  @Deprecated
+  void decreaseDeviceVolume();
 
   /**
    * Decreases the volume of the device.
    *
-   * <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME} is {@linkplain
-   * #getAvailableCommands() available}.
+   * <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS} is
+   * {@linkplain #getAvailableCommands() available}.
+   *
+   * @param flags Either 0 or a bitwise combination of one or more {@link C.VolumeFlags}.
    */
-  void decreaseDeviceVolume();
+  void decreaseDeviceVolume(@C.VolumeFlags int flags);
+
+  /**
+   * @deprecated Use {@link #setDeviceMuted(boolean, int)} instead.
+   */
+  @Deprecated
+  void setDeviceMuted(boolean muted);
 
   /**
    * Sets the mute state of the device.
    *
-   * <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME} is {@linkplain
-   * #getAvailableCommands() available}.
+   * <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS} is
+   * {@linkplain #getAvailableCommands() available}.
+   *
+   * @param muted Whether to set the device to be muted or not
+   * @param flags Either 0 or a bitwise combination of one or more {@link C.VolumeFlags}.
    */
-  void setDeviceMuted(boolean muted);
+  void setDeviceMuted(boolean muted, @C.VolumeFlags int flags);
 }