Cache API

Introduction

The caching API allows to store (parts of) a streaming source on the user's device.

Caching can happen prior to and independent from playback. During playback, a player will always consult the cache before attempting to download any manifest or segment. This enables API users to pre-cache (parts of) a given source, which can then be immediately played from cache during playback. This approach drastically reduces startup times, removes download delays and can serve as a guard for viewer experience over flaky connections.

As of THEOplayer 2.26, the global THEOplayer object exposes the Caching API, which can be accessed as: THEOplayer.cache

Example usage

// Create a task that will cache 30 seconds of content
var sourceDescription = {sources: '//cdn.theoplayer.com/video/elephants-dream/playlist.m3u8'};
var task = THEOplayer.cache.createTask(sourceDescription, {amount: 30});
 
// Retrieve an already existing task
task = THEOplayer.cache.tasks[0];

// Example of querying information
task.addEventListener('statechange', function() {
    if (task.status === 'done') {
        console.log('Caching completed! THEOplayer has ' + task.secondsCached + ' seconds of content cached');
    }
})

// Start caching
task.start();
 
// Evict cached content
task.remove();

API Definition

The cache provides the following properties:

Property	Type	Description
status	'uninitialised' | 'initialised'	Indicates the status of the cache uninitialised means that previously persisted tasks are not yet available initialised means that previously persisted tasks are available in the tasks property
tasks	CachingTask[]	The list of all caching tasks. The list should be regarded as read-only. To remove a task, invoke the remove method on the CachingTask object.

 The cache provides the following methods for storing and removing sources on a local device:

Method	Arguments	Description
createTask	source : SourceDescription, parameters : CachingParameters	Calling this method will provide a task which will be used to cache the provided source, abiding to the provided parameters.

 The cache exposes the following events (via addEventListener):

Event	Description
statechange	Thrown to indicate that the status of the cache has been changed

 

CachingParameters

A CachingParameters interface should have the following properties:

Property	Type	Required	Description
amount	number or string	yes	The amount of data to cache for the given stream. Can specify an amount in seconds (e.g. 20) or a percentage string (e.g. "50%").
expirationDate	Date	no	The expiration date for the cached data - has to be in the future. Data will remain in the cache until at least the provided date if enough disk space is available. The default expiration date is 30 minutes from the start of the caching task.

 CachingTask

The CachingTask has the following properties:

Property	Type	Description
status	'idle' | 'loading' | 'done' | 'error' | 'evicted'	The current status of this caching task: idle means that the task has been created, but has not started downloading content. loading means that the task is currently downloading the content done means that the task has finished downloading all content error means that the task has encountered an error while downloading or evicting content evicted means that all data associated with the task has been removed because the task expired or the user invoked the remove method
source	SourceDescription	The source description processed by this caching task.
parameters	CachingParameters	The parameters for this caching task. These parameters can not be modified after creating a task. Instead, a new task should be created with different parameters.
duration	number	The amount of content in seconds that will be available after this task has finished.
cached	TimeRanges	A TimeRanges object indicating which data has been currently cached.
secondsCached	number	The amount of content that has already been cached.
percentageCached	number	The percentage of content (between 0 and 1) that has already been cached.

The CachingTask provides the following methods:

Method	Arguments	Description
start		Start downloading the necessary streaming elements - like manifests and segments - and store them on your device. An element will only be cached if it is not yet present in the cache.
remove		Remove the task and try to evict all associated streaming elements. An element referenced by multiple tasks will only be evicted if all associated tasks are removed.

The CachingTask exposes the following events (via addEventListener):

Event	Description
statechange	Thrown to indicate that the status of the caching task has been changed
progress	Thrown to indicate that segments associated to the task have been added to the cache