Player API - 1.X

API Introduction

The below methods can be called on a THEOplayer instance:

theoplayer.player(identifier);      

Where 'identifier' is either a sequence number (starting at 0), an HTML-id given to the <video>-tag to which the player was attached or the player instance itself.

Player API Methods

Method Description
addEventListener(eventName,listener) Adds the given event listener for the given event.
exitFullscreen() Exits full screen and returns to normal viewing mode.
load() Re-loads the video's information and, in case of a HLS VOD stream, the first fragments.
play() Starts playing the video.
pause() Pauses the currently playing video.
requestFullscreen() Initiates full screen when available. When no full screen support is available, full window playback will be used. Should be called through a click-handler.
removeEventListener(eventName,listener) Removes the given event listener for the given event.
setSource(sourceDescription) Changes the source to the given SourceDescription

Player API Properties

Property Description
aspectRatio Sets or returns if the aspect ratio must be modified. Can be set to "fill" or "original". "fill" means the video will be stretched to extend to the entire size of the video-element, "original" means the video can be letter boxed and will maintain the original aspect ratio.
audioTracks Returns an object that can be used to list and change the audio tracks available for the current stream.
autoplay Sets or returns if the video should automatically start playing on platforms which offer support for this.
buffered 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.
currentFrame Sets or returns the current frame number of the active video quality. Setting this value will seek to the given frame number if frameAccurateSeekEnabled is true.
currentMonotonicTime Sets or returns the current playback position in the video (in seconds) for a monotonic time scale. In case of a live stream, the start point of the available DVR content is marked as currentMonotonicTime 0. For Video on Demand, currentMonotonicTime and currentTime are equal.
currentProgramDateTime 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.
currentSrc Returns the manifest url for the current rendition.
currentTime Sets or returns the current playback position in the video (in seconds). In case of a live stream, the live-point is marked as currentTime 0, while the DVR window is indicated by a negative time.
duration Returns the length of the currently loaded video (in seconds) if available. In case of a DVR stream, the duration will be the negative number of seconds which is available in the DVR-window.
dvr Returns whether the current source contains DVR content.
element Returns the DOM element of the player.
ended Returns whether the video has ended or not.
endFrame Sets or returns the end frame of the clipping window, in number of frames of the active video quality. See endTime for the semantics of the end of the clipping window.
endTime Sets or returns the end time of the clipping window, in seconds. The player will prevent playing or seeking to a time after this end time, and will end the video when playback reaches this end time. Defaults to +Infinity (no end clipping).
error Returns an object representing the error state of the video.
frameAccurateSeekEnabled Returns true if frame accurate seeking is currently possible in the video.
frameRate Returns the number of frames per second of the active video quality.
fullscreenEnabled Returns true if the player has been set to full screen or full window mode.
height Sets or returns the height of the player in pixels. Height can be set using % orauto as well.
initialized Returns true if the player has been initialized or not. If the player has not been initialized, certain functionality might not be available.
live Returns true if the current source contains live content.
loop Sets or returns whether the video should loop.
muted Sets or returns whether the audio output of the video is muted or not.
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.
paused Returns whether the video is paused or not.
playbackRate Sets or returns the current media playback rate. Playback rates should be positive numbers.
played Returns a TimeRanges object containing the ranges of the media that has already been played (seen) by the user. A played range is a time-range of played media.
poster Sets or returns the content poster.
seeking Returns whether the user is currently seeking in the video.
src Sets or returns the current source of the video.
startFrame Sets or returns the start frame of the clipping window, in number of frames of the active video quality. See startTime for the semantics of the start of the clipping window.
startTime Sets or returns the start time of the clipping window, in seconds. The player will prevent playing or seeking to a time before this start time, and by default will start playing at the clipping window start time. Defaults to -Infinity (no start clipping).
videoHeight Returns the height of the video in pixels for the current quality.
videoWidth Returns the width of the video in pixels for the current quality.
videoTracks Returns an object that can be used to list and change the video tracks available for the current stream and the available qualities for each track.
volume Sets or returns the volume of the video.
warning Returns the last playback warning.
width Sets or returns the width of the player in pixels. Width can be set using % or auto as well.

Player API Events

Event Description
canplay Fires when the player can start playing.
canplaythrough Fires when the player can probably play through the video without stopping for buffering.
durationchange Fires when the duration of the video changed.
ended Fires when the current video ended.
error Fires when an error occurred during the loading or playback.
fullscreenchange Fires when the player enters or exits full screen mode.
initialized Fires when the player has been initialized. When the player has not yet initialized, certain functionality might not be available.
loadeddata Fires when the player has loaded the media data for the first frame of the video.
loadedmetadata Fires when the player has loaded meta data (manifest) for the video.
loadstart Fires when the player starts downloading the video data.
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.
pause Fires when the video has been paused.
play Fires when the video has been started or is no longer paused.
playing Fires when the video is ready to play after having been paused or stopped for buffering.
seeked Fires when the user is finished moving/skipping to a new position in the video.
seeking Fires when the user is moving/skipping to a new position in the video.
stalled Fires when the browser is trying to get media data, but data is not available.
timeupdate Fires when the current playback position has changed.
unsupportedPlatform Fires when the player could not be loaded on the current browser platform.
volumechange Fires when the volume has been changed.
waiting Fires when the video stops because it needs to buffer the next frame.

SourceDescription

Property Type Optional Description
configuration SourceConfiguration yes Optional source configuration object which can be used to configure ads, clipping and other stream specific parameters.
mutedAutoplay 'none' OR 'all' yes

Returns or sets whether the player should activate muted autoplay. Default is set to 'none'.

  • 'none' : disallow muted autoplay. If the player is requested to autoplay while unmuted, and the platform does not support unmuted autoplay, the player will not start playback.
  • 'all' : allow muted autoplay. If the player is requested to autoplay while unmuted, and the platform supports muted autoplay, the player will start muted playback.
sources string OR string[] OR TypedSource OR TypedSource[] no The sources which should be played. Can be a string or typed source containing src and type attributes, or an array hereof.
textTracks TextTrackDescription[] yes Optional array containing native TextTrack descriptions, formatted in the HTML5 <track>-format. (default, kind, src, srclang, label)

TypedSource

Property Type Optional Description
src string no Specifies the URL of the media file.
type string no Specifies the media type of the media resource.

TextTrackDescription

Property Type Optional Description
default boolean yes This attribute indicates that the track should be enabled unless the user's preferences indicate that another track is more appropriate. This may only be used on one track element per media element.
id string yes The id of the TextTrack.
kind 'subtitles' OR 'captions' OR 'descriptions' OR 'chapters' OR 'metadata' yes How the text track is meant to be used. If omitted the default kind is subtitles. If the attribute is not present, it will use the subtitles. If the attribute contains an invalid value, it will use metadata.
label string yes A user-readable title of the text track which is used by the player when listing available text tracks.
src string no Address of the track (.vtt file). Must be a valid URL. This attribute must be defined.
srclang string yes Language of the track text data. It must be a valid BCP 47 language tag. If the kind attribute is set to subtitles, then srclang must be defined.