Create and configure a DefaultPreloadManager

This page describes how to create a DefaultPreloadManager, which preloads media content for your app based on the strategy you choose.

Preload managers based on the BasePreloadManager abstract class let you rank content by the criteria you choose. This document explains how to use the derived class DefaultPreloadManager, in which each media item is ranked with an integer representing its location in a list (for example, its position in a video carousel). The preload manager prioritizes loading the items based on how close it is to the item the user is currently playing. That way, if a user moves to another item, the new item can start playing right away.

There are three steps to creating an instance of DefaultPreloadManager:

• Define a TargetPreloadStatusControl which the preload manager can query to find out if the media item is ready to be loaded and how much to load.
• Create the builder which you'll use to create the preload manager, and to create your app's ExoPlayer objects.
• Use the builder to create the preload manager by calling the builder's build() method.

Create a target preload status control

When you create the DefaultPreloadManager.Builder, you'll pass it a target preload status control object that you define. This object implements the TargetPreloadStatusControl interface. When the preload manager is getting ready to preload media, it calls your status control's getTargetPreloadStatus() method to find out how much content to load. The status control can reply with one of these status codes:

• STAGE_SPECIFIED_RANGE_LOADED: The preload manager should load the content from the specified start position and for the specified duration (given in milliseconds).
• STAGE_TRACKS_SELECTED: The preload manager should load and process the content track's information, and select the tracks. The preload manager shouldn't start loading the content yet.
• STAGE_SOURCE_PREPARED: The preload manager should prepare the content source. For example, if the content's metadata is in a separate manifest file, the preload manager might fetch and parse that manifest.
• null: The preload manager shouldn't load any content or metadata for that media item.

You'll need to have a strategy for deciding how much content to load for each media item. In this example, more content is loaded for items closest to the item that's currently playing. If the user is playing content with index n, the controller returns the following codes:

• Index n+1 (the next media item): Load 3000 ms (3 seconds) from the default start position
• Index n-1 (the previous media item): Load 1000 ms (1 second) from the default start position
• Other media items in the range n-2 to n+2: Return PreloadStatus.TRACKS_SELECTED
• Other media items in the range n-4 to n+4: Return PreloadStatus.SOURCE_PREPARED
• For all other media items, return null

class MyTargetPreloadStatusControl(
    currentPlayingIndex: Int = C.INDEX_UNSET
) : TargetPreloadStatusControl<Int, DefaultPreloadManager.PreloadStatus> {

    override fun getTargetPreloadStatus(index: Int): DefaultPreloadManager.PreloadStatus? {
        if (index - currentPlayingIndex == 1) { // next track
            // return a PreloadStatus that is labelled by STAGE_SPECIFIED_RANGE_LOADED and
            // suggest loading 3000ms from the default start position
            return DefaultPreloadManager.PreloadStatus.specifiedRangeLoaded(3000L)
        } else if (index - currentPlayingIndex == -1) { // previous track
            // return a PreloadStatus that is labelled by STAGE_SPECIFIED_RANGE_LOADED and
            // suggest loading 3000ms from the default start position
            return DefaultPreloadManager.PreloadStatus.specifiedRangeLoaded(3000L)
        } else if (abs(index - currentPlayingIndex) == 2) {
            // return a PreloadStatus that is labelled by STAGE_TRACKS_SELECTED
            return DefaultPreloadManager.PreloadStatus.TRACKS_SELECTED
        } else if (abs(index - currentPlayingIndex) <= 4) {
            // return a PreloadStatus that is labelled by STAGE_SOURCE_PREPARED
            return DefaultPreloadManager.PreloadStatus.SOURCE_PREPARED
        }
        return null
    }
}
PreloadManagerKotlinSnippets.kt

Key points about the code

• You'll pass an instance of MyTargetPreloadStatusControl to the preload manager builder when you create it.
• currentPlayingIndex holds the index of whatever media item is currently playing. It's the app's job to keep that value up to date.
• When the preload manager is ready to load content, it calls getTargetPreloadStatus and passes the ranking information you specified for that corresponding media item. In the case of DefaultPreloadManager, that ranking information is an integer, specifying the item's position in a carousel. The method chooses what code to return by comparing that index with the index of the item that's currently selected.

Create the preload manager

To create your preload manager, you need a DefaultPreloadManager.Builder. That builder is configured with the current context and the app's target preload status control. The builder also provides setter methods which you can use to set the preload manager's custom components.

Besides using the builder to create the preload manager, you'll also use it to create the ExoPlayer objects your app uses to play the content.

val targetPreloadStatusControl = MyTargetPreloadStatusControl()
val preloadManagerBuilder =
    DefaultPreloadManager.Builder(context, targetPreloadStatusControl)
val preloadManager = preloadManagerBuilder.build()
PreloadManagerKotlinSnippets.kt

Key points about the code

• MyTargetPreloadStatusControl is the class you defined in Create a target preload status control.
• You'll use the same DefaultPreloadManager.Builder to create the ExoPlayer objects that will play content managed by that preload manager.