Clean up MediaSessionExt documentation

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=163828712
This commit is contained in:
olly 2017-08-01 07:50:12 -07:00 committed by Oliver Woodman
parent 395249a950
commit b2da61f70b
5 changed files with 112 additions and 116 deletions

View File

@ -21,40 +21,50 @@ import com.google.android.exoplayer2.C;
import com.google.android.exoplayer2.Player;
/**
* A default implementation of the {@link MediaSessionConnector.PlaybackController}. You can safely
* override any method for instance to intercept calls for a given action.
* A default implementation of {@link MediaSessionConnector.PlaybackController}.
* <p>
* Methods can be safely overridden by subclasses to intercept calls for given actions.
*/
public class DefaultPlaybackController implements MediaSessionConnector.PlaybackController {
/**
* The default fast forward increment, in milliseconds.
*/
public static final int DEFAULT_FAST_FORWARD_MS = 15000;
/**
* The default rewind increment, in milliseconds.
*/
public static final int DEFAULT_REWIND_MS = 5000;
private static final long BASE_ACTIONS = PlaybackStateCompat.ACTION_PLAY_PAUSE
| PlaybackStateCompat.ACTION_PLAY | PlaybackStateCompat.ACTION_PAUSE
| PlaybackStateCompat.ACTION_STOP;
protected final long fastForwardIncrementMs;
protected final long rewindIncrementMs;
protected final long fastForwardIncrementMs;
/**
* Creates a new {@link DefaultPlaybackController}. This is equivalent to calling
* {@code DefaultPlaybackController(15000L, 5000L)}.
* Creates a new instance.
* <p>
* Equivalent to {@code DefaultPlaybackController(
* DefaultPlaybackController.DEFAULT_REWIND_MS,
* DefaultPlaybackController.DEFAULT_FAST_FORWARD_MS)}.
*/
public DefaultPlaybackController() {
this(15000L, 5000L);
this(DEFAULT_REWIND_MS, DEFAULT_FAST_FORWARD_MS);
}
/**
* Creates a new {@link DefaultPlaybackController} and sets the fast forward and rewind increments
* in milliseconds.
* Creates a new instance with the given fast forward and rewind increments.
*
* @param fastForwardIncrementMs A positive value will cause the
* {@link PlaybackStateCompat#ACTION_FAST_FORWARD} playback action to be added. A zero or a
* negative value will cause it to be removed.
* @param rewindIncrementMs A positive value will cause the
* {@link PlaybackStateCompat#ACTION_REWIND} playback action to be added. A zero or a
* negative value will cause it to be removed.
* @param rewindIncrementMs The rewind increment in milliseconds. A zero or negative value will
* cause the rewind action to be disabled.
* @param fastForwardIncrementMs The fast forward increment in milliseconds. A zero or negative
* value will cause the fast forward action to be removed.
*/
public DefaultPlaybackController(long fastForwardIncrementMs, long rewindIncrementMs) {
this.fastForwardIncrementMs = fastForwardIncrementMs;
public DefaultPlaybackController(long rewindIncrementMs, long fastForwardIncrementMs) {
this.rewindIncrementMs = rewindIncrementMs;
this.fastForwardIncrementMs = fastForwardIncrementMs;
}
@Override

View File

@ -44,30 +44,27 @@ import java.util.List;
import java.util.Map;
/**
* Mediates between a {@link MediaSessionCompat} and an {@link Player} instance set with
* {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}.
* Connects a {@link MediaSessionCompat} to a {@link Player}.
* <p>
* The {@code MediaSessionConnector} listens for media actions sent by a media controller and
* realizes these actions by calling appropriate ExoPlayer methods. Further, the state of ExoPlayer
* will be synced automatically with the {@link PlaybackStateCompat} of the media session to
* broadcast state transitions to clients. You can optionally extend this behaviour by providing
* various collaborators.
* <p>
* Media actions to initiate media playback ({@code PlaybackStateCompat#ACTION_PREPARE_*} and
* {@code PlaybackStateCompat#ACTION_PLAY_*} need to be handled by a {@link PlaybackPreparer} which
* build a {@link com.google.android.exoplayer2.source.MediaSource} to prepare ExoPlayer. Deploy
* your preparer by calling {@link #setPlaybackPreparer(PlaybackPreparer)}.
* <p>
* To support a media session queue and navigation within this queue, you can set a
* {@link QueueNavigator} to maintain the queue yourself and implement queue navigation commands
* (like 'skip to next') sent by controllers. It's recommended to use the
* {@link TimelineQueueNavigator} to allow users navigating the windows of the ExoPlayer timeline.
* <p>
* If you want to allow media controllers to manipulate the queue, implement a {@link QueueEditor}
* and deploy it with {@link #setQueueEditor(QueueEditor)}.
* <p>
* Set an {@link ErrorMessageProvider} to provide an error code and a human readable error message
* to be broadcast to controllers.
* The connector listens for actions sent by the media session's controller and implements these
* actions by calling appropriate ExoPlayer methods. The playback state of the media session is
* automatically synced with the player. The connector can also be optionally extended by providing
* various collaborators:
* <ul>
* <li>Actions to initiate media playback ({@code PlaybackStateCompat#ACTION_PREPARE_*} and
* {@code PlaybackStateCompat#ACTION_PLAY_*}) can be handled by a {@link PlaybackPreparer} passed
* when calling {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}. Custom
* actions can be handled by passing one or more {@link CustomActionProvider}s in a similar way.
* </li>
* <li>To enable a media queue and navigation within it, you can set a {@link QueueNavigator} by
* calling {@link #setQueueNavigator(QueueNavigator)}. Use of {@link TimelineQueueNavigator} is
* recommended for most use cases.</li>
* <li>To enable editing of the media queue, you can set a {@link QueueEditor} by calling
* {@link #setQueueEditor(QueueEditor)}.</li>
* <li>An {@link ErrorMessageProvider} for providing human readable error messages and
* corresponding error codes can be set by calling
* {@link #setErrorMessageProvider(ErrorMessageProvider)}.</li>
* </ul>
*/
public final class MediaSessionConnector {
@ -78,12 +75,7 @@ public final class MediaSessionConnector {
public static final String EXTRAS_PITCH = "EXO_PITCH";
/**
* Interface to which media controller commands regarding preparing playback for a given media
* clip are delegated to.
* <p>
* Normally preparing playback includes preparing the player with a
* {@link com.google.android.exoplayer2.source.MediaSource} and setting up the media session queue
* with a corresponding list of queue items.
* Interface to which playback preparation actions are delegated.
*/
public interface PlaybackPreparer {
@ -131,7 +123,7 @@ public final class MediaSessionConnector {
}
/**
* Controller to handle playback actions.
* Interface to which playback actions are delegated.
*/
public interface PlaybackController {
@ -178,8 +170,8 @@ public final class MediaSessionConnector {
}
/**
* Navigator to handle queue navigation actions and maintain the media session queue with
* {#link MediaSessionCompat#setQueue(List)} to provide the active queue item to the connector.
* Handles queue navigation actions, and updates the media session queue by calling
* {@code MediaSessionCompat.setQueue()}.
*/
public interface QueueNavigator {
@ -211,7 +203,7 @@ public final class MediaSessionConnector {
*/
void onCurrentWindowIndexChanged(Player player);
/**
* Gets the id of the currently active queue item or
* Gets the id of the currently active queue item, or
* {@link MediaSessionCompat.QueueItem#UNKNOWN_ID} if the active item is unknown.
* <p>
* To let the connector publish metadata for the active queue item, the queue item with the
@ -241,7 +233,7 @@ public final class MediaSessionConnector {
}
/**
* Editor to manipulate the queue.
* Handles media session queue edits.
*/
public interface QueueEditor {
@ -302,12 +294,12 @@ public final class MediaSessionConnector {
}
/**
* Provides an user readable error code and a message for {@link ExoPlaybackException}s.
* Converts an exception into an error code and a user readable error message.
*/
public interface ErrorMessageProvider {
/**
* Returns a pair of an error code and a user readable error message for a given
* {@link ExoPlaybackException}.
* Returns a pair consisting of an error code and a user readable error message for a given
* exception.
*/
Pair<Integer, String> getErrorMessage(ExoPlaybackException playbackException);
}
@ -316,6 +308,7 @@ public final class MediaSessionConnector {
* The wrapped {@link MediaSessionCompat}.
*/
public final MediaSessionCompat mediaSession;
private final MediaControllerCompat mediaController;
private final Handler handler;
private final boolean doMaintainMetadata;
@ -334,11 +327,10 @@ public final class MediaSessionConnector {
private ExoPlaybackException playbackException;
/**
* Creates a {@code MediaSessionConnector}. This is equivalent to calling
* {@code #MediaSessionConnector(mediaSession, new DefaultPlaybackController)}.
* Creates an instance. Must be called on the same thread that is used to construct the player
* instances passed to {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}.
* <p>
* Constructing the {@link MediaSessionConnector} needs to be done on the same thread as
* constructing the player instance.
* Equivalent to {@code MediaSessionConnector(mediaSession, new DefaultPlaybackController())}.
*
* @param mediaSession The {@link MediaSessionCompat} to connect to.
*/
@ -347,14 +339,13 @@ public final class MediaSessionConnector {
}
/**
* Creates a {@code MediaSessionConnector}. This is equivalent to calling
* {@code #MediaSessionConnector(mediaSession, playbackController, true)}.
* Creates an instance. Must be called on the same thread that is used to construct the player
* instances passed to {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}.
* <p>
* Constructing the {@link MediaSessionConnector} needs to be done on the same thread as
* constructing the player instance.
* Equivalent to {@code MediaSessionConnector(mediaSession, playbackController, true)}.
*
* @param mediaSession The {@link MediaSessionCompat} to connect to.
* @param playbackController The {@link PlaybackController}.
* @param playbackController A {@link PlaybackController} for handling playback actions.
*/
public MediaSessionConnector(MediaSessionCompat mediaSession,
PlaybackController playbackController) {
@ -362,19 +353,14 @@ public final class MediaSessionConnector {
}
/**
* Creates a {@code MediaSessionConnector} with {@link CustomActionProvider}s.
* <p>
* If you choose to pass {@code false} for {@code doMaintainMetadata} you need to maintain the
* metadata of the media session yourself (provide at least the duration to allow clients to show
* a progress bar).
* <p>
* Constructing the {@link MediaSessionConnector} needs to be done on the same thread as
* constructing the player instance.
* Creates an instance. Must be called on the same thread that is used to construct the player
* instances passed to {@link #setPlayer(Player, PlaybackPreparer, CustomActionProvider...)}.
*
* @param mediaSession The {@link MediaSessionCompat} to connect to.
* @param playbackController The {@link PlaybackController}.
* @param doMaintainMetadata Sets whether the connector should maintain the metadata of the
* session.
* @param playbackController A {@link PlaybackController} for handling playback actions.
* @param doMaintainMetadata Whether the connector should maintain the metadata of the session. If
* {@code false}, you need to maintain the metadata of the media session yourself (provide at
* least the duration to allow clients to show a progress bar).
*/
public MediaSessionConnector(MediaSessionCompat mediaSession,
PlaybackController playbackController, boolean doMaintainMetadata) {
@ -392,17 +378,14 @@ public final class MediaSessionConnector {
}
/**
* Sets the player to which media commands sent by a media controller are delegated.
* <p>
* The media session callback is set if the {@code player} is not {@code null} and the callback is
* removed if the {@code player} is {@code null}.
* Sets the player to be connected to the media session.
* <p>
* The order in which any {@link CustomActionProvider}s are passed determines the order of the
* actions published with the playback state of the session.
*
* @param player The player to be connected to the {@code MediaSession}.
* @param playbackPreparer The playback preparer for the player.
* @param customActionProviders Optional {@link CustomActionProvider}s to publish and handle
* @param playbackPreparer An optional {@link PlaybackPreparer} for preparing the player.
* @param customActionProviders An optional {@link CustomActionProvider}s to publish and handle
* custom actions.
*/
public void setPlayer(Player player, PlaybackPreparer playbackPreparer,
@ -411,7 +394,7 @@ public final class MediaSessionConnector {
this.player.removeListener(exoPlayerEventListener);
mediaSession.setCallback(null);
}
setPlaybackPreparer(playbackPreparer);
this.playbackPreparer = playbackPreparer;
this.player = player;
this.customActionProviders = (player != null && customActionProviders != null)
? customActionProviders : new CustomActionProvider[0];
@ -424,9 +407,9 @@ public final class MediaSessionConnector {
}
/**
* Sets the optional {@link ErrorMessageProvider}.
* Sets the {@link ErrorMessageProvider}.
*
* @param errorMessageProvider The {@link ErrorMessageProvider}.
* @param errorMessageProvider The error message provider.
*/
public void setErrorMessageProvider(ErrorMessageProvider errorMessageProvider) {
this.errorMessageProvider = errorMessageProvider;
@ -437,25 +420,21 @@ public final class MediaSessionConnector {
* {@code ACTION_SKIP_TO_PREVIOUS}, {@code ACTION_SKIP_TO_QUEUE_ITEM} and
* {@code ACTION_SET_SHUFFLE_MODE_ENABLED}.
*
* @param queueNavigator The navigator to handle queue navigation.
* @param queueNavigator The queue navigator.
*/
public void setQueueNavigator(QueueNavigator queueNavigator) {
this.queueNavigator = queueNavigator;
}
/**
* Sets the queue editor to handle commands to manipulate the queue sent by a media controller.
* Sets the {@link QueueEditor} to handle queue edits sent by the media controller.
*
* @param queueEditor The editor to handle queue manipulation actions.
* @param queueEditor The queue editor.
*/
public void setQueueEditor(QueueEditor queueEditor) {
this.queueEditor = queueEditor;
}
private void setPlaybackPreparer(PlaybackPreparer playbackPreparer) {
this.playbackPreparer = playbackPreparer;
}
private void updateMediaSessionPlaybackState() {
PlaybackStateCompat.Builder builder = new PlaybackStateCompat.Builder();
if (player == null) {
@ -603,6 +582,7 @@ public final class MediaSessionConnector {
}
private class ExoPlayerEventListener implements Player.EventListener {
@Override
public void onTimelineChanged(Timeline timeline, Object manifest) {
if (queueNavigator != null) {

View File

@ -26,10 +26,13 @@ import com.google.android.exoplayer2.util.RepeatModeUtil;
*/
public final class RepeatModeActionProvider implements MediaSessionConnector.CustomActionProvider {
/**
* The default repeat toggle modes.
*/
public static final @RepeatModeUtil.RepeatToggleModes int DEFAULT_REPEAT_TOGGLE_MODES =
RepeatModeUtil.REPEAT_TOGGLE_MODE_ONE | RepeatModeUtil.REPEAT_TOGGLE_MODE_ALL;
private static final String ACTION_REPEAT_MODE = "ACTION_EXO_REPEAT_MODE";
@RepeatModeUtil.RepeatToggleModes
private static final int DEFAULT_REPEAT_MODES = RepeatModeUtil.REPEAT_TOGGLE_MODE_ONE
| RepeatModeUtil.REPEAT_TOGGLE_MODE_ALL;
private final Player player;
@RepeatModeUtil.RepeatToggleModes
@ -39,20 +42,20 @@ public final class RepeatModeActionProvider implements MediaSessionConnector.Cus
private final CharSequence repeatOffDescription;
/**
* Creates a new {@link RepeatModeActionProvider}.
* Creates a new instance.
* <p>
* This is equivalent to calling the two argument constructor with
* {@code RepeatModeUtil#REPEAT_TOGGLE_MODE_ONE | RepeatModeUtil#REPEAT_TOGGLE_MODE_ALL}.
* Equivalent to {@code RepeatModeActionProvider(context, player,
* RepeatModeActionProvider.DEFAULT_REPEAT_TOGGLE_MODES)}.
*
* @param context The context.
* @param player The player on which to toggle the repeat mode.
*/
public RepeatModeActionProvider(Context context, Player player) {
this(context, player, DEFAULT_REPEAT_MODES);
this(context, player, DEFAULT_REPEAT_TOGGLE_MODES);
}
/**
* Creates a new {@link RepeatModeActionProvider} for the given repeat toggle modes.
* Creates a new instance enabling the given repeat toggle modes.
*
* @param context The context.
* @param player The player on which to toggle the repeat mode.

View File

@ -29,9 +29,8 @@ import java.util.Collections;
import java.util.List;
/**
* An abstract implementation of the {@link MediaSessionConnector.QueueNavigator} that's based on an
* {@link Player}'s current {@link Timeline} and maps the timeline of the player to the media
* session queue.
* An abstract implementation of the {@link MediaSessionConnector.QueueNavigator} that maps the
* windows of a {@link Player}'s {@link Timeline} to the media session queue.
*/
public abstract class TimelineQueueNavigator implements MediaSessionConnector.QueueNavigator {
@ -44,10 +43,9 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu
private long activeQueueItemId;
/**
* Creates a new timeline queue navigator for a given {@link MediaSessionCompat}.
* Creates an instance for a given {@link MediaSessionCompat}.
* <p>
* This is equivalent to calling
* {@code #TimelineQueueNavigator(mediaSession, DEFAULT_MAX_QUEUE_SIZE)}.
* Equivalent to {@code TimelineQueueNavigator(mediaSession, DEFAULT_MAX_QUEUE_SIZE)}.
*
* @param mediaSession The {@link MediaSessionCompat}.
*/
@ -56,12 +54,11 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu
}
/**
* Creates a new timeline queue navigator for a given {@link MediaSessionCompat} and a maximum
* queue size of {@code maxQueueSize}.
* Creates an instance for a given {@link MediaSessionCompat} and maximum queue size.
* <p>
* If the actual queue size is larger than {@code maxQueueSize} a floating window of
* {@code maxQueueSize} is applied and moved back and forth when the user is navigating within the
* queue.
* If the number of windows in the {@link Player}'s {@link Timeline} exceeds {@code maxQueueSize},
* the media session queue will correspond to {@code maxQueueSize} windows centered on the one
* currently being played.
*
* @param mediaSession The {@link MediaSessionCompat}.
* @param maxQueueSize The maximum queue size.
@ -80,12 +77,6 @@ public abstract class TimelineQueueNavigator implements MediaSessionConnector.Qu
*/
public abstract MediaDescriptionCompat getMediaDescription(int windowIndex);
/**
* Supports the following media actions: {@code PlaybackStateCompat.ACTION_SKIP_TO_NEXT |
* PlaybackStateCompat.ACTION_SKIP_TO_PREVIOUS | PlaybackStateCompat.ACTION_SKIP_TO_QUEUE_ITEM}.
*
* @return The bit mask of the supported media actions.
*/
@Override
public long getSupportedQueueNavigatorActions(Player player) {
if (player == null || player.getCurrentTimeline().getWindowCount() < 2) {

View File

@ -249,11 +249,23 @@ public class PlaybackControlView extends FrameLayout {
};
/**
* The default fast forward increment, in milliseconds.
*/
public static final int DEFAULT_FAST_FORWARD_MS = 15000;
/**
* The default rewind increment, in milliseconds.
*/
public static final int DEFAULT_REWIND_MS = 5000;
/**
* The default show timeout, in milliseconds.
*/
public static final int DEFAULT_SHOW_TIMEOUT_MS = 5000;
public static final @RepeatModeUtil.RepeatToggleModes int DEFAULT_REPEAT_TOGGLE_MODES
= RepeatModeUtil.REPEAT_TOGGLE_MODE_NONE;
/**
* The default repeat toggle modes.
*/
public static final @RepeatModeUtil.RepeatToggleModes int DEFAULT_REPEAT_TOGGLE_MODES =
RepeatModeUtil.REPEAT_TOGGLE_MODE_NONE;
/**
* The maximum number of windows that can be shown in a multi-window time bar.