Controllers - Preloading Controller

The Preloading 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.


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.
textTracks (since 1.6.115) An array of TextTrackDescriptions for sideloading additional text tracks.


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

Additionally, a PreloadItem also supports the following property:

Property Description
online Returns whether or not one of the available stream sources is online. When this property changes, an online or offline event will be thrown.

PreloadItem Events

A PreloadItem supports the following events:

Event Description
offline Fires when the player detects all of the potential streaming sources are offline.
online Fires when the player detects a streaming source comes online after being offline.