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
|
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:
|
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 |