Skip to content

Commit

Permalink
Extend Player interface, overloading 4 device-volume methods with flags
Browse files Browse the repository at this point in the history 
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
  • Loading branch information
@oceanjules @rohitjoins
oceanjules authored and rohitjoins committed Apr 13, 2023
1 parent e033dba commit c71e4bf
Show file tree
Hide file tree
Showing 37 changed files with 1,257 additions and 205 deletions.
6 changes: 6 additions & 0 deletions RELEASENOTES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,12 @@
([#293](https://github.com/androidx/media/issues/293)).
* Fix bug where calling `MediaSession.setPlayer` doesn't update the
available commands.
* Deprecate 4 volume-controlling methods in `Player` and add overloaded
methods which allow users to specify volume flags:
* `void setDeviceVolume(int, int)`
* `void increaseDeviceVolume(int)`
* `void decreaseDeviceVolume(int)`
* `void setDeviceMuted(boolean, int)`
* Audio:
* Fix bug where some playbacks fail when tunneling is enabled and
`AudioProcessors` are active, e.g. for gapless trimming
Expand Down
40 changes: 29 additions & 11 deletions api.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,11 @@ package androidx.media3.common {
field public static final int USAGE_VOICE_COMMUNICATION = 2; // 0x2
field public static final int USAGE_VOICE_COMMUNICATION_SIGNALLING = 3; // 0x3
field public static final java.util.UUID UUID_NIL;
field public static final int VOLUME_FLAG_ALLOW_RINGER_MODES = 2; // 0x2
field public static final int VOLUME_FLAG_PLAY_SOUND = 4; // 0x4
field public static final int VOLUME_FLAG_REMOVE_SOUND_AND_VIBRATE = 8; // 0x8
field public static final int VOLUME_FLAG_SHOW_UI = 1; // 0x1
field public static final int VOLUME_FLAG_VIBRATE = 16; // 0x10
field public static final int WAKE_MODE_LOCAL = 1; // 0x1
field public static final int WAKE_MODE_NETWORK = 2; // 0x2
field public static final int WAKE_MODE_NONE = 0; // 0x0
Expand Down Expand Up @@ -163,6 +168,9 @@ package androidx.media3.common {
@IntDef(open=true, value={androidx.media3.common.C.TRACK_TYPE_UNKNOWN, androidx.media3.common.C.TRACK_TYPE_DEFAULT, androidx.media3.common.C.TRACK_TYPE_AUDIO, androidx.media3.common.C.TRACK_TYPE_VIDEO, androidx.media3.common.C.TRACK_TYPE_TEXT, androidx.media3.common.C.TRACK_TYPE_IMAGE, androidx.media3.common.C.TRACK_TYPE_METADATA, androidx.media3.common.C.TRACK_TYPE_CAMERA_MOTION, androidx.media3.common.C.TRACK_TYPE_NONE}) @java.lang.annotation.Documented @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE) @java.lang.annotation.Target(java.lang.annotation.ElementType.TYPE_USE) public static @interface C.TrackType {
}

@IntDef(flag=true, value={androidx.media3.common.C.VOLUME_FLAG_SHOW_UI, androidx.media3.common.C.VOLUME_FLAG_ALLOW_RINGER_MODES, androidx.media3.common.C.VOLUME_FLAG_PLAY_SOUND, androidx.media3.common.C.VOLUME_FLAG_REMOVE_SOUND_AND_VIBRATE, androidx.media3.common.C.VOLUME_FLAG_VIBRATE}) @java.lang.annotation.Documented @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE) @java.lang.annotation.Target({java.lang.annotation.ElementType.TYPE_USE}) public static @interface C.VolumeFlags {
}

@IntDef({androidx.media3.common.C.WAKE_MODE_NONE, androidx.media3.common.C.WAKE_MODE_LOCAL, androidx.media3.common.C.WAKE_MODE_NETWORK}) @java.lang.annotation.Documented @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE) @java.lang.annotation.Target({java.lang.annotation.ElementType.FIELD, java.lang.annotation.ElementType.METHOD, java.lang.annotation.ElementType.PARAMETER, java.lang.annotation.ElementType.LOCAL_VARIABLE, java.lang.annotation.ElementType.TYPE_USE}) public static @interface C.WakeMode {
}

Expand Down Expand Up @@ -666,7 +674,8 @@ package androidx.media3.common {
method public void clearVideoSurfaceHolder(@Nullable android.view.SurfaceHolder);
method public void clearVideoSurfaceView(@Nullable android.view.SurfaceView);
method public void clearVideoTextureView(@Nullable android.view.TextureView);
method public void decreaseDeviceVolume();
method @Deprecated public void decreaseDeviceVolume();
method public void decreaseDeviceVolume(@androidx.media3.common.C.VolumeFlags int);
method public android.os.Looper getApplicationLooper();
method public androidx.media3.common.AudioAttributes getAudioAttributes();
method public androidx.media3.common.Player.Commands getAvailableCommands();
Expand Down Expand Up @@ -710,7 +719,8 @@ package androidx.media3.common {
method @FloatRange(from=0, to=1.0) public float getVolume();
method public boolean hasNextMediaItem();
method public boolean hasPreviousMediaItem();
method public void increaseDeviceVolume();
method @Deprecated public void increaseDeviceVolume();
method public void increaseDeviceVolume(@androidx.media3.common.C.VolumeFlags int);
method public boolean isCommandAvailable(@androidx.media3.common.Player.Command int);
method public boolean isCurrentMediaItemDynamic();
method public boolean isCurrentMediaItemLive();
Expand Down Expand Up @@ -738,8 +748,10 @@ package androidx.media3.common {
method public void seekToNextMediaItem();
method public void seekToPrevious();
method public void seekToPreviousMediaItem();
method public void setDeviceMuted(boolean);
method public void setDeviceVolume(@IntRange(from=0) int);
method @Deprecated public void setDeviceMuted(boolean);
method public void setDeviceMuted(boolean, @androidx.media3.common.C.VolumeFlags int);
method @Deprecated public void setDeviceVolume(@IntRange(from=0) int);
method public void setDeviceVolume(@IntRange(from=0) int, int);
method public void setMediaItem(androidx.media3.common.MediaItem);
method public void setMediaItem(androidx.media3.common.MediaItem, long);
method public void setMediaItem(androidx.media3.common.MediaItem, boolean);
Expand All @@ -759,7 +771,8 @@ package androidx.media3.common {
method public void setVideoTextureView(@Nullable android.view.TextureView);
method public void setVolume(@FloatRange(from=0, to=1.0) float);
method public void stop();
field public static final int COMMAND_ADJUST_DEVICE_VOLUME = 26; // 0x1a
field @Deprecated public static final int COMMAND_ADJUST_DEVICE_VOLUME = 26; // 0x1a
field public static final int COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS = 34; // 0x22
field public static final int COMMAND_CHANGE_MEDIA_ITEMS = 20; // 0x14
field public static final int COMMAND_GET_AUDIO_ATTRIBUTES = 21; // 0x15
field public static final int COMMAND_GET_CURRENT_MEDIA_ITEM = 16; // 0x10
Expand All @@ -783,7 +796,8 @@ package androidx.media3.common {
field public static final int COMMAND_SEEK_TO_NEXT_MEDIA_ITEM = 8; // 0x8
field public static final int COMMAND_SEEK_TO_PREVIOUS = 7; // 0x7
field public static final int COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM = 6; // 0x6
field public static final int COMMAND_SET_DEVICE_VOLUME = 25; // 0x19
field @Deprecated public static final int COMMAND_SET_DEVICE_VOLUME = 25; // 0x19
field public static final int COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS = 33; // 0x21
field public static final int COMMAND_SET_MEDIA_ITEM = 31; // 0x1f
field @Deprecated public static final int COMMAND_SET_MEDIA_ITEMS_METADATA = 19; // 0x13
field public static final int COMMAND_SET_PLAYLIST_METADATA = 19; // 0x13
Expand Down Expand Up @@ -855,7 +869,7 @@ package androidx.media3.common {
field public static final int TIMELINE_CHANGE_REASON_SOURCE_UPDATE = 1; // 0x1
}

@IntDef({androidx.media3.common.Player.COMMAND_INVALID, androidx.media3.common.Player.COMMAND_PLAY_PAUSE, androidx.media3.common.Player.COMMAND_PREPARE, androidx.media3.common.Player.COMMAND_STOP, androidx.media3.common.Player.COMMAND_SEEK_TO_DEFAULT_POSITION, androidx.media3.common.Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_SEEK_TO_PREVIOUS, androidx.media3.common.Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_SEEK_TO_NEXT, androidx.media3.common.Player.COMMAND_SEEK_TO_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_SEEK_BACK, androidx.media3.common.Player.COMMAND_SEEK_FORWARD, androidx.media3.common.Player.COMMAND_SET_SPEED_AND_PITCH, androidx.media3.common.Player.COMMAND_SET_SHUFFLE_MODE, androidx.media3.common.Player.COMMAND_SET_REPEAT_MODE, androidx.media3.common.Player.COMMAND_GET_CURRENT_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_GET_TIMELINE, androidx.media3.common.Player.COMMAND_GET_MEDIA_ITEMS_METADATA, androidx.media3.common.Player.COMMAND_GET_METADATA, androidx.media3.common.Player.COMMAND_SET_MEDIA_ITEMS_METADATA, androidx.media3.common.Player.COMMAND_SET_PLAYLIST_METADATA, androidx.media3.common.Player.COMMAND_SET_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_CHANGE_MEDIA_ITEMS, androidx.media3.common.Player.COMMAND_GET_AUDIO_ATTRIBUTES, androidx.media3.common.Player.COMMAND_GET_VOLUME, androidx.media3.common.Player.COMMAND_GET_DEVICE_VOLUME, androidx.media3.common.Player.COMMAND_SET_VOLUME, androidx.media3.common.Player.COMMAND_SET_DEVICE_VOLUME, androidx.media3.common.Player.COMMAND_ADJUST_DEVICE_VOLUME, androidx.media3.common.Player.COMMAND_SET_VIDEO_SURFACE, androidx.media3.common.Player.COMMAND_GET_TEXT, androidx.media3.common.Player.COMMAND_SET_TRACK_SELECTION_PARAMETERS, androidx.media3.common.Player.COMMAND_GET_TRACKS, androidx.media3.common.Player.COMMAND_RELEASE}) @java.lang.annotation.Documented @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE) @java.lang.annotation.Target({java.lang.annotation.ElementType.FIELD, java.lang.annotation.ElementType.METHOD, java.lang.annotation.ElementType.PARAMETER, java.lang.annotation.ElementType.LOCAL_VARIABLE, java.lang.annotation.ElementType.TYPE_USE}) public static @interface Player.Command {
@IntDef({androidx.media3.common.Player.COMMAND_INVALID, androidx.media3.common.Player.COMMAND_PLAY_PAUSE, androidx.media3.common.Player.COMMAND_PREPARE, androidx.media3.common.Player.COMMAND_STOP, androidx.media3.common.Player.COMMAND_SEEK_TO_DEFAULT_POSITION, androidx.media3.common.Player.COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_SEEK_TO_PREVIOUS, androidx.media3.common.Player.COMMAND_SEEK_TO_NEXT_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_SEEK_TO_NEXT, androidx.media3.common.Player.COMMAND_SEEK_TO_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_SEEK_BACK, androidx.media3.common.Player.COMMAND_SEEK_FORWARD, androidx.media3.common.Player.COMMAND_SET_SPEED_AND_PITCH, androidx.media3.common.Player.COMMAND_SET_SHUFFLE_MODE, androidx.media3.common.Player.COMMAND_SET_REPEAT_MODE, androidx.media3.common.Player.COMMAND_GET_CURRENT_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_GET_TIMELINE, androidx.media3.common.Player.COMMAND_GET_MEDIA_ITEMS_METADATA, androidx.media3.common.Player.COMMAND_GET_METADATA, androidx.media3.common.Player.COMMAND_SET_MEDIA_ITEMS_METADATA, androidx.media3.common.Player.COMMAND_SET_PLAYLIST_METADATA, androidx.media3.common.Player.COMMAND_SET_MEDIA_ITEM, androidx.media3.common.Player.COMMAND_CHANGE_MEDIA_ITEMS, androidx.media3.common.Player.COMMAND_GET_AUDIO_ATTRIBUTES, androidx.media3.common.Player.COMMAND_GET_VOLUME, androidx.media3.common.Player.COMMAND_GET_DEVICE_VOLUME, androidx.media3.common.Player.COMMAND_SET_VOLUME, androidx.media3.common.Player.COMMAND_SET_DEVICE_VOLUME, androidx.media3.common.Player.COMMAND_SET_DEVICE_VOLUME_WITH_FLAGS, androidx.media3.common.Player.COMMAND_ADJUST_DEVICE_VOLUME, androidx.media3.common.Player.COMMAND_ADJUST_DEVICE_VOLUME_WITH_FLAGS, androidx.media3.common.Player.COMMAND_SET_VIDEO_SURFACE, androidx.media3.common.Player.COMMAND_GET_TEXT, androidx.media3.common.Player.COMMAND_SET_TRACK_SELECTION_PARAMETERS, androidx.media3.common.Player.COMMAND_GET_TRACKS, androidx.media3.common.Player.COMMAND_RELEASE}) @java.lang.annotation.Documented @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.SOURCE) @java.lang.annotation.Target({java.lang.annotation.ElementType.FIELD, java.lang.annotation.ElementType.METHOD, java.lang.annotation.ElementType.PARAMETER, java.lang.annotation.ElementType.LOCAL_VARIABLE, java.lang.annotation.ElementType.TYPE_USE}) public static @interface Player.Command {
}

public static final class Player.Commands {
Expand Down Expand Up @@ -1499,7 +1513,8 @@ package androidx.media3.session {
method public final void clearVideoSurfaceHolder(@Nullable android.view.SurfaceHolder);
method public final void clearVideoSurfaceView(@Nullable android.view.SurfaceView);
method public final void clearVideoTextureView(@Nullable android.view.TextureView);
method public final void decreaseDeviceVolume();
method @Deprecated public final void decreaseDeviceVolume();
method public final void decreaseDeviceVolume(@androidx.media3.common.C.VolumeFlags int);
method public final android.os.Looper getApplicationLooper();
method public final androidx.media3.common.AudioAttributes getAudioAttributes();
method public final androidx.media3.common.Player.Commands getAvailableCommands();
Expand Down Expand Up @@ -1546,7 +1561,8 @@ package androidx.media3.session {
method @FloatRange(from=0, to=1) public final float getVolume();
method public final boolean hasNextMediaItem();
method public final boolean hasPreviousMediaItem();
method public final void increaseDeviceVolume();
method @Deprecated public final void increaseDeviceVolume();
method public final void increaseDeviceVolume(@androidx.media3.common.C.VolumeFlags int);
method public final boolean isCommandAvailable(@androidx.media3.common.Player.Command int);
method public final boolean isConnected();
method public final boolean isCurrentMediaItemDynamic();
Expand Down Expand Up @@ -1579,8 +1595,10 @@ package androidx.media3.session {
method public final void seekToPrevious();
method public final void seekToPreviousMediaItem();
method public final com.google.common.util.concurrent.ListenableFuture<androidx.media3.session.SessionResult> sendCustomCommand(androidx.media3.session.SessionCommand, android.os.Bundle);
method public final void setDeviceMuted(boolean);
method public final void setDeviceVolume(@IntRange(from=0) int);
method @Deprecated public final void setDeviceMuted(boolean);
method public final void setDeviceMuted(boolean, @androidx.media3.common.C.VolumeFlags int);
method @Deprecated public final void setDeviceVolume(@IntRange(from=0) int);
method public final void setDeviceVolume(@IntRange(from=0) int, @androidx.media3.common.C.VolumeFlags int);
method public final void setMediaItem(androidx.media3.common.MediaItem);
method public final void setMediaItem(androidx.media3.common.MediaItem, long);
method public final void setMediaItem(androidx.media3.common.MediaItem, boolean);
Expand Down
2 changes: 1 addition & 1 deletion libraries/cast/build.gradle
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
apply from: "$gradle.ext.androidxMediaSettingsDir/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 + 'lib-common')
compileOnly 'org.checkerframework:checker-qual:' + checkerframeworkVersion
Expand Down
30 changes: 29 additions & 1 deletion libraries/cast/src/main/java/androidx/media3/cast/CastPlayer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -755,22 +755,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.
Expand Down
31 changes: 31 additions & 0 deletions libraries/common/src/main/java/androidx/media3/common/C.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -409,6 +409,37 @@ private C() {}
/** The default stream type used by audio renderers. Equal to {@link #STREAM_TYPE_MUSIC}. */
@UnstableApi 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:
*
Expand Down
44 changes: 40 additions & 4 deletions libraries/common/src/main/java/androidx/media3/common/ForwardingPlayer.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -846,30 +846,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;
Expand Down
Loading

0 comments on commit c71e4bf

Please sign in to comment.