API Introduction

THEOplayer provides the following constructor:

THEOplayer.Player(domElement : HTMLElement, playerConfiguration? : PlayerConfiguration)

? = argument is optional.

This method returns a new instance of the THEOplayer DASH player that will be initialized in the given HTMLElement.

The global THEOplayer variable also supports the version property, which contains the version of the player.

PlayerConfiguration

Property Type Description
libraryLocation string

This parameter should point to the directory where the THEOplayer library worker files (theoplayer.d.js, theoplayer.e.js, theoplayer.p.js) are located, e.g. '/js/theoplayer/'. This parameter is required when using a HLS source.

isEmbeddable boolean

This parameter should be set to true when you want to use THEOplayer in an iframe.

pip PiPConfiguration

An optional configuration for picture-in-picture (sticking the player in the corner of the screen):

  • position: (optional, possible values: "top-left", "top-right", "bottom-left", "bottom-right")
    The corner in which the player should be shown while in picture-in-picture. Defaults to the bottom right corner.
  • visibility: (optional, a number from number 0 to 1)
    The maximum percentage of the original player position that should be visible to enable picture-in-picture automatically. If not configured, picture-in-picture can only be turned on by setting presentationMode to "picture-in-picture".

Properties

The player object provides the following properties:

Property Type Description
ads Ads An Ads object that contains information about the current and the scheduled advertisements.
audioTracks MediaTrackList A MediaTrackList object that contains all the audio tracks for the current source of the player instance.
autoplay boolean Gets or sets whether or not the player will automatically start playback of its source.
buffered TimeRanges Returns a TimeRanges object containing the ranges of the media that have been buffered by the player. A buffered range is a time-range of buffered media.
cast Cast A Cast object that provides information about the current casting state and allows you to control available casting integrations like Chromecast.
currentProgramDateTime Date Sets or returns the current program date time reference if Program Date Time information is embedded in the playback manifest. Setting the property will seek to the playback position with this timestamp.
currentTime number Sets or returns the current playback position in the video (in seconds).
duration number The duration of the current source in seconds.
ended boolean Indicates whether or not playback has reached the end of the current source.
error MediaError The last encountered player error.
muted boolean True if the player has its audio playback muted.
paused boolean True if the player is currently paused.
playbackRate number The current playback rate of the player. 1 referring to normal speed.
played TimeRanges The played TimeRanges of the player.
poster string Sets or returns the content poster URL. Setting the property to the empty string clears the current poster.
preload 'none' OR 'metadata' OR 'auto' Returns or sets whether the player should preload a certain type of data. Default is set to 'none'.
  • 'none' : After setting the source, the player will not load the manifest nor any media files until the play method is invoked on the player.
  • 'metadata' : After setting the source, the player will automatically load the manifest file and will wait for loading media files until the play method is invoked on the player.
  • 'auto' : After setting the source, the player will load both the manifest files and enough media files until a sufficient playback buffer has been obtained.
presentationMode

'inline' | 'picture-in-picture' | 'fullscreen'

Returns or set the presentationMode of the player. Default is set to 'inline':

  • 'inline': the player will be shown at its original location.
  • 'picture-in-picture': the player will be shown in a corner of the page (also see the PlayerConfiguration for more options).
  • 'fullscreen': the player will play in fullscreen.
readyState number (0 - 4) Returns the readystate of the player.
  • 0 - HAVE_NOTHING : The player has no information about the duration of its source.
  • 1 - HAVE_METADATA : The player has information about the duration of its source.
  • 2 - HAVE_CURRENT_DATA : The player has its current frame in its buffer.
  • 3 - HAVE_FUTURE_DATA : The player has enough data for immediate playback.
  • 4 - HAVE_ENOUGH_DATA : The player has enough data for continuous playback.
seekable TimeRanges The seekable TimeRanges of the player.
seeking boolean True if the player is currently seeking to a new time in its seekable range.
source SourceDescription The current playback SourceDescription. Upon setting, the player applies the provided parameters in the source description. The new source description is an object that should be constructed by the user and which should implement the SourceDescription interface.
src string Sets or returns the current source of the video. Advised to use player.source instead.
textTracks TextTrackList A TextTrackList object that contains all the text tracks for the current source of the player instance.
videoHeight number Returns the current height of the active video rendition.
videoTracks MediaTracklist A MediaTrackList object that contains all the video tracks for the current source of the player instance.
videoWidth number Returns the current width of the active video rendition.
volume number (0-1) Returns or sets the current volume percentage as a floating point value between 0 and 1.
vr VR An VR object to access and control 360/VR playback.

Methods

The player object provides the following methods:

Method Arguments Description
addEventListener type : string, listener : EventListener Adds the given listener to the player instance for the given event type.
pause none After invoking this method, the player pauses playback.
play none After invoking this method, the player starts playback.
removeEventListener type : string, listener : EventListener Removes the given listener from the player instance for the given event type.
setSource SourceDescription After invoking this method, the player sets the provided playback source and applies the provided parameters in the source description. The source description is an object that should be constructed by the user and which should implement the SourceDescription interface.
stop none After invoking this method, the player stops playback completely and unloads all loaded resources.

Events

The player object exposes the following events:

Event Description
canplay Thrown to indicate that the player can now continue playback, usually after a 'waiting' event.
  • currentTime : The current time of the player.
  • readyState : 3 – HAVE_FUTURE_DATA.
  • type : 'canplay'.
canplaythrough Thrown to indicate that the player can now continue playback uninterrupted with a readyState property value of 4 – HAVE_ENOUGH_DATA.
  • currentTime : The current time of the player.
  • readyState : 4 – HAVE_ENOUGH_DATA.
  • type : 'canplaythrough'.
contentprotectionerror Thrown to indicate that an error occurred during handling of the content protection of the stream.
  • error : A message indicating the cause of the error.
  • licenseAcquisitionMessage : A message returned by the license acquisition server indicating the cause of the error.
  • licenseAcquisitionURL : The URL of the license acquisition server.
  • mediaTrackType : The type of the track on which an error occurred.
  • status : The HTTP response status of the license acquisition server.
  • statusText : Contains the status message corresponding to the status.
  • type : 'contentprotectionerror'.
contentprotectionsuccess Thrown to indicate that the player has successfully gone through all content protection steps.
  • mediaTrackType : The type of the track on which DRM was successful.
  • type : 'contentprotectionsuccess'.
encrypted Thrown to indicate that the player is waiting for the decryption of part of its media buffer.
  • currentTime : The current time of the player.
  • initData : The content decryption module initialization data.
  • initDataType : 'cenc'.
  • type : 'encrypted'.
ended Thrown when the players currentTime property has reached the end of the set source.
  • currentTime : The current time of the player.
  • type : 'ended'.
error Thrown to indicate that an error has occurred in the player.
  • error : A message indicating the cause of the error.
  • type : 'error'.
loadeddata Thrown the first time the readyState property goes from 1 – HAVE_METADATA – to 2 – HAVE_CURRENT_DATA.
  • currentTime : The current time of the player.
  • readyState : 2 – HAVE_CURRENT_DATA.
  • type : 'loadeddata'.
loadedmetadata Thrown the first time the readyState property goes from 0 – HAVE_NOTHING – to 1 – HAVE_METADATA.
  • currentTime : The current time of the player.
  • readyState : 1 – HAVE_METADATA.
  • type : 'loadedmetadata'.
pause Thrown when the pause method is invoked.
  • currentTime : The current time of the player.
  • type : 'pause'.
play Thrown when the play method is invoked.
  • currentTime : The current time of the player.
  • type : 'play'.
playing Thrown when the player starts with the playback of media.
  • currentTime : The current time of the player.
  • type : 'playing'.
presentationmodechange Thrown when the presentationMode has been changed. The new presentationMode can be retrieved via presentationMode.
progress Thrown when new media data is added to the buffer of the player.
  • currentTime : The current time of the player.
  • type : 'progress'.
ratechange Thrown when the playbackRate property of the player is set to a new value.
  • currentTime : The current time of the player.
  • playbackRate : The new rate of playback.
  • type : 'ratechange'.
readystatechange Thrown when the readyState property of the player changes to a new value.
  • currentTime : The current time of the player.
  • readyState : The new ready state of the player (0-4).
  • type : 'readystatechange'.
representationchange Thrown to indicate that the displayed representation has changed to a new value due to changes in the download speed.
  • type : 'representationchange'.
  • previousRepresentation : The old playback representation.
  • representation : The new playback representation.
seeked Thrown when the player has completed the setting of a new value to the currentTime property.
  • currentTime : The current time of the player.
  • type : 'seeked'.
seeking Thrown when the currentTime property of the player is set to a new value.
  • currentTime : The current time of the player.
  • type : 'seeking'.
segmentnotfound Thrown to indicate that a segment required for uninterrupted playback was not found. Occurs for example when watching a sliding window stream with insufficient bandwidth.
  • error : A message indicating the cause of the error.
  • retryCount : The amount of times that the player has tried to download the given segment.
  • segmentStartTime : The start time of the segment.
  • type : 'segmentnotfound'.
timeupdate Periodically thrown during playback to indicate that the currentTime property is changing to indicate the new playback position.
  • currentTime : The current time of the player.
  • type : 'timeupdate'.
volumechange Thrown when the volume property of the player is set to a new value.
  • currentTime : The current time of the player.
  • type : 'volumechange'.
  • volume : The new volume of the player (0-1).
waiting Thrown when the readyState of the player goes below a value of 3 – HAVE_ENOUGH_DATA.
  • currentTime : The current time of the player.
  • type : 'waiting'.