Android Development

Android Builders Weblog: Elevating media playback: Introducing preloading with Media3

5 September 2025

Posted by Mayuri Khinvasara Khabya – Developer Relations Engineer (LinkedIn and X)

In right this moment’s media-centric apps, delivering a easy, uninterrupted playback expertise is vital to a pleasant consumer expertise. Customers anticipate their movies to begin immediately and play seamlessly with out pauses.

The core problem is latency. Historically, a video participant solely begins its work—connecting, downloading, parsing, buffering—after the consumer has chosen an merchandise for playback. This reactive strategy is gradual for right this moment’s brief kind video context. The answer is to be proactive. We have to anticipate what the consumer will watch subsequent and get the content material prepared forward of time. That is the essence of preloading.

The important thing advantages of preloading embrace:

🚀 Sooner Playback Begin: Movies are already able to go, resulting in faster transitions between gadgets and a extra instant begin.
📉 Decreased Buffering: By proactively loading knowledge, playback is way much less prone to stall, for instance attributable to community hiccups.
✨ Ensuing smoother Person Expertise: The mix of sooner begins and fewer buffering creates a extra fluid, seamless interplay for customers to get pleasure from.

On this three-part sequence, we’ll introduce and deep dive into Media3’s highly effective utilities for (pre)loading elements.

In Half 1, we’ll cowl the foundations: understanding the completely different preloading methods accessible in Media3, enabling PreloadConfiguration and establishing the DefaultPreloadManager, enabling your app to preload gadgets. By the tip of this weblog, it’s best to have the ability to preload and play media gadgets along with your configured rating and period.
In Half 2, we’ll get into extra superior subjects of DefaultPreloadManager: utilizing listeners for analytics, exploring production-ready greatest practices just like the sliding window sample and customized shared elements of DefaultPreloadManager and ExoPlayer.
In Half 3, we’ll dive deep into disk caching with DefaultPreloadManager.

Preloading to the rescue! 🦸‍♀️

The core thought behind preloading is straightforward: load media content material earlier than you want it. By the point a consumer swipes to the following video, the primary segments of the video are already downloaded and accessible, prepared for instant playback.

Consider it like a restaurant. A busy kitchen would not anticipate an order to begin chopping onions. 🧅 They do their prep work prematurely. Preloading is the prep work to your video participant.

When enabled, preloading will help reduce be a part of latency when a consumer skips to the following merchandise earlier than the playback buffer reaches the following merchandise. The primary interval of the following window is ready and video, audio and textual content samples are buffered. The preloaded interval is later queued into the participant with buffered samples instantly accessible and able to be fed to the codec for rendering.

In Media3 there are two major APIs for preloading, every fitted to completely different use instances. Choosing the proper API is step one.

1. Preloading playlist gadgets with PreloadConfiguration

That is the easy strategy, helpful for linear, sequential media like playlists the place the playback order is predictable (like a sequence of episodes). You give the participant the complete checklist of media gadgets utilizing ExoPlayer’s playlist APIs and set the PreloadConfiguration for the participant, then it routinely preloads the following gadgets within the sequence as configured. This API makes an attempt to optimize the be a part of latency when a consumer skips to the following merchandise earlier than the playback buffer already overlaps into the following merchandise.

Preloading is simply began when no media is being loaded for the continuing playback, which prevents it from competing for bandwidth with the first playback.

In case you’re nonetheless unsure whether or not you want preloading, this API is a superb low-lift choice to attempt it out!

participant.preloadConfiguration =
    PreloadConfiguration(/* targetPreloadDurationUs= */ 5_000_000L)

With the PreloadConfiguration above, the participant tries to preload 5 seconds of media for the following merchandise within the playlist.

As soon as opted-in, playlist preloading will be turned off once more by utilizing PreloadConfiguration.DEFAULT to disable playlist preloading:

participant.preloadConfiguration = PreloadConfiguration.DEFAULT

2. Preloading dynamic lists with PreloadManager

For dynamic UIs like vertical feeds or carousels, the place the “subsequent” merchandise is decided by consumer interplay, the PreloadManager API is acceptable. It is a new highly effective, standalone part inside the Media3 ExoPlayer library particularly designed to proactively preload. It manages a group of potential MediaSources, prioritizing them based mostly on proximity to the consumer’s present place and gives granular management over what to preload, appropriate for advanced eventualities like dynamic feeds of brief kind movies.

Setting Up Your PreloadManager

The DefaultPreloadManager is the canonical implementation for PreloadManager.

The builder of DefaultPreloadManager can construct each the DefaultPreloadManager and any ExoPlayer cases that can play its preloaded content material. To create a DefaultPreloadManager, you will want to cross a TargetPreloadStatusControl, which the preload supervisor can question to learn the way a lot to load for an merchandise. We’ll clarify and outline an instance of TargetPreloadStatusControl within the part under.

val preloadManagerBuilder =
DefaultPreloadManager.Builder(context, targetPreloadStatusControl)
val preloadManager = val preloadManagerBuilder.construct()

// Construct ExoPlayer with DefaultPreloadManager.Builder
val participant = preloadManagerBuilder.buildExoPlayer()

Utilizing the identical builder for each the ExoPlayer and DefaultPreloadManager is important, which ensures that the elements underneath the hood of them are accurately shared.

And that is it! You now have a supervisor able to obtain directions.

Configuring Period and Rating with TargetPreloadStatusControl

What if you wish to preload, say, 10 seconds of video ? You possibly can present the place of your media gadgets within the carousel, and the DefaultPreloadManager prioritizes loading the gadgets based mostly on how shut it’s to the merchandise the consumer is presently enjoying.

If you wish to management how a lot period of the merchandise to preload, you’ll be able to inform that with DefaultPreloadManager.PreloadStatus you come back.

For instance,

Merchandise ‘A’ is the best precedence, load 5 seconds of video.
Merchandise ‘B’ is medium precedence however whenever you get to it, load 3 seconds of video.
Merchandise ‘C’ is much less precedence, load solely tracks.
Merchandise ‘D’ is even much less of a precedence, simply put together.
Some other gadgets are far-off, Don’t preload something.

This granular management will help you optimize your useful resource utilization which is beneficial for a seamless playback.

import androidx.media3.exoplayer.DefaultPreloadManager.PreloadStatus


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


    // The app is chargeable for updating this based mostly on UI state
    override enjoyable getTargetPreloadStatus(index: Int): PreloadStatus? {

        val distance = index - currentPlayingIndex

        // Adjoining gadgets (Subsequent): preload 5 seconds
        if (distance == 1) { 
        // Return a PreloadStatus that's labelled by STAGE_SPECIFIED_RANGE_LOADED and recommend loading // 5000ms from the default begin place
                    return PreloadStatus.specifiedRangeLoaded(5000L)
                } 

        // Adjoining gadgets (Earlier): preload 3 seconds
        else if (distance == -1) { 
        // Return a PreloadStatus that's labelled by STAGE_SPECIFIED_RANGE_LOADED //and recommend loading 3000ms from the default begin place
                    return PreloadStatus.specifiedRangeLoaded(3000L)
                } 

        // Objects two positions away: simply choose tracks
        else if (distance) == 2) {
        // Return a PreloadStatus that's labelled by STAGE_TRACKS_SELECTED
                    return PreloadStatus.TRACKS_SELECTED
                } 

        // Objects 4 positions away: simply choose put together
        else if (abs(distance) <= 4) {
        // Return a PreloadStatus that's labelled by STAGE_SOURCE_PREPARED
                    return PreloadStatus.SOURCE_PREPARED
                }

             // All different gadgets are too far-off
             return null
            }
}

Tip: PreloadManager can maintain each the earlier and subsequent gadgets preloaded, whereas the PreloadConfiguration will solely stay up for the following gadgets.

Managing Preloading Objects

Along with your supervisor created, you can begin telling it what to work on. As your consumer scrolls by a feed, you may determine the upcoming movies and add them to the supervisor. The interplay with the PreloadManager is a state-driven dialog between your UI and the preloading engine.

1. Add Media Objects

As you populate your feed, you need to inform the supervisor of the media it wants to trace. If you’re beginning, you might add your entire checklist you need to preload. Subsequently you’ll be able to maintain including a single merchandise to the checklist as and when required. You’ve full management over what gadgets are within the preloading checklist which suggests you additionally need to handle what’s added and faraway from the supervisor.

val initialMediaItems = pullMediaItemsFromService(/* depend= */ 20)
for (index in 0 till initialMediaItems.dimension) {
    preloadManager.add(
        initialMediaItems.get(index),index)
    )
}

The supervisor will now begin fetching knowledge for this MediaItem within the background.

After including, inform the supervisor to re-evaluate its new checklist (hinting that one thing has modified like including/ eradicating an merchandise, or the consumer switches to play a brand new merchandise.)

preloadManager.invalidate()

2. Retrieve and Play an Merchandise

Right here comes the principle playback logic. When the consumer decides to play that video, you need not create a brand new MediaSource. As an alternative, you ask the PreloadManager for the one it has already ready. You possibly can retrieve the MediaSource from the Preload Supervisor utilizing the MediaItem.

If the retrieved merchandise from the PreloadManager is null, meaning the mediaItem is just not preloaded but or added to the PreloadMamager, so that you select to set the mediaItem instantly.

// When a media merchandise is about to display on the display screen
val mediaSource = preloadManager.getMediaSource(mediaItem)
if (mediaSource!= null) {
  participant.setMediaSource(mediaSource)
} else {
  // If mediaSource is null, that mediaItem hasn't been added but.
  // So, ship it on to the participant.
  participant.setMediaItem(mediaItem)
}
participant.put together()
// When the media merchandise is displaying on the heart of the display screen
participant.play()

By getting ready the MediaSource retrieved from the PreloadManager, you seamlessly transition from preloading to playback, utilizing the information that is already in reminiscence. That is what makes the beginning time sooner.

3. Preserve the present index in sync with the UI

Since our feed / checklist might be dynamic, it is essential to inform the PreloadManager of your present enjoying index in order that it will possibly all the time prioritize gadgets nearest to your present index for preloading.

preloadManager.setCurrentPlayingIndex(currentIndex)
// Must name invalidate() to replace the priorities
preloadManager.invalidate()

4. Take away an Merchandise

To maintain the supervisor environment friendly, it’s best to take away gadgets it not wants to trace, resembling gadgets which can be far-off from the consumer’s present place.

// When an merchandise is just too removed from the present enjoying index
preloadManager.take away(mediaItem)

If you should clear all gadgets directly, you’ll be able to name preloadManager.reset().

5. Launch the Supervisor

Whenever you not want the PreloadManager (e.g., when your UI is destroyed), you need to launch it to unlock its assets. A very good place to do that is the place you’re already releasing your Participant’s assets. It’s beneficial to launch the supervisor earlier than the participant because the participant can proceed to play should you do not want any extra preloading.

// In your Exercise's onDestroy() or Composable's onDispose
preloadManager.launch()

Demo time

Verify it reside in motion 👍

Within the demo under , we see the influence of PreloadManager on the suitable facet which has sooner load occasions, whereas the left facet exhibits the present expertise. It’s also possible to view the code pattern for the demo. (Bonus: It additionally shows startup latency for each video)

Jetpack Media3 API for fast loading of short videos [PreloadManager]

What’s Subsequent?

And that is a wrap for Half 1! You now have the instruments to construct a dynamic preloading system. You possibly can both use PreloadConfiguration to preload the following merchandise of a playlist in ExoPlayer or arrange a DefaultPreloadManager, add and take away gadgets on the fly, configure the goal preload standing, and accurately retrieve the preloaded content material for playback.

In Half 2, we’ll go deeper on the DefaultPreloadManager. We’ll discover how one can hear for preloading occasions, talk about greatest practices like utilizing a sliding window to keep away from reminiscence points, and peek underneath the hood at customized shared elements of ExoPlayer and DefaultPreloadManager.

Do you could have any suggestions to share? We’re keen to listen to from you.

Keep tuned, and go make your app sooner! 🚀