diff --git a/library/common/src/main/java/com/google/android/exoplayer2/Player.java b/library/common/src/main/java/com/google/android/exoplayer2/Player.java index a256b179b2..01525cb3b1 100644 --- a/library/common/src/main/java/com/google/android/exoplayer2/Player.java +++ b/library/common/src/main/java/com/google/android/exoplayer2/Player.java @@ -73,7 +73,7 @@ import java.util.List; */ public interface Player { - /** A set of {@link Event events}. */ + /** A set of {@linkplain Event events}. */ final class Events { private final FlagSet flags; @@ -81,7 +81,7 @@ public interface Player { /** * Creates an instance. * - * @param flags The {@link FlagSet} containing the {@link Event events}. + * @param flags The {@link FlagSet} containing the {@linkplain Event events}. */ public Events(FlagSet flags) { this.flags = flags; @@ -98,10 +98,10 @@ public interface Player { } /** - * Returns whether any of the given {@link Event events} occurred. + * Returns whether any of the given {@linkplain Event events} occurred. * - * @param events The {@link Event events}. - * @return Whether any of the {@link Event events} occurred. + * @param events The {@linkplain Event events}. + * @return Whether any of the {@linkplain Event events} occurred. */ public boolean containsAny(@Event int... events) { return flags.containsAny(events); @@ -211,6 +211,7 @@ public interface Player { } /** Creates an instance. */ + @SuppressWarnings("deprecation") // Setting deprecated windowIndex field public PositionInfo( @Nullable Object windowUid, int mediaItemIndex, @@ -349,7 +350,7 @@ public interface Player { } /** - * A set of {@link Command commands}. + * A set of {@linkplain Command commands}. * *

Instances are immutable. */ @@ -432,9 +433,9 @@ public interface Player { } /** - * Adds {@link Command commands}. + * Adds {@linkplain Command commands}. * - * @param commands The {@link Command commands} to add. + * @param commands The {@linkplain Command commands} to add. * @return This builder. * @throws IllegalStateException If {@link #build()} has already been called. */ @@ -447,7 +448,7 @@ public interface Player { /** * Adds {@link Commands}. * - * @param commands The set of {@link Command commands} to add. + * @param commands The set of {@linkplain Command commands} to add. * @return This builder. * @throws IllegalStateException If {@link #build()} has already been called. */ @@ -458,7 +459,7 @@ public interface Player { } /** - * Adds all existing {@link Command commands}. + * Adds all existing {@linkplain Command commands}. * * @return This builder. * @throws IllegalStateException If {@link #build()} has already been called. @@ -497,9 +498,9 @@ public interface Player { } /** - * Removes {@link Command commands}. + * Removes {@linkplain Command commands}. * - * @param commands The {@link Command commands} to remove. + * @param commands The {@linkplain Command commands} to remove. * @return This builder. * @throws IllegalStateException If {@link #build()} has already been called. */ @@ -631,7 +632,8 @@ public interface Player { *

State changes and events that happen within one {@link Looper} message queue iteration are * reported together and only after all individual callbacks were triggered. * - *

Only state changes represented by {@link Event events} are reported through this method. + *

Only state changes represented by {@linkplain Event events} are reported through this + * method. * *

Listeners should prefer this method over individual callbacks in the following cases: * @@ -777,7 +779,7 @@ public interface Player { *

{@link #onEvents(Player, Events)} will also be called to report this event along with * other events that happen in the same {@link Looper} message queue iteration. * - * @param playbackState The new playback {@link State state}. + * @param playbackState The new playback {@link State}. */ default void onPlaybackStateChanged(@State int playbackState) {} @@ -788,7 +790,7 @@ public interface Player { * other events that happen in the same {@link Looper} message queue iteration. * * @param playWhenReady Whether playback will proceed when ready. - * @param reason The {@link PlayWhenReadyChangeReason reason} for the change. + * @param reason The {@link PlayWhenReadyChangeReason} for the change. */ default void onPlayWhenReadyChanged( boolean playWhenReady, @PlayWhenReadyChangeReason int reason) {} @@ -830,7 +832,7 @@ public interface Player { *

{@link #onEvents(Player, Events)} will also be called to report this event along with * other events that happen in the same {@link Looper} message queue iteration. * - * @param shuffleModeEnabled Whether shuffling of {@link MediaItem media items} is enabled. + * @param shuffleModeEnabled Whether shuffling of {@linkplain MediaItem media items} is enabled. */ default void onShuffleModeEnabledChanged(boolean shuffleModeEnabled) {} @@ -1032,10 +1034,10 @@ public interface Player { default void onRenderedFirstFrame() {} /** - * Called when there is a change in the {@link Cue Cues}. + * Called when there is a change in the {@linkplain Cue cues}. * - *

Both {@link #onCues(List)} and {@link #onCues(CueGroup)} are called when there is a change - * in the cues. You should only implement one or the other. + *

Both this method and {@link #onCues(CueGroup)} are called when there is a change in the + * cues. You should only implement one or the other. * *

{@link #onEvents(Player, Events)} will also be called to report this event along with * other events that happen in the same {@link Looper} message queue iteration. @@ -1048,8 +1050,8 @@ public interface Player { /** * Called when there is a change in the {@link CueGroup}. * - *

Both {@link #onCues(List)} and {@link #onCues(CueGroup)} are called when there is a change - * in the cues. You should only implement one or the other. + *

Both this method and {@link #onCues(List)} are called when there is a change in the cues. + * You should only implement one or the other. * *

{@link #onEvents(Player, Events)} will also be called to report this event along with * other events that happen in the same {@link Looper} message queue iteration. @@ -1395,21 +1397,47 @@ public interface Player { int EVENT_DEVICE_VOLUME_CHANGED = 30; /** - * Commands that can be executed on a {@code Player}. One of {@link #COMMAND_PLAY_PAUSE}, {@link - * #COMMAND_PREPARE}, {@link #COMMAND_STOP}, {@link #COMMAND_SEEK_TO_DEFAULT_POSITION}, {@link - * #COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM}, {@link #COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM}, {@link - * #COMMAND_SEEK_TO_PREVIOUS}, {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM}, {@link - * #COMMAND_SEEK_TO_NEXT}, {@link #COMMAND_SEEK_TO_MEDIA_ITEM}, {@link #COMMAND_SEEK_BACK}, {@link - * #COMMAND_SEEK_FORWARD}, {@link #COMMAND_SET_SPEED_AND_PITCH}, {@link - * #COMMAND_SET_SHUFFLE_MODE}, {@link #COMMAND_SET_REPEAT_MODE}, {@link - * #COMMAND_GET_CURRENT_MEDIA_ITEM}, {@link #COMMAND_GET_TIMELINE}, {@link - * #COMMAND_GET_MEDIA_ITEMS_METADATA}, {@link #COMMAND_SET_MEDIA_ITEMS_METADATA}, {@link - * #COMMAND_CHANGE_MEDIA_ITEMS}, {@link #COMMAND_GET_AUDIO_ATTRIBUTES}, {@link - * #COMMAND_GET_VOLUME}, {@link #COMMAND_GET_DEVICE_VOLUME}, {@link #COMMAND_SET_VOLUME}, {@link - * #COMMAND_SET_DEVICE_VOLUME}, {@link #COMMAND_ADJUST_DEVICE_VOLUME}, {@link - * #COMMAND_SET_VIDEO_SURFACE}, {@link #COMMAND_GET_TEXT}, {@link - * #COMMAND_SET_TRACK_SELECTION_PARAMETERS}, {@link #COMMAND_GET_TRACKS} or {@link - * #COMMAND_SET_MEDIA_ITEM}. + * Commands that indicate which method calls are currently permitted on a particular {@code + * Player} instance, and which corresponding {@link Player.Listener} methods will be invoked. + * + *

The currently available commands can be inspected with {@link #getAvailableCommands()} and + * {@link #isCommandAvailable(int)}. + * + *

One of the following values: + * + *

*/ // @Target list includes both 'default' targets and TYPE_USE, to ensure backwards compatibility // with Kotlin usages from before TYPE_USE was added. @@ -1455,11 +1483,11 @@ public interface Player { int COMMAND_PLAY_PAUSE = 1; /** Command to prepare the player. */ int COMMAND_PREPARE = 2; - /** Command to stop playback or release the player. */ + /** Command to stop playback. */ int COMMAND_STOP = 3; /** Command to seek to the default position of the current {@link MediaItem}. */ int COMMAND_SEEK_TO_DEFAULT_POSITION = 4; - /** Command to seek anywhere into the current {@link MediaItem}. */ + /** Command to seek anywhere inside the current {@link MediaItem}. */ int COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM = 5; /** * @deprecated Use {@link #COMMAND_SEEK_IN_CURRENT_MEDIA_ITEM} instead. @@ -1471,7 +1499,10 @@ public interface Player { * @deprecated Use {@link #COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM} instead. */ @Deprecated int COMMAND_SEEK_TO_PREVIOUS_WINDOW = COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM; - /** Command to seek to an earlier position in the current or previous {@link MediaItem}. */ + /** + * Command to seek to an earlier position in the current {@link MediaItem} or the default position + * of the previous {@link MediaItem}. + */ int COMMAND_SEEK_TO_PREVIOUS = 7; /** Command to seek to the default position of the next {@link MediaItem}. */ int COMMAND_SEEK_TO_NEXT_MEDIA_ITEM = 8; @@ -1479,7 +1510,10 @@ public interface Player { * @deprecated Use {@link #COMMAND_SEEK_TO_NEXT_MEDIA_ITEM} instead. */ @Deprecated int COMMAND_SEEK_TO_NEXT_WINDOW = COMMAND_SEEK_TO_NEXT_MEDIA_ITEM; - /** Command to seek to a later position in the current or next {@link MediaItem}. */ + /** + * Command to seek to a later position in the current {@link MediaItem} or the default position of + * the next {@link MediaItem}. + */ int COMMAND_SEEK_TO_NEXT = 9; /** Command to seek anywhere in any {@link MediaItem}. */ int COMMAND_SEEK_TO_MEDIA_ITEM = 10; @@ -1487,9 +1521,9 @@ public interface Player { * @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 into the current {@link MediaItem}. */ + /** Command to seek back by a fixed increment inside the current {@link MediaItem}. */ int COMMAND_SEEK_BACK = 11; - /** Command to seek forward by a fixed increment into the current {@link MediaItem}. */ + /** Command to seek forward by a fixed increment inside the current {@link MediaItem}. */ int COMMAND_SEEK_FORWARD = 12; /** Command to set the playback speed and pitch. */ int COMMAND_SET_SPEED_AND_PITCH = 13; @@ -1501,13 +1535,15 @@ public interface Player { int COMMAND_GET_CURRENT_MEDIA_ITEM = 16; /** Command to get the information about the current timeline. */ int COMMAND_GET_TIMELINE = 17; - /** Command to get the {@link MediaItem MediaItems} metadata. */ + /** Command to get metadata related to the playlist and current {@link MediaItem}. */ + // TODO(b/263132691): Rename this to COMMAND_GET_METADATA int COMMAND_GET_MEDIA_ITEMS_METADATA = 18; - /** Command to set the {@link MediaItem MediaItems} metadata. */ + /** Command to set the playlist metadata. */ + // TODO(b/263132691): Rename this to COMMAND_SET_PLAYLIST_METADATA int COMMAND_SET_MEDIA_ITEMS_METADATA = 19; - /** Command to set a {@link MediaItem MediaItem}. */ + /** Command to set a {@link MediaItem}. */ int COMMAND_SET_MEDIA_ITEM = 31; - /** Command to change the {@link MediaItem MediaItems} in the playlist. */ + /** Command to change the {@linkplain MediaItem media items} in the playlist. */ int COMMAND_CHANGE_MEDIA_ITEMS = 20; /** Command to get the player current {@link AudioAttributes}. */ int COMMAND_GET_AUDIO_ATTRIBUTES = 21; @@ -1517,7 +1553,7 @@ public interface Player { int COMMAND_GET_DEVICE_VOLUME = 23; /** Command to set the player volume. */ int COMMAND_SET_VOLUME = 24; - /** Command to set the device volume and mute it. */ + /** Command to set the device volume. */ int COMMAND_SET_DEVICE_VOLUME = 25; /** Command to increase and decrease the device volume and mute it. */ int COMMAND_ADJUST_DEVICE_VOLUME = 26; @@ -1562,17 +1598,17 @@ public interface Player { void removeListener(Listener listener); /** - * Clears the playlist, adds the specified {@link MediaItem MediaItems} and resets the position to - * the default position. + * Clears the playlist, adds the specified {@linkplain MediaItem media items} and resets the + * position to the default position. * - * @param mediaItems The new {@link MediaItem MediaItems}. + * @param mediaItems The new {@linkplain MediaItem media items}. */ void setMediaItems(List mediaItems); /** - * Clears the playlist and adds the specified {@link MediaItem MediaItems}. + * Clears the playlist and adds the specified {@linkplain MediaItem media items}. * - * @param mediaItems The new {@link MediaItem MediaItems}. + * @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 * by {@link #getCurrentMediaItemIndex()} and {@link #getCurrentPosition()}. @@ -1580,9 +1616,9 @@ public interface Player { void setMediaItems(List mediaItems, boolean resetPosition); /** - * Clears the playlist and adds the specified {@link MediaItem MediaItems}. + * Clears the playlist and adds the specified {@linkplain MediaItem media items}. * - * @param mediaItems The new {@link MediaItem MediaItems}. + * @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. * @param startPositionMs The position in milliseconds to start playback from. If {@link @@ -1639,7 +1675,7 @@ public interface Player { /** * Adds a list of media items to the end of the playlist. * - * @param mediaItems The {@link MediaItem MediaItems} to add. + * @param mediaItems The {@linkplain MediaItem media items} to add. */ void addMediaItems(List mediaItems); @@ -1648,7 +1684,7 @@ public interface Player { * * @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 {@link MediaItem MediaItems} to add. + * @param mediaItems The {@linkplain MediaItem media items} to add. */ void addMediaItems(int index, List mediaItems); @@ -1745,9 +1781,9 @@ public interface Player { void prepare(); /** - * Returns the current {@link State playback state} of the player. + * Returns the current {@linkplain State playback state} of the player. * - * @return The current {@link State playback state}. + * @return The current {@linkplain State playback state}. * @see Listener#onPlaybackStateChanged(int) */ @State @@ -1757,7 +1793,7 @@ public interface Player { * Returns the reason why playback is suppressed even though {@link #getPlayWhenReady()} is {@code * true}, or {@link #PLAYBACK_SUPPRESSION_REASON_NONE} if playback is not suppressed. * - * @return The current {@link PlaybackSuppressionReason playback suppression reason}. + * @return The current {@link PlaybackSuppressionReason}. * @see Listener#onPlaybackSuppressionReasonChanged(int) */ @PlaybackSuppressionReason @@ -1795,11 +1831,11 @@ public interface Player { /** * Resumes playback as soon as {@link #getPlaybackState()} == {@link #STATE_READY}. Equivalent to - * {@code setPlayWhenReady(true)}. + * {@link #setPlayWhenReady(boolean) setPlayWhenReady(true)}. */ void play(); - /** Pauses playback. Equivalent to {@code setPlayWhenReady(false)}. */ + /** Pauses playback. Equivalent to {@link #setPlayWhenReady(boolean) setPlayWhenReady(false)}. */ void pause(); /** @@ -2241,7 +2277,7 @@ public interface Player { @Nullable MediaItem getCurrentMediaItem(); - /** Returns the number of {@link MediaItem media items} in the playlist. */ + /** Returns the number of {@linkplain MediaItem media items} in the playlist. */ int getMediaItemCount(); /** Returns the {@link MediaItem} at the given index. */ @@ -2274,7 +2310,7 @@ public interface Player { /** * Returns an estimate of the total buffered duration from the current position, in milliseconds. - * This includes pre-buffered data for subsequent ads and {@link MediaItem media items}. + * This includes pre-buffered data for subsequent ads and {@linkplain MediaItem media items}. */ long getTotalBufferedDuration();