SourceDescription API

The SourceDescription interface is used to describe a configuration of a source for a THEOplayer instance.

Properties

The SourceDescription object provides the following methods:

Property Type Optional Description
ads AdDescription[] yes The ads property can be used to add an array of AdDescriptions to the player. All valid and supported advertisement files will be cued for playback in the player. Each ad in the array should be described as an AdDescription.
analytics  AnalyticsDescription[] yes The analyticcs property can be used to add an array of AnalyticsDescriptions to the player. All valid and supported descriptions will enable the related pre-integration. Each configuration in the array should be described as an AnalyticsDescription.
blockContentIfAdError boolean yes Block the player if there was an issue playing the ads (mostly by an adblocker). Defaults to false.
initialRendition string yes Sets the starting rendition of the player. Possible values are 'default', 'high', 'low' and 'first'. This rendition is active until the Adaptive Bitrate algorithm has gathered sufficient data to control the rendition behaviour. high will pick the highest bitrate available, low will pick the lowest available bitrate, first will pick the first bitrate listed in the manifest, default uses the browser/device default starting rendition.
metadata MetadataDescription yes Metadata that can be used to describe content, e.g. when casting to chromecast or caching the data. Added in 2.21.0.
poster string yes The poster property can be used to specify a content poster per source. The player's content poster will be updated as soon as a new source with valid poster is set, or when the player's own poster property is altered.
sources TypedSource OR TypedSource[] no The sources property can either be a string, an array of strings, a TypedSource or an array of TypedSources. A single string represents the source of the manifest to be played. When this property is an array of strings, the first element of the array will initially be used as the player’s source. When that source is unavailable, the player will fall back to the other elements of this array.
textTracks TextTrackDescription[] yes The textTracks property can be used to add an array of side-loaded text tracks to the player. All valid tracks will be available for playback as long as the player’s source is not set again. Each text track should be described as a TextTrackDescription.
vr VRConfiguration yes The vr property can be used to configure virtual reality (VR) content.

TypedSource

The TypedSource object provides the following properties:

Method Type Optional Version Description
abr ABRConfiguration yes ≥2.17 This optional property can be used to specify an integration, along with credentials and modes such as QBR qualit or bitsave that can be applied on a stream.
crossOrigin string yes ≥2.9 This optional property can be used to configure the cross-origin requests for this source.
Values are "" (empty string), "anonymous" or "use-credentials". Default is "".
contentProtection ContentProtectionDescription yes ≥ 2.15 This optional property can be used to specify required DRM parameters for a playback source. Information like the license acquisition URL, request headers and other vendor-specific parameters are wrapped in an object implementing the ContentProtectionDescription interface.
drm DEPRECATED ContentProtectionDescription yes ≥ 2.7 - 2.14 This optional property can be used to specify required DRM parameters for a playback source. Information like the license acquisition URL, request headers and other vendor-specific parameters are wrapped in an object implementing the ContentProtectionDescription interface.
src string no ≥ 2.4 The ‘src’ property represents the source URL of the manifest or video file to be played. 
ssai ServerSideAdInsertionConfiguration yes ≥ 2.12 This optional property can be used to specify required Server-Side Ad Injection parameters for a playback source. Parameters used to configure the player to optimally play streams with server-inserted ads from specific SSAI vendors are wrapped in an object implementing the ServerSideAdInsertionConfiguration interface.
type string no ≥ 2.4 Specifies the content type (MIME type) of the source being played. 'application/dash+xml' indicates MPEG-DASH, 'application/x-mpegURL' or 'application/vnd.apple.mpegurl' indicates HLS. Other formats (such as 'video/mp4' or 'video/webm') will use native HTML5 playback if supported by the browser.

AdDescription

The AdDescription object can be of type THEOplayerAdDescription, GoogleIMAAdDescription or SpotXAdDescription:

THEOplayerAdDescription

The THEOplayerAdDescription object provides the following properties:

Method Type Optional Description
sources string no The 'sources' property represents the source of the ad (VAST/VMAP). The player will download the content available at the URL and will schedule the specified advertisement(s). Currently, the player supports VAST and VMAP files. VPAID-support is currently only available via our google ima-integration (see below).
integration string yes To use the THEOplayer ad system, the integration property can be omitted or specified as 'theo'
timeOffset number | string yes

Specifies when an ad should be played in the content video.
Currently supports the following values: seconds (number, e.g. '15'), 'start', 'end', time stamps (string in the format HH:MM:SS or HH:MM:SS.mmm, e.g. 00:00:15) and percentages (string, e.g. '10%').
Note: only use this property for VAST-files. THEOplayer will ignore this value for VMAP-files, because they already have their own offset.

 

skipOffset number | string yes Specifies when an ad can be skipped.
Currently supports the following values: seconds (number, e.g. '15'), time stamp (string in the format HH:MM:SS.mmm, e.g. 00:00:15.000) and percentages (string, e.g. '10%').
This value overwrites the value specified in the VAST-files, unless the skipOffset would be higher than the duration of the ad video (e.g. 110%).
Note: this is not yet supported for our Google IMA integration.

GoogleIMAAdDescription

The GoogleIMAAdDescription object provides the following properties:

Method Type Optional Description
sources string no The 'sources' property represents the source of the ad (VAST/VMAP). The player will download the content available at the URL and will schedule the specified advertisement(s). Currently, the player supports VAST and VMAP files. VPAID-support is currently only available via our google ima-integration.
integration string yes Use the value 'google-ima' to use the Google IMA ad integration.
To use the integration of Google IMA, it is required to load the SDK first. You can find the getting started of Google IMA sdk at: https://developers.google.com/interactive-media-ads/docs/sdks/html5/quickstart
timeOffset number | string yes

Specifies when an ad should be played in the content video.
Currently supports the following values: seconds (number, e.g. '15'), 'start', 'end', time stamps (string in the format HH:MM:SS or HH:MM:SS.mmm, e.g. 00:00:15) and percentages (string, e.g. '10%').
Note: only use this property for VAST-files. THEOplayer will ignore this value for VMAP-files, because they already have their own offset.

As per version 2.18.0, we support numbers for our IMA ad integration. As per version 2.21.0, we support the other formats.


SpotXAdDescription (≥ 2.13)

The SpotXAdDescription object provides the following properties:

Method Type Optional Description
integration string yes Use the value 'spotx' to use the SpotX ad integration. The SpotX integration uses Google IMA. To use Google IMA, it is required to load the SDK first. You can find the getting started of Google IMA sdk at: https://developers.google.com/interactive-media-ads/docs/sdks/html5/quickstart
id number | string no Your SpotX id
cacheBuster boolean yes Add the cb parameter with a random number to the SpotX tag
maximumAdDuration number | string yes Add the VMaxd parameter with a duration to the SpotX tag
custom SpotXData yes SpotX custom data
app SpotXData yes SpotX app data
device SpotXData yes SpotX device data
user SpotXData yes SpotX user data
sources string yes SpotX ad tag (to directly set the SpotX source link)

Example

player.source = {
    sources: ...,
    ads: [{   
        integration: 'spotx',
        id: 123456,
        cacheBuster: true,
        app: {
            bundle: 'com.exampleapps.example',
            name: 'My CTV App'
        },
        device: {
            ifa: '38400000-8cf0-11bd-b23e-10b96e40000d',
            ua: 'Mozilla/5.0 (iPhone; CPU iPhone OS 10_3 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) CriOS/56.0.2924.75 Mobile/14E5239e Safari/602.1',
            geo: {
                lat: -24.378528,
                lon: -128.325119
            },
            dnt: 1,
            lmt: 1,
        },
custom: {
category: ['category1', 'category2'],
somekey: 'somevalue'
}         user: {             yob: 1984,             gender: 'm'         }     } ]};


SpotXData (≥ 2.13)

The SpotXDataobject is an object which can contain SpotX specific properties:

A detailed overview of these properties can be found here:

https://www.spotx.tv/resources/downloads/downloadable-resources/platform-api-doc/
https://www.spotx.tv/resources/downloads/downloadable-resources/mobile-integration-docs/

 

MetadataDescription (≥ 2.21)

A MetaDataDescription can in general contain string value pairs with any kind of values. Otherwise it can be a ChromecastMetadataDescription.

ChromecastMetadataDescription (≥ 2.21)

 A ChromecastMetadataDescription consists of:

Property Type Optional Description
images string[] | ChromecastMetaDataImage[]  yes The images property can either be an array of strings representing the image urls, or an array of ChromecastMetadataImages.
releaseDate string yes The release date using the following string format: "YYYY-MM-DD", e.g. "2017-03-14"
title string yes The title of this content
subtitle string yes The subtitle / short explanation about the content
type string yes The type is one of the following options:
  • "movie"
  • "audio"
  • "tv-show"
  • "generic"
Defaults to "generic" if unset

ChromecastMetaDataImage (≥ 2.21)

 A ChromecastMetaDataImage consists of:

Property Type Optional Description
height number no The height of the image
src string no The URL to the metadata image
width number no The width of the image

in the following format:

  • src: string
  • width: number
  • height: number


ContentProtectionDescription

The ContentProtectionDescription object provides a set of content protection parameters for integration with content protection services of a given flavor. Currently, PlayReady and Widevine are supported.

Properties

The ContentProtectionDescription object has the following properties

Method Type Optional Description
clearkey LicenseAcquisitionDescription yes Optionally specifies license parameters for integration with a Clearkey license.
fairplay FairPlayLicenseAcquisitionDescription yes  Optionally specifies license acquisition parameters for integration with a FairPlay license server. 
playready LicenseAcquisitionDescription yes Optionally specifies license acquisition parameters for integration with a PlayReady license server.
widevine WidevineLicenseAcquisitionDescription yes Optionally specifies license acquisition parameters for integration with a WideVine license server.
aes128 AES128Description yes Optionally specifies parameters for integration with an AES-128 system.

LicenseAcquisitionDescription

The LicenseAcquisitionDescription object contains data that is to be used during the licensing process with a given DRM server.

Properties

The LicenseAcquisitionDescription object has the following properties

Method Type Optional Description
headers {[string] : string} yes Optionally specifies request headers that should be sent with any license requests to the DRM server. This is a plain object where the keys of the object are header names and corresponding values are header values.
keys DecryptionKey[] yes Species the decryption keys (only available for clearkey).
licenseAcquisitionURL string no Specifies the URL of the licensing server.
useCredentials boolean yes Optionally indicates whether the XMLHttpRequest.withCredentials flag should be enabled to allow the player to make cross-site Access-Control requests using credentials like cookies, authorization headers or TLS client certificates. Defaults to false.

FairPlayLicenseAcquisitionDescription

The FairPlayLicenseAcquisitionDescription object contains the same data as the LicenseAcquisitionDescription object with the addition of a certificate or the URL for the certificate server required to use FairPlay DRM.

Properties

The FairPlayLicenseAcquisitionDescription object has the following properties.

Property Type Optional Version Description
certificate string or UInt8Array yes ≥ 2.16 Specifies a base64-encoded UintArray or actual Uint8Array which contains the Fairplay certificate. Can replace the certificateURL (see below).
certificateURL string no ≥ 2.6 Specified the URL of the FairPlay certificate server. Can be replaced by an actual certificate (see above).
headers {[string] : string} yes ≥ 2.6 See LicenseAcquisitionDescription.
licenseAcquisitionURL string no ≥ 2.6 See LicenseAcquisitionDescription.
useCredentials boolean yes ≥ 2.6 See LicenseAcquisitionDescription.

WidevineLicenseAcquisitionDescription

The WidevineLicenseAcquisitionDescription object contains the same data as the LicenseAcquisitionDescription object with the addition of an optional certificate required to use Widevine DRM on e.g. Google Chrome.

Properties

The WidevineLicenseAcquisitionDescription object has the following properties.

Property Type Optional Version Description
certificate string or ArrayBuffer yes ≥ 2.17 Specifies a base64-encoded ArrayBuffer or actual ArrayBuffer which contains the Widevine certificate.
headers {[string] : string} yes ≥ 2.6 See LicenseAcquisitionDescription.
licenseAcquisitionURL string no ≥ 2.6 See LicenseAcquisitionDescription.
useCredentials boolean yes ≥ 2.6 See LicenseAcquisitionDescription.

AES128Description

The AES128Description object contains the property to indicate if credentials should be used when loading AES-128 keys, or not.

Properties

The AES128Description object has the following properties.

Property Type Optional Description
useCredentials boolean yes Specified if credentials should be sent when retrieving the decryption key.

DecryptionKey

An object implementing the DecryptionKey interface contains a decryption key (only available for clearkey).

Properties

The DecryptionKey object provides the following properties: 

Method Type Optional Description
id string no Specifies the key id (kid).
value string no Specifies the key (k).

ABRConfiguration (≥ 2.17)

An object implementing the ABRConfiguration interface specifies information on mediamelon credentials and QBR related information. For more information check the MediaMelon pre-integration API.

Properties

The MediaMelonConfiguration object provides the following properties:

Property Type Optional Version Description
integration string yes ≥ 2.12 Specifies an identifier for a supported MediaMelon integration. Check the MediaMelon pre-integration API for more information.

TextTrackDescription

An object implementing the TextTrackDescription interface contains a description of a side-loaded text track that will be added to the player.

Properties

The TextTrackDescription object provides the following properties:

Method Type Optional Description
default boolean yes This attribute indicates that the track should be enabled. This may only be used on one track element per media element.
kind string yes Optionally specifies a kind for the track which indicates how the player should interpret the track. The following kinds are available:
  • 'subtitles': The track defines subtitles, used to display subtitles in a video.
  • 'captions': The track defines translation of dialogue and sound effects. (suitable for deaf users)
  • 'descriptions': The track defines a textual description of the video. (suitable for blind users)
  • 'chapters': The track defines chapter titles. (suitable for navigating the media resource)
  • 'metadata': The track defines content used by scripts. Not visible for the user.

If not specified, the player will default to 'subtitles'. If not recognized, the player will interpret as 'metadata'.

label string yes Optionally specifies a label for the track which can be used to identify it.
src string no Specifies a source URL where the text track can be downloaded from.
srclang string no Specifies the main language of the track.

ServerSideAdInsertionConfiguration (≥ 2.12)

An object implementing the ServerSideAdInsertionConfiguration interface specifies information to play a stream with server-inserted ads. To integrate with specific SSAI vendors, check the Server-Side Ad Insertion pre-integration API.

Properties

The ServerSideAdInsertionConfiguration object provides the following properties:

Property Type Optional Version Description
integration string yes ≥ 2.12 Specifies an identifier for a supported SSAI integration. Check the Server-Side Ad Insertion pre-integration API for more information.

VRConfiguration (≥ 2.12)

An object implementing the VRConfiguration interface specifies information to play a stream with virtual reality (VR) content. To interact with the VR-enabled playback, check the 360° Video and Virtual Reality API.

Properties

The VRConfiguration object provides the following properties:

Property Type Optional Version Description
360 boolean yes ≥ 2.12 Specifies whether this source contains 360° video content.
stereoMode string yes ≥ 2.12 If set, specifies that this source contains stereoscopic video content. The following values are supported:
  • 'horizontal': The two viewpoints are in a side-by-side layout. The view for the left eye is in the left half of the video frame, the view for the right eye is in the right half of the video frame.
  • 'vertical': The two viewpoints are in a top-bottom layout. The view for the left eye is in the upper half of the video frame, the view for the right eye is in the lower half of the video frame.