Note: this article is about THEOplayer 1.X.

Preloading involves loading parts of a video source before the video starts playing. When the video later starts playing, it can do this much faster because it has already downloaded some data. This can improve the user experience dramatically when you expect the user will want to play the video. On the other hand, when the video is less likely to be played, you can configure the player to not preload it and save bandwidth.

Preloading the current video

THEOplayer uses the preload attribute on the original <video> element to control preloading of the current video source, in line with the HTML5 specification. This attribute can be set to the following values:

Value Description
none Do not preload anything. The video is loaded only when an explicit load request is made, e.g. by clicking the 'play' button or by calling load() on the player instance.
metadata Preload the metadata of the video. For HLS streams, this translates to preloading the HLS manifest files. For static videos (e.g. MP4 files), this translates to preloading data from the start of the video in order to acquire e.g. the video's width and height and the initial video frames.
auto Preload enough data to allow for smooth initial playback. For HLS streams, this translates to preloading the HLS manifest files as well as a couple of media segments at the start of the stream. For static videos, this translates to preloading enough data from the start of the video.

Example: Configuring preload in HTML

<video controls preload="auto"

Example: Configuring preload in JavaScript

theoplayer.onReady = function () {
    var video = document.createElement("video");
    video.controls = "controls";
    video.preload = "auto";
    video.src = "//";

Playlist preloading

THEOplayer uses the same preload configuration for the current video to preload the next video in a playlist. When the player is nearing the end of the current video, it will automatically start preloading the next video.

Preload controller API

For more advanced control over which videos must be preloaded, THEOplayer provides a preload controller API. Using this API, you can provide one or more videos which should be preloaded when the currently playing video reaches its end.

Note that THEOplayer will always prefer downloading data for the currently playing video over downloading data for a preloading video. Only when the currently playing video has enough data to play to the end of the video, will the player start preloading other videos.

Interactive video experiences is one example use case for this functionality. In an interactive video, the user must choose between multiple options at the end of a video, with each option leading to a different video. The preload controller can be configured to start preloading all of these options, and load the chosen video when the user has made their choice.

Example: Preload suggested videos

In the example below, two suggested videos are scheduled for preloading along with a main video. When the main video ends, the user is presented the option to play one of the two suggested videos. When they click one of the buttons, the selected video is attached to the player along with its preloaded data and starts playing.

<video controls src="/path/to/main-video.m3u8"></video>
<div id="endscreen" style="display: none">
    <p>What video do you want to play next?</p>
    <button id="playA">A</button>
    <button id="playB">B</button>

theoplayer.onReady = function () {
    var player = theoplayer.player(0);
    var controller = theoplayer.controller(0, "PreloadController");

    // Schedule two videos to preload
    var preloadA = controller.schedule("/path/to/suggested-video-a.m3u8");
    var preloadB = controller.schedule({
        src : "/path/to/suggested-video-b.m3u8",
        startTime : 60,
        endTime : 90

    // Show end screen when the main video ends
    player.addEventListener("ended", function onEnded () {
        player.removeEventListener("ended", onEnded);
        document.querySelector("#endscreen").style.display = "block";
    // Load a preloaded video when the user clicks one of the buttons
    document.querySelector("#playA").addEventListener("click", function () {
    document.querySelector("#playB").addEventListener("click", function () {