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

> ## 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 ); } ``` |