Version: Android 1.2.1

Playlists

Playlists are reactive lists of videos that can be played and observed efficiently, with built-in support for pagination, caching and preloading. This is the recommended way of fetching and playing videos through our player.

As with querying videos, the start point is the video store (VideoKit.videos()). Also, to fetch playlist you will need a valid session or the call will return an error.

Inspecting playlists#

Every playlist holds a list of videos in memory. At first, this list represent the first "page" of results that were retrieved from server. These videos can be retrieved with Playlist.getVideo:

val playlist: Playlist = ...
val size: Int = playlist.size
val video: Video = playlist.getVideo(0)

If getVideo is called with an index bigger than playlist.size, it will throw an exception. If you need more videos than those available at the moment, you can request a new batch of results by using Playlist.loadMore():

// Load next page
val nextPage: Call<Unit> = playlist.loadMore()
nextPage.onSuccess {
  // Got new videos!
}

Note that if Playlist.loadMoreOnAccess is true (default), the playlist will automatically load new pages as you consume the playlist with getVideo, checking if you are getting close enough to the last available video. This makes it easy to show a list of videos without worrying about dynamic contents.

Observing playlists#

Playlists can be observed by registering a PlaylistListener. This is extremely useful when videos are shown in a RecyclerView, for example, so that you can call the appropriate notify* methods whenever something changes.

val playlist: Playlist = ...
playlist.addListener(object: PlaylistListener {
    override fun onVideoInserted(id: String, index: Int) { ... }
    override fun onVideoRemoved(id: String, index: Int) { ... }
    override fun onVideoChanged(id: String, index: Int) { ... }
    override fun onVideoMoved(id: String, fromIndex: Int, toIndex: Int) { ... }
})

Obtain playlists#

As with other APIs, we use request objects to define the query parameters. All request objects extend the PlaylistRequest interface. We expose several types of requests, each one with different configuration options.

Once you have the request, just call getPlaylist:

val videos: VideoStore = VideoKit.videos()
videos.getPlaylist(request).onSuccess {
    // Got playlist!
}.onError {
    // Something went wrong.
}

By user#

You can filter by user using UserPlaylistRequest:

val request = UserPlaylistRequest(userIdentity)
val request = UserPlaylistRequest.builder(userIdentity) {
    order(SortOrder.DESC)
    pageSize(50)
}

By metadata and tags#

You can filter by metadata and tags using FilteredPlaylistRequest:

val request = FilteredPlaylistRequest(tags = tags, metadata = metadata)
val request = FilteredPlaylistRequest.builder() {
    tags("tag1", "tag2")
    metadata("key", "value")
    order(SortOrder.DESC)
    pageSize(50)
}

Custom playlists#

You can create a playlist with custom videos using CustomPlaylistRequest:

val request = CustomPlaylistRequest(ids = listOf("videoId1", "videoId2"))
val request = CustomPlaylistRequest.builder() {
    ids("videoId1", "videoId2", "videoId3")
}

This is a special type of playlist which can be controlled by the user.

It is mutable! You can use add or remove functions to add ids, and videos will be loaded accordingly
It can't support the concept of page, so loadMore does nothing.

Preloading#

As you access videos (through getVideo) and consume them (through the player SDK), the playlist will automatically cache video data and preload videos that we think you might request soon. You can customize the preload quality using preloadQuality:

playlist.preloadQuality = Quality.AUTO // recommended
playlist.preloadQuality = Quality.FIXED_144P
playlist.preloadQuality = Quality.FIXED_240P
playlist.preloadQuality = Quality.FIXED_360P
playlist.preloadQuality = Quality.FIXED_540P
playlist.preloadQuality = Quality.FIXED_720P

You can also choose whether to enable HLS playback or not using the preloadUseHls boolean:

playlist.preloadUseHls = true // recommended
playlist.preloadUseHls = false

When passing the playlist to a player, it is fundamental that these settings match the player values, Player.playbackQuality and Player.useHls respectively, otherwise preloading will be wasting useful resources.