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 { ...@@ -1403,6 +1403,9 @@ public interface Player {
* <p>The currently available commands can be inspected with {@link #getAvailableCommands()} and * <p>The currently available commands can be inspected with {@link #getAvailableCommands()} and
* {@link #isCommandAvailable(int)}. * {@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: * <p>One of the following values:
* *
* <ul> * <ul>
...@@ -1479,21 +1482,62 @@ public interface Player { ...@@ -1479,21 +1482,62 @@ public interface Player {
COMMAND_GET_TRACKS, COMMAND_GET_TRACKS,
}) })
@interface Command {} @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; 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; 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; 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; 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; int COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM = 5;
/** /**
* @deprecated Use {@link #COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM} instead. * @deprecated Use {@link #COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM} instead.
*/ */
@Deprecated int COMMAND_SEEK_IN_CURRENT_WINDOW = COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM; @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; int COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM = 6;
/** /**
* @deprecated Use {@link #COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM} instead. * @deprecated Use {@link #COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM} instead.
...@@ -1502,9 +1546,17 @@ public interface Player { ...@@ -1502,9 +1546,17 @@ public interface Player {
/** /**
* Command to seek to an earlier position in the current {@link MediaItem} or the default position * Command to seek to an earlier position in the current {@link MediaItem} or the default position
* of the previous {@link MediaItem}. * 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; 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; int COMMAND_SEEK_TO_NEXT_MEDIA_ITEM = 8;
/** /**
* @deprecated Use {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM} instead. * @deprecated Use {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM} instead.
...@@ -1513,57 +1565,259 @@ public interface Player { ...@@ -1513,57 +1565,259 @@ public interface Player {
/** /**
* Command to seek to a later position in the current {@link MediaItem} or the default position of * Command to seek to a later position in the current {@link MediaItem} or the default position of
* the next {@link MediaItem}. * 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; 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; int COMMAND_SEEK_TO_MEDIA_ITEM = 10;
/** /**
* @deprecated Use {@link #COMMAND_SEEK_TO_MEDIA_ITEM} instead. * @deprecated Use {@link #COMMAND_SEEK_TO_MEDIA_ITEM} instead.
*/ */
@Deprecated int COMMAND_SEEK_TO_WINDOW = COMMAND_SEEK_TO_MEDIA_ITEM; @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; 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; 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; 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; 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; 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; 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; 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 // TODO(b/263132691): Rename this to COMMAND_GET_METADATA
int COMMAND_GET_MEDIA_ITEMS_METADATA = 18; 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 // TODO(b/263132691): Rename this to COMMAND_SET_PLAYLIST_METADATA
int COMMAND_SET_MEDIA_ITEMS_METADATA = 19; 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; 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; 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; 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; 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; 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; 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; 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; 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; 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; 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; 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; int COMMAND_GET_TRACKS = 30;
/** Represents an invalid {@link Command}. */ /** Represents an invalid {@link Command}. */
...@@ -1601,6 +1855,9 @@ public interface Player { ...@@ -1601,6 +1855,9 @@ public interface Player {
* Clears the playlist, adds the specified {@linkplain MediaItem media items} and resets the * Clears the playlist, adds the specified {@linkplain MediaItem media items} and resets the
* position to the default position. * 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}. * @param mediaItems The new {@linkplain MediaItem media items}.
*/ */
void setMediaItems(List<MediaItem> mediaItems); void setMediaItems(List<MediaItem> mediaItems);
...@@ -1608,6 +1865,9 @@ public interface Player { ...@@ -1608,6 +1865,9 @@ public interface Player {
/** /**
* Clears the playlist and adds the specified {@linkplain MediaItem media items}. * 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 mediaItems The new {@linkplain MediaItem media items}.
* @param resetPosition Whether the playback position should be reset to the default position in * @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 * the first {@link Timeline.Window}. If false, playback will start from the position defined
...@@ -1618,6 +1878,9 @@ public interface Player { ...@@ -1618,6 +1878,9 @@ public interface Player {
/** /**
* Clears the playlist and adds the specified {@linkplain MediaItem media items}. * 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 mediaItems The new {@linkplain MediaItem media items}.
* @param startIndex The {@link MediaItem} index to start playback from. If {@link C#INDEX_UNSET} * @param startIndex The {@link MediaItem} index to start playback from. If {@link C#INDEX_UNSET}
* is passed, the current position is not reset. * is passed, the current position is not reset.
...@@ -1634,6 +1897,9 @@ public interface Player { ...@@ -1634,6 +1897,9 @@ public interface Player {
* Clears the playlist, adds the specified {@link MediaItem} and resets the position to the * Clears the playlist, adds the specified {@link MediaItem} and resets the position to the
* default position. * 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}. * @param mediaItem The new {@link MediaItem}.
*/ */
void setMediaItem(MediaItem mediaItem); void setMediaItem(MediaItem mediaItem);
...@@ -1641,6 +1907,9 @@ public interface Player { ...@@ -1641,6 +1907,9 @@ public interface Player {
/** /**
* Clears the playlist and adds the specified {@link MediaItem}. * 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 mediaItem The new {@link MediaItem}.
* @param startPositionMs The position in milliseconds to start playback from. * @param startPositionMs The position in milliseconds to start playback from.
*/ */
...@@ -1649,6 +1918,9 @@ public interface Player { ...@@ -1649,6 +1918,9 @@ public interface Player {
/** /**
* Clears the playlist and adds the specified {@link MediaItem}. * 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 mediaItem The new {@link MediaItem}.
* @param resetPosition Whether the playback position should be reset to the default position. If * @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()} * false, playback will start from the position defined by {@link #getCurrentMediaItemIndex()}
...@@ -1659,6 +1931,9 @@ public interface Player { ...@@ -1659,6 +1931,9 @@ public interface Player {
/** /**
* Adds a media item to the end of the playlist. * 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. * @param mediaItem The {@link MediaItem} to add.
*/ */
void addMediaItem(MediaItem mediaItem); void addMediaItem(MediaItem mediaItem);
...@@ -1666,6 +1941,9 @@ public interface Player { ...@@ -1666,6 +1941,9 @@ public interface Player {
/** /**
* Adds a media item at the given index of the playlist. * 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 * @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. * the playlist, the media item is added to the end of the playlist.
* @param mediaItem The {@link MediaItem} to add. * @param mediaItem The {@link MediaItem} to add.
...@@ -1675,6 +1953,9 @@ public interface Player { ...@@ -1675,6 +1953,9 @@ public interface Player {
/** /**
* Adds a list of media items to the end of the playlist. * 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. * @param mediaItems The {@linkplain MediaItem media items} to add.
*/ */
void addMediaItems(List<MediaItem> mediaItems); void addMediaItems(List<MediaItem> mediaItems);
...@@ -1682,6 +1963,9 @@ public interface Player { ...@@ -1682,6 +1963,9 @@ public interface Player {
/** /**
* Adds a list of media items at the given index of the playlist. * 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 * @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. * the playlist, the media items are added to the end of the playlist.
* @param mediaItems The {@linkplain MediaItem media items} to add. * @param mediaItems The {@linkplain MediaItem media items} to add.
...@@ -1691,6 +1975,9 @@ public interface Player { ...@@ -1691,6 +1975,9 @@ public interface Player {
/** /**
* Moves the media item at the current index to the new index. * 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 * @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. * 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 * @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 { ...@@ -1701,6 +1988,9 @@ public interface Player {
/** /**
* Moves the media item range to the new index. * 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 * @param fromIndex The start of the range to move. If the index is larger than the size of the
* playlist, the request is ignored. * playlist, the request is ignored.
* @param toIndex The first item not to be included in the range (exclusive). If the index is * @param toIndex The first item not to be included in the range (exclusive). If the index is
...@@ -1714,6 +2004,9 @@ public interface Player { ...@@ -1714,6 +2004,9 @@ public interface Player {
/** /**
* Removes the media item at the given index of the playlist. * 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 * @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. * of the playlist, the request is ignored.
*/ */
...@@ -1722,6 +2015,9 @@ public interface Player { ...@@ -1722,6 +2015,9 @@ public interface Player {
/** /**
* Removes a range of media items from the playlist. * 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 * @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. * 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 * @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 { ...@@ -1729,7 +2025,12 @@ public interface Player {
*/ */
void removeMediaItems(int fromIndex, int toIndex); 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(); void clearMediaItems();
/** /**
...@@ -1737,13 +2038,6 @@ public interface Player { ...@@ -1737,13 +2038,6 @@ public interface Player {
* *
* <p>This method does not execute the command. * <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}. * @param command A {@link Command}.
* @return Whether the {@link Command} is available. * @return Whether the {@link Command} is available.
* @see Listener#onAvailableCommandsChanged(Commands) * @see Listener#onAvailableCommandsChanged(Commands)
...@@ -1760,13 +2054,6 @@ public interface Player { ...@@ -1760,13 +2054,6 @@ public interface Player {
* Listener#onAvailableCommandsChanged(Commands)} to get an update when the available commands * Listener#onAvailableCommandsChanged(Commands)} to get an update when the available commands
* change. * 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}. * @return The currently available {@link Commands}.
* @see Listener#onAvailableCommandsChanged * @see Listener#onAvailableCommandsChanged
*/ */
...@@ -1775,6 +2062,9 @@ public interface Player { ...@@ -1775,6 +2062,9 @@ public interface Player {
/** /**
* Prepares the 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 * <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. * loading media and acquire resources needed for playback.
*/ */
...@@ -1832,10 +2122,18 @@ public interface Player { ...@@ -1832,10 +2122,18 @@ public interface Player {
/** /**
* Resumes playback as soon as {@link #getPlaybackState()} == {@link #STATE_READY}. Equivalent to * Resumes playback as soon as {@link #getPlaybackState()} == {@link #STATE_READY}. Equivalent to
* {@link #setPlayWhenReady(boolean) setPlayWhenReady(true)}. * {@link #setPlayWhenReady(boolean) setPlayWhenReady(true)}.
*
* <p>This method must only be called if {@link #COMMAND_PLAY_PAUSE} is {@linkplain
* #getAvailableCommands() available}.
*/ */
void play(); 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(); void pause();
/** /**
...@@ -1843,6 +2141,9 @@ public interface Player { ...@@ -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>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. * @param playWhenReady Whether playback should proceed when ready.
*/ */
void setPlayWhenReady(boolean playWhenReady); void setPlayWhenReady(boolean playWhenReady);
...@@ -1858,6 +2159,9 @@ public interface Player { ...@@ -1858,6 +2159,9 @@ public interface Player {
/** /**
* Sets the {@link RepeatMode} to be used for playback. * 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. * @param repeatMode The repeat mode.
*/ */
void setRepeatMode(@RepeatMode int repeatMode); void setRepeatMode(@RepeatMode int repeatMode);
...@@ -1874,6 +2178,9 @@ public interface Player { ...@@ -1874,6 +2178,9 @@ public interface Player {
/** /**
* Sets whether shuffling of media items is enabled. * 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. * @param shuffleModeEnabled Whether shuffling is enabled.
*/ */
void setShuffleModeEnabled(boolean shuffleModeEnabled); void setShuffleModeEnabled(boolean shuffleModeEnabled);
...@@ -1897,6 +2204,9 @@ public interface Player { ...@@ -1897,6 +2204,9 @@ public interface Player {
* Seeks to the default position associated with the current {@link MediaItem}. The position can * 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. * 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. * 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(); void seekToDefaultPosition();
...@@ -1905,6 +2215,9 @@ public interface Player { ...@@ -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. * 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. * 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 * @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 * should be seeked to. If the index is larger than the size of the playlist, the request is
* ignored. * ignored.
...@@ -1914,6 +2227,9 @@ public interface Player { ...@@ -1914,6 +2227,9 @@ public interface Player {
/** /**
* Seeks to a position specified in milliseconds in the current {@link MediaItem}. * 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} * @param positionMs The seek position in the current {@link MediaItem}, or {@link C#TIME_UNSET}
* to seek to the media item's default position. * to seek to the media item's default position.
*/ */
...@@ -1922,6 +2238,9 @@ public interface Player { ...@@ -1922,6 +2238,9 @@ public interface Player {
/** /**
* Seeks to a position specified in milliseconds in the specified {@link MediaItem}. * 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 * @param mediaItemIndex The index of the {@link MediaItem}. If the index is larger than the size
* of the playlist, the request is ignored. * of the playlist, the request is ignored.
* @param positionMs The seek position in the specified {@link MediaItem}, or {@link C#TIME_UNSET} * @param positionMs The seek position in the specified {@link MediaItem}, or {@link C#TIME_UNSET}
...@@ -1939,6 +2258,9 @@ public interface Player { ...@@ -1939,6 +2258,9 @@ public interface Player {
/** /**
* Seeks back in the current {@link MediaItem} by {@link #getSeekBackIncrement()} milliseconds. * 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(); void seekBack();
...@@ -1953,6 +2275,9 @@ public interface Player { ...@@ -1953,6 +2275,9 @@ public interface Player {
/** /**
* Seeks forward in the current {@link MediaItem} by {@link #getSeekForwardIncrement()} * Seeks forward in the current {@link MediaItem} by {@link #getSeekForwardIncrement()}
* milliseconds. * milliseconds.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_FORWARD} is {@linkplain
* #getAvailableCommands() available}.
*/ */
void seekForward(); void seekForward();
...@@ -1998,6 +2323,9 @@ public interface Player { ...@@ -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 * <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 * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
* details. * details.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM} is
* {@linkplain #getAvailableCommands() available}.
*/ */
void seekToPreviousMediaItem(); void seekToPreviousMediaItem();
...@@ -2029,6 +2357,9 @@ public interface Player { ...@@ -2029,6 +2357,9 @@ public interface Player {
* MediaItem}. * MediaItem}.
* <li>Otherwise, seeks to 0 in the current {@link MediaItem}. * <li>Otherwise, seeks to 0 in the current {@link MediaItem}.
* </ul> * </ul>
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_PREVIOUS} is {@linkplain
* #getAvailableCommands() available}.
*/ */
void seekToPrevious(); void seekToPrevious();
...@@ -2074,6 +2405,9 @@ public interface Player { ...@@ -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 * <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 * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
* details. * details.
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM} is {@linkplain
* #getAvailableCommands() available}.
*/ */
void seekToNextMediaItem(); void seekToNextMediaItem();
...@@ -2089,6 +2423,9 @@ public interface Player { ...@@ -2089,6 +2423,9 @@ public interface Player {
* has not ended, seeks to the live edge of the current {@link MediaItem}. * has not ended, seeks to the live edge of the current {@link MediaItem}.
* <li>Otherwise, does nothing. * <li>Otherwise, does nothing.
* </ul> * </ul>
*
* <p>This method must only be called if {@link #COMMAND_SEEK_TO_NEXT} is {@linkplain
* #getAvailableCommands() available}.
*/ */
void seekToNext(); void seekToNext();
...@@ -2100,6 +2437,9 @@ public interface Player { ...@@ -2100,6 +2437,9 @@ public interface Player {
* Listener#onPlaybackParametersChanged(PlaybackParameters)} will be called whenever the currently * Listener#onPlaybackParametersChanged(PlaybackParameters)} will be called whenever the currently
* active playback parameters change. * 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. * @param playbackParameters The playback parameters.
*/ */
void setPlaybackParameters(PlaybackParameters playbackParameters); void setPlaybackParameters(PlaybackParameters playbackParameters);
...@@ -2110,6 +2450,9 @@ public interface Player { ...@@ -2110,6 +2450,9 @@ public interface Player {
* <p>This is equivalent to {@code * <p>This is equivalent to {@code
* setPlaybackParameters(getPlaybackParameters().withSpeed(speed))}. * 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 * @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. * normal speed, 2 is twice as fast, 0.5 is half normal speed.
*/ */
...@@ -2133,6 +2476,9 @@ public interface Player { ...@@ -2133,6 +2476,9 @@ public interface Player {
* *
* <p>Calling this method does not clear the playlist, reset the playback position or the playback * <p>Calling this method does not clear the playlist, reset the playback position or the playback
* error. * error.
*
* <p>This method must only be called if {@link #COMMAND_STOP} is {@linkplain
* #getAvailableCommands() available}.
*/ */
void stop(); void stop();
...@@ -2148,11 +2494,15 @@ public interface Player { ...@@ -2148,11 +2494,15 @@ public interface Player {
* Releases the player. This method must be called when the player is no longer required. The * 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. * player must not be used after calling this method.
*/ */
// TODO(b/261158047): Document that COMMAND_RELEASE must be available once it exists.
void release(); void release();
/** /**
* Returns the current tracks. * Returns the current tracks.
* *
* <p>This method must only be called if {@link #COMMAND_GET_TRACKS} is {@linkplain
* #getAvailableCommands() available}.
*
* @see Listener#onTracksChanged(Tracks) * @see Listener#onTracksChanged(Tracks)
*/ */
Tracks getCurrentTracks(); Tracks getCurrentTracks();
...@@ -2180,6 +2530,9 @@ public interface Player { ...@@ -2180,6 +2530,9 @@ public interface Player {
* .setMaxVideoSizeSd() * .setMaxVideoSizeSd()
* .build()) * .build())
* }</pre> * }</pre>
*
* <p>This method must only be called if {@link #COMMAND_SET_TRACK_SELECTION_PARAMETERS} is
* {@linkplain #getAvailableCommands() available}.
*/ */
void setTrackSelectionParameters(TrackSelectionParameters parameters); void setTrackSelectionParameters(TrackSelectionParameters parameters);
...@@ -2192,16 +2545,27 @@ public interface Player { ...@@ -2192,16 +2545,27 @@ public interface Player {
* metadata that has been parsed from the media and output via {@link * 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}, * 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. * 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(); MediaMetadata getMediaMetadata();
/** /**
* Returns the playlist {@link MediaMetadata}, as set by {@link * Returns the playlist {@link MediaMetadata}, as set by {@link
* #setPlaylistMetadata(MediaMetadata)}, or {@link MediaMetadata#EMPTY} if not supported. * #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(); 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); void setPlaylistMetadata(MediaMetadata mediaMetadata);
/** /**
...@@ -2213,11 +2577,19 @@ public interface Player { ...@@ -2213,11 +2577,19 @@ public interface Player {
/** /**
* Returns the current {@link Timeline}. Never null, but may be empty. * 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) * @see Listener#onTimelineChanged(Timeline, int)
*/ */
Timeline getCurrentTimeline(); 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(); int getCurrentPeriodIndex();
/** /**
...@@ -2230,6 +2602,9 @@ public interface Player { ...@@ -2230,6 +2602,9 @@ public interface Player {
* Returns the index of the current {@link MediaItem} in the {@link #getCurrentTimeline() * Returns the index of the current {@link MediaItem} in the {@link #getCurrentTimeline()
* timeline}, or the prospective index if the {@link #getCurrentTimeline() current timeline} is * timeline}, or the prospective index if the {@link #getCurrentTimeline() current timeline} is
* empty. * empty.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/ */
int getCurrentMediaItemIndex(); int getCurrentMediaItemIndex();
...@@ -2248,6 +2623,9 @@ public interface Player { ...@@ -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 * <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 * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
* details. * details.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/ */
int getNextMediaItemIndex(); int getNextMediaItemIndex();
...@@ -2266,21 +2644,37 @@ public interface Player { ...@@ -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 * <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 * the current repeat mode is {@link #REPEAT_MODE_OFF}. See {@link #REPEAT_MODE_ONE} for more
* details. * details.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/ */
int getPreviousMediaItemIndex(); int getPreviousMediaItemIndex();
/** /**
* Returns the currently playing {@link MediaItem}. May be null if the timeline is empty. * 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) * @see Listener#onMediaItemTransition(MediaItem, int)
*/ */
@Nullable @Nullable
MediaItem getCurrentMediaItem(); 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(); 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); MediaItem getMediaItemAt(int index);
/** /**
...@@ -2375,12 +2769,18 @@ public interface Player { ...@@ -2375,12 +2769,18 @@ public interface Player {
/** /**
* If {@link #isPlayingAd()} returns true, returns the index of the ad group in the period * If {@link #isPlayingAd()} returns true, returns the index of the ad group in the period
* currently being played. Returns {@link C#INDEX_UNSET} otherwise. * 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(); int getCurrentAdGroupIndex();
/** /**
* If {@link #isPlayingAd()} returns true, returns the index of the ad in its ad group. Returns * If {@link #isPlayingAd()} returns true, returns the index of the ad in its ad group. Returns
* {@link C#INDEX_UNSET} otherwise. * {@link C#INDEX_UNSET} otherwise.
*
* <p>This method must only be called if {@link #COMMAND_GET_TIMELINE} is {@linkplain
* #getAvailableCommands() available}.
*/ */
int getCurrentAdIndexInAdGroup(); int getCurrentAdIndexInAdGroup();
...@@ -2405,13 +2805,21 @@ public interface Player { ...@@ -2405,13 +2805,21 @@ public interface Player {
*/ */
long getContentBufferedPosition(); 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(); AudioAttributes getAudioAttributes();
/** /**
* Sets the audio volume, valid values are between 0 (silence) and 1 (unity gain, signal * Sets the audio volume, valid values are between 0 (silence) and 1 (unity gain, signal
* unchanged), inclusive. * 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. * @param volume Linear output gain to apply to all audio channels.
*/ */
void setVolume(@FloatRange(from = 0, to = 1.0) float volume); void setVolume(@FloatRange(from = 0, to = 1.0) float volume);
...@@ -2419,6 +2827,9 @@ public interface Player { ...@@ -2419,6 +2827,9 @@ public interface Player {
/** /**
* Returns the audio volume, with 0 being silence and 1 being unity gain (signal unchanged). * 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. * @return The linear gain applied to all audio channels.
*/ */
@FloatRange(from = 0, to = 1.0) @FloatRange(from = 0, to = 1.0)
...@@ -2427,6 +2838,9 @@ public interface Player { ...@@ -2427,6 +2838,9 @@ public interface Player {
/** /**
* Clears any {@link Surface}, {@link SurfaceHolder}, {@link SurfaceView} or {@link TextureView} * Clears any {@link Surface}, {@link SurfaceHolder}, {@link SurfaceView} or {@link TextureView}
* currently set on the player. * currently set on the player.
*
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*/ */
void clearVideoSurface(); void clearVideoSurface();
...@@ -2434,6 +2848,9 @@ public interface Player { ...@@ -2434,6 +2848,9 @@ public interface Player {
* Clears the {@link Surface} onto which video is being rendered if it matches the one passed. * Clears the {@link Surface} onto which video is being rendered if it matches the one passed.
* Else does nothing. * 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. * @param surface The surface to clear.
*/ */
void clearVideoSurface(@Nullable Surface surface); void clearVideoSurface(@Nullable Surface surface);
...@@ -2449,6 +2866,9 @@ public interface Player { ...@@ -2449,6 +2866,9 @@ public interface Player {
* this method, since passing the holder allows the player to track the lifecycle of the surface * this method, since passing the holder allows the player to track the lifecycle of the surface
* automatically. * automatically.
* *
* <p>This method must only be called if {@link #COMMAND_SET_VIDEO_SURFACE} is {@linkplain
* #getAvailableCommands() available}.
*
* @param surface The {@link Surface}. * @param surface The {@link Surface}.
*/ */
void setVideoSurface(@Nullable Surface surface); void setVideoSurface(@Nullable Surface surface);
...@@ -2460,6 +2880,9 @@ public interface Player { ...@@ -2460,6 +2880,9 @@ public interface Player {
* <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread * <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread
* associated with {@link #getApplicationLooper()}. * 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. * @param surfaceHolder The surface holder.
*/ */
void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder); void setVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder);
...@@ -2468,6 +2891,9 @@ public interface Player { ...@@ -2468,6 +2891,9 @@ public interface Player {
* Clears the {@link SurfaceHolder} that holds the {@link Surface} onto which video is being * Clears the {@link SurfaceHolder} that holds the {@link Surface} onto which video is being
* rendered if it matches the one passed. Else does nothing. * 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. * @param surfaceHolder The surface holder to clear.
*/ */
void clearVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder); void clearVideoSurfaceHolder(@Nullable SurfaceHolder surfaceHolder);
...@@ -2479,6 +2905,9 @@ public interface Player { ...@@ -2479,6 +2905,9 @@ public interface Player {
* <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread * <p>The thread that calls the {@link SurfaceHolder.Callback} methods must be the thread
* associated with {@link #getApplicationLooper()}. * 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. * @param surfaceView The surface view.
*/ */
void setVideoSurfaceView(@Nullable SurfaceView surfaceView); void setVideoSurfaceView(@Nullable SurfaceView surfaceView);
...@@ -2487,6 +2916,9 @@ public interface Player { ...@@ -2487,6 +2916,9 @@ public interface Player {
* Clears the {@link SurfaceView} onto which video is being rendered if it matches the one passed. * Clears the {@link SurfaceView} onto which video is being rendered if it matches the one passed.
* Else does nothing. * 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. * @param surfaceView The texture view to clear.
*/ */
void clearVideoSurfaceView(@Nullable SurfaceView surfaceView); void clearVideoSurfaceView(@Nullable SurfaceView surfaceView);
...@@ -2498,6 +2930,9 @@ public interface Player { ...@@ -2498,6 +2930,9 @@ public interface Player {
* <p>The thread that calls the {@link TextureView.SurfaceTextureListener} methods must be the * <p>The thread that calls the {@link TextureView.SurfaceTextureListener} methods must be the
* thread associated with {@link #getApplicationLooper()}. * 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. * @param textureView The texture view.
*/ */
void setVideoTextureView(@Nullable TextureView textureView); void setVideoTextureView(@Nullable TextureView textureView);
...@@ -2506,6 +2941,9 @@ public interface Player { ...@@ -2506,6 +2941,9 @@ public interface Player {
* Clears the {@link TextureView} onto which video is being rendered if it matches the one passed. * Clears the {@link TextureView} onto which video is being rendered if it matches the one passed.
* Else does nothing. * 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. * @param textureView The texture view to clear.
*/ */
void clearVideoTextureView(@Nullable TextureView textureView); void clearVideoTextureView(@Nullable TextureView textureView);
...@@ -2527,7 +2965,12 @@ public interface Player { ...@@ -2527,7 +2965,12 @@ public interface Player {
*/ */
Size getSurfaceSize(); 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(); CueGroup getCurrentCues();
/** Gets the device information. */ /** Gets the device information. */
...@@ -2543,26 +2986,52 @@ public interface Player { ...@@ -2543,26 +2986,52 @@ public interface Player {
* *
* <p>For devices with {@link DeviceInfo#PLAYBACK_TYPE_REMOTE remote playback}, the volume of the * <p>For devices with {@link DeviceInfo#PLAYBACK_TYPE_REMOTE remote playback}, the volume of the
* remote device is returned. * remote device is returned.
*
* <p>This method must only be called if {@link #COMMAND_GET_DEVICE_VOLUME} is {@linkplain
* #getAvailableCommands() available}.
*/ */
@IntRange(from = 0) @IntRange(from = 0)
int getDeviceVolume(); 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(); boolean isDeviceMuted();
/** /**
* Sets the volume of the device. * 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. * @param volume The volume to set.
*/ */
void setDeviceVolume(@IntRange(from = 0) int volume); 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(); 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(); 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); 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