Skip to content

SDK / exoplayer

Go to a project
Commit de203fe0 by ibaker Committed by christosts
Options

Document the relationship between Player methods and available commands 

#minor-release

PiperOrigin-RevId: 496668378
(cherry picked from commit 54e79689)
parent 730f3a3a
Inline Side-by-side
Showing with 524 additions and 55 deletions
library/common/src/main/java/com/google/android/exoplayer2/Player.java
......@@ -1403,6 +1403,9 @@ public interface Player {
* <p>The currently available commands can be inspected with {@link #getAvailableCommands()} and
* {@link #isCommandAvailable(int)}.
*
* <p>See the documentation of each command constant for the details of which methods it permits
* calling.
*
* <p>One of the following values:
*
* <ul>
......@@ -1479,21 +1482,62 @@ public interface Player {
COMMAND_GET_TRACKS,
})
@interface Command {}
/** Command to start, pause or resume playback. */
/**
* Command to start, pause or resume playback.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #play()}
* <li>{@link #pause()}
* <li>{@link #setPlayWhenReady(boolean)}
* </ul>
*/
int COMMAND_PLAY_PAUSE = 1;
/** Command to prepare the player. */
/**
* Command to prepare the player.
*
* <p>The {@link #prepare()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_PREPARE = 2;
/** Command to stop playback. */
/**
* Command to stop playback.
*
* <p>The {@link #stop()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_STOP = 3;
/** Command to seek to the default position of the current {@link MediaItem}. */
/**
* Command to seek to the default position of the current {@link MediaItem}.
*
* <p>The {@link #seekToDefaultPosition()} method must only be called if this command is
* {@linkplain #isCommandAvailable(int) available}.
*/
int COMMAND_SEEK_TO_DEFAULT_POSITION = 4;
/** Command to seek anywhere inside the current {@link MediaItem}. */
/**
* Command to seek anywhere inside the current {@link MediaItem}.
*
* <p>The {@link #seekTo(long)} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM = 5;
/**
* @deprecated Use {@link #COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM} instead.
*/
@Deprecated int COMMAND_SEEK_IN_CURRENT_WINDOW = COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM;
/** Command to seek to the default position of the previous {@link MediaItem}. */
/**
* Command to seek to the default position of the previous {@link MediaItem}.
*
* <p>The {@link #seekToPreviousMediaItem()} method must only be called if this command is
* {@linkplain #isCommandAvailable(int) available}.
*/
int COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM = 6;
/**
* @deprecated Use {@link #COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM} instead.
......@@ -1502,9 +1546,17 @@ public interface Player {
/**
* Command to seek to an earlier position in the current {@link MediaItem} or the default position
* of the previous {@link MediaItem}.
*
* <p>The {@link #seekToPrevious()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_SEEK_TO_PREVIOUS = 7;
/** Command to seek to the default position of the next {@link MediaItem}. */
/**
* Command to seek to the default position of the next {@link MediaItem}.
*
* <p>The {@link #seekToNextMediaItem()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_SEEK_TO_NEXT_MEDIA_ITEM = 8;
/**
* @deprecated Use {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM} instead.
......@@ -1513,57 +1565,259 @@ public interface Player {
/**
* Command to seek to a later position in the current {@link MediaItem} or the default position of
* the next {@link MediaItem}.
*
* <p>The {@link #seekToNext()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_SEEK_TO_NEXT = 9;
/** Command to seek anywhere in any {@link MediaItem}. */
/**
* Command to seek anywhere in any {@link MediaItem}.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #seekTo(int, long)}
* <li>{@link #seekToDefaultPosition(int)}
* </ul>
*/
int COMMAND_SEEK_TO_MEDIA_ITEM = 10;
/**
* @deprecated Use {@link #COMMAND_SEEK_TO_MEDIA_ITEM} instead.
*/
@Deprecated int COMMAND_SEEK_TO_WINDOW = COMMAND_SEEK_TO_MEDIA_ITEM;
/** Command to seek back by a fixed increment inside the current {@link MediaItem}. */
/**
* Command to seek back by a fixed increment inside the current {@link MediaItem}.
*
* <p>The {@link #seekBack()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_SEEK_BACK = 11;
/** Command to seek forward by a fixed increment inside the current {@link MediaItem}. */
/**
* Command to seek forward by a fixed increment inside the current {@link MediaItem}.
*
* <p>The {@link #seekForward()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_SEEK_FORWARD = 12;
/** Command to set the playback speed and pitch. */
/**
* Command to set the playback speed and pitch.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #setPlaybackParameters(PlaybackParameters)}
* <li>{@link #setPlaybackSpeed(float)}
* </ul>
*/
int COMMAND_SET_SPEED_AND_PITCH = 13;
/** Command to enable shuffling. */
/**
* Command to enable shuffling.
*
* <p>The {@link #setShuffleModeEnabled(boolean)} method must only be called if this command is
* {@linkplain #isCommandAvailable(int) available}.
*/
int COMMAND_SET_SHUFFLE_MODE = 14;
/** Command to set the repeat mode. */
/**
* Command to set the repeat mode.
*
* <p>The {@link #setRepeatMode(int)} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_SET_REPEAT_MODE = 15;
/** Command to get the currently playing {@link MediaItem}. */
/**
* Command to get the currently playing {@link MediaItem}.
*
* <p>The {@link #getCurrentMediaItem()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_GET_CURRENT_MEDIA_ITEM = 16;
/** Command to get the information about the current timeline. */
/**
* Command to get the information about the current timeline.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #getCurrentTimeline()}
* <li>{@link #getCurrentMediaItemIndex()}
* <li>{@link #getCurrentPeriodIndex()}
* <li>{@link #getMediaItemCount()}
* <li>{@link #getMediaItemAt(int)}
* <li>{@link #getNextMediaItemIndex()}
* <li>{@link #getPreviousMediaItemIndex()}
* <li>{@link #hasPreviousMediaItem()}
* <li>{@link #hasNextMediaItem()}
* <li>{@link #getCurrentAdGroupIndex()}
* <li>{@link #getCurrentAdIndexInAdGroup()}
* </ul>
*/
int COMMAND_GET_TIMELINE = 17;
/** Command to get metadata related to the playlist and current {@link MediaItem}. */
/**
* Command to get metadata related to the playlist and current {@link MediaItem}.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #getMediaMetadata()}
* <li>{@link #getPlaylistMetadata()}
* </ul>
*/
// TODO(b/263132691): Rename this to COMMAND_GET_METADATA
int COMMAND_GET_MEDIA_ITEMS_METADATA = 18;
/** Command to set the playlist metadata. */
/**
* Command to set the playlist metadata.
*
* <p>The {@link #setPlaylistMetadata(MediaMetadata)} method must only be called if this command
* is {@linkplain #isCommandAvailable(int) available}.
*/
// TODO(b/263132691): Rename this to COMMAND_SET_PLAYLIST_METADATA
int COMMAND_SET_MEDIA_ITEMS_METADATA = 19;
/** Command to set a {@link MediaItem}. */
/**
* Command to set a {@link MediaItem}.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #setMediaItem(MediaItem)}
* <li>{@link #setMediaItem(MediaItem, boolean)}
* <li>{@link #setMediaItem(MediaItem, long)}
* </ul>
*/
int COMMAND_SET_MEDIA_ITEM = 31;
/** Command to change the {@linkplain MediaItem media items} in the playlist. */
/**
* Command to change the {@linkplain MediaItem media items} in the playlist.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #addMediaItem(MediaItem)}
* <li>{@link #addMediaItem(int, MediaItem)}
* <li>{@link #addMediaItems(List)}
* <li>{@link #addMediaItems(int, List)}
* <li>{@link #clearMediaItems()}
* <li>{@link #moveMediaItem(int, int)}
* <li>{@link #moveMediaItems(int, int, int)}
* <li>{@link #removeMediaItem(int)}
* <li>{@link #removeMediaItems(int, int)}
* <li>{@link #setMediaItems(List)}
* <li>{@link #setMediaItems(List, boolean)}
* <li>{@link #setMediaItems(List, int, long)}
* </ul>
*/
int COMMAND_CHANGE_MEDIA_ITEMS = 20;
/** Command to get the player current {@link AudioAttributes}. */
/**
* Command to get the player current {@link AudioAttributes}.
*
* <p>The {@link #getAudioAttributes()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_GET_AUDIO_ATTRIBUTES = 21;
/** Command to get the player volume. */
/**
* Command to get the player volume.
*
* <p>The {@link #getVolume()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_GET_VOLUME = 22;
/** Command to get the device volume and whether it is muted. */
/**
* Command to get the device volume and whether it is muted.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #getDeviceVolume()}
* <li>{@link #isDeviceMuted()}
* </ul>
*/
int COMMAND_GET_DEVICE_VOLUME = 23;
/** Command to set the player volume. */
/**
* Command to set the player volume.
*
* <p>The {@link #setVolume(float)} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_SET_VOLUME = 24;
/** Command to set the device volume. */
/**
* Command to set the device volume.
*
* <p>The {@link #setDeviceVolume(int)} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_SET_DEVICE_VOLUME = 25;
/** Command to increase and decrease the device volume and mute it. */
/**
* Command to increase and decrease the device volume and mute it.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #increaseDeviceVolume()}
* <li>{@link #decreaseDeviceVolume()}
* <li>{@link #setDeviceMuted(boolean)}
* </ul>
*/
int COMMAND_ADJUST_DEVICE_VOLUME = 26;
/** Command to set and clear the surface on which to render the video. */
/**
* Command to set and clear the surface on which to render the video.
*
* <p>The following methods must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}:
*
* <ul>
* <li>{@link #setVideoSurface(Surface)}
* <li>{@link #clearVideoSurface()}
* <li>{@link #clearVideoSurface(Surface)}
* <li>{@link #setVideoSurfaceHolder(SurfaceHolder)}
* <li>{@link #clearVideoSurfaceHolder(SurfaceHolder)}
* <li>{@link #setVideoSurfaceView(SurfaceView)}
* <li>{@link #clearVideoSurfaceView(SurfaceView)}
* </ul>
*/
int COMMAND_SET_VIDEO_SURFACE = 27;
/** Command to get the text that should currently be displayed by the player. */
/**
* Command to get the text that should currently be displayed by the player.
*
* <p>The {@link #getCurrentCues()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_GET_TEXT = 28;
/** Command to set the player's track selection parameters. */
/**
* Command to set the player's track selection parameters.
*
* <p>The {@link #setTrackSelectionParameters(TrackSelectionParameters)} method must only be
* called if this command is {@linkplain #isCommandAvailable(int) available}.
*/
int COMMAND_SET_TRACK_SELECTION_PARAMETERS = 29;
/** Command to get details of the current track selection. */
/**
* Command to get details of the current track selection.
*
* <p>The {@link #getCurrentTracks()} method must only be called if this command is {@linkplain
* #isCommandAvailable(int) available}.
*/
int COMMAND_GET_TRACKS = 30;
/** Represents an invalid {@link Command}. */
......@@ -1601,6 +1855,9 @@ public interface Player {
* Clears the playlist, adds the specified {@linkplain MediaItem media items} and resets the
* position to the default position.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItems The new {@linkplain MediaItem media items}.
*/
void setMediaItems(List<MediaItem> mediaItems);
......@@ -1608,6 +1865,9 @@ public interface Player {
/**
* Clears the playlist and adds the specified {@linkplain MediaItem media items}.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItems The new {@linkplain MediaItem media items}.
* @param resetPosition Whether the playback position should be reset to the default position in
* the first {@link Timeline.Window}. If false, playback will start from the position defined
......@@ -1618,6 +1878,9 @@ public interface Player {
/**
* Clears the playlist and adds the specified {@linkplain MediaItem media items}.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItems The new {@linkplain MediaItem media items}.
* @param startIndex The {@link MediaItem} index to start playback from. If {@link C#INDEX_UNSET}
* is passed, the current position is not reset.
......@@ -1634,6 +1897,9 @@ public interface Player {
* Clears the playlist, adds the specified {@link MediaItem} and resets the position to the
* default position.
*
* <p>This method must only be called if {@link #COMMAND_SET_MEDIA_ITEM} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItem The new {@link MediaItem}.
*/
void setMediaItem(MediaItem mediaItem);
......@@ -1641,6 +1907,9 @@ public interface Player {
/**
* Clears the playlist and adds the specified {@link MediaItem}.
*
* <p>This method must only be called if {@link #COMMAND_SET_MEDIA_ITEM} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItem The new {@link MediaItem}.
* @param startPositionMs The position in milliseconds to start playback from.
*/
......@@ -1649,6 +1918,9 @@ public interface Player {
/**
* Clears the playlist and adds the specified {@link MediaItem}.
*
* <p>This method must only be called if {@link #COMMAND_SET_MEDIA_ITEM} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItem The new {@link MediaItem}.
* @param resetPosition Whether the playback position should be reset to the default position. If
* false, playback will start from the position defined by {@link #getCurrentMediaItemIndex()}
......@@ -1659,6 +1931,9 @@ public interface Player {
/**
* Adds a media item to the end of the playlist.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItem The {@link MediaItem} to add.
*/
void addMediaItem(MediaItem mediaItem);
......@@ -1666,6 +1941,9 @@ public interface Player {
/**
* Adds a media item at the given index of the playlist.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param index The index at which to add the media item. If the index is larger than the size of
* the playlist, the media item is added to the end of the playlist.
* @param mediaItem The {@link MediaItem} to add.
......@@ -1675,6 +1953,9 @@ public interface Player {
/**
* Adds a list of media items to the end of the playlist.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItems The {@linkplain MediaItem media items} to add.
*/
void addMediaItems(List<MediaItem> mediaItems);
......@@ -1682,6 +1963,9 @@ public interface Player {
/**
* Adds a list of media items at the given index of the playlist.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param index The index at which to add the media items. If the index is larger than the size of
* the playlist, the media items are added to the end of the playlist.
* @param mediaItems The {@linkplain MediaItem media items} to add.
......@@ -1691,6 +1975,9 @@ public interface Player {
/**
* Moves the media item at the current index to the new index.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param currentIndex The current index of the media item to move. If the index is larger than
* the size of the playlist, the request is ignored.
* @param newIndex The new index of the media item. If the new index is larger than the size of
......@@ -1701,6 +1988,9 @@ public interface Player {
/**
* Moves the media item range to the new index.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param fromIndex The start of the range to move. If the index is larger than the size of the
* playlist, the request is ignored.
* @param toIndex The first item not to be included in the range (exclusive). If the index is
......@@ -1714,6 +2004,9 @@ public interface Player {
/**
* Removes the media item at the given index of the playlist.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param index The index at which to remove the media item. If the index is larger than the size
* of the playlist, the request is ignored.
*/
......@@ -1722,6 +2015,9 @@ public interface Player {
/**
* Removes a range of media items from the playlist.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*
* @param fromIndex The index at which to start removing media items. If the index is larger than
* the size of the playlist, the request is ignored.
* @param toIndex The index of the first item to be kept (exclusive). If the index is larger than
......@@ -1729,7 +2025,12 @@ public interface Player {
*/
void removeMediaItems(int fromIndex, int toIndex);
/** Clears the playlist. */
/**
* Clears the playlist.
*
* <p>This method must only be called if {@link #COMMAND_CHANGE_MEDIA_ITEMS} is {@linkplain
* #getAvailableCommands() available}.
*/
void clearMediaItems();
/**
......@@ -1737,13 +2038,6 @@ public interface Player {
*
* <p>This method does not execute the command.
*
* <p>Executing a command that is not available (for example, calling {@link
* #seekToNextMediaItem()} if {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM} is unavailable) will
* neither throw an exception nor generate a {@link #getPlayerError()} player error}.
*
* <p>{@link #COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM} and {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM}
* are unavailable if there is no such {@link MediaItem}.
*
* @param command A {@link Command}.
* @return Whether the {@link Command} is available.
* @see Listener#onAvailableCommandsChanged(Commands)
......@@ -1760,13 +2054,6 @@ public interface Player {
* Listener#onAvailableCommandsChanged(Commands)} to get an update when the available commands
* change.
*
* <p>Executing a command that is not available (for example, calling {@link
* #seekToNextMediaItem()} if {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM} is unavailable) will
* neither throw an exception nor generate a {@link #getPlayerError()} player error}.
*
* <p>{@link #COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM} and {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM}
* are unavailable if there is no such {@link MediaItem}.
*
* @return The currently available {@link Commands}.
* @see Listener#onAvailableCommandsChanged
*/
......@@ -1775,6 +2062,9 @@ public interface Player {
/**
* Prepares the player.
*
* <p>This method must only be called if {@link #COMMAND_PREPARE} is {@linkplain
* #getAvailableCommands() available}.
*
* <p>This will move the player out of {@link #STATE_IDLE idle state} and the player will start
* loading media and acquire resources needed for playback.
*/
......@@ -1832,10 +2122,18 @@ public interface Player {
/**
* Resumes playback as soon as {@link #getPlaybackState()} == {@link #STATE_READY}. Equivalent to
* {@link #setPlayWhenReady(boolean) setPlayWhenReady(true)}.
*
* <p>This method must only be called if {@link #COMMAND_PLAY_PAUSE} is {@linkplain
* #getAvailableCommands() available}.
*/
void play();
/** Pauses playback. Equivalent to {@link #setPlayWhenReady(boolean) setPlayWhenReady(false)}. */
/**
* Pauses playback. Equivalent to {@link #setPlayWhenReady(boolean) setPlayWhenReady(false)}.
*
* <p>This method must only be called if {@link #COMMAND_PLAY_PAUSE} is {@linkplain
* #getAvailableCommands() available}.
*/
void pause();
/**
......@@ -1843,6 +2141,9 @@ public interface Player {
*
* <p>If the player is already in the ready state then this method pauses and resumes playback.
*
* <p>This method must only be called if {@link #COMMAND_PLAY_PAUSE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param playWhenReady Whether playback should proceed when ready.
*/
void setPlayWhenReady(boolean playWhenReady);
......@@ -1858,6 +2159,9 @@ public interface Player {
/**
* Sets the {@link RepeatMode} to be used for playback.
*
* <p>This method must only be called if {@link #COMMAND_SET_REPEAT_MODE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param repeatMode The repeat mode.
*/
void setRepeatMode(@RepeatMode int repeatMode);
......@@ -1874,6 +2178,9 @@ public interface Player {
/**
* Sets whether shuffling of media items is enabled.
*
* <p>This method must only be called if {@link #COMMAND_SET_SHUFFLE_MODE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param shuffleModeEnabled Whether shuffling is enabled.
*/
void setShuffleModeEnabled(boolean shuffleModeEnabled);
......@@ -1897,6 +2204,9 @@ public interface Player {
* Seeks to the default position associated with the current {@link MediaItem}. The position can
* depend on the type of media being played. For live streams it will typically be the live edge.
* For other streams it will typically be the start.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_DEFAULT_POSITION} is {@linkplain
* #getAvailableCommands() available}.
*/
void seekToDefaultPosition();
......@@ -1905,6 +2215,9 @@ public interface Player {
* depend on the type of media being played. For live streams it will typically be the live edge.
* For other streams it will typically be the start.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_MEDIA_ITEM} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItemIndex The index of the {@link MediaItem} whose associated default position
* should be seeked to. If the index is larger than the size of the playlist, the request is
* ignored.
......@@ -1914,6 +2227,9 @@ public interface Player {
/**
* Seeks to a position specified in milliseconds in the current {@link MediaItem}.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM} is
* {@linkplain #getAvailableCommands() available}.
*
* @param positionMs The seek position in the current {@link MediaItem}, or {@link C#TIME_UNSET}
* to seek to the media item's default position.
*/
......@@ -1922,6 +2238,9 @@ public interface Player {
/**
* Seeks to a position specified in milliseconds in the specified {@link MediaItem}.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_MEDIA_ITEM} is {@linkplain
* #getAvailableCommands() available}.
*
* @param mediaItemIndex The index of the {@link MediaItem}. If the index is larger than the size
* of the playlist, the request is ignored.
* @param positionMs The seek position in the specified {@link MediaItem}, or {@link C#TIME_UNSET}
......@@ -1939,6 +2258,9 @@ public interface Player {
/**
* Seeks back in the current {@link MediaItem} by {@link #getSeekBackIncrement()} milliseconds.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_BACK} is {@linkplain
* #getAvailableCommands() available}.
*/
void seekBack();
......@@ -1953,6 +2275,9 @@ public interface Player {
/**
* Seeks forward in the current {@link MediaItem} by {@link #getSeekForwardIncrement()}
* milliseconds.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_FORWARD} is {@linkplain
* #getAvailableCommands() available}.
*/
void seekForward();
......@@ -1998,6 +2323,9 @@ public interface Player {
* <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
* the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
* details.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM} is
* {@linkplain #getAvailableCommands() available}.
*/
void seekToPreviousMediaItem();
......@@ -2029,6 +2357,9 @@ public interface Player {
* MediaItem}.
* <li>Otherwise, seeks to 0 in the current {@link MediaItem}.
* </ul>
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_PREVIOUS} is {@linkplain
* #getAvailableCommands() available}.
*/
void seekToPrevious();
......@@ -2074,6 +2405,9 @@ public interface Player {
* <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
* the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
* details.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM} is {@linkplain
* #getAvailableCommands() available}.
*/
void seekToNextMediaItem();
......@@ -2089,6 +2423,9 @@ public interface Player {
* has not ended, seeks to the live edge of the current {@link MediaItem}.
* <li>Otherwise, does nothing.
* </ul>
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_NEXT} is {@linkplain
* #getAvailableCommands() available}.
*/
void seekToNext();
......@@ -2100,6 +2437,9 @@ public interface Player {
* Listener#onPlaybackParametersChanged(PlaybackParameters)} will be called whenever the currently
* active playback parameters change.
*
* <p>This method must only be called if {@link #COMMAND_SET_SPEED_AND_PITCH} is {@linkplain
* #getAvailableCommands() available}.
*
* @param playbackParameters The playback parameters.
*/
void setPlaybackParameters(PlaybackParameters playbackParameters);
......@@ -2110,6 +2450,9 @@ public interface Player {
* <p>This is equivalent to {@code
* setPlaybackParameters(getPlaybackParameters().withSpeed(speed))}.
*
* <p>This method must only be called if {@link #COMMAND_SET_SPEED_AND_PITCH} is {@linkplain
* #getAvailableCommands() available}.
*
* @param speed The linear factor by which playback will be sped up. Must be higher than 0. 1 is
* normal speed, 2 is twice as fast, 0.5 is half normal speed.
*/
......@@ -2133,6 +2476,9 @@ public interface Player {
*
* <p>Calling this method does not clear the playlist, reset the playback position or the playback
* error.
*
* <p>This method must only be called if {@link #COMMAND_STOP} is {@linkplain
* #getAvailableCommands() available}.
*/
void stop();
......@@ -2148,11 +2494,15 @@ public interface Player {
* Releases the player. This method must be called when the player is no longer required. The
* player must not be used after calling this method.
*/
// TODO(b/261158047): Document that COMMAND_RELEASE must be available once it exists.
void release();
/**
* Returns the current tracks.
*
* <p>This method must only be called if {@link #COMMAND_GET_TRACKS} is {@linkplain
* #getAvailableCommands() available}.
*
* @see Listener#onTracksChanged(Tracks)
*/
Tracks getCurrentTracks();
......@@ -2180,6 +2530,9 @@ public interface Player {
* .setMaxVideoSizeSd()
* .build())
* }</pre>
*
* <p>This method must only be called if {@link #COMMAND_SET_TRACK_SELECTION_PARAMETERS} is
* {@linkplain #getAvailableCommands() available}.
*/
void setTrackSelectionParameters(TrackSelectionParameters parameters);
......@@ -2192,16 +2545,27 @@ public interface Player {
* metadata that has been parsed from the media and output via {@link
* Listener#onMetadata(Metadata)}. If a field is populated in the {@link MediaItem#mediaMetadata},
* it will be prioritised above the same field coming from static or timed metadata.
*
* <p>This method must only be called if {@link #COMMAND_GET_MEDIA_ITEMS_METADATA} is {@linkplain
* #getAvailableCommands() available}.
*/
MediaMetadata getMediaMetadata();
/**
* Returns the playlist {@link MediaMetadata}, as set by {@link
* #setPlaylistMetadata(MediaMetadata)}, or {@link MediaMetadata#EMPTY} if not supported.
*
* <p>This method must only be called if {@link #COMMAND_GET_MEDIA_ITEMS_METADATA} is {@linkplain
* #getAvailableCommands() available}.
*/
MediaMetadata getPlaylistMetadata();
/** Sets the playlist {@link MediaMetadata}. */
/**
* Sets the playlist {@link MediaMetadata}.
*
* <p>This method must only be called if {@link #COMMAND_SET_MEDIA_ITEMS_METADATA} is {@linkplain
* #getAvailableCommands() available}.
*/
void setPlaylistMetadata(MediaMetadata mediaMetadata);
/**
......@@ -2213,11 +2577,19 @@ public interface Player {
/**
* Returns the current {@link Timeline}. Never null, but may be empty.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*
* @see Listener#onTimelineChanged(Timeline, int)
*/
Timeline getCurrentTimeline();
/** Returns the index of the period currently being played. */
/**
* Returns the index of the period currently being played.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/
int getCurrentPeriodIndex();
/**
......@@ -2230,6 +2602,9 @@ public interface Player {
* Returns the index of the current {@link MediaItem} in the {@link #getCurrentTimeline()
* timeline}, or the prospective index if the {@link #getCurrentTimeline() current timeline} is
* empty.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/
int getCurrentMediaItemIndex();
......@@ -2248,6 +2623,9 @@ public interface Player {
* <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
* the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
* details.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/
int getNextMediaItemIndex();
......@@ -2266,21 +2644,37 @@ public interface Player {
* <p>Note: When the repeat mode is {@link #REPEAT_MODE_ONE}, this method behaves the same as when
* the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
* details.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/
int getPreviousMediaItemIndex();
/**
* Returns the currently playing {@link MediaItem}. May be null if the timeline is empty.
*
* <p>This method must only be called if {@link #COMMAND_GET_CURRENT_MEDIA_ITEM} is {@linkplain
* #getAvailableCommands() available}.
*
* @see Listener#onMediaItemTransition(MediaItem, int)
*/
@Nullable
MediaItem getCurrentMediaItem();
/** Returns the number of {@linkplain MediaItem media items} in the playlist. */
/**
* Returns the number of {@linkplain MediaItem media items} in the playlist.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/
int getMediaItemCount();
/** Returns the {@link MediaItem} at the given index. */
/**
* Returns the {@link MediaItem} at the given index.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/
MediaItem getMediaItemAt(int index);
/**
......@@ -2375,12 +2769,18 @@ public interface Player {
/**
* If {@link #isPlayingAd()} returns true, returns the index of the ad group in the period
* currently being played. Returns {@link C#INDEX_UNSET} otherwise.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/
int getCurrentAdGroupIndex();
/**
* If {@link #isPlayingAd()} returns true, returns the index of the ad in its ad group. Returns
* {@link C#INDEX_UNSET} otherwise.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/
int getCurrentAdIndexInAdGroup();
......@@ -2405,13 +2805,21 @@ public interface Player {
*/
long getContentBufferedPosition();
/** Returns the attributes for audio playback. */
/**
* Returns the attributes for audio playback.
*
* <p>This method must only be called if {@link #COMMAND_GET_AUDIO_ATTRIBUTES} is {@linkplain
* #getAvailableCommands() available}.
*/
AudioAttributes getAudioAttributes();
/**
* Sets the audio volume, valid values are between 0 (silence) and 1 (unity gain, signal
* unchanged), inclusive.
*
* <p>This method must only be called if {@link #COMMAND_SET_VOLUME} is {@linkplain
* #getAvailableCommands() available}.
*
* @param volume Linear output gain to apply to all audio channels.
*/
void setVolume(@FloatRange(from = 0, to = 1.0) float volume);
......@@ -2419,6 +2827,9 @@ public interface Player {
/**
* Returns the audio volume, with 0 being silence and 1 being unity gain (signal unchanged).
*
* <p>This method must only be called if {@link #COMMAND_GET_VOLUME} is {@linkplain
* #getAvailableCommands() available}.
*
* @return The linear gain applied to all audio channels.
*/
@FloatRange(from = 0, to = 1.0)
......@@ -2427,6 +2838,9 @@ public interface Player {
/**
* Clears any {@link Surface}, {@link SurfaceHolder}, {@link SurfaceView} or {@link TextureView}
* currently set on the player.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*/
void clearVideoSurface();
......@@ -2434,6 +2848,9 @@ public interface Player {
* Clears the {@link Surface} onto which video is being rendered if it matches the one passed.
* Else does nothing.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param surface The surface to clear.
*/
void clearVideoSurface(@Nullable Surface surface);
......@@ -2449,6 +2866,9 @@ public interface Player {
* this method, since passing the holder allows the player to track the lifecycle of the surface
* automatically.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param surface The {@link Surface}.
*/
void setVideoSurface(@Nullable Surface surface);
......@@ -2460,6 +2880,9 @@ public interface Player {
* <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread
* associated with {@link #getApplicationLooper()}.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param surfaceHolder The surface holder.
*/
void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder);
......@@ -2468,6 +2891,9 @@ public interface Player {
* Clears the {@link SurfaceHolder} that holds the {@link Surface} onto which video is being
* rendered if it matches the one passed. Else does nothing.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param surfaceHolder The surface holder to clear.
*/
void clearVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder);
......@@ -2479,6 +2905,9 @@ public interface Player {
* <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread
* associated with {@link #getApplicationLooper()}.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param surfaceView The surface view.
*/
void setVideoSurfaceView(@Nullable SurfaceView surfaceView);
......@@ -2487,6 +2916,9 @@ public interface Player {
* Clears the {@link SurfaceView} onto which video is being rendered if it matches the one passed.
* Else does nothing.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param surfaceView The texture view to clear.
*/
void clearVideoSurfaceView(@Nullable SurfaceView surfaceView);
......@@ -2498,6 +2930,9 @@ public interface Player {
* <p>The thread that calls the {@link TextureView.SurfaceTextureListener} methods must be the
* thread associated with {@link #getApplicationLooper()}.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param textureView The texture view.
*/
void setVideoTextureView(@Nullable TextureView textureView);
......@@ -2506,6 +2941,9 @@ public interface Player {
* Clears the {@link TextureView} onto which video is being rendered if it matches the one passed.
* Else does nothing.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param textureView The texture view to clear.
*/
void clearVideoTextureView(@Nullable TextureView textureView);
......@@ -2527,7 +2965,12 @@ public interface Player {
*/
Size getSurfaceSize();
/** Returns the current {@link CueGroup}. */
/**
* Returns the current {@link CueGroup}.
*
* <p>This method must only be called if {@link #COMMAND_GET_TEXT} is {@linkplain
* #getAvailableCommands() available}.
*/
CueGroup getCurrentCues();
/** Gets the device information. */
......@@ -2543,26 +2986,52 @@ public interface Player {
*
* <p>For devices with {@link DeviceInfo#PLAYBACK_TYPE_REMOTE remote playback}, the volume of the
* remote device is returned.
*
* <p>This method must only be called if {@link #COMMAND_GET_DEVICE_VOLUME} is {@linkplain
* #getAvailableCommands() available}.
*/
@IntRange(from = 0)
int getDeviceVolume();
/** Gets whether the device is muted or not. */
/**
* Gets whether the device is muted or not.
*
* <p>This method must only be called if {@link #COMMAND_GET_DEVICE_VOLUME} is {@linkplain
* #getAvailableCommands() available}.
*/
boolean isDeviceMuted();
/**
* Sets the volume of the device.
*
* <p>This method must only be called if {@link #COMMAND_SET_DEVICE_VOLUME} is {@linkplain
* #getAvailableCommands() available}.
*
* @param volume The volume to set.
*/
void setDeviceVolume(@IntRange(from = 0) int volume);
/** Increases the volume of the device. */
/**
* Increases the volume of the device.
*
* <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME} is {@linkplain
* #getAvailableCommands() available}.
*/
void increaseDeviceVolume();
/** Decreases the volume of the device. */
/**
* Decreases the volume of the device.
*
* <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME} is {@linkplain
* #getAvailableCommands() available}.
*/
void decreaseDeviceVolume();
/** Sets the mute state of the device. */
/**
* Sets the mute state of the device.
*
* <p>This method must only be called if {@link #COMMAND_ADJUST_DEVICE_VOLUME} is {@linkplain
* #getAvailableCommands() available}.
*/
void setDeviceMuted(boolean muted);
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment