MediaSession: Define an extra field for staying paused after play
Introduced a new constant EXTRA_PREPARE_ONLY, which allows
MediaController to ask MediaSession to stay paused right after play
requests are called. If this field is set to true in extra bundle and it
is passed during playFromMediaId, playFromSearch, and playFromUri
requests, MediaSession will prepare the given media, but not start
playing it.
Bug: 25841735
Change-Id: I2a2f71a251bd6f475698fe8a5bb696ac70003e2b
diff --git a/api/current.txt b/api/current.txt
index da45517..9d2fb66 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -22064,6 +22064,7 @@
method public void setRatingType(int);
method public void setSessionActivity(android.app.PendingIntent);
field public static final int FLAG_HANDLES_MEDIA_BUTTONS = 1; // 0x1
+ field public static final int FLAG_HANDLES_PREPARE_ONLY = 4; // 0x4
field public static final int FLAG_HANDLES_TRANSPORT_CONTROLS = 2; // 0x2
}
@@ -22142,6 +22143,7 @@
field public static final long ACTION_SKIP_TO_QUEUE_ITEM = 4096L; // 0x1000L
field public static final long ACTION_STOP = 1L; // 0x1L
field public static final android.os.Parcelable.Creator<android.media.session.PlaybackState> CREATOR;
+ field public static final java.lang.String EXTRA_PREPARE_ONLY = "android.media.session.extra.PREPARE_ONLY";
field public static final long PLAYBACK_POSITION_UNKNOWN = -1L; // 0xffffffffffffffffL
field public static final int STATE_BUFFERING = 6; // 0x6
field public static final int STATE_CONNECTING = 8; // 0x8
diff --git a/api/system-current.txt b/api/system-current.txt
index 302ebe1..1900ce5 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -23481,6 +23481,7 @@
method public void setRatingType(int);
method public void setSessionActivity(android.app.PendingIntent);
field public static final int FLAG_HANDLES_MEDIA_BUTTONS = 1; // 0x1
+ field public static final int FLAG_HANDLES_PREPARE_ONLY = 4; // 0x4
field public static final int FLAG_HANDLES_TRANSPORT_CONTROLS = 2; // 0x2
}
@@ -23559,6 +23560,7 @@
field public static final long ACTION_SKIP_TO_QUEUE_ITEM = 4096L; // 0x1000L
field public static final long ACTION_STOP = 1L; // 0x1L
field public static final android.os.Parcelable.Creator<android.media.session.PlaybackState> CREATOR;
+ field public static final java.lang.String EXTRA_PREPARE_ONLY = "android.media.session.extra.PREPARE_ONLY";
field public static final long PLAYBACK_POSITION_UNKNOWN = -1L; // 0xffffffffffffffffL
field public static final int STATE_BUFFERING = 6; // 0x6
field public static final int STATE_CONNECTING = 8; // 0x8
diff --git a/api/test-current.txt b/api/test-current.txt
index 050caa0..ce89801 100644
--- a/api/test-current.txt
+++ b/api/test-current.txt
@@ -22072,6 +22072,7 @@
method public void setRatingType(int);
method public void setSessionActivity(android.app.PendingIntent);
field public static final int FLAG_HANDLES_MEDIA_BUTTONS = 1; // 0x1
+ field public static final int FLAG_HANDLES_PREPARE_ONLY = 4; // 0x4
field public static final int FLAG_HANDLES_TRANSPORT_CONTROLS = 2; // 0x2
}
@@ -22150,6 +22151,7 @@
field public static final long ACTION_SKIP_TO_QUEUE_ITEM = 4096L; // 0x1000L
field public static final long ACTION_STOP = 1L; // 0x1L
field public static final android.os.Parcelable.Creator<android.media.session.PlaybackState> CREATOR;
+ field public static final java.lang.String EXTRA_PREPARE_ONLY = "android.media.session.extra.PREPARE_ONLY";
field public static final long PLAYBACK_POSITION_UNKNOWN = -1L; // 0xffffffffffffffffL
field public static final int STATE_BUFFERING = 6; // 0x6
field public static final int STATE_CONNECTING = 8; // 0x8
diff --git a/media/java/android/media/session/MediaController.java b/media/java/android/media/session/MediaController.java
index b1a51a56..3d9b60d 100644
--- a/media/java/android/media/session/MediaController.java
+++ b/media/java/android/media/session/MediaController.java
@@ -605,6 +605,7 @@
/**
* Request that the player start playback for a specific media id.
*
+ * @see PlaybackState#EXTRA_PREPARE_ONLY
* @param mediaId The id of the requested media.
* @param extras Optional extras that can include extra information about the media item
* to be played.
@@ -626,6 +627,7 @@
* An empty or null query should be treated as a request to play any
* music.
*
+ * @see PlaybackState#EXTRA_PREPARE_ONLY
* @param query The search query.
* @param extras Optional extras that can include extra information
* about the query.
@@ -646,6 +648,7 @@
/**
* Request that the player start playback for a specific {@link Uri}.
*
+ * @see PlaybackState#EXTRA_PREPARE_ONLY
* @param uri The URI of the requested media.
* @param extras Optional extras that can include extra information about the media item
* to be played.
diff --git a/media/java/android/media/session/MediaSession.java b/media/java/android/media/session/MediaSession.java
index e1e9b79..8c5b19c 100644
--- a/media/java/android/media/session/MediaSession.java
+++ b/media/java/android/media/session/MediaSession.java
@@ -87,6 +87,12 @@
public static final int FLAG_HANDLES_TRANSPORT_CONTROLS = 1 << 1;
/**
+ * Set this flag on the session to indicate that it can handle
+ * the {@link PlaybackState#EXTRA_PREPARE_ONLY} field.
+ */
+ public static final int FLAG_HANDLES_PREPARE_ONLY = 1 << 2;
+
+ /**
* System only flag for a session that needs to have priority over all other
* sessions. This flag ensures this session will receive media button events
* regardless of the current ordering in the system.
@@ -100,6 +106,7 @@
@IntDef(flag = true, value = {
FLAG_HANDLES_MEDIA_BUTTONS,
FLAG_HANDLES_TRANSPORT_CONTROLS,
+ FLAG_HANDLES_PREPARE_ONLY,
FLAG_EXCLUSIVE_GLOBAL_PRIORITY })
public @interface SessionFlags { }
diff --git a/media/java/android/media/session/PlaybackState.java b/media/java/android/media/session/PlaybackState.java
index bbe04b5..1079a1f 100644
--- a/media/java/android/media/session/PlaybackState.java
+++ b/media/java/android/media/session/PlaybackState.java
@@ -133,6 +133,21 @@
public static final long ACTION_PLAY_FROM_URI = 1 << 13;
/**
+ * Used as an optional boolean extra field in
+ * {@link MediaController.TransportControls#playFromMediaId},
+ * {@link MediaController.TransportControls#playFromSearch}, and
+ * {@link MediaController.TransportControls#playFromUri}. Value of {@code true} overrides
+ * the default behavior of starting the playback after preparing. Check
+ * {@link MediaSession#FLAG_HANDLES_PREPARE_ONLY} to see if the media session supports this.
+ *
+ * @see MediaSession#FLAG_HANDLES_PREPARE_ONLY
+ * @see MediaController.TransportControls#playFromMediaId
+ * @see MediaController.TransportControls#playFromSearch
+ * @see MediaController.TransportControls#playFromUri
+ */
+ public static final String EXTRA_PREPARE_ONLY = "android.media.session.extra.PREPARE_ONLY";
+
+ /**
* This is the default playback state and indicates that no media has been
* added yet, or the performer has been reset and has no content to play.
*