]

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"
       src="//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"></video>

Example: Configuring preload in JavaScript

theoplayer.onReady = function () {
    var video = document.createElement("video");
    video.controls = "controls";
    video.preload = "auto";
    video.src = "//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8";
    document.body.appendChild(video);
    theoplayer(video);
};

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.

API: PreloadController

The preload controller can be requested from the global theoplayer variable using the controller method by passing "PreloadController" as the controller name. This controller has the following methods and properties:

Name Description
schedule(options | source | sources) Schedules a new video to be preloaded. This function takes as argument a preload options object (see below) and constructs a new PreloadItem with these options. The returned item can later be passed to unschedule or attach. Passing just a source URL string or an array of source URLs has the same effect as passing an options object with only the src property set.
unschedule(item) Removes a PreloadItem from the preload schedule. It will stop preloading and clear all of its preloaded data.
attach(item) Attaches the given PreloadItem to the parent player. If it has preloaded data, that data will be made available immediately to the player. Other data will be loaded by the player as usual.
item(index) Retrieves the scheduled PreloadItem object at the given index.
length Retrieves the number of scheduled PreloadItem objects.

API: preload options object

An options object to be passed to PreloadController.schedule() can have the following properties:

Property Description
src (required) The source of the media to preload. Can be a string for a single source URL, or an array of alternative source URLs.
targetBuffer The maximum amount of data to preload, expressed in number of seconds of media data. Only applicable for video-on-demand HLS streams. If not specified, a default amount is used which aims for smooth initial playback.
startTime The start time of the clipping window, in seconds.
endTime The end time of the clipping window, in seconds.
startFrame The start frame of the clipping window, in number of frames.
endFrame The end frame of the clipping window, in number of frames.

API: PreloadItem

A PreloadItem has the same properties as the options object from which it was constructed.

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>
</div>

<script>
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 () {
        controller.unschedule(preloadB);
        controller.attach(preloadA);
        player.play();
    });
    document.querySelector("#playB").addEventListener("click", function () {
        controller.unschedule(preloadA);
        controller.attach(preloadB);
        player.play();
    });
};
</script>