/* * Copyright 2018 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.media; import static android.media.MediaPlayerBase.BUFFERING_STATE_UNKNOWN; import android.annotation.CallbackExecutor; import android.annotation.IntDef; import android.annotation.NonNull; import android.annotation.Nullable; import android.app.PendingIntent; import android.content.Context; import android.content.Intent; import android.media.MediaPlayerBase.BuffState; import android.media.MediaPlayerBase.PlayerState; import android.media.MediaPlaylistAgent.RepeatMode; import android.media.MediaPlaylistAgent.ShuffleMode; import android.media.update.ApiLoader; import android.media.update.MediaSession2Provider; import android.media.update.MediaSession2Provider.BuilderBaseProvider; import android.media.update.MediaSession2Provider.CommandButtonProvider; import android.media.update.MediaSession2Provider.ControllerInfoProvider; import android.media.update.ProviderCreator; import android.net.Uri; import android.os.Bundle; import android.os.IInterface; import android.os.ResultReceiver; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.util.List; import java.util.concurrent.Executor; /** * @hide * Allows a media app to expose its transport controls and playback information in a process to * other processes including the Android framework and other apps. Common use cases are as follows. *
* A MediaSession2 should be created when an app wants to publish media playback information or * handle media keys. In general an app only needs one session for all playback, though multiple * sessions can be created to provide finer grain controls of media. *
* If you want to support background playback, {@link MediaSessionService2} is preferred * instead. With it, your playback can be revived even after playback is finished. See * {@link MediaSessionService2} for details. *
* A session can be obtained by {@link Builder}. The owner of the session may pass its session token * to other processes to allow them to create a {@link MediaController2} to interact with the * session. *
* When a session receive transport control commands, the session sends the commands directly to * the the underlying media player set by {@link Builder} or * {@link #updatePlayer}. *
* When an app is finished performing playback it must call {@link #close()} to clean up the session * and notify any controllers. *
* {@link MediaSession2} objects should be used on the thread on the looper. * * @see MediaSessionService2 */ public class MediaSession2 implements AutoCloseable { private final MediaSession2Provider mProvider; /** * @hide */ @IntDef({ERROR_CODE_UNKNOWN_ERROR, ERROR_CODE_APP_ERROR, ERROR_CODE_NOT_SUPPORTED, ERROR_CODE_AUTHENTICATION_EXPIRED, ERROR_CODE_PREMIUM_ACCOUNT_REQUIRED, ERROR_CODE_CONCURRENT_STREAM_LIMIT, ERROR_CODE_PARENTAL_CONTROL_RESTRICTED, ERROR_CODE_NOT_AVAILABLE_IN_REGION, ERROR_CODE_CONTENT_ALREADY_PLAYING, ERROR_CODE_SKIP_LIMIT_REACHED, ERROR_CODE_ACTION_ABORTED, ERROR_CODE_END_OF_QUEUE, ERROR_CODE_SETUP_REQUIRED}) @Retention(RetentionPolicy.SOURCE) public @interface ErrorCode {} /** * This is the default error code and indicates that none of the other error codes applies. */ public static final int ERROR_CODE_UNKNOWN_ERROR = 0; /** * Error code when the application state is invalid to fulfill the request. */ public static final int ERROR_CODE_APP_ERROR = 1; /** * Error code when the request is not supported by the application. */ public static final int ERROR_CODE_NOT_SUPPORTED = 2; /** * Error code when the request cannot be performed because authentication has expired. */ public static final int ERROR_CODE_AUTHENTICATION_EXPIRED = 3; /** * Error code when a premium account is required for the request to succeed. */ public static final int ERROR_CODE_PREMIUM_ACCOUNT_REQUIRED = 4; /** * Error code when too many concurrent streams are detected. */ public static final int ERROR_CODE_CONCURRENT_STREAM_LIMIT = 5; /** * Error code when the content is blocked due to parental controls. */ public static final int ERROR_CODE_PARENTAL_CONTROL_RESTRICTED = 6; /** * Error code when the content is blocked due to being regionally unavailable. */ public static final int ERROR_CODE_NOT_AVAILABLE_IN_REGION = 7; /** * Error code when the requested content is already playing. */ public static final int ERROR_CODE_CONTENT_ALREADY_PLAYING = 8; /** * Error code when the application cannot skip any more songs because skip limit is reached. */ public static final int ERROR_CODE_SKIP_LIMIT_REACHED = 9; /** * Error code when the action is interrupted due to some external event. */ public static final int ERROR_CODE_ACTION_ABORTED = 10; /** * Error code when the playback navigation (previous, next) is not possible because the queue * was exhausted. */ public static final int ERROR_CODE_END_OF_QUEUE = 11; /** * Error code when the session needs user's manual intervention. */ public static final int ERROR_CODE_SETUP_REQUIRED = 12; /** * Interface definition of a callback to be invoked when a {@link MediaItem2} in the playlist * didn't have a {@link DataSourceDesc} but it's needed now for preparing or playing it. * * #see #setOnDataSourceMissingHelper */ public interface OnDataSourceMissingHelper { /** * Called when a {@link MediaItem2} in the playlist didn't have a {@link DataSourceDesc} * but it's needed now for preparing or playing it. Returned data source descriptor will be * sent to the player directly to prepare or play the contents. *
* An exception may be thrown if the returned {@link DataSourceDesc} is duplicated in the * playlist, so items cannot be differentiated. * * @param session the session for this event * @param item media item from the controller * @return a data source descriptor if the media item. Can be {@code null} if the content * isn't available. */ @Nullable DataSourceDesc onDataSourceMissing(@NonNull MediaSession2 session, @NonNull MediaItem2 item); } /** * Callback to be called for all incoming commands from {@link MediaController2}s. *
* If it's not set, the session will accept all controllers and all incoming commands by * default. */ // TODO(jaewan): Move this to updatable for default implementation (b/74091963) public static abstract class SessionCallback { /** * Called when a controller is created for this session. Return allowed commands for * controller. By default it allows all connection requests and commands. *
* You can reject the connection by return {@code null}. In that case, controller receives * {@link MediaController2.ControllerCallback#onDisconnected(MediaController2)} and cannot * be usable. * * @param session the session for this event * @param controller controller information. * @return allowed commands. Can be {@code null} to reject connection. */ public @Nullable SessionCommandGroup2 onConnect(@NonNull MediaSession2 session, @NonNull ControllerInfo controller) { SessionCommandGroup2 commands = new SessionCommandGroup2(); commands.addAllPredefinedCommands(); return commands; } /** * Called when a controller is disconnected * * @param session the session for this event * @param controller controller information */ public void onDisconnected(@NonNull MediaSession2 session, @NonNull ControllerInfo controller) { } /** * Called when a controller sent a command that will be sent directly to the player. Return * {@code false} here to reject the request and stop sending command to the player. * * @param session the session for this event * @param controller controller information. * @param command a command. This method will be called for every single command. * @return {@code true} if you want to accept incoming command. {@code false} otherwise. * @see SessionCommand2#COMMAND_CODE_PLAYBACK_PLAY * @see SessionCommand2#COMMAND_CODE_PLAYBACK_PAUSE * @see SessionCommand2#COMMAND_CODE_PLAYBACK_STOP * @see SessionCommand2#COMMAND_CODE_PLAYLIST_SKIP_NEXT_ITEM * @see SessionCommand2#COMMAND_CODE_PLAYLIST_SKIP_PREV_ITEM * @see SessionCommand2#COMMAND_CODE_PLAYBACK_PREPARE * @see SessionCommand2#COMMAND_CODE_SESSION_FAST_FORWARD * @see SessionCommand2#COMMAND_CODE_SESSION_REWIND * @see SessionCommand2#COMMAND_CODE_PLAYBACK_SEEK_TO * @see SessionCommand2#COMMAND_CODE_PLAYLIST_SKIP_TO_PLAYLIST_ITEM * @see SessionCommand2#COMMAND_CODE_PLAYLIST_ADD_ITEM * @see SessionCommand2#COMMAND_CODE_PLAYLIST_REMOVE_ITEM * @see SessionCommand2#COMMAND_CODE_PLAYLIST_GET_LIST * @see SessionCommand2#COMMAND_CODE_SET_VOLUME */ public boolean onCommandRequest(@NonNull MediaSession2 session, @NonNull ControllerInfo controller, @NonNull SessionCommand2 command) { return true; } /** * Called when a controller set rating of a media item through * {@link MediaController2#setRating(String, Rating2)}. *
* To allow setting user rating for a {@link MediaItem2}, the media item's metadata * should have {@link Rating2} with the key {@link MediaMetadata#METADATA_KEY_USER_RATING}, * in order to provide possible rating style for controller. Controller will follow the * rating style. * * @param session the session for this event * @param controller controller information * @param mediaId media id from the controller * @param rating new rating from the controller */ public void onSetRating(@NonNull MediaSession2 session, @NonNull ControllerInfo controller, @NonNull String mediaId, @NonNull Rating2 rating) { } /** * Called when a controller sent a custom command through * {@link MediaController2#sendCustomCommand(SessionCommand2, Bundle, ResultReceiver)}. * * @param session the session for this event * @param controller controller information * @param customCommand custom command. * @param args optional arguments * @param cb optional result receiver */ public void onCustomCommand(@NonNull MediaSession2 session, @NonNull ControllerInfo controller, @NonNull SessionCommand2 customCommand, @Nullable Bundle args, @Nullable ResultReceiver cb) { } /** * Called when a controller requested to play a specific mediaId through * {@link MediaController2#playFromMediaId(String, Bundle)}. * * @param session the session for this event * @param controller controller information * @param mediaId media id * @param extras optional extra bundle * @see SessionCommand2#COMMAND_CODE_SESSION_PLAY_FROM_MEDIA_ID */ public void onPlayFromMediaId(@NonNull MediaSession2 session, @NonNull ControllerInfo controller, @NonNull String mediaId, @Nullable Bundle extras) { } /** * Called when a controller requested to begin playback from a search query through * {@link MediaController2#playFromSearch(String, Bundle)} *
* An empty query indicates that the app may play any music. The implementation should * attempt to make a smart choice about what to play. * * @param session the session for this event * @param controller controller information * @param query query string. Can be empty to indicate any suggested media * @param extras optional extra bundle * @see SessionCommand2#COMMAND_CODE_SESSION_PLAY_FROM_SEARCH */ public void onPlayFromSearch(@NonNull MediaSession2 session, @NonNull ControllerInfo controller, @NonNull String query, @Nullable Bundle extras) { } /** * Called when a controller requested to play a specific media item represented by a URI * through {@link MediaController2#playFromUri(Uri, Bundle)} * * @param session the session for this event * @param controller controller information * @param uri uri * @param extras optional extra bundle * @see SessionCommand2#COMMAND_CODE_SESSION_PLAY_FROM_URI */ public void onPlayFromUri(@NonNull MediaSession2 session, @NonNull ControllerInfo controller, @NonNull Uri uri, @Nullable Bundle extras) { } /** * Called when a controller requested to prepare for playing a specific mediaId through * {@link MediaController2#prepareFromMediaId(String, Bundle)}. *
* 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 MediaPlayerBase#PLAYER_STATE_PAUSED} after the preparation is done. *
* The playback of the prepared content should start in the later calls of * {@link MediaSession2#play()}. *
* Override {@link #onPlayFromMediaId} to handle requests for starting * playback without preparation. * * @param session the session for this event * @param controller controller information * @param mediaId media id to prepare * @param extras optional extra bundle * @see SessionCommand2#COMMAND_CODE_SESSION_PREPARE_FROM_MEDIA_ID */ public void onPrepareFromMediaId(@NonNull MediaSession2 session, @NonNull ControllerInfo controller, @NonNull String mediaId, @Nullable Bundle extras) { } /** * Called when a controller requested to prepare playback from a search query through * {@link MediaController2#prepareFromSearch(String, Bundle)}. *
* 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 MediaPlayerBase#PLAYER_STATE_PAUSED} * after the preparation is done. The playback of the prepared content should start in the * later calls of {@link MediaSession2#play()}. *
* Override {@link #onPlayFromSearch} to handle requests for starting playback without * preparation. * * @param session the session for this event * @param controller controller information * @param query query string. Can be empty to indicate any suggested media * @param extras optional extra bundle * @see SessionCommand2#COMMAND_CODE_SESSION_PREPARE_FROM_SEARCH */ public void onPrepareFromSearch(@NonNull MediaSession2 session, @NonNull ControllerInfo controller, @NonNull String query, @Nullable Bundle extras) { } /** * Called when a controller requested to prepare a specific media item represented by a URI * through {@link MediaController2#prepareFromUri(Uri, Bundle)}. *
* 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 MediaPlayerBase#PLAYER_STATE_PAUSED} after the preparation is done. *
* The playback of the prepared content should start in the later calls of * {@link MediaSession2#play()}. *
* Override {@link #onPlayFromUri} to handle requests for starting playback without * preparation. * * @param session the session for this event * @param controller controller information * @param uri uri * @param extras optional extra bundle * @see SessionCommand2#COMMAND_CODE_SESSION_PREPARE_FROM_URI */ public void onPrepareFromUri(@NonNull MediaSession2 session, @NonNull ControllerInfo controller, @NonNull Uri uri, @Nullable Bundle extras) { } /** * Called when a controller called {@link MediaController2#fastForward()} * * @param session the session for this event */ public void onFastForward(@NonNull MediaSession2 session) { } /** * Called when a controller called {@link MediaController2#rewind()} * * @param session the session for this event */ public void onRewind(@NonNull MediaSession2 session) { } /** * Called when the player's current playing item is changed *
* When it's called, you should invalidate previous playback information and wait for later * callbacks. * * @param session the controller for this event * @param player the player for this event * @param item new item */ // TODO(jaewan): Use this (b/74316764) public void onCurrentMediaItemChanged(@NonNull MediaSession2 session, @NonNull MediaPlayerBase player, @NonNull MediaItem2 item) { } /** * Called when the player is prepared, i.e. it is ready to play the content * referenced by the given data source. * @param session the session for this event * @param player the player for this event * @param item the media item for which buffering is happening */ public void onMediaPrepared(@NonNull MediaSession2 session, @NonNull MediaPlayerBase player, @NonNull MediaItem2 item) { } /** * Called to indicate that the state of the player has changed. * See {@link MediaPlayerBase#getPlayerState()} for polling the player state. * @param session the session for this event * @param player the player for this event * @param state the new state of the player. */ public void onPlayerStateChanged(@NonNull MediaSession2 session, @NonNull MediaPlayerBase player, @PlayerState int state) { } /** * Called to report buffering events for a data source. * * @param session the session for this event * @param player the player for this event * @param item the media item for which buffering is happening. * @param state the new buffering state. */ public void onBufferingStateChanged(@NonNull MediaSession2 session, @NonNull MediaPlayerBase player, @NonNull MediaItem2 item, @BuffState int state) { } /** * Called to indicate that the playback speed has changed. * @param session the session for this event * @param player the player for this event * @param speed the new playback speed. */ public void onPlaybackSpeedChanged(@NonNull MediaSession2 session, @NonNull MediaPlayerBase player, float speed) { } /** * Called to indicate that {@link #seekTo(long)} is completed. * * @param session the session for this event. * @param mpb the player that has completed seeking. * @param position the previous seeking request. * @see #seekTo(long) */ public void onSeekCompleted(@NonNull MediaSession2 session, @NonNull MediaPlayerBase mpb, long position) { } /** * Called when a playlist is changed from the {@link MediaPlaylistAgent}. *
* This is called when the underlying agent has called
* {@link MediaPlaylistAgent.PlaylistEventCallback#onPlaylistChanged(MediaPlaylistAgent,
* List, MediaMetadata2)}.
*
* @param session the session for this event
* @param playlistAgent playlist agent for this event
* @param list new playlist
* @param metadata new metadata
*/
public void onPlaylistChanged(@NonNull MediaSession2 session,
@NonNull MediaPlaylistAgent playlistAgent, @NonNull List
* APIs here should be package private, but should have documentations for developers.
* Otherwise, javadoc will generate documentation with the generic types such as follows.
*
* This class is hidden to prevent from generating test stub, which fails with
* 'unexpected bound' because it tries to auto generate stub class as follows.
*
* If the {@link MediaPlaylistAgent} isn't set, session will create the default playlist
* agent.
*
* @param playlistAgent a {@link MediaPlaylistAgent} that manages playlist of the
* {@code player}
*/
U setPlaylistAgent(@NonNull MediaPlaylistAgent playlistAgent) {
mProvider.setPlaylistAgent_impl(playlistAgent);
return (U) this;
}
/**
* Sets the {@link VolumeProvider2} for this session to handle volume events. If not set,
* system will adjust the appropriate stream volume for this session's player.
*
* @param volumeProvider The provider that will receive volume button events.
*/
@NonNull U setVolumeProvider(@Nullable VolumeProvider2 volumeProvider) {
mProvider.setVolumeProvider_impl(volumeProvider);
return (U) this;
}
/**
* Set an intent for launching UI for this Session. This can be used as a
* quick link to an ongoing media screen. The intent should be for an
* activity that may be started using {@link Context#startActivity(Intent)}.
*
* @param pi The intent to launch to show UI for this session.
*/
@NonNull U setSessionActivity(@Nullable PendingIntent pi) {
mProvider.setSessionActivity_impl(pi);
return (U) this;
}
/**
* Set ID of the session. If it's not set, an empty string with used to create a session.
*
* Use this if and only if your app supports multiple playback at the same time and also
* wants to provide external apps to have finer controls of them.
*
* @param id id of the session. Must be unique per package.
* @throws IllegalArgumentException if id is {@code null}
* @return
*/
@NonNull U setId(@NonNull String id) {
mProvider.setId_impl(id);
return (U) this;
}
/**
* Set callback for the session.
*
* @param executor callback executor
* @param callback session callback.
* @return
*/
@NonNull U setSessionCallback(@NonNull @CallbackExecutor Executor executor,
@NonNull C callback) {
mProvider.setSessionCallback_impl(executor, callback);
return (U) this;
}
/**
* Build {@link MediaSession2}.
*
* @return a new session
* @throws IllegalStateException if the session with the same id is already exists for the
* package.
*/
@NonNull T build() {
return mProvider.build_impl();
}
}
/**
* Builder for {@link MediaSession2}.
*
* Any incoming event from the {@link MediaController2} will be handled on the thread
* that created session with the {@link Builder#build()}.
*/
// Override all methods just to show them with the type instead of generics in Javadoc.
// This workarounds javadoc issue described in the MediaSession2.BuilderBase.
public static final class Builder extends BuilderBase
* It's up to the controller's decision to respect or ignore this customization request.
*/
public static final class CommandButton {
private final CommandButtonProvider mProvider;
/**
* @hide
*/
public CommandButton(CommandButtonProvider provider) {
mProvider = provider;
}
/**
* Get command associated with this button. Can be {@code null} if the button isn't enabled
* and only providing placeholder.
*
* @return command or {@code null}
*/
public @Nullable
SessionCommand2 getCommand() {
return mProvider.getCommand_impl();
}
/**
* Resource id of the button in this package. Can be {@code 0} if the command is predefined
* and custom icon isn't needed.
*
* @return resource id of the icon. Can be {@code 0}.
*/
public int getIconResId() {
return mProvider.getIconResId_impl();
}
/**
* Display name of the button. Can be {@code null} or empty if the command is predefined
* and custom name isn't needed.
*
* @return custom display name. Can be {@code null} or empty.
*/
public @Nullable String getDisplayName() {
return mProvider.getDisplayName_impl();
}
/**
* Extra information of the button. It's private information between session and controller.
*
* @return
*/
public @Nullable Bundle getExtras() {
return mProvider.getExtras_impl();
}
/**
* Return whether it's enabled
*
* @return {@code true} if enabled. {@code false} otherwise.
*/
public boolean isEnabled() {
return mProvider.isEnabled_impl();
}
/**
* @hide
*/
public @NonNull CommandButtonProvider getProvider() {
return mProvider;
}
/**
* Builder for {@link CommandButton}.
*/
public static final class Builder {
private final CommandButtonProvider.BuilderProvider mProvider;
public Builder() {
mProvider = ApiLoader.getProvider().createMediaSession2CommandButtonBuilder(this);
}
public @NonNull Builder setCommand(@Nullable SessionCommand2 command) {
return mProvider.setCommand_impl(command);
}
public @NonNull Builder setIconResId(int resId) {
return mProvider.setIconResId_impl(resId);
}
public @NonNull Builder setDisplayName(@Nullable String displayName) {
return mProvider.setDisplayName_impl(displayName);
}
public @NonNull Builder setEnabled(boolean enabled) {
return mProvider.setEnabled_impl(enabled);
}
public @NonNull Builder setExtras(@Nullable Bundle extras) {
return mProvider.setExtras_impl(extras);
}
public @NonNull CommandButton build() {
return mProvider.build_impl();
}
}
}
/**
* Constructor is hidden and apps can only instantiate indirectly through {@link Builder}.
*
* This intended behavior and here's the reasons.
* 1. Prevent multiple sessions with the same tag in a media app.
* Whenever it happens only one session was properly setup and others were all dummies.
* Android framework couldn't find the right session to dispatch media key event.
* 2. Simplify session's lifecycle.
* {@link android.media.session.MediaSession} is available after all of
* {@link android.media.session.MediaSession#setFlags(int)},
* {@link android.media.session.MediaSession#setCallback(
* android.media.session.MediaSession.Callback)},
* and {@link android.media.session.MediaSession#setActive(boolean)}.
* It was common for an app to omit one, so framework had to add heuristics to figure out
* which should be the highest priority for handling media key event.
* @hide
*/
public MediaSession2(MediaSession2Provider provider) {
super();
mProvider = provider;
}
/**
* @hide
*/
public @NonNull MediaSession2Provider getProvider() {
return mProvider;
}
/**
* Sets the underlying {@link MediaPlayerBase} and {@link MediaPlaylistAgent} for this session
* to dispatch incoming event to.
*
* When a {@link MediaPlaylistAgent} is specified here, the playlist agent should manage
* {@link MediaPlayerBase} for calling {@link MediaPlayerBase#setNextDataSources(List)}.
*
* If the {@link MediaPlaylistAgent} isn't set, session will recreate the default playlist
* agent.
*
* @param player a {@link MediaPlayerBase} that handles actual media playback in your app
* @param playlistAgent a {@link MediaPlaylistAgent} that manages playlist of the {@code player}
* @param volumeProvider a {@link VolumeProvider2}. If {@code null}, system will adjust the
* appropriate stream volume for this session's player.
*/
public void updatePlayer(@NonNull MediaPlayerBase player,
@Nullable MediaPlaylistAgent playlistAgent, @Nullable VolumeProvider2 volumeProvider) {
mProvider.updatePlayer_impl(player, playlistAgent, volumeProvider);
}
@Override
public void close() {
mProvider.close_impl();
}
/**
* @return player
*/
public @NonNull MediaPlayerBase getPlayer() {
return mProvider.getPlayer_impl();
}
/**
* @return playlist agent
*/
public @NonNull MediaPlaylistAgent getPlaylistAgent() {
return mProvider.getPlaylistAgent_impl();
}
/**
* @return volume provider
*/
public @Nullable VolumeProvider2 getVolumeProvider() {
return mProvider.getVolumeProvider_impl();
}
/**
* Returns the {@link SessionToken2} for creating {@link MediaController2}.
*/
public @NonNull
SessionToken2 getToken() {
return mProvider.getToken_impl();
}
public @NonNull List
* It's up to controller's decision how to represent the layout in its own UI.
* Here's the same way
* (layout[i] means a CommandButton at index i in the given list)
* For 5 icons row
* layout[3] layout[1] layout[0] layout[2] layout[4]
* For 3 icons row
* layout[1] layout[0] layout[2]
* For 5 icons row with overflow icon (can show +5 extra buttons with overflow button)
* expanded row: layout[5] layout[6] layout[7] layout[8] layout[9]
* main row: layout[3] layout[1] layout[0] layout[2] layout[4]
*
* This API can be called in the {@link SessionCallback#onConnect(
* MediaSession2, ControllerInfo)}.
*
* @param controller controller to specify layout.
* @param layout ordered list of layout.
*/
public void setCustomLayout(@NonNull ControllerInfo controller,
@NonNull List
* This calls {@link MediaPlayerBase#play()}.
*/
public void play() {
mProvider.play_impl();
}
/**
* Pause playback.
*
* This calls {@link MediaPlayerBase#pause()}.
*/
public void pause() {
mProvider.pause_impl();
}
/**
* Stop playback, and reset the player to the initial state.
*
* This calls {@link MediaPlayerBase#reset()}.
*/
public void stop() {
mProvider.stop_impl();
}
/**
* 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 MediaPlayerBase#PLAYER_STATE_PAUSED}. Afterwards, {@link #play} can be called
* to start playback.
*
* This calls {@link MediaPlayerBase#reset()}.
*/
public void prepare() {
mProvider.prepare_impl();
}
/**
* Move to a new location in the media stream.
*
* @param pos Position to move to, in milliseconds.
*/
public void seekTo(long pos) {
mProvider.seekTo_impl(pos);
}
/**
* @hide
*/
public void skipForward() {
// To match with KEYCODE_MEDIA_SKIP_FORWARD
}
/**
* @hide
*/
public void skipBackward() {
// To match with KEYCODE_MEDIA_SKIP_BACKWARD
}
/**
* Notify errors to the connected controllers
*
* @param errorCode error code
* @param extras extras
*/
public void notifyError(@ErrorCode int errorCode, @Nullable Bundle extras) {
mProvider.notifyError_impl(errorCode, extras);
}
/**
* Gets the current player state.
*
* @return the current player state
*/
public @PlayerState int getPlayerState() {
return mProvider.getPlayerState_impl();
}
/**
* Gets the current position.
*
* @return the current playback position in ms, or {@link MediaPlayerBase#UNKNOWN_TIME} if
* unknown.
*/
public long getCurrentPosition() {
return mProvider.getCurrentPosition_impl();
}
/**
* Gets the buffered position, or {@link MediaPlayerBase#UNKNOWN_TIME} if unknown.
*
* @return the buffered position in ms, or {@link MediaPlayerBase#UNKNOWN_TIME}.
*/
public long getBufferedPosition() {
return mProvider.getBufferedPosition_impl();
}
/**
* Gets the current buffering state of the player.
* During buffering, see {@link #getBufferedPosition()} for the quantifying the amount already
* buffered.
*
* @return the buffering state.
*/
public @BuffState int getBufferingState() {
// TODO(jaewan): Implement this
return BUFFERING_STATE_UNKNOWN;
}
/**
* Get the playback speed.
*
* @return speed
*/
public float getPlaybackSpeed() {
// TODO(jaewan): implement this (b/74093080)
return -1;
}
/**
* Set the playback speed.
*/
public void setPlaybackSpeed(float speed) {
// TODO(jaewan): implement this (b/74093080)
}
/**
* Sets the data source missing helper. Helper will be used to provide default implementation of
* {@link MediaPlaylistAgent} when it isn't set by developer.
*
* Default implementation of the {@link MediaPlaylistAgent} will call helper when a
* {@link MediaItem2} in the playlist doesn't have a {@link DataSourceDesc}. This may happen
* when
*
* If it's not set, playback wouldn't happen for the item without data source descriptor.
*
* The helper will be run on the executor that was specified by
* {@link Builder#setSessionCallback(Executor, SessionCallback)}.
*
* @param helper a data source missing helper.
* @throws IllegalStateException when the helper is set when the playlist agent is set
* @see #setPlaylist(List, MediaMetadata2)
* @see SessionCallback#onCommandRequest(MediaSession2, ControllerInfo, SessionCommand2)
* @see SessionCommand2#COMMAND_CODE_PLAYLIST_ADD_ITEM
* @see SessionCommand2#COMMAND_CODE_PLAYLIST_REPLACE_ITEM
*/
public void setOnDataSourceMissingHelper(@NonNull OnDataSourceMissingHelper helper) {
mProvider.setOnDataSourceMissingHelper_impl(helper);
}
/**
* Clears the data source missing helper.
*
* @see #setOnDataSourceMissingHelper(OnDataSourceMissingHelper)
*/
public void clearOnDataSourceMissingHelper() {
mProvider.clearOnDataSourceMissingHelper_impl();
}
/**
* Returns the playlist from the {@link MediaPlaylistAgent}.
*
* This list may differ with the list that was specified with
* {@link #setPlaylist(List, MediaMetadata2)} depending on the {@link MediaPlaylistAgent}
* implementation. Use media items returned here for other playlist agent APIs such as
* {@link MediaPlaylistAgent#skipToPlaylistItem(MediaItem2)}.
*
* @return playlist
* @see MediaPlaylistAgent#getPlaylist()
* @see SessionCallback#onPlaylistChanged(
* MediaSession2, MediaPlaylistAgent, List, MediaMetadata2)
*/
public List
* This may be an asynchronous call, and {@link MediaPlaylistAgent} may keep the copy of the
* list. Wait for {@link SessionCallback#onPlaylistChanged(MediaSession2, MediaPlaylistAgent,
* List, MediaMetadata2)} to know the operation finishes.
*
* You may specify a {@link MediaItem2} without {@link DataSourceDesc}. In that case,
* {@link MediaPlaylistAgent} has responsibility to dynamically query {@link DataSourceDesc}
* when such media item is ready for preparation or play. Default implementation needs
* {@link OnDataSourceMissingHelper} for such case.
*
* @param list A list of {@link MediaItem2} objects to set as a play list.
* @throws IllegalArgumentException if given list is {@code null}, or has duplicated media
* items.
* @see MediaPlaylistAgent#setPlaylist(List, MediaMetadata2)
* @see SessionCallback#onPlaylistChanged(
* MediaSession2, MediaPlaylistAgent, List, MediaMetadata2)
* @see #setOnDataSourceMissingHelper
*/
public void setPlaylist(@NonNull List
* This calls {@link MediaPlaylistAgent#skipToPlaylistItem(MediaItem2)} and the behavior depends
* on the playlist agent implementation, especially with the shuffle/repeat mode.
*
* @param item The item in the playlist you want to play
* @see #getShuffleMode()
* @see #getRepeatMode()
*/
public void skipToPlaylistItem(@NonNull MediaItem2 item) {
mProvider.skipToPlaylistItem_impl(item);
}
/**
* Skips to the previous item.
*
* This calls {@link MediaPlaylistAgent#skipToPreviousItem()} and the behavior depends on the
* playlist agent implementation, especially with the shuffle/repeat mode.
*
* @see #getShuffleMode()
* @see #getRepeatMode()
**/
public void skipToPreviousItem() {
mProvider.skipToPreviousItem_impl();
}
/**
* Skips to the next item.
*
* This calls {@link MediaPlaylistAgent#skipToNextItem()} and the behavior depends on the
* playlist agent implementation, especially with the shuffle/repeat mode.
*
* @see #getShuffleMode()
* @see #getRepeatMode()
*/
public void skipToNextItem() {
mProvider.skipToNextItem_impl();
}
/**
* Gets the playlist metadata from the {@link MediaPlaylistAgent}.
*
* @return the playlist metadata
*/
public MediaMetadata2 getPlaylistMetadata() {
return mProvider.getPlaylistMetadata_impl();
}
/**
* Adds the media item to the playlist at position index. Index equals or greater than
* the current playlist size will add the item at the end of the playlist.
*
* This will not change the currently playing media item.
* If index is less than or equal to the current index of the play list,
* the current index of the play list will be incremented correspondingly.
*
* @param index the index you want to add
* @param item the media item you want to add
*/
public void addPlaylistItem(int index, @NonNull MediaItem2 item) {
mProvider.addPlaylistItem_impl(index, item);
}
/**
* Removes the media item in the playlist.
*
* If the item is the currently playing item of the playlist, current playback
* will be stopped and playback moves to next source in the list.
*
* @param item the media item you want to add
*/
public void removePlaylistItem(@NonNull MediaItem2 item) {
mProvider.removePlaylistItem_impl(item);
}
/**
* Replaces the media item at index in the playlist. This can be also used to update metadata of
* an item.
*
* @param index the index of the item to replace
* @param item the new item
*/
public void replacePlaylistItem(int index, @NonNull MediaItem2 item) {
mProvider.replacePlaylistItem_impl(index, item);
}
/**
* Return currently playing media item.
*
* @return currently playing media item
*/
public MediaItem2 getCurrentMediaItem() {
// TODO(jaewan): Rename provider, and implement (b/74316764)
return mProvider.getCurrentPlaylistItem_impl();
}
/**
* Updates the playlist metadata to the {@link MediaPlaylistAgent}.
*
* @param metadata metadata of the playlist
*/
public void updatePlaylistMetadata(@Nullable MediaMetadata2 metadata) {
mProvider.updatePlaylistMetadata_impl(metadata);
}
/**
* Gets the repeat mode from the {@link MediaPlaylistAgent}.
*
* @return repeat mode
* @see MediaPlaylistAgent#REPEAT_MODE_NONE
* @see MediaPlaylistAgent#REPEAT_MODE_ONE
* @see MediaPlaylistAgent#REPEAT_MODE_ALL
* @see MediaPlaylistAgent#REPEAT_MODE_GROUP
*/
public @RepeatMode int getRepeatMode() {
return mProvider.getRepeatMode_impl();
}
/**
* Sets the repeat mode to the {@link MediaPlaylistAgent}.
*
* @param repeatMode repeat mode
* @see MediaPlaylistAgent#REPEAT_MODE_NONE
* @see MediaPlaylistAgent#REPEAT_MODE_ONE
* @see MediaPlaylistAgent#REPEAT_MODE_ALL
* @see MediaPlaylistAgent#REPEAT_MODE_GROUP
*/
public void setRepeatMode(@RepeatMode int repeatMode) {
mProvider.setRepeatMode_impl(repeatMode);
}
/**
* Gets the shuffle mode from the {@link MediaPlaylistAgent}.
*
* @return The shuffle mode
* @see MediaPlaylistAgent#SHUFFLE_MODE_NONE
* @see MediaPlaylistAgent#SHUFFLE_MODE_ALL
* @see MediaPlaylistAgent#SHUFFLE_MODE_GROUP
*/
public @ShuffleMode int getShuffleMode() {
return mProvider.getShuffleMode_impl();
}
/**
* Sets the shuffle mode to the {@link MediaPlaylistAgent}.
*
* @param shuffleMode The shuffle mode
* @see MediaPlaylistAgent#SHUFFLE_MODE_NONE
* @see MediaPlaylistAgent#SHUFFLE_MODE_ALL
* @see MediaPlaylistAgent#SHUFFLE_MODE_GROUP
*/
public void setShuffleMode(@ShuffleMode int shuffleMode) {
mProvider.setShuffleMode_impl(shuffleMode);
}
}
U extends BuilderBase
* abstract static class BuilderBase<
* T extends android.media.MediaSession2,
* U extends android.media.MediaSession2.BuilderBase<
* T, U, C extends android.media.MediaSession2.SessionCallback>, C>
* @hide
*/
static abstract class BuilderBase
*
*