---
title: "Web Player SDK Events"
slug: "web-player-sdk-events"
tags: ["Timeshift"]
updated: 2026-03-02T16:01:13Z
published: 2026-03-02T16:01:13Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.tritondigital.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Player SDK Events

Below is a list of all events sent by the SDK.

| **Events** |
| --- |
| module: global SDK event:**player-ready** Callback when Web Player SDK is ready. All modules are loaded. |
| module: MediaPlayer event:**stream-start** Stream playback started. |
| module: MediaPlayer event:**stream-stop** Stream playback stopped. |
| module: MediaPlayer event:**stream-select** A stream mount point was selected. |
| module: MediaPlayer event:**stream-config-ready** The live stream configuration is ready. |
| module: MediaPlayer event:**stream-config-error** The live stream config parsing returns an error. |
| module: MediaPlayer event:**stream-config-load-error** The live stream config loading returns an error. |
| module: MediaPlayer event:**stream-fail** Connection to the stream failed. |
| module: MediaPlayer event:**stream-error** A stream error has occurred event properties: text (String) The error text. |
| module: MediaPlayer event: **stream-status** Stream status information. event properties: - **status**(String) The status text message "Playback of media in the current context or situation is not allowed." Available in English, French, Spanish and Portuguese (depending the OS language). - **code**(String Status code, refer to the list below.) - **message**(String). Field for adding error or other event message. Here is the list of the status messages and their associated codes. The code can be used to display a message other than the default one provided in the 'status' property. \| **Code** \| **Status** \| \| --- \| --- \| \| LIVE_PAUSE \| Stopped \| \| LIVE_PLAYING \| On Air \| \| LIVE_STOP \| Disconnected \| \| LIVE_FAILED \| Stream unavailable \| \| LIVE_BUFFERING \| Buffering... \| \| LIVE_CONNECTING \| Live stream connection in progress... \| \| LIVE_RECONNECTING \| Will reconnect live stream in x seconds \| \| HLS_STREAM_GEOBLOCKED \| Sorry, this content is not available in your area \| \| STATION_NOT_FOUND \| Station not found \| \| PLAY_NOT_ALLOWED \| Playback of media in the current context or situation is not allowed \| **Note:** when a live stream is geo-blocked, `LIVE_FAILED` is received. When an HLS stream is geo-blocked, `HLS_STREAM_GEOBLOCKED` is received. |
| **Code** | **Status** |
| LIVE_PAUSE | Stopped |
| LIVE_PLAYING | On Air |
| LIVE_STOP | Disconnected |
| LIVE_FAILED | Stream unavailable |
| LIVE_BUFFERING | Buffering... |
| LIVE_CONNECTING | Live stream connection in progress... |
| LIVE_RECONNECTING | Will reconnect live stream in x seconds |
| HLS_STREAM_GEOBLOCKED | Sorry, this content is not available in your area |
| STATION_NOT_FOUND | Station not found |
| PLAY_NOT_ALLOWED | Playback of media in the current context or situation is not allowed |
| module: MediaPlayer event:**track-cue-point** A new track cue point was received in the stream. event data properties: - **cuePoint**(Object) - The properties of the cuePoint object are: - **cueTitle**(String) - The title of the song - **artistName**(String) - The artist name - **albumName**(String) - The album name - **parameters**(Object) - The original parameters list sent by the cue point. Example (JavaScript): ```javascript /** Attach an addEventListener to the TD Web Player SDK instance **/ player.addEventListener( 'track-cue-point', onTrackCuePoint ); function onTrackCuePoint( event ) { var cueTitle = event data.cuePoint.cueTitle; } ``` |
| module: MediaPlayer event:**custom-cue-point** A new custom cue point was received in the stream. event data properties: - **cuePoint**(Object) containing the custom properties. - **parameters**(Object) - The original parameters list sent by the cue point. |
| module: MediaPlayer event:**speech-cue-point** A new speech cue point was received in the stream. event data properties: - **cuePoint**(Object) - The properties of the cuePoint object are: - **cueTitle**(String) - The title of the song - **artistName**(String) - The artist name for the song - **parameters**(Object) - The original parameters list sent by the cue point. For other parameters available within this cuepoint, please refer to the *STWCue Metadata Dictionary*. |
| module: MediaPlayer event:**hls-cue-point** A new HLS cue point has been received in the stream (**iOS only**). event data properties: - **cuePoint**(Object) - The properties of the cuePoint object are: - **hls_track_id**(String) - Track ID of the following segment. - **hls_segment_id**(String) - Segment ID of the following segment. |
| module: MediaPlayer event:**timeout-alert** TimeOut Connection Alert: stream will stop in 30 seconds. Please refer to the**play()**function documentation (parameter**connectionTimeOut**) . |
| module: MediaPlayer event:**timeout-reach** TimeOut Reached (the user did not click on the previous TimeOut Alert Message). At this time, the stream was automatically stopped by the Player SDK. |
| module: MediaPlayer event:**targetspot-cue-point** A new TargetSpot cue point was received in the stream. event properties: **duration**: duration of the TargetSpot Ad Break, in milliseconds |
| module: MediaPlayer event:**timeshift-info** Provides general information about the HLS stream. Embed the code snippet described under [Event Listener](/v1/docs/using-timeshift-radio#event-listener) to subscribe to the information. event properties: **totalDuration**: duration of the Timeshift session, in milliseconds |
| module: MediaPlayer event:**ad-break-cue-point** A new Ad Break cue point was received in the stream. event properties: - **adBreakData**(Object) - The properties of the adBreakData object are: - **url**(String) - The url of the synchronized banner - **duration**(Integer) - The duration of the Ad Break - **cueTitle**(String) - The title of the Ad Break - **adVast**(String) - Ad VAST response. - **vastUrl**(String) - URL to get the VAST. - **duration**(String) - Ad duration |
| module: MediaPlayer event:**ad-break-cue-point-complete** The current Ad break is finished. |
| module: MediaPlayer event:**ad-playback-start** Ad Playback: Every time an audio/video ad starts playing, this event is fired. event properties: **type**(String) - The Ad Server Type (i.e.**vastAd**when VAST Ad Server was used). |
| module: MediaPlayer event:**ad-blocker-detected** Event fired when an ad blocker is enabled on client-side. event properties: message (String) - The Ad blocker message. |
| module: MediaPlayer event:**ad-playback-complete** Ad Playback: Every time an audio/video ad playback is complete, this event is fired. This is where you should call the**play()**function to play the Live Stream. event properties: **type**(String) - The Ad Server Type (i.e.**vastAd**when VAST Ad Server was used). |
| module: MediaPlayer event:**ad-playback-error** Ad Playback: Every time an audio/video ad playback returns an error (i.e. the ad did not play), this event is fired. This is where you should call the**play()**function to play the Live Stream. |
| module: MediaPlayer event:**ad-countdown** Ad CountDown: Event is fired when an audio/video ad is playing, allowing you to display a count down message (i.e., Advertisement: The stream will start in xx second(s) ) event properties: - **countDown**(Integer) - The value in seconds before the end of the ad. |
| module: MediaPlayer event:**ad-quartile** Ad Quartile. Event is fired on every quartile, when an audio/video ad is playing. event properties: - **type**(String) - The possible values for type are: - **start**(ad playback start = 0%) - **firstQuartile**(25 %) - **midpoint**(50 %) - **thirdQuartile**(75 %) - **complete**(100%) |
| module: MediaPlayer event:**vpaid-ad-companions** VPAID campaign: when a VPAID campaign contains ad companions, this event is fired. Listen to this event to display the VPAID ad companions in the page. event properties: - **companions**(Array) - Array of VAST companion ads |
| module: MediaPlayer event:**configuration-error** Configuration Error - Event error is fired because the JSON data object sent to the library is invalid. Please verify if the JSON data object is correct. |
| module: MediaPlayer event:**stream-geo-blocked** Stream is Geo-blocked. Event is fired when the call to the provisioning server returns a Stream Geo Blocked status. Connection to the stream will not be possible. A message should be displayed to the user, such as: "Sorry, the stream is not available in your area". |
| module: MediaPlayer event:**video-mid-roll-playback-start** Video Mid Roll Ad Playback: Every time a video mid-roll ad playback starts playing, this event is fired. |
| module: MediaPlayer event:**video-mid-roll-playback-complete** Video Mid Roll Ad Playback: Every time a video mid-roll ad playback is complete, this event is fired. |
| module: SyncBanners event:**ad-break-synced-element** An ad break banner is available in the ad break cue-point and will be automatically loaded and displayed in its HTML div element in the page. event properties: - **type**(String) - The synced banner type. Possible values: legacy or VAST. - **id**(String) - The HTML banner ID, as defined in the "elements" property of the SyncBanners module. - **data**(Object) - Defined only if type is VAST. Contains the VAST object property of the banner. - **url**(String) - Defined only if type is legacy. Contains the synced banner URL. |
| module: NowPlayingApi event:**list-loaded** Now Playing History loaded. Event is fired when now playing history data has been loaded and is available. event properties: - **data**(Object) - List of Now playing data (track, ad, speech) ```javascript /** Attach an addEventListener to the TD Web Player SDK instance **/ player.addEventListener( 'list-loaded', onListLoaded ); function onListLoaded( e ) { console.log( 'tdplayer::onListLoaded' ); console.log( e.data ); $.each( e.data.list, function(index, item){ console.log('Artist : ' + item.artistName ); console.log('Title : ' + item.cueTitle ); console.log('Time : ' + item.cueTimeStart ); } ); } ``` |
| module: NowPlayingApi event:**list-empty** Now Playing History is empty (no data). Event is fired when now playing history data has been loaded and is empty. ```javascript /** TD Web Player SDK instance **/ var player = new TDSdk( tdPlayerConfig ); /** Attach an addEventListener to the TD Player SDK instance **/ player.addEventListener( 'list-empty', onListEmpty); function onListEmpty( e ) { console.log( 'tdplayer::onListEmpty' ); } ``` |
| module: NowPlayingApi event:**nowplaying-api-error** Now Playing API Error - Event is fired when now playing history data has not been retrieved due to en error. ```javascript /** TD Player SDK instance **/ var player = new TDSdk( tdPlayerConfig ); /** Attach an addEventListener to the TD Player SDK instance **/ player.addEventListener( 'nowplaying-api-error', onNowPlayingApiError); function onNowPlayingApiError( e ) { console.log( 'tdplayer::onNowPlayingApiError' + e ); } ``` |