Topics covered here: * *
When a controller is created with the {@link SessionToken} for a {@link MediaSession} (i.e. * session token type is {@link SessionToken#TYPE_SESSION}), the controller will connect to the * specific session. * *
When a controller is created with the {@link SessionToken} for a {@link MediaSessionService} * (i.e. session token type is {@link SessionToken#TYPE_SESSION_SERVICE} or {@link * SessionToken#TYPE_LIBRARY_SERVICE}), the controller binds to the service for connecting to a * {@link MediaSession} in it. {@link MediaSessionService} will provide a session to connect. * *
When you're done, use {@link #releaseFuture(Future)} or {@link #release()} to clean up * resources. This also helps the session service to be destroyed when there's no controller * associated with it. Releasing the controller will still deliver all pending commands sent to the * session and only unbind from the session service once these commands have been handled, or after * a timeout of {@link #RELEASE_UNBIND_TIMEOUT_MS}. * *
Methods of this class should be called from the application thread associated with the {@link * #getApplicationLooper() application looper}. Otherwise, {@link IllegalStateException} will be * thrown. Also, the methods of {@link Player.Listener} and {@link Listener} will be called from the * application thread. * *
The app targeting API level 30 or higher must include a {@code In addition to {@link MediaSession}, the controller also supports connecting to a legacy media
* session - {@linkplain android.media.session.MediaSession framework session} and {@linkplain
* MediaSessionCompat AndroidX session compat}.
*
* To request legacy sessions to play media, use one of the {@link #setMediaItem} methods and set
* either {@link MediaItem#mediaId}, {@link MediaItem.RequestMetadata#mediaUri} or {@link
* MediaItem.RequestMetadata#searchQuery}. Once the controller is {@linkplain #prepare() prepared},
* the controller triggers one of the following callbacks depending on the provided information and
* the value of {@link #getPlayWhenReady()}:
*
* The detailed behavior of the {@link MediaController} differs depending on the type of the
* token as follows.
*
* The hints are session-specific arguments sent to the session when connecting. The contents
* of this bundle may affect the connection result.
*
* The hints are only used when connecting to the {@link MediaSession}. They will be ignored
* when connecting to {@link MediaSessionCompat}.
*
* @param connectionHints A bundle containing the connection hints.
* @return The builder to allow chaining.
*/
@CanIgnoreReturnValue
public Builder setConnectionHints(Bundle connectionHints) {
this.connectionHints = new Bundle(checkNotNull(connectionHints));
return this;
}
/**
* Sets a listener for the controller.
*
* @param listener The listener.
* @return The builder to allow chaining.
*/
@CanIgnoreReturnValue
public Builder setListener(Listener listener) {
this.listener = checkNotNull(listener);
return this;
}
/**
* Sets a {@link Looper} that must be used for all calls to the {@link Player} methods and that
* is used to call {@link Player.Listener} methods on. The {@link Looper#myLooper()} current
* looper} at that time this builder is created will be used if not specified. The {@link
* Looper#getMainLooper() main looper} will be used if the current looper doesn't exist.
*
* @param looper The looper.
* @return The builder to allow chaining.
*/
@CanIgnoreReturnValue
public Builder setApplicationLooper(Looper looper) {
applicationLooper = checkNotNull(looper);
return this;
}
/**
* Sets a {@link BitmapLoader} for the {@link MediaController} to decode bitmaps from compressed
* binary data. If not set, a {@link CacheBitmapLoader} that wraps a {@link SimpleBitmapLoader}
* will be used.
*
* @param bitmapLoader The bitmap loader.
* @return The builder to allow chaining.
*/
@UnstableApi
@CanIgnoreReturnValue
public Builder setBitmapLoader(BitmapLoader bitmapLoader) {
this.bitmapLoader = checkNotNull(bitmapLoader);
return this;
}
/**
* Builds a {@link MediaController} asynchronously.
*
* The controller instance can be obtained like the following example:
*
* The future must be kept by callers until the future is complete to get the controller
* instance. Otherwise, the future might be garbage collected and the listener added by {@link
* ListenableFuture#addListener(Runnable, Executor)} would never be called.
*
* @return A future of the controller instance.
*/
public ListenableFuture The methods will be called from the application thread associated with the {@link
* #getApplicationLooper() application looper} of the controller.
*/
public interface Listener {
/**
* Called when the controller is disconnected from the session. The controller becomes
* unavailable afterwards and this listener won't be called anymore.
*
* It will be also called after the {@link #release()}, so you can put clean up code here.
* You don't need to call {@link #release()} after this.
*
* @param controller The controller.
*/
default void onDisconnected(MediaController controller) {}
/**
* Called when the session sets the custom layout through {@link MediaSession#setCustomLayout}.
*
* Return a {@link ListenableFuture} to reply with a {@link SessionResult} to the session
* asynchronously. You can also return a {@link SessionResult} directly by using Guava's {@link
* Futures#immediateFuture(Object)}.
*
* The default implementation returns a {@link ListenableFuture} of {@link
* SessionResult#RESULT_ERROR_NOT_SUPPORTED}.
*
* @param controller The controller.
* @param layout The ordered list of {@link CommandButton}.
* @return The result of handling the custom layout.
*/
default ListenableFuture Return a {@link ListenableFuture} to reply with a {@link SessionResult} to the session
* asynchronously. You can also return a {@link SessionResult} directly by using Guava's {@link
* Futures#immediateFuture(Object)}.
*
* The default implementation returns {@link ListenableFuture} of {@link
* SessionResult#RESULT_ERROR_NOT_SUPPORTED}.
*
* @param controller The controller.
* @param command The custom command.
* @param args The additional arguments. May be empty.
* @return The result of handling the custom command.
*/
default ListenableFuture This method does not call {@link Player#release()} of the underlying player in the session.
*/
@Override
public final void release() {
verifyApplicationThread();
if (released) {
return;
}
released = true;
applicationHandler.removeCallbacksAndMessages(null);
try {
impl.release();
} catch (Exception e) {
// Should not be here.
Log.d(TAG, "Exception while releasing impl", e);
}
if (connectionNotified) {
notifyControllerListener(listener -> listener.onDisconnected(this));
} else {
connectionNotified = true;
connectionCallback.onRejected();
}
}
/**
* Releases the future controller returned by {@link Builder#buildAsync()}. It makes sure that the
* controller is released by canceling the future if the future is not yet done.
*
* Must be called on the {@linkplain #getApplicationLooper() application thread} of the media
* controller.
*/
public static void releaseFuture(Future controllerFuture) {
if (controllerFuture.cancel(/* mayInterruptIfRunning= */ true)) {
// Successfully canceled the Future. The controller will be released by MediaControllerHolder.
return;
}
MediaController controller;
try {
controller = Futures.getDone(controllerFuture);
} catch (CancellationException | ExecutionException e) {
Log.w(TAG, "MediaController future failed (so we couldn't release it)", e);
return;
}
controller.release();
}
/**
* Returns the {@link SessionToken} of the connected session, or {@code null} if it is not
* connected.
*
* This may differ from the {@link SessionToken} from the constructor. For example, if the
* controller is created with the token for {@link MediaSessionService}, this will return a token
* for the {@link MediaSession} in the service.
*/
@Nullable
public final SessionToken getConnectedToken() {
return isConnected() ? impl.getConnectedToken() : null;
}
/** Returns whether this controller is connected to a {@link MediaSession} or not. */
public final boolean isConnected() {
return impl.isConnected();
}
@Override
public final void play() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring play().");
return;
}
impl.play();
}
@Override
public final void pause() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring pause().");
return;
}
impl.pause();
}
@Override
public final void prepare() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring prepare().");
return;
}
impl.prepare();
}
@Override
public final void seekToDefaultPosition() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekTo().");
return;
}
impl.seekToDefaultPosition();
}
@Override
public final void seekToDefaultPosition(int mediaItemIndex) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekTo().");
return;
}
impl.seekToDefaultPosition(mediaItemIndex);
}
@Override
public final void seekTo(long positionMs) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekTo().");
return;
}
impl.seekTo(positionMs);
}
@Override
public final void seekTo(int mediaItemIndex, long positionMs) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekTo().");
return;
}
impl.seekTo(mediaItemIndex, positionMs);
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link MediaSessionCompat}, it returns {code 0}.
*/
@Override
public final long getSeekBackIncrement() {
verifyApplicationThread();
return isConnected() ? impl.getSeekBackIncrement() : 0;
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link MediaSessionCompat}, it calls {@link
* MediaControllerCompat.TransportControls#rewind()}.
*/
@Override
public final void seekBack() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekBack().");
return;
}
impl.seekBack();
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link MediaSessionCompat}, it returns {code 0}.
*/
@Override
public final long getSeekForwardIncrement() {
verifyApplicationThread();
return isConnected() ? impl.getSeekForwardIncrement() : 0;
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link MediaSessionCompat}, it calls {@link
* MediaControllerCompat.TransportControls#fastForward()}.
*/
@Override
public final void seekForward() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekForward().");
return;
}
impl.seekForward();
}
/** Returns an intent for launching UI associated with the session if exists, or {@code null}. */
@Nullable
public final PendingIntent getSessionActivity() {
return isConnected() ? impl.getSessionActivity() : null;
}
@Override
@Nullable
public final PlaybackException getPlayerError() {
verifyApplicationThread();
return isConnected() ? impl.getPlayerError() : null;
}
@Override
public final void setPlayWhenReady(boolean playWhenReady) {
verifyApplicationThread();
if (isConnected()) {
impl.setPlayWhenReady(playWhenReady);
}
}
@Override
public final boolean getPlayWhenReady() {
verifyApplicationThread();
return isConnected() && impl.getPlayWhenReady();
}
@Override
public final @PlaybackSuppressionReason int getPlaybackSuppressionReason() {
verifyApplicationThread();
return isConnected()
? impl.getPlaybackSuppressionReason()
: Player.PLAYBACK_SUPPRESSION_REASON_NONE;
}
@Override
public final @State int getPlaybackState() {
verifyApplicationThread();
return isConnected() ? impl.getPlaybackState() : Player.STATE_IDLE;
}
@Override
public final boolean isPlaying() {
verifyApplicationThread();
return isConnected() && impl.isPlaying();
}
@Override
public final boolean isLoading() {
verifyApplicationThread();
return isConnected() && impl.isLoading();
}
@Override
public final long getDuration() {
verifyApplicationThread();
return isConnected() ? impl.getDuration() : C.TIME_UNSET;
}
@Override
public final long getCurrentPosition() {
verifyApplicationThread();
return isConnected() ? impl.getCurrentPosition() : 0;
}
@Override
public final long getBufferedPosition() {
verifyApplicationThread();
return isConnected() ? impl.getBufferedPosition() : 0;
}
@Override
@IntRange(from = 0, to = 100)
public final int getBufferedPercentage() {
verifyApplicationThread();
return isConnected() ? impl.getBufferedPercentage() : 0;
}
@Override
public final long getTotalBufferedDuration() {
verifyApplicationThread();
return isConnected() ? impl.getTotalBufferedDuration() : 0;
}
@Override
public final long getCurrentLiveOffset() {
verifyApplicationThread();
return isConnected() ? impl.getCurrentLiveOffset() : C.TIME_UNSET;
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, it's the same as {@link #getDuration()}
* to match the behavior with {@link #getContentPosition()} and {@link
* #getContentBufferedPosition()}.
*/
@Override
public final long getContentDuration() {
verifyApplicationThread();
return isConnected() ? impl.getContentDuration() : C.TIME_UNSET;
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, it's the same as {@link
* #getCurrentPosition()} because content position isn't available.
*/
@Override
public final long getContentPosition() {
verifyApplicationThread();
return isConnected() ? impl.getContentPosition() : 0;
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, it's the same as {@link
* #getBufferedPosition()} because content buffered position isn't available.
*/
@Override
public final long getContentBufferedPosition() {
verifyApplicationThread();
return isConnected() ? impl.getContentBufferedPosition() : 0;
}
@Override
public final boolean isPlayingAd() {
verifyApplicationThread();
return isConnected() && impl.isPlayingAd();
}
@Override
public final int getCurrentAdGroupIndex() {
verifyApplicationThread();
return isConnected() ? impl.getCurrentAdGroupIndex() : C.INDEX_UNSET;
}
@Override
public final int getCurrentAdIndexInAdGroup() {
verifyApplicationThread();
return isConnected() ? impl.getCurrentAdIndexInAdGroup() : C.INDEX_UNSET;
}
@Override
public final void setPlaybackParameters(PlaybackParameters playbackParameters) {
verifyApplicationThread();
checkNotNull(playbackParameters, "playbackParameters must not be null");
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setPlaybackParameters().");
return;
}
impl.setPlaybackParameters(playbackParameters);
}
@Override
public final void setPlaybackSpeed(float speed) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setPlaybackSpeed().");
return;
}
impl.setPlaybackSpeed(speed);
}
@Override
public final PlaybackParameters getPlaybackParameters() {
verifyApplicationThread();
return isConnected() ? impl.getPlaybackParameters() : PlaybackParameters.DEFAULT;
}
@Override
public final AudioAttributes getAudioAttributes() {
verifyApplicationThread();
if (!isConnected()) {
return AudioAttributes.DEFAULT;
}
return impl.getAudioAttributes();
}
/**
* Requests that the connected {@link MediaSession} rates the media. This will cause the rating to
* be set for the current user. The rating style must follow the user rating style from the
* session. You can get the rating style from the session through the {@link
* MediaMetadata#userRating}.
*
* If the user rating was {@code null}, the media item does not accept setting user rating.
*
* @param mediaId The non-empty {@link MediaItem#mediaId}.
* @param rating The rating to set.
* @return A {@link ListenableFuture} of {@link SessionResult} representing the pending
* completion.
*/
public final ListenableFuture If the user rating was {@code null}, the media item does not accept setting user rating.
*
* @param rating The rating to set.
* @return A {@link ListenableFuture} of {@link SessionResult} representing the pending
* completion.
*/
public final ListenableFuture A command is not accepted if it is not a custom command or the command is not in the list of
* {@linkplain #getAvailableSessionCommands() available session commands}.
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, {@link SessionResult#resultCode} will
* return the custom result code from the {@code android.os.ResultReceiver#onReceiveResult(int,
* Bundle)} instead of the standard result codes defined in the {@link SessionResult}.
*
* @param command The custom command.
* @param args The additional arguments. May be empty.
* @return A {@link ListenableFuture} of {@link SessionResult} representing the pending
* completion.
*/
public final ListenableFuture Caveat: Some methods of the {@link Timeline} such as {@link Timeline#getPeriodByUid(Object,
* Timeline.Period)}, {@link Timeline#getIndexOfPeriod(Object)}, and {@link
* Timeline#getUidOfPeriod(int)} will throw {@link UnsupportedOperationException} because of the
* limitation of restoring the instance sent from session as described in {@link
* Timeline#CREATOR}.
*/
@Override
public final Timeline getCurrentTimeline() {
verifyApplicationThread();
return isConnected() ? impl.getCurrentTimeline() : Timeline.EMPTY;
}
@Override
public final void setMediaItem(MediaItem mediaItem) {
verifyApplicationThread();
checkNotNull(mediaItem, "mediaItems must not be null");
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setMediaItem().");
return;
}
impl.setMediaItem(mediaItem);
}
@Override
public final void setMediaItem(MediaItem mediaItem, long startPositionMs) {
verifyApplicationThread();
checkNotNull(mediaItem, "mediaItems must not be null");
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setMediaItem().");
return;
}
impl.setMediaItem(mediaItem, startPositionMs);
}
@Override
public final void setMediaItem(MediaItem mediaItem, boolean resetPosition) {
verifyApplicationThread();
checkNotNull(mediaItem, "mediaItems must not be null");
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setMediaItems().");
return;
}
impl.setMediaItem(mediaItem, resetPosition);
}
@Override
public final void setMediaItems(List The MediaController returns {@code false}.
*/
@Override
public final boolean canAdvertiseSession() {
return false;
}
@Override
@Nullable
public final MediaItem getCurrentMediaItem() {
Timeline timeline = getCurrentTimeline();
return timeline.isEmpty()
? null
: timeline.getWindow(getCurrentMediaItemIndex(), window).mediaItem;
}
@Override
public final int getMediaItemCount() {
return getCurrentTimeline().getWindowCount();
}
@Override
public final MediaItem getMediaItemAt(int index) {
return getCurrentTimeline().getWindow(index, window).mediaItem;
}
@Override
public final int getCurrentPeriodIndex() {
verifyApplicationThread();
return isConnected() ? impl.getCurrentPeriodIndex() : C.INDEX_UNSET;
}
/**
* @deprecated Use {@link #getCurrentMediaItemIndex()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final int getCurrentWindowIndex() {
return getCurrentMediaItemIndex();
}
@Override
public final int getCurrentMediaItemIndex() {
verifyApplicationThread();
return isConnected() ? impl.getCurrentMediaItemIndex() : C.INDEX_UNSET;
}
/**
* @deprecated Use {@link #getPreviousMediaItemIndex()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final int getPreviousWindowIndex() {
return getPreviousMediaItemIndex();
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, this will always return {@link
* C#INDEX_UNSET} even when {@link #hasPreviousMediaItem()} is {@code true}.
*/
@Override
public final int getPreviousMediaItemIndex() {
verifyApplicationThread();
return isConnected() ? impl.getPreviousMediaItemIndex() : C.INDEX_UNSET;
}
/**
* @deprecated Use {@link #getNextMediaItemIndex()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final int getNextWindowIndex() {
return getNextMediaItemIndex();
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, this will always return {@link
* C#INDEX_UNSET} even when {@link #hasNextMediaItem()} is {@code true}.
*/
@Override
public final int getNextMediaItemIndex() {
verifyApplicationThread();
return isConnected() ? impl.getNextMediaItemIndex() : C.INDEX_UNSET;
}
/**
* @deprecated Use {@link #hasPreviousMediaItem()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final boolean hasPrevious() {
return hasPreviousMediaItem();
}
/**
* @deprecated Use {@link #hasNextMediaItem()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final boolean hasNext() {
return hasNextMediaItem();
}
/**
* @deprecated Use {@link #hasPreviousMediaItem()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final boolean hasPreviousWindow() {
return hasPreviousMediaItem();
}
/**
* @deprecated Use {@link #hasNextMediaItem()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final boolean hasNextWindow() {
return hasNextMediaItem();
}
@Override
public final boolean hasPreviousMediaItem() {
verifyApplicationThread();
return isConnected() && impl.hasPreviousMediaItem();
}
@Override
public final boolean hasNextMediaItem() {
verifyApplicationThread();
return isConnected() && impl.hasNextMediaItem();
}
/**
* @deprecated Use {@link #seekToPreviousMediaItem()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final void previous() {
seekToPreviousMediaItem();
}
/**
* @deprecated Use {@link #seekToNextMediaItem()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final void next() {
seekToNextMediaItem();
}
/**
* @deprecated Use {@link #seekToPreviousMediaItem()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final void seekToPreviousWindow() {
seekToPreviousMediaItem();
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, it's the same as {@link #seekToPrevious}.
*/
@Override
public final void seekToPreviousMediaItem() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekToPreviousMediaItem().");
return;
}
impl.seekToPreviousMediaItem();
}
/**
* @deprecated Use {@link #seekToNextMediaItem()} instead.
*/
@UnstableApi
@Deprecated
@Override
public final void seekToNextWindow() {
seekToNextMediaItem();
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, it's the same as {@link #seekToNext}.
*/
@Override
public final void seekToNextMediaItem() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekToNextMediaItem().");
return;
}
impl.seekToNextMediaItem();
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, it won't update the current media item
* index immediately because the previous media item index is unknown.
*/
@Override
public final void seekToPrevious() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekToPrevious().");
return;
}
impl.seekToPrevious();
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, it always returns {@code 0}.
*/
@Override
public final long getMaxSeekToPreviousPosition() {
verifyApplicationThread();
return isConnected() ? impl.getMaxSeekToPreviousPosition() : 0L;
}
/**
* {@inheritDoc}
*
* Interoperability: When connected to {@link
* android.support.v4.media.session.MediaSessionCompat}, it won't update the current media item
* index immediately because the previous media item index is unknown.
*/
@Override
public final void seekToNext() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring seekToNext().");
return;
}
impl.seekToNext();
}
@Override
public final @RepeatMode int getRepeatMode() {
verifyApplicationThread();
return isConnected() ? impl.getRepeatMode() : Player.REPEAT_MODE_OFF;
}
@Override
public final void setRepeatMode(@RepeatMode int repeatMode) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setRepeatMode().");
return;
}
impl.setRepeatMode(repeatMode);
}
@Override
public final boolean getShuffleModeEnabled() {
verifyApplicationThread();
return isConnected() && impl.getShuffleModeEnabled();
}
@Override
public final void setShuffleModeEnabled(boolean shuffleModeEnabled) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setShuffleMode().");
return;
}
impl.setShuffleModeEnabled(shuffleModeEnabled);
}
@Override
public final VideoSize getVideoSize() {
verifyApplicationThread();
return isConnected() ? impl.getVideoSize() : VideoSize.UNKNOWN;
}
@UnstableApi
@Override
public final Size getSurfaceSize() {
verifyApplicationThread();
return isConnected() ? impl.getSurfaceSize() : Size.UNKNOWN;
}
@Override
public final void clearVideoSurface() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring clearVideoSurface().");
return;
}
impl.clearVideoSurface();
}
@Override
public final void clearVideoSurface(@Nullable Surface surface) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring clearVideoSurface().");
return;
}
impl.clearVideoSurface(surface);
}
@Override
public final void setVideoSurface(@Nullable Surface surface) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setVideoSurface().");
return;
}
impl.setVideoSurface(surface);
}
@Override
public final void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setVideoSurfaceHolder().");
return;
}
impl.setVideoSurfaceHolder(surfaceHolder);
}
@Override
public final void clearVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring clearVideoSurfaceHolder().");
return;
}
impl.clearVideoSurfaceHolder(surfaceHolder);
}
@Override
public final void setVideoSurfaceView(@Nullable SurfaceView surfaceView) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setVideoSurfaceView().");
return;
}
impl.setVideoSurfaceView(surfaceView);
}
@Override
public final void clearVideoSurfaceView(@Nullable SurfaceView surfaceView) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring clearVideoSurfaceView().");
return;
}
impl.clearVideoSurfaceView(surfaceView);
}
@Override
public final void setVideoTextureView(@Nullable TextureView textureView) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setVideoTextureView().");
return;
}
impl.setVideoTextureView(textureView);
}
@Override
public final void clearVideoTextureView(@Nullable TextureView textureView) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring clearVideoTextureView().");
return;
}
impl.clearVideoTextureView(textureView);
}
@Override
public final CueGroup getCurrentCues() {
verifyApplicationThread();
return isConnected() ? impl.getCurrentCues() : CueGroup.EMPTY_TIME_ZERO;
}
@Override
@FloatRange(from = 0, to = 1)
public final float getVolume() {
verifyApplicationThread();
return isConnected() ? impl.getVolume() : 1;
}
@Override
public final void setVolume(@FloatRange(from = 0, to = 1) float volume) {
verifyApplicationThread();
checkArgument(volume >= 0 && volume <= 1, "volume must be between 0 and 1");
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setVolume().");
return;
}
impl.setVolume(volume);
}
@Override
public final DeviceInfo getDeviceInfo() {
verifyApplicationThread();
if (!isConnected()) {
return DeviceInfo.UNKNOWN;
}
return impl.getDeviceInfo();
}
@Override
@IntRange(from = 0)
public final int getDeviceVolume() {
verifyApplicationThread();
if (!isConnected()) {
return 0;
}
return impl.getDeviceVolume();
}
@Override
public final boolean isDeviceMuted() {
verifyApplicationThread();
if (!isConnected()) {
return false;
}
return impl.isDeviceMuted();
}
/**
* @deprecated Use {@link #setDeviceVolume(int, int)} instead.
*/
@Deprecated
@Override
public final void setDeviceVolume(@IntRange(from = 0) int volume) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setDeviceVolume().");
return;
}
impl.setDeviceVolume(volume);
}
@Override
public final void setDeviceVolume(@IntRange(from = 0) int volume, @C.VolumeFlags int flags) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setDeviceVolume().");
return;
}
impl.setDeviceVolume(volume, flags);
}
/**
* @deprecated Use {@link #increaseDeviceVolume(int)} instead.
*/
@Deprecated
@Override
public final void increaseDeviceVolume() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring increaseDeviceVolume().");
return;
}
impl.increaseDeviceVolume();
}
@Override
public final void increaseDeviceVolume(@C.VolumeFlags int flags) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring increaseDeviceVolume().");
return;
}
impl.increaseDeviceVolume(flags);
}
/**
* @deprecated Use {@link #decreaseDeviceVolume(int)} instead.
*/
@Deprecated
@Override
public final void decreaseDeviceVolume() {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring decreaseDeviceVolume().");
return;
}
impl.decreaseDeviceVolume();
}
@Override
public final void decreaseDeviceVolume(@C.VolumeFlags int flags) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring decreaseDeviceVolume().");
return;
}
impl.decreaseDeviceVolume(flags);
}
/**
* @deprecated Use {@link #setDeviceMuted(boolean, int)} instead.
*/
@Deprecated
@Override
public final void setDeviceMuted(boolean muted) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setDeviceMuted().");
return;
}
impl.setDeviceMuted(muted);
}
@Override
public final void setDeviceMuted(boolean muted, @C.VolumeFlags int flags) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setDeviceMuted().");
return;
}
impl.setDeviceMuted(muted, flags);
}
@Override
public final MediaMetadata getMediaMetadata() {
verifyApplicationThread();
return isConnected() ? impl.getMediaMetadata() : MediaMetadata.EMPTY;
}
@Override
public final Tracks getCurrentTracks() {
verifyApplicationThread();
return isConnected() ? impl.getCurrentTracks() : Tracks.EMPTY;
}
@Override
public final TrackSelectionParameters getTrackSelectionParameters() {
verifyApplicationThread();
if (!isConnected()) {
return TrackSelectionParameters.DEFAULT_WITHOUT_CONTEXT;
}
return impl.getTrackSelectionParameters();
}
@Override
public final void setTrackSelectionParameters(TrackSelectionParameters parameters) {
verifyApplicationThread();
if (!isConnected()) {
Log.w(TAG, "The controller is not connected. Ignoring setTrackSelectionParameters().");
}
impl.setTrackSelectionParameters(parameters);
}
@Override
public final Looper getApplicationLooper() {
// Don't verify application thread. We allow calls to this method from any thread.
return applicationHandler.getLooper();
}
/**
* Gets the optional time diff (in milliseconds) used for calculating the current position, or
* {@link C#TIME_UNSET} if no diff should be applied.
*/
/* package */ final long getTimeDiffMs() {
return timeDiffMs;
}
/**
* Sets the time diff (in milliseconds) used when calculating the current position.
*
* @param timeDiffMs {@link C#TIME_UNSET} for reset.
*/
@VisibleForTesting(otherwise = NONE)
/* package */ final void setTimeDiffMs(long timeDiffMs) {
verifyApplicationThread();
this.timeDiffMs = timeDiffMs;
}
@Override
public final void addListener(Player.Listener listener) {
// Don't verify application thread. We allow calls to this method from any thread.
checkNotNull(listener, "listener must not be null");
impl.addListener(listener);
}
@Override
public final void removeListener(Player.Listener listener) {
verifyApplicationThread();
checkNotNull(listener, "listener must not be null");
impl.removeListener(listener);
}
@Override
public final boolean isCommandAvailable(@Command int command) {
return getAvailableCommands().contains(command);
}
@Override
public final Commands getAvailableCommands() {
verifyApplicationThread();
if (!isConnected()) {
return Commands.EMPTY;
}
return impl.getAvailableCommands();
}
/**
* Returns whether the {@link SessionCommand.CommandCode} is available. The {@code
* sessionCommandCode} must not be {@link SessionCommand#COMMAND_CODE_CUSTOM}. Use {@link
* #isSessionCommandAvailable(SessionCommand)} for custom commands.
*/
public final boolean isSessionCommandAvailable(
@SessionCommand.CommandCode int sessionCommandCode) {
return getAvailableSessionCommands().contains(sessionCommandCode);
}
/** Returns whether the {@link SessionCommand} is available. */
public final boolean isSessionCommandAvailable(SessionCommand sessionCommand) {
return getAvailableSessionCommands().contains(sessionCommand);
}
/**
* Returns the current available session commands from {@link
* Listener#onAvailableSessionCommandsChanged(MediaController, SessionCommands)}, or {@link
* SessionCommands#EMPTY} if it is not connected.
*
* @return The available session commands.
*/
public final SessionCommands getAvailableSessionCommands() {
verifyApplicationThread();
if (!isConnected()) {
return SessionCommands.EMPTY;
}
return impl.getAvailableSessionCommands();
}
private static ListenableFuture{@code
*
*
*
* Backward Compatibility with legacy media sessions
*
*
*
*
* Other playlist change methods, like {@link #addMediaItem} or {@link #removeMediaItem}, trigger
* the {@link MediaSessionCompat.Callback#onAddQueueItem onAddQueueItem} and {@link
* MediaSessionCompat.Callback#onRemoveQueueItem} onRemoveQueueItem} callbacks. Check {@link
* #getAvailableCommands()} to see if playlist modifications are {@linkplain
* androidx.media3.common.Player.Command#COMMAND_CHANGE_MEDIA_ITEMS supported} by the legacy
* session.
*/
@DoNotMock
public class MediaController implements Player {
/**
* The timeout for handling pending commands after calling {@link #release()}. If the timeout is
* reached, the controller is unbound from the session service even if commands are still pending.
*/
@UnstableApi public static final long RELEASE_UNBIND_TIMEOUT_MS = 30_000;
private static final String TAG = "MediaController";
private static final String WRONG_THREAD_ERROR_MESSAGE =
"MediaController method is called from a wrong thread."
+ " See javadoc of MediaController for details.";
/** A builder for {@link MediaController}. */
public static final class Builder {
private final Context context;
private final SessionToken token;
private Bundle connectionHints;
private Listener listener;
private Looper applicationLooper;
private @MonotonicNonNull BitmapLoader bitmapLoader;
/**
* Creates a builder for {@link MediaController}.
*
*
*
*
* @param context The context.
* @param token The token to connect to.
*/
public Builder(Context context, SessionToken token) {
this.context = checkNotNull(context);
this.token = checkNotNull(token);
connectionHints = Bundle.EMPTY;
listener = new Listener() {};
applicationLooper = Util.getCurrentOrMainLooper();
}
/**
* Sets connection hints for the controller.
*
* {@code
* MediaController.Builder builder = ...;
* ListenableFuture
*
*