From f9f240ab7d9918a14437d3ae63ae959e4ff906cc Mon Sep 17 00:00:00 2001 From: Donghyun Cho Date: Wed, 24 Feb 2016 14:56:11 +0900 Subject: [PATCH] MediaSession: Update javadoc of prepare-related methods Bug:25841735, Bug:25153060, Bug:25153353 Change-Id: I95cd2b7381e3d8abe5a5c79dbd8655a02f8d40c3 --- .../media/session/MediaController.java | 43 +++++++++++-------- .../android/media/session/MediaSession.java | 39 +++++++++-------- 2 files changed, 46 insertions(+), 36 deletions(-) diff --git a/media/java/android/media/session/MediaController.java b/media/java/android/media/session/MediaController.java index 13db00ef3cd1c..622900f5c7f94 100644 --- a/media/java/android/media/session/MediaController.java +++ b/media/java/android/media/session/MediaController.java @@ -592,10 +592,11 @@ public final class MediaController { } /** - * Request that the player prepare its playback. Once the preparation is done, the session - * will change its playback state to {@link PlaybackState#STATE_PAUSED}. Afterwards, - * {@link #play} can be called to start playback. If the preparation is not needed, - * {@link #play} can be directly called without this method. + * Request that the player prepare its playback. In other words, other sessions can continue + * to play during the preparation of this session. This method can be used to speed up the + * start of the playback. Once the preparation is done, the session will change its playback + * state to {@link PlaybackState#STATE_PAUSED}. Afterwards, {@link #play} can be called to + * start playback. */ public void prepare() { try { @@ -606,10 +607,12 @@ public final class MediaController { } /** - * Request that the player prepare playback for a specific media id. Once the preparation is - * done, the session will change its playback state to {@link PlaybackState#STATE_PAUSED}. - * Afterwards, {@link #play} can be called to start playback. If the preparation is not - * needed, {@link #playFromMediaId} can be directly called without this method. + * Request that the player prepare playback for a specific media id. In other words, other + * sessions can continue to play during the preparation of this session. This method can be + * used to speed up the start of the playback. Once the preparation is done, the session + * will change its playback state to {@link PlaybackState#STATE_PAUSED}. Afterwards, + * {@link #play} can be called to start playback. If the preparation is not needed, + * {@link #playFromMediaId} can be directly called without this method. * * @param mediaId The id of the requested media. * @param extras Optional extras that can include extra information about the media item @@ -628,12 +631,13 @@ public final class MediaController { } /** - * Request that the player prepare playback for a specific search query. - * An empty or null query should be treated as a request to prepare any - * music. Once the preparation is done, the session will change its playback state to - * {@link PlaybackState#STATE_PAUSED}. Afterwards, {@link #play} can be called to start - * playback. If the preparation is not needed, {@link #playFromSearch} can be directly - * called without this method. + * Request that the player prepare playback for a specific search query. An empty or null + * query should be treated as a request to prepare any music. In other words, other sessions + * can continue to play during the preparation of this session. This method can be used to + * speed up the start of the playback. Once the preparation is done, the session will + * change its playback state to {@link PlaybackState#STATE_PAUSED}. Afterwards, + * {@link #play} can be called to start playback. If the preparation is not needed, + * {@link #playFromSearch} can be directly called without this method. * * @param query The search query. * @param extras Optional extras that can include extra information @@ -653,11 +657,12 @@ public final class MediaController { } /** - * Request that the player prepare playback for a specific {@link Uri}. - * Once the preparation is done, the session will change its playback state to - * {@link PlaybackState#STATE_PAUSED}. Afterwards, {@link #play} can be called to start - * playback. If the preparation is not needed, {@link #playFromUri} can be directly - * called without this method. + * Request that the player prepare playback for a specific {@link Uri}. In other words, + * other sessions can continue to play during the preparation of this session. This method + * can be used to speed up the start of the playback. Once the preparation is done, the + * session will change its playback state to {@link PlaybackState#STATE_PAUSED}. Afterwards, + * {@link #play} can be called to start playback. If the preparation is not needed, + * {@link #playFromUri} can be directly called without this method. * * @param uri The URI of the requested media. * @param extras Optional extras that can include extra information about the media item diff --git a/media/java/android/media/session/MediaSession.java b/media/java/android/media/session/MediaSession.java index 3b1b6c86ffcb0..d4f4fbf4ace77 100644 --- a/media/java/android/media/session/MediaSession.java +++ b/media/java/android/media/session/MediaSession.java @@ -814,40 +814,45 @@ public final class MediaSession { } /** - * Override to handle requests to prepare playback. The state of playback should be updated - * to {@link PlaybackState#STATE_PAUSED} after the preparation is done. Override - * {@link #onPlay} to handle requests for starting playback of prepared content. + * Override to handle requests to prepare playback. During the preparation, a session should + * not hold audio focus in order to allow other sessions play seamlessly. The state of + * playback should be updated to {@link PlaybackState#STATE_PAUSED} after the preparation is + * done. */ public void onPrepare() { } /** * Override to handle requests to prepare for playing a specific mediaId that was provided - * by your app's {@link MediaBrowserService}. The state of playback should be updated - * to {@link PlaybackState#STATE_PAUSED} after the preparation is done. The playback of - * the prepared content should start in the implementation of {@link #onPlay}. Override - * {@link #onPlayFromMediaId} to handle requests for starting playback without preparation. + * by your app's {@link MediaBrowserService}. During the preparation, a session should not + * hold audio focus in order to allow other sessions play seamlessly. The state of playback + * should be updated to {@link PlaybackState#STATE_PAUSED} after the preparation is done. + * The playback of the prepared content should start in the implementation of + * {@link #onPlay}. Override {@link #onPlayFromMediaId} to handle requests for starting + * playback without preparation. */ public void onPrepareFromMediaId(String mediaId, Bundle extras) { } /** - * Override to handle requests to prepare playback from a search query. An - * empty query indicates that the app may prepare any music. The - * implementation should attempt to make a smart choice about what to - * play. The state of playback should be updated to {@link PlaybackState#STATE_PAUSED} - * after the preparation is done. The playback of the prepared content should start - * in the implementation of {@link #onPlay}. Override {@link #onPlayFromSearch} - * to handle requests for starting playback without preparation. + * Override to handle requests to prepare playback from a search query. An empty query + * indicates that the app may prepare any music. The implementation should attempt to make a + * smart choice about what to play. During the preparation, a session should not hold audio + * focus in order to allow other sessions play seamlessly. The state of playback should be + * updated to {@link PlaybackState#STATE_PAUSED} after the preparation is done. The playback + * of the prepared content should start in the implementation of {@link #onPlay}. Override + * {@link #onPlayFromSearch} to handle requests for starting playback without preparation. */ public void onPrepareFromSearch(String query, Bundle extras) { } /** * Override to handle requests to prepare a specific media item represented by a URI. - * The state of playback should be updated to {@link PlaybackState#STATE_PAUSED} - * after the preparation is done. The playback of the prepared content should start in - * the implementation of {@link #onPlay}. Override {@link #onPlayFromUri} to handle requests + * During the preparation, a session should not hold audio focus in order to allow + * other sessions play seamlessly. The state of playback should be updated to + * {@link PlaybackState#STATE_PAUSED} after the preparation is done. + * The playback of the prepared content should start in the implementation of + * {@link #onPlay}. Override {@link #onPlayFromUri} to handle requests * for starting playback without preparation. */ public void onPrepareFromUri(Uri uri, Bundle extras) {