Class MultiControllerPlaylist
- java.lang.Object
-
- com.castlabs.android.player.AbstractPlayerListener
-
- com.castlabs.android.player.playlist.MultiControllerPlaylist
-
- All Implemented Interfaces:
PlayerListener,PlayerViewLifecycleDelegate.LifecycleListener,Playlist
- Direct Known Subclasses:
PlaylistController
public class MultiControllerPlaylist extends AbstractPlayerListener implements PlayerViewLifecycleDelegate.LifecycleListener, Playlist
Playlist management. Use this class if you want to have playlist-like behaviour.In order to use it, you should create an instance, initializing it with a
PlayerViewor just aContextin case you are using a custom View. Then, playback is started through theopen(PlayerConfig...)method, which takes a list of items to play consecutively.For the sake of completely seamless Playlist item transitions, this class uses two underlying
PlayerControllers, preparing one shortly before the current item reaches the end.You should also register a
MultiControllerPlaylist.PlaylistListenerin the constructor to get Playlist-specific events, such as when a Playlist item change occurs. It's important to add the corresponding unbinding and binding logic here for the old and newPlayerControllersrespectively.The current Playlist can be obtained with
getPlaylist()and the current item withgetCurrentItem(). The MultiControllerPlaylist operates onPlayerConfigobjects.This class provides methods to manage the Playlist:
addItem(PlayerConfig)addItem(int, PlayerConfig)removeItem(PlayerConfig)swap(PlayerConfig, PlayerConfig)slideNext()slidePrevious()
The MultiControllerPlaylist allows for some configuration. The
setNextItemThreshold(int)method allows to set how much time before the end of an asset should the next playlist item be prepared. Looping can be enabled withenableLooping(boolean). Looping will result in playback starting over from the first Playlist item once the last finishes.Both these settings are dynamic, and will take effect immediately for the following Playlist item.
Playback behaviour of live content items is undefined.
- Since:
- 4.2.5
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classMultiControllerPlaylist.AbstractPlaylistListenerAbstract implementation of theMultiControllerPlaylist.PlaylistListener.static classMultiControllerPlaylist.BuilderBuilder forMultiControllerPlayliststatic interfaceMultiControllerPlaylist.ItemChangeFlagsstatic interfaceMultiControllerPlaylist.PlaylistListenerPlaylist-related events listener.
-
Field Summary
Fields Modifier and Type Field Description static intDEFAULT_ITEM_CHANGE_FLAGSDefault behaviour when it comes to item change.static intITEM_THRESHOLD_FULLY_BUFFEREDDefault value forsetNextItemThreshold(int).static intITEM_THRESHOLD_UPON_STARTThe value to be set insetNextItemThreshold(int)indicating the next stream should be prepared together with the current streamstatic intKEEP_ALLFlag which indicates to carry all the track selections and bandwidth estimate from one PlayerController onto the next one, as well as theTrickplayConfiguration.static intKEEP_AUDIO_TRACKFlag which indicates to carry the selectedAudioTrackfrom one PlayerController onto the next one.static intKEEP_BANDWIDTH_ESTIMATEFlag which indicates to carry the last available bitrate estimate from one PlayerController onto the next one.static intKEEP_SUBTITLE_TRACKFlag which indicates to carry the selectedSubtitleTrackfrom one PlayerController onto the next one.static intKEEP_TRICKPLAY_CONFIGFlag which indicates to carry the currentTrickplayConfigurationfrom one PlayerController onto the next one.static intKEEP_VIDEO_QUALITYFlag which indicates to carry the selectedVideoTrackQualityfrom one PlayerController onto the next one.
-
Constructor Summary
Constructors Constructor Description MultiControllerPlaylist(Context context, MultiControllerPlaylist.PlaylistListener listener)Deprecated.Use theBuilder.MultiControllerPlaylist(PlayerView playerView, MultiControllerPlaylist.PlaylistListener listener)Deprecated.Use theBuilder.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description voidaddItem(int position, PlayerConfig config)Adds an item at the specified position in the playlist.voidaddItem(PlayerConfig config)Adds an item at the end of the playlist.voidenableLooping(boolean enableLooping)Whether to enable Playlist looping or not.PlayerControllergetCurrentController()Returns the current underlyingPlayerController.PlayerConfiggetCurrentItem()Returns the currently playing itemintgetCurrentItemIndex()Returns current item indexCollection<PlayerConfig>getLoadedConfigs()List<PlayerConfig>getPlaylist()Returns the current Playlist as a List ofPlayerConfigitems.intgetSize()Returns the number of Configs in the playlist.static voidmigratePlayerListeners(PlayerController oldController, PlayerController newController)Deprecated.PlayerConfignextItem()Advances playback to the next Playlist item.voidonError(CastlabsPlayerException error)Error callback that is called when exceptions are raised on background threads.voidonFatalErrorOccurred(CastlabsPlayerException error)Error callback that is called when a fatal exception is raised on background threads.voidonFullyBuffered()Invoked when all the remaining content has been buffered.voidonPlaybackPositionChanged(long playbackPositionMs)Event triggered when the playback position changed.voidonPostDestroy()voidonPostRelease(boolean backgroundPlayback)voidonPostResume(PlayerController playerController)voidonPostStart()voidonSeekRangeChanged(long startTimeMs, long endTimeMs)Event triggered when the seek range changedvoidonSeekTo(long newPosition)This callback is invoked when the position of the video playback is actively changed by thePlayerController.voidonStateChanged(PlayerController.State state)State change event triggered when the player state changedvoidonVideoSizeChanged(int width, int height, float pixelWidthHeightRatio)Invoked each time there's a change in the size of the video being rendered.voidopen(int startIndex, Parcelable... playerConfigs)Start playback with the specified index and with an Array ofPlayerConfigsorBundles.voidopen(int startIndex, List<? extends Parcelable> playerConfigs)Start playback with the specified index and player configsvoidopen(Bundle... bundles)Starts playback with an Array of Bundles.voidopen(Parcelable... playerConfigs)Starts playback with an Array ofPlayerConfigsorBundles.voidopen(PlayerConfig... playerConfigs)Starts playback with an Array ofPlayerConfigs.voidopen(List<? extends Parcelable> playerConfigs)Starts playback with a List ofPlayerConfigsorBundles.PlayerConfigplayItem(int index)Advances playback to the Playlist item specified by the index.PlayerConfigpreviousItem()Moves backwards in the Playlist.voidremoveItem(PlayerConfig config)Removes an item from the PlaylistvoidsetItemChangeFlags(int flags)Sets the behaviour that will be applied when a new playlist item is about to be played.voidsetNextItemThreshold(int nextItemThresholdMs)voidslideNext()Slides the current item in the playlist to the next position.voidslidePrevious()Slides the current item in the playlist to the previous position.voidswap(PlayerConfig playerConfig1, PlayerConfig playerConfig2)Interchanges two Playlist items.-
Methods inherited from class com.castlabs.android.player.AbstractPlayerListener
onDisplayChanged, onDurationChanged, onPlayerModelChanged, onSeekCompleted, onSpeedChanged, onVideoKeyStatusChanged
-
-
-
-
Field Detail
-
ITEM_THRESHOLD_FULLY_BUFFERED
public static final int ITEM_THRESHOLD_FULLY_BUFFERED
Default value forsetNextItemThreshold(int). This is a special value indicating that the nextPlayerControllershould be prepared as soon as the current one is done loading data. This corresponds to thePlayerListener.onFullyBuffered()method.- See Also:
- Constant Field Values
-
ITEM_THRESHOLD_UPON_START
public static final int ITEM_THRESHOLD_UPON_START
The value to be set insetNextItemThreshold(int)indicating the next stream should be prepared together with the current stream- See Also:
- Constant Field Values
-
KEEP_BANDWIDTH_ESTIMATE
public static final int KEEP_BANDWIDTH_ESTIMATE
Flag which indicates to carry the last available bitrate estimate from one PlayerController onto the next one. This will allow playback to continue in the same (or closest) possible quality, if ABR is enabled.- See Also:
- Constant Field Values
-
KEEP_VIDEO_QUALITY
public static final int KEEP_VIDEO_QUALITY
Flag which indicates to carry the selectedVideoTrackQualityfrom one PlayerController onto the next one. Video quality matching will be made exclusively by theirbitrate. If no matching quality is found, the one with the closest bitrate will be selected.- See Also:
- Constant Field Values
-
KEEP_AUDIO_TRACK
public static final int KEEP_AUDIO_TRACK
Flag which indicates to carry the selectedAudioTrackfrom one PlayerController onto the next one. Track matching is based solely on theirlanguage.- See Also:
- Constant Field Values
-
KEEP_SUBTITLE_TRACK
public static final int KEEP_SUBTITLE_TRACK
Flag which indicates to carry the selectedSubtitleTrackfrom one PlayerController onto the next one. Track matching is based solely on theirlanguage.- See Also:
- Constant Field Values
-
KEEP_TRICKPLAY_CONFIG
public static final int KEEP_TRICKPLAY_CONFIG
Flag which indicates to carry the currentTrickplayConfigurationfrom one PlayerController onto the next one. Current Trickplay enabled state (PlayerController.enableTrickplayMode(boolean)will also be carried over.- Since:
- 4.2.4
- See Also:
- Constant Field Values
-
KEEP_ALL
public static final int KEEP_ALL
Flag which indicates to carry all the track selections and bandwidth estimate from one PlayerController onto the next one, as well as theTrickplayConfiguration.- See Also:
- Constant Field Values
-
DEFAULT_ITEM_CHANGE_FLAGS
public static final int DEFAULT_ITEM_CHANGE_FLAGS
Default behaviour when it comes to item change.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
MultiControllerPlaylist
public MultiControllerPlaylist(@NonNull PlayerView playerView, @Nullable MultiControllerPlaylist.PlaylistListener listener)Deprecated.Use theBuilder.Constructor which takes aPlayerView. If you're not using it, or have a custom UI, use theMultiControllerPlaylist(Context, PlaylistListener)constructor instead.- Parameters:
playerView- PlayerView to bind the PlayerController. If it already has aPlayerController, it will be ignored and replaced with a new one.listener- aMultiControllerPlaylist.PlaylistListenerto be informed about Playlist events.
-
MultiControllerPlaylist
public MultiControllerPlaylist(@NonNull Context context, @Nullable MultiControllerPlaylist.PlaylistListener listener)Deprecated.Use theBuilder.- Parameters:
context- the Context used to create the PlayerControllers.listener- aMultiControllerPlaylist.PlaylistListenerto be informed about Playlist events.
-
-
Method Detail
-
getLoadedConfigs
public Collection<PlayerConfig> getLoadedConfigs()
-
migratePlayerListeners
public static void migratePlayerListeners(@Nullable PlayerController oldController, @Nullable PlayerController newController)Deprecated.Migrates all the listeners from one PlayerController to the other. Typical usage of this method is in an implementation ofMultiControllerPlaylist.PlaylistListener.onItemChange(PlayerConfig, PlayerController, PlayerController).- Parameters:
oldController- the PlayerController where to get and remove the listeners fromnewController- the PlayerController where to set the listeners to
-
enableLooping
public void enableLooping(boolean enableLooping)
Whether to enable Playlist looping or not. If enabled, playback will carry on to the first Playlist item one the last one finishes. It can also have an effect with methods such asnextItem()andslideNext().- Parameters:
enableLooping- whether to enable Playlist looping or not
-
setNextItemThreshold
public void setNextItemThreshold(int nextItemThresholdMs)
- Parameters:
nextItemThresholdMs- how much time before the end of an asset should the next Playlist item be prepared, in milliseconds. Default value isITEM_THRESHOLD_FULLY_BUFFERED, see alsoITEM_THRESHOLD_UPON_START
-
setItemChangeFlags
public void setItemChangeFlags(int flags)
Sets the behaviour that will be applied when a new playlist item is about to be played.The MultiControllerPlaylist can take care of carrying some configuration to the new PlayerController, especially related to currently selected tracks.
Takes effect immediately, if changed mid-playback, the flags will be evaluated on the next item change.
You should ideally call this method right after MultiControllerPlaylist creation.
- Parameters:
flags- flags to set.- See Also:
MultiControllerPlaylist.ItemChangeFlags
-
onPostStart
public void onPostStart()
- Specified by:
onPostStartin interfacePlayerViewLifecycleDelegate.LifecycleListener
-
onPostResume
public void onPostResume(@NonNull PlayerController playerController)- Specified by:
onPostResumein interfacePlayerViewLifecycleDelegate.LifecycleListener
-
onPostRelease
public void onPostRelease(boolean backgroundPlayback)
- Specified by:
onPostReleasein interfacePlayerViewLifecycleDelegate.LifecycleListener
-
onPostDestroy
public void onPostDestroy()
- Specified by:
onPostDestroyin interfacePlayerViewLifecycleDelegate.LifecycleListener
-
open
public void open(@NonNull Parcelable... playerConfigs)Description copied from interface:PlaylistStarts playback with an Array ofPlayerConfigsorBundles.The playlist might apply some generic configuration to the items passed to this method. This implies that the items in the playlist *won't necessarily be the same instances*.
-
open
public void open(int startIndex, @NonNull Parcelable... playerConfigs)Description copied from interface:PlaylistStart playback with the specified index and with an Array ofPlayerConfigsorBundles.The playlist might apply some generic configuration to the items passed to this method. This implies that the items in the playlist *won't necessarily be the same instances*.
-
open
public void open(@NonNull Bundle... bundles)Starts playback with an Array of Bundles. Refer toPlayerController.open(Bundle)to see the supported keys.- Parameters:
bundles- array of Bundles, each representing a Playlist item.
-
open
public void open(@NonNull PlayerConfig... playerConfigs)Starts playback with an Array ofPlayerConfigs.- Parameters:
playerConfigs- array of PlayerConfigs, each representing a Playlist item.
-
open
public void open(@NonNull List<? extends Parcelable> playerConfigs)Description copied from interface:PlaylistStarts playback with a List ofPlayerConfigsorBundles.The playlist might apply some generic configuration to the items passed to this method. This implies that the items in the playlist *won't necessarily be the same instances*.
-
open
public void open(int startIndex, @NonNull List<? extends Parcelable> playerConfigs)Description copied from interface:PlaylistStart playback with the specified index and player configsThe playlist might apply some generic configuration to the items passed to this method. This implies that the items in the playlist *won't necessarily be the same instances*.
-
getCurrentController
@NonNull public PlayerController getCurrentController()
Returns the current underlyingPlayerController. If there's currently no playing media, a Controller will be created and returned.- Returns:
- the current underlying PlayerController.
-
getPlaylist
public List<PlayerConfig> getPlaylist()
Returns the current Playlist as a List ofPlayerConfigitems.- Specified by:
getPlaylistin interfacePlaylist- Returns:
- the current Playlist
-
getSize
public int getSize()
Description copied from interface:PlaylistReturns the number of Configs in the playlist.
-
getCurrentItem
public PlayerConfig getCurrentItem()
Returns the currently playing item- Specified by:
getCurrentItemin interfacePlaylist- Returns:
- the currently playing item
-
getCurrentItemIndex
public int getCurrentItemIndex()
Description copied from interface:PlaylistReturns current item index- Specified by:
getCurrentItemIndexin interfacePlaylist- Returns:
- Current item index or
-1otherwise
-
addItem
public void addItem(@NonNull PlayerConfig config)Description copied from interface:PlaylistAdds an item at the end of the playlist.
-
addItem
public void addItem(int position, @NonNull PlayerConfig config)Adds an item at the specified position in the playlist.- Specified by:
addItemin interfacePlaylist- Parameters:
position- the position at which to add the item.config- item to add- Throws:
IndexOutOfBoundsException- if the position is negative or greater than the current Playlist size.
-
removeItem
public void removeItem(@NonNull PlayerConfig config)Removes an item from the Playlist- Specified by:
removeItemin interfacePlaylist- Parameters:
config- item to remove
-
swap
public void swap(@NonNull PlayerConfig playerConfig1, @NonNull PlayerConfig playerConfig2)Interchanges two Playlist items. If any of such items is the currently playing item, playback won't be affected.
-
slideNext
public void slideNext()
Slides the current item in the playlist to the next position. If the current item is the last in the playlist, will be set to the first one only ifloopingis enabled.
-
slidePrevious
public void slidePrevious()
Slides the current item in the playlist to the previous position. If the current item is the fist in the playlist, will be set to the last one only ifloopingis enabled.
-
onFatalErrorOccurred
public void onFatalErrorOccurred(@NonNull CastlabsPlayerException error)Description copied from interface:PlayerListenerError callback that is called when a fatal exception is raised on background threads. All Exceptions are wrapped in aCastlabsPlayerException. This method will be invoked *only* for fatal errors, and *before* the PlayerController isreleased. ThePlayerListener.onError(CastlabsPlayerException)method will be invoked after this one.- Specified by:
onFatalErrorOccurredin interfacePlayerListener- Overrides:
onFatalErrorOccurredin classAbstractPlayerListener- Parameters:
error- the player exception
-
onError
public void onError(@NonNull CastlabsPlayerException error)Description copied from interface:PlayerListenerError callback that is called when exceptions are raised on background threads. All Exceptions are wrapped in aCastlabsPlayerException. If the error isfatal, the PlayerController will bereleasedright before this callback.- Specified by:
onErrorin interfacePlayerListener- Overrides:
onErrorin classAbstractPlayerListener- Parameters:
error- the player exception
-
onStateChanged
public void onStateChanged(@NonNull PlayerController.State state)Description copied from interface:PlayerListenerState change event triggered when the player state changed- Specified by:
onStateChangedin interfacePlayerListener- Overrides:
onStateChangedin classAbstractPlayerListener- Parameters:
state- the new state
-
nextItem
@Nullable public PlayerConfig nextItem()
Advances playback to the next Playlist item. This is affected bylooping.
-
playItem
@Nullable public PlayerConfig playItem(int index)
Description copied from interface:PlaylistAdvances playback to the Playlist item specified by the index.
-
previousItem
@Nullable public PlayerConfig previousItem()
Moves backwards in the Playlist. This is affected bylooping.- Specified by:
previousItemin interfacePlaylist- Returns:
- the next item to play. If null, the start of the Playlist has been reached.
-
onSeekTo
public void onSeekTo(long newPosition)
Description copied from interface:PlayerListenerThis callback is invoked when the position of the video playback is actively changed by thePlayerController.- Specified by:
onSeekToin interfacePlayerListener- Overrides:
onSeekToin classAbstractPlayerListener- Parameters:
newPosition- the new position in microseconds
-
onVideoSizeChanged
public void onVideoSizeChanged(int width, int height, float pixelWidthHeightRatio)Description copied from interface:PlayerListenerInvoked each time there's a change in the size of the video being rendered.- Specified by:
onVideoSizeChangedin interfacePlayerListener- Overrides:
onVideoSizeChangedin classAbstractPlayerListener- Parameters:
width- The video width in pixels.height- The video height in pixels.pixelWidthHeightRatio- The width to height ratio of each pixel. For the normal case of square pixels this will be equal to 1.0. Different values are indicative of anamorphic content.
-
onSeekRangeChanged
public void onSeekRangeChanged(long startTimeMs, long endTimeMs)Description copied from interface:PlayerListenerEvent triggered when the seek range changed- Specified by:
onSeekRangeChangedin interfacePlayerListener- Overrides:
onSeekRangeChangedin classAbstractPlayerListener- Parameters:
startTimeMs- the possible seek start time in millisecondsendTimeMs- the possible seek end time in milliseconds
-
onPlaybackPositionChanged
public void onPlaybackPositionChanged(long playbackPositionMs)
Description copied from interface:PlayerListenerEvent triggered when the playback position changed. Note that for performance reasons, this is triggered at most once per second, hence you will only see when seconds changing during playback.- Specified by:
onPlaybackPositionChangedin interfacePlayerListener- Overrides:
onPlaybackPositionChangedin classAbstractPlayerListener- Parameters:
playbackPositionMs- the current playback position in milliseconds
-
onFullyBuffered
public void onFullyBuffered()
Description copied from interface:PlayerListenerInvoked when all the remaining content has been buffered. From this point onwards no more network activity is required to finish playing the current media.- Specified by:
onFullyBufferedin interfacePlayerListener- Overrides:
onFullyBufferedin classAbstractPlayerListener
-
-