API
Events

Events

This page shows the list of available callbacks to handle player notifications

Details

onAudioBecomingNoisy

Platforms: Android | iOS

Callback function that is called when the audio is about to become 'noisy' due to a change in audio outputs. Typically this is called when audio output is being switched from an external source like headphones back to the internal speaker. It's a good idea to pause the media when this happens so the speaker doesn't start blasting sound.

Payload: none

onAudioFocusChanged

Platform: Android

Callback function that is called when the audio focus changes. This is called when the audio focus is gained or lost. This is useful for determining if the media should be paused or not.

Payload:

PropertyTypeDescription
hasAudioFocusbooleanBoolean indicating whether the media has audio focus

Example:

{
  hasAudioFocus: true;
}

onAudioTracks

Platforms: Android | iOS

Callback function that is called when audio tracks change

Payload:

An array of

PropertyTypeDescription
indexnumberInternal track ID
titlestringDescriptive name for the track
languagestring2 letter ISO 639-1 code (opens in a new tab) representing the language
bitratenumberbitrate of track
typestringMime type of track
selectedbooleantrue if track is playing

Example:

{
  audioTracks: [
    { language: 'es', title: 'Spanish', type: 'audio/mpeg', index: 0, selected: true },
    { language: 'en', title: 'English', type: 'audio/mpeg', index: 1 }
  ];
}

onBandwidthUpdate

Platforms: Android | iOS

Callback function that is called when the available bandwidth changes.

Payload:

PropertyTypeDescription
bitratenumberThe estimated bitrate in bits/sec
widthnumberThe width of the video (android only)
heightnumberThe height of the video (android only)
trackIdstringThe track ID of the video track (android only)

Example on iOS:

{
  bitrate: 1000000;
}

Example on Android:

{
  bitrate: 1000000;
  width: 1920;
  height: 1080;
  trackId: 'some-track-id';
}

Note: On Android, you must set the reportBandwidth prop to enable this event. This is due to the high volume of events generated.

onBuffer

Platforms: Android | iOS

Callback function that is called when the player buffers.

Payload:

PropertyTypeDescription
isBufferingbooleanBoolean indicating whether buffering is active

Example:

{
  isBuffering: true;
}

onControlsVisibilityChange

Platform: Android

Callback function that is called when the controls are hidden or shown. Not possible on iOS.

Payload:

PropertyTypeDescription
isVisiblebooleanBoolean indicating whether controls are visible

Example:

{
  isVisible: true;
}

onEnd

Platforms: All

Callback function that is called when the player reaches the end of the media.

Payload: none

onError

Platforms: All

Callback function that is called when the player experiences a playback error.

Payload:

PropertyTypeDescription
errorobjectObject containing properties with information about the error

onExternalPlaybackChange

Platform: iOS

Callback function that is called when external playback mode for current playing video has changed. Mostly useful when connecting/disconnecting to Apple TV – it's called on connection/disconnection.

Payload:

PropertyTypeDescription
isExternalPlaybackActivebooleanBoolean indicating whether external playback mode is active

Example:

{
  isExternalPlaybackActive: true;
}

onFullscreenPlayerWillPresent

Platforms: Android | iOS | visionOS

Callback function that is called when the player is about to enter fullscreen mode.

Payload: none

onFullscreenPlayerDidPresent

Platforms: Android | iOS | visionOS

Callback function that is called when the player has entered fullscreen mode.

Payload: none

onFullscreenPlayerWillDismiss

Platforms: Android | iOS | visionOS

Callback function that is called when the player is about to exit fullscreen mode.

Payload: none

onFullscreenPlayerDidDismiss

Platforms: Android | iOS | visionOS

Callback function that is called when the player has exited fullscreen mode.

Payload: none

onLoad

Platforms: All

Callback function that is called when the media is loaded and ready to play.

Payload:

PropertyTypeDescription
currentTimenumberTime in seconds where the media will start
durationnumberLength of the media in seconds
naturalSizeobjectProperties:
_ width - Width in pixels that the video was encoded at
_ height - Height in pixels that the video was encoded at
* orientation - "portrait", "landscape" or "square"
audioTracksarrayAn array of audio track info objects with the following properties:
_ index - Index number
_ title - Description of the track
_ language - 2 letter ISO 639-1 (opens in a new tab) or 3 letter ISO639-2 (opens in a new tab) language code
_ type - Mime type of track
textTracksarrayAn array of text track info objects with the following properties:
_ index - Index number
_ title - Description of the track
_ language - 2 letter ISO 639-1 (opens in a new tab) or 3 letter ISO 639-2 (opens in a new tab) language code
_ type - Mime type of track
videoTracksarrayAn array of video track info objects with the following properties:
_ trackId - ID for the track
_ bitrate - Bit rate in bits per second
_ codecs - Comma separated list of codecs
_ height - Height of the video
* width - Width of the video
trackIdstringProvide key information about the video track, typically including: Resolution, Bitrate.

Example:

{
  canPlaySlowForward: true,
  canPlayReverse: false,
  canPlaySlowReverse: false,
  canPlayFastForward: false,
  canStepForward: false,
  canStepBackward: false,
  currentTime: 0,
  duration: 5910.208984375,
  naturalSize: {
     height: 1080
     orientation: 'landscape'
     width: '1920'
  },
  audioTracks: [
    { language: 'es', title: 'Spanish', type: 'audio/mpeg', index: 0 },
    { language: 'en', title: 'English', type: 'audio/mpeg', index: 1 }
  ],
  textTracks: [
    { title: '#1 French', language: 'fr', index: 0, type: 'text/vtt' },
    { title: '#2 English CC', language: 'en', index: 1, type: 'text/vtt' },
    { title: '#3 English Director Commentary', language: 'en', index: 2, type: 'text/vtt' }
  ],
  videoTracks: [
    { index: 0, bitrate: 3987904, codecs: "avc1.640028", height: 720, trackId: "f1-v1-x3", width: 1280 },
    { index: 1, bitrate: 7981888, codecs: "avc1.640028", height: 1080, trackId: "f2-v1-x3", width: 1920 },
    { index: 2, bitrate: 1994979, codecs: "avc1.4d401f", height: 480, trackId: "f3-v1-x3", width: 848 }
  ],
  trackId: "720p 2400kbps"
}

onLoadStart

Platforms: All

Callback function that is called when the media starts loading.

Payload:

PropertyTypeDescription
isNetworkbooleanBoolean indicating if the media is being loaded from the network
typestringType of the media. Not available on Windows
uristringURI for the media source. Not available on Windows

Example:

{
  isNetwork: true,
  type: '',
  uri: 'https://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8'
}

onPlaybackStateChanged

Platforms: Android | iOS | visionOS

Callback function that is called when the playback state changes.

Payload:

PropertyTypeDescription
isPlayingbooleanBoolean indicating if the media is playing or not
isSeekingbooleanBoolean indicating if the player is seeking or not

Example:

{
  isPlaying: true,
  isSeeking: false
}

onPictureInPictureStatusChanged

Platform: iOS

Callback function that is called when picture in picture becomes active or inactive.

PropertyTypeDescription
isActivebooleanBoolean indicating whether picture in picture is active

Example:

{
  isActive: true;
}

onPlaybackRateChange

Platforms: All

Callback function that is called when the rate of playback changes - either paused or starts/resumes.

PropertyTypeDescription
playbackRatenumber0 when playback is paused, 1 when playing at normal speed. Other values when playback is slowed down or sped up

Example:

{
  playbackRate: 0, // indicates paused
}

onProgress

Platforms: All

Callback function that is called every progressUpdateInterval milliseconds with info about which position the media is currently playing.

PropertyTypeDescription
currentTimenumberCurrent position in seconds
playableDurationnumberPosition to where the media can be played to using just the buffer in seconds
seekableDurationnumberPosition to where the media can be seeked to in seconds. Typically, the total length of the media

Example:

{
  currentTime: 5.2,
  playableDuration: 34.6,
  seekableDuration: 888
}

onReadyForDisplay

Platforms: Android | iOS | Web

Callback function that is called when the first video frame is ready for display. This is when the poster is removed.

Payload: none

onReceiveAdEvent

Platforms: Android | iOS

Callback function that is called when an AdEvent is received from the IMA's SDK.

Enum AdEvent possible values for Android (opens in a new tab) and iOS (opens in a new tab):

Events
EventPlatformDescription
AD_BREAK_ENDEDiOSFired the first time each ad break ends. Applications must reenable seeking when this occurs (only used for dynamic ad insertion).
AD_BREAK_READYAndroid, iOSFires when an ad rule or a VMAP ad break would have played if autoPlayAdBreaks is false.
AD_BREAK_STARTEDiOSFired first time each ad break begins playback. If an ad break is watched subsequent times this will not be fired. Applications must disable seeking when this occurs (only used for dynamic ad insertion).
AD_BUFFERINGAndroidFires when the ad has stalled playback to buffer.
AD_CAN_PLAYAndroidFires when the ad is ready to play without buffering, either at the beginning of the ad or after buffering completes.
AD_METADATAAndroidFires when an ads list is loaded.
AD_PERIOD_ENDEDiOSFired every time the stream switches from advertising or slate to content. This will be fired even when an ad is played a second time or when seeking into an ad (only used for dynamic ad insertion).
AD_PERIOD_STARTEDiOSFired every time the stream switches from content to advertising or slate. This will be fired even when an ad is played a second time or when seeking into an ad (only used for dynamic ad insertion).
AD_PROGRESSAndroidFires when the ad's current time value changes. The event data will be populated with an AdProgressData object.
ALL_ADS_COMPLETEDAndroid, iOSFires when the ads manager is done playing all the valid ads in the ads response, or when the response doesn't return any valid ads.
CLICKAndroid, iOSFires when the ad is clicked.
COMPLETEDAndroid, iOSFires when the ad completes playing.
CONTENT_PAUSE_REQUESTEDAndroidFires when content should be paused. This usually happens right before an ad is about to cover the content.
CONTENT_RESUME_REQUESTEDAndroidFires when content should be resumed. This usually happens when an ad finishes or collapses.
CUEPOINTS_CHANGEDiOSCuepoints changed for VOD stream (only used for dynamic ad insertion).
DURATION_CHANGEAndroidFires when the ad's duration changes.
ERRORAndroid, iOSFires when an error occurred while loading the ad and prevent it from playing.
FIRST_QUARTILEAndroid, iOSFires when the ad playhead crosses first quartile.
IMPRESSIONAndroidFires when the impression URL has been pinged.
INTERACTIONAndroidFires when an ad triggers the interaction callback. Ad interactions contain an interaction ID string in the ad data.
LINEAR_CHANGEDAndroidFires when the displayed ad changes from linear to nonlinear, or the reverse.
LOADEDAndroid, iOSFires when ad data is available.
LOGAndroid, iOSFires when a non-fatal error is encountered. The user need not take any action since the SDK will continue with the same or next ad playback depending on the error situation.
MIDPOINTAndroid, iOSFires when the ad playhead crosses midpoint.
PAUSEDAndroid, iOSFires when the ad is paused.
RESUMEDAndroid, iOSFires when the ad is resumed.
SKIPPABLE_STATE_CHANGEDAndroidFires when the displayed ads skippable state is changed.
SKIPPEDAndroid, iOSFires when the ad is skipped by the user.
STARTEDAndroid, iOSFires when the ad starts playing.
STREAM_LOADEDiOSStream request has loaded (only used for dynamic ad insertion).
TAPPEDiOSFires when the ad is tapped.
THIRD_QUARTILEAndroid, iOSFires when the ad playhead crosses third quartile.
UNKNOWNiOSAn unknown event has fired
USER_CLOSEAndroidFires when the ad is closed by the user.
VIDEO_CLICKEDAndroidFires when the non-clickthrough portion of a video ad is clicked.
VIDEO_ICON_CLICKEDAndroidFires when a user clicks a video icon.
VOLUME_CHANGEDAndroidFires when the ad volume has changed.
VOLUME_MUTEDAndroidFires when the ad volume has been muted.

Payload:

PropertyTypeDescription
eventAdEventThe ad event received
dataRecord<string, string> | undefinedThe ad event data

Example:

{
  "data": {
    "key": "value"
  },
  "event": "LOG"
}

onRestoreUserInterfaceForPictureInPictureStop

Platforms: iOS | visionOS

Callback function that corresponds to Apple's restoreUserInterfaceForPictureInPictureStopWithCompletionHandler (opens in a new tab). Call restoreUserInterfaceForPictureInPictureStopCompleted inside of this function when done restoring the user interface.

Payload: none

onSeek

Platforms: Android | iOS | Windows UWP

Callback function that is called when a seek completes.

Payload:

PropertyTypeDescription
currentTimenumberThe current time after the seek
seekTimenumberThe requested time

Example:

{
  currentTime: 100.5;
  seekTime: 100;
}

Both the currentTime & seekTime are reported because the video player may not seek to the exact requested position in order to improve seek performance.

Note: on iOS, when controls are enable, this callback is not reported. This is a known limitation.

onTimedMetadata

Platforms: Android | iOS | visionOS

Callback function that is called when timed metadata becomes available

Payload:

PropertyTypeDescription
metadataarrayArray of metadata objects

Example:

{
  metadata: [
    {value: 'Streaming Encoder', identifier: 'TRSN'},
    {value: 'Internet Stream', identifier: 'TRSO'},
    {value: 'Any Time You Like', identifier: 'TIT2'},
  ];
}

onTextTrackDataChanged

Platforms: Android | iOS

Callback function that is called when new subtitle data is available. It provides the actual subtitle content for the current selected text track, if available (mainly WebVTT).

Payload:

PropertyTypeDescription
subtitleTracksstringThe subtitles text content in a compatible format.

Example:

{
  subtitleTracks: "This blade has a dark past.",
}

For details on how to control the visibility of subtitles, see the subtitleStyle section.

onTextTracks

Platforms: Android | iOS

Callback function that is called when text tracks change

Payload:

PropertyTypeDescription
indexnumberInternal track ID
titlestringDescriptive name for the track
languagestring2 letter ISO 639-1 code (opens in a new tab) representing the language
typestringMime type of the track
_ TextTrackType.SRT - SubRip (.srt)
_ TextTrackType.TTML - TTML (.ttml)
* TextTrackType.VTT - WebVTT (.vtt)
iOS only supports VTT, Android supports all 3
selectedbooleantrue if track is playing

Example:

{
  textTracks: [
    {
      index: 0,
      title: 'Any Time You Like',
      type: 'srt',
      selected: true,
    },
  ];
}

onVideoTracks

Platform: Android

Callback function that is called when video tracks change

Payload:

PropertyTypeDescription
indexnumberindex of the track
trackIdstringInternal track ID
codecsstringMimeType of codec used for this track
widthnumberTrack width
heightnumberTrack height
bitratenumberBitrate in bps
selectedbooleantrue if track is selected for playing
rotationnumber0, 90, 180 or 270 rotation to apply to the track (android only)

Example:

{
  videoTracks: [
    {
      index: O,
      trackId: "0",
      codecs: 'video/mp4',
      width: 1920,
      height: 1080,
      bitrate: 10000,
      selected: true,
      rotation: 0,
    },
  ];
}

onVolumeChange

Platforms: Android | iOS | visionOS

Callback function that is called when the volume of player changes.

Note: This event applies to the volume of the player, not the volume of the device.

Payload:

PropertyTypeDescription
volumenumberThe volume of the player (between 0 and 1)

Example:

{
  volume: 0.5;
}