Player API details

Further customize your THEOlive player through API

A basic player API is made available in the THEOlive NPM player:


mutedbooleanGet or set whether the audio is muted.
pausedbooleanReturns whether the player is paused.
volumenumberGet or set the current volume percentage as a floating point value between 0 and 1. (Not supported on iOS safari due to browser restrictions)
presentationPresentation | undefinedReturns the Presentation API. This value is undefined when using the version without UI.
badNetworkModebooleanGet whether the player is in bad network mode. Setting this value to true enters bad network mode, setting it to false exits it.
videoTracksMediaTrackListGet the video tracks of the stream. (This list will always contain either no video tracks or exactly one)


play(): voidStart or resume playback.
pause(): voidPause playback.
destroy(): voidDestroy the player. This stops playback and releases all resources associated with this player.
channelId: string,
config?: LoadConfiguration
): Promise
Load a channel.
channelId: The id of the channel to load.
config: The configuration for loading the channel. (available from v3.1.0) This will always result in either a channelloaded or a channeloffline event.
preloadChannels(channelIds: string[]): PromiseFetch the metadata of a list of THEOlive channels. This API method is used for smooth zapping so all channel metadata is loaded up front.
addEventListener(type: string, listener: (event: Event) => void)Add a event listener for the given event type.
removeEventListener(type: string, listener: (event: Event) => void)Remove a previously registered event listener.


Event nameDescription
playFired when the player is no longer paused, when play() is called or autoplay is enabled.
pauseFired when the player is paused, when pause() is called.
playingFired when the player is not paused and starts progressing playback, so initially when the player starts or when the player recovers from a stall.
waitingFired when the player is not paused but stops progressing, when the buffer is empty.
volumechangeFired when either the volume or the muted property changes. (Not supported on iOS safari due to browser restrictions)
channelloadedFired when the player has loaded a channel.
channelofflineFired when the player tried to load a channel but it wasn't able to start playback. Common use cases are that the channel is still starting up or it isn't receiving any ingest. As the player automatically retries to load the channel, this event might be fired periodically.
intenttofallbackFired when the player notices its channel is not in a healthy state. When a fallback channel is configured, the player will automatically fallback to that channel. Expert users can listen to this event to have full control over how to fallback to an alternative.
errorFired when the player enters a state from which it cannot recover without a new loadChannel call.
enterbadnetworkmodeFired when the player enters bad network mode.
exitbadnetworkmodeFired when the player exits bad network mode.
adbeginFired when an ad begins.
adendFired when an ad ends.
adbreakbeginFired when an ad break begins.
adbreakendFired when an ad break ends.
adskipFired when an ad is skipped.
aderrorFired when an ad errors.

Presentation API

Property / MethodReturn typeDescription
currentMode'fullscreen' | 'inline'Returns the current presentation mode.
requestMode(mode)voidSet the mode to 'fullscreen' or 'inline'.
supportsMode(mode)booleanReturns whether the current platform supports the given mode.


PropertyReturn typeDescription
adsConfiguration (optional)AdsConfigurationThe pre-roll ad configuration.


PropertyReturn typeDescription
adsAdDescription[]The list of ads to play before the stream loads.
blockContentIfAdError (optional)booleanWhether the player should be blocked when an ad-related error occurs.

Warning: A blocked player is not usable anymore


PropertyReturn typeDescription
sourcestringThe URL of the ad resource.
type (optional)'vast' | 'vmap' | 'adrule'The type of ad resource.

MediaTrackList events

addtrackFired when a new track is added to the track list.
removetrackFired when a track was removed from the track list.


idstringAn id identifying the track
uidnumberA uuid identifying the track
activeQualityQualityThe currently playing quality
qualitiesQuality[]All qualities in this track


idstringAn id identifying this quality
uuidnumberA uuid identifying this quality
bandwidthnumberThe peak bandwidth needed to play this quality as defined in the HESP manifest
averageBandwidthnumber | undefinedThe average bandwidth needed to play this quality as defined in the HESP manifest