From 4f4335943cda6c189cc4ca1ec70a5a21c058af35 Mon Sep 17 00:00:00 2001
From: tonihei <tonihei@google.com>
Date: Fri, 22 Sep 2023 06:27:05 -0700
Subject: [PATCH] Cross-reference per-stream volume methods from device volume
 methods

The per-stream methods are generally preferred and having a reference
to them from the device-wide methods may help with discoverability.

Issue: google/ExoPlayer#11295
PiperOrigin-RevId: 567604785
---
 .../java/androidx/media3/common/Player.java    | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/libraries/common/src/main/java/androidx/media3/common/Player.java b/libraries/common/src/main/java/androidx/media3/common/Player.java
index 793f30bbb5..3a631280ca 100644
--- a/libraries/common/src/main/java/androidx/media3/common/Player.java
+++ b/libraries/common/src/main/java/androidx/media3/common/Player.java
@@ -3319,6 +3319,9 @@ public interface Player {
    * <p>For devices with {@link DeviceInfo#PLAYBACK_TYPE_REMOTE remote playback}, the volume of the
    * remote device is returned.
    *
+   * <p>Note that this method returns the volume of the device. To check the current stream volume,
+   * use {@link getVolume()}.
+   *
    * <p>This method must only be called if {@link #COMMAND_GET_DEVICE_VOLUME} is {@linkplain
    * #getAvailableCommands() available}.
    */
@@ -3328,6 +3331,9 @@ public interface Player {
   /**
    * Gets whether the device is muted or not.
    *
+   * <p>Note that this method returns the mute state of the device. To check if the current stream
+   * is muted, use {@code getVolume() == 0}.
+   *
    * <p>This method must only be called if {@link #COMMAND_GET_DEVICE_VOLUME} is {@linkplain
    * #getAvailableCommands() available}.
    */
@@ -3342,6 +3348,9 @@ public interface Player {
   /**
    * Sets the volume of the device with volume flags.
    *
+   * <p>Note that this method affects the device volume. To change the volume of the current stream
+   * only, use {@link #setVolume}.
+   *
    * <p>This method must only be called if {@link #COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS} is
    * {@linkplain #getAvailableCommands() available}.
    *
@@ -3362,6 +3371,9 @@ public interface Player {
    * <p>The {@link #getDeviceVolume()} device volume cannot be increased above {@link
    * DeviceInfo#maxVolume}, if defined.
    *
+   * <p>Note that this method affects the device volume. To change the volume of the current stream
+   * only, use {@link #setVolume}.
+   *
    * <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS} is
    * {@linkplain #getAvailableCommands() available}.
    *
@@ -3381,6 +3393,9 @@ public interface Player {
    * <p>The {@link #getDeviceVolume()} device volume cannot be decreased below {@link
    * DeviceInfo#minVolume}.
    *
+   * <p>Note that this method affects the device volume. To change the volume of the current stream
+   * only, use {@link #setVolume}.
+   *
    * <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS} is
    * {@linkplain #getAvailableCommands() available}.
    *
@@ -3397,6 +3412,9 @@ public interface Player {
   /**
    * Sets the mute state of the device.
    *
+   * <p>Note that this method affects the device volume. To mute just the current stream, use {@code
+   * setVolume(0)} instead.
+   *
    * <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS} is
    * {@linkplain #getAvailableCommands() available}.
    *