* docs: add visionOS platform

* update docs

2024-01-16 07:21:38 +01:00

27 KiB

Raw Blame History

Events

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

List

Name	Platforms Support
onAudioBecomingNoisy	Android, iOS
onAudioFocusChanged	Android
onAudioTracks	Android
onBandwidthUpdate	Android
onBuffer	Android, iOS
onEnd	All
onError	All
onExternalPlaybackChange	iOS
onFullscreenPlayerWillPresent	Android, iOS, visionOS
onFullscreenPlayerDidPresent	Android, iOS, visionOS
onFullscreenPlayerWillDismiss	Android, iOS, visionOS
onFullscreenPlayerDidDismiss	Android, iOS, visionOS
onLoad	All
onLoadStart	All
onPictureInPictureStatusChanged	iOS
onPlaybackRateChange	All
onPlaybackStateChanged	Android, iOS, visionOS
onProgress	All
onReadyForDisplay	Android, iOS
onReceiveAdEvent	Android, iOS
onRestoreUserInterfaceForPictureInPictureStop	iOS, visionOS
onSeek	All
onTimedMetadata	Android, iOS, visionOS
onTextTracks	Android
onVideoTracks	Android
onVolumeChange	Android, iOS, visionOS

Details

`onAudioBecomingNoisy`

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

Platforms: Android, iOS

`onAudioFocusChanged`

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:

Property	Type	Description
hasAudioFocus	boolean	Boolean indicating whether the media has audio focus

Example:

{
  hasAudioFocus: true
}

`onAudioTracks`

Callback function that is called when audio tracks change

Payload:

An array of

Property	Type	Description
index	number	Index number of the track
title	string	Description of the track
language	string	2 letter ISO 639-1 or 3 letter ISO 639-2 language code
type	string	Mime type of track

Example:

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

`onBandwidthUpdate`

Callback function that is called when the available bandwidth changes.

Payload:

Property	Type	Description
bitrate	number	The estimated bitrate in bits/sec
width	number	The width of the video (android only)
height	number	The height of the video (android only)
trackId	string	The 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.

Platforms: Android

`onBuffer`

Callback function that is called when the player buffers.

Payload:

Property	Type	Description
isBuffering	boolean	Boolean indicating whether buffering is active

Example:

{
  isBuffering: true
}

Platforms: Android, iOS

`onEnd`

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

Payload: none

Platforms: all

`onError`

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

Payload:

Property	Type	Description
error	object	Object containing properties with information about the error

Platforms: all

`onExternalPlaybackChange`

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:

Property	Type	Description
isExternalPlaybackActive	boolean	Boolean indicating whether external playback mode is active

Example:

{
  isExternalPlaybackActive: true
}

Platforms: iOS

`onFullscreenPlayerWillPresent`

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

Payload: none

Platforms: Android, iOS

`onFullscreenPlayerDidPresent`

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

Payload: none

Platforms: Android, iOS

`onFullscreenPlayerWillDismiss`

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

Payload: none

Platforms: Android, iOS

`onFullscreenPlayerDidDismiss`

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

Payload: none

Platforms: Android, iOS

`onLoad`

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

Payload:

Property	Type	Description
currentTime	number	Time in seconds where the media will start
duration	number	Length of the media in seconds
naturalSize	object	Properties: * width - Width in pixels that the video was encoded at * height - Height in pixels that the video was encoded at * orientation - "portrait" or "landscape"
audioTracks	array	An array of audio track info objects with the following properties: * index - Index number * title - Description of the track * language - 2 letter ISO 639-1 or 3 letter ISO639-2 language code * type - Mime type of track
textTracks	array	An array of text track info objects with the following properties: * index - Index number * title - Description of the track * language - 2 letter ISO 639-1 or 3 letter ISO 639-2 language code * type - Mime type of track
videoTracks	array	An 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

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: [
    { bitrate: 3987904, codecs: "avc1.640028", height: 720, trackId: "f1-v1-x3", width: 1280 },
    { bitrate: 7981888, codecs: "avc1.640028", height: 1080, trackId: "f2-v1-x3", width: 1920 },
    { bitrate: 1994979, codecs: "avc1.4d401f", height: 480, trackId: "f3-v1-x3", width: 848 }
  ]
}

Platforms: all

`onLoadStart`

Callback function that is called when the media starts loading.

Payload:

Property	Description
isNetwork	boolean
type	string
uri	string

Example:

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

Platforms: all

`onPlaybackStateChanged`

Callback function that is called when the playback state changes.

Payload:

Property	Description
isPlaying	boolean

Example:

{
  isPlaying: true,
}

Platforms: Android, iOS

`onPictureInPictureStatusChanged`

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

Property	Type	Description
isActive	boolean	Boolean indicating whether picture in picture is active

Example:

{
isActive: true
}

Platforms: iOS

`onPlaybackRateChange`

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

Property	Type	Description
playbackRate	number	0 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
}

Platforms: all

`onProgress`

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

Property	Type	Description
currentTime	number	Current position in seconds
playableDuration	number	Position to where the media can be played to using just the buffer in seconds
seekableDuration	number	Position 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
}

Platforms: all

`onReadyForDisplay`

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

Payload: none

iOS: readyForDisplay
Android STATE_READY

Platforms: Android, iOS, Web

`onReceiveAdEvent`

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

Enum AdEvent possible values for Android and iOS:

Events

Event	Platform	Description
`AD_BREAK_ENDED`	iOS	Fired the first time each ad break ends. Applications must reenable seeking when this occurs (only used for dynamic ad insertion).
`AD_BREAK_READY`	Android, iOS	Fires when an ad rule or a VMAP ad break would have played if autoPlayAdBreaks is false.
`AD_BREAK_STARTED`	iOS	Fired 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_BUFFERING`	Android	Fires when the ad has stalled playback to buffer.
`AD_CAN_PLAY`	Android	Fires when the ad is ready to play without buffering, either at the beginning of the ad or after buffering completes.
`AD_METADATA`	Android	Fires when an ads list is loaded.
`AD_PERIOD_ENDED`	iOS	Fired 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_STARTED`	iOS	Fired 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_PROGRESS`	Android	Fires when the ad's current time value changes. The event `data` will be populated with an AdProgressData object.
`ALL_ADS_COMPLETED`	Android, iOS	Fires 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.
`CLICK`	Android, iOS	Fires when the ad is clicked.
`COMPLETED`	Android, iOS	Fires when the ad completes playing.
`CONTENT_PAUSE_REQUESTED`	Android	Fires when content should be paused. This usually happens right before an ad is about to cover the content.
`CONTENT_RESUME_REQUESTED`	Android	Fires when content should be resumed. This usually happens when an ad finishes or collapses.
`CUEPOINTS_CHANGED`	iOS	Cuepoints changed for VOD stream (only used for dynamic ad insertion).
`DURATION_CHANGE`	Android	Fires when the ad's duration changes.
`ERROR`	Android, iOS	Fires when an error occurred while loading the ad and prevent it from playing.
`FIRST_QUARTILE`	Android, iOS	Fires when the ad playhead crosses first quartile.
`IMPRESSION`	Android	Fires when the impression URL has been pinged.
`INTERACTION`	Android	Fires when an ad triggers the interaction callback. Ad interactions contain an interaction ID string in the ad data.
`LINEAR_CHANGED`	Android	Fires when the displayed ad changes from linear to nonlinear, or the reverse.
`LOADED`	Android, iOS	Fires when ad data is available.
`LOG`	Android, iOS	Fires 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.
`MIDPOINT`	Android, iOS	Fires when the ad playhead crosses midpoint.
`PAUSED`	Android, iOS	Fires when the ad is paused.
`RESUMED`	Android, iOS	Fires when the ad is resumed.
`SKIPPABLE_STATE_CHANGED`	Android	Fires when the displayed ads skippable state is changed.
`SKIPPED`	Android, iOS	Fires when the ad is skipped by the user.
`STARTED`	Android, iOS	Fires when the ad starts playing.
`STREAM_LOADED`	iOS	Stream request has loaded (only used for dynamic ad insertion).
`TAPPED`	iOS	Fires when the ad is tapped.
`THIRD_QUARTILE`	Android, iOS	Fires when the ad playhead crosses third quartile.
`UNKNOWN`	iOS	An unknown event has fired
`USER_CLOSE`	Android	Fires when the ad is closed by the user.
`VIDEO_CLICKED`	Android	Fires when the non-clickthrough portion of a video ad is clicked.
`VIDEO_ICON_CLICKED`	Android	Fires when a user clicks a video icon.
`VOLUME_CHANGED`	Android	Fires when the ad volume has changed.
`VOLUME_MUTED`	Android	Fires when the ad volume has been muted.

Payload:

Property	Type	Description
event	AdEvent	The ad event received
data	Record<string, string> \| undefined	The ad event data

Example:

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

Platforms: Android, iOS

`onRestoreUserInterfaceForPictureInPictureStop`

Callback function that corresponds to Apple's restoreUserInterfaceForPictureInPictureStopWithCompletionHandler. Call restoreUserInterfaceForPictureInPictureStopCompleted inside of this function when done restoring the user interface.

Payload: none

Platforms: iOS

`onSeek`

Callback function that is called when a seek completes.

Payload:

Property	Type	Description
currentTime	number	The current time after the seek
seekTime	number	The 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.

Platforms: Android, iOS, Windows UWP

`onTimedMetadata`

Callback function that is called when timed metadata becomes available

Payload:

Property	Type	Description
metadata	array	Array of metadata objects

Example:

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

Platforms: Android, iOS

`onTextTracks`

Callback function that is called when text tracks change

Payload:

Property	Type	Description
index	number	Internal track ID
title	string	Descriptive name for the track
language	string	2 letter ISO 639-1 code representing the language
type	string	Mime type of the track * TextTrackType.SRT - SubRip (.srt) * TextTrackType.TTML - TTML (.ttml) * TextTrackType.VTT - WebVTT (.vtt) iOS only supports VTT, Android supports all 3
selected	boolean	true if track is playing

Example:

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

Platforms: Android

`onVideoTracks`

Callback function that is called when video tracks change

Payload:

Property	Type	Description
trackId	number	Internal track ID
codecs	string	MimeType of codec used for this track
width	number	Track width
height	number	Track height
bitrate	number	Bitrate in bps
selected	boolean	true if track is selected for playing

Example:

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

Platforms: Android

`onVolumeChange`

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:

Property	Type	Description
volume	number	The volume of the player (between 0 and 1)

Example:

{
  volume: 0.5
}

Platforms: Android, iOS

27 KiB Raw Blame History Unescape Escape

Events

List

Details

onAudioBecomingNoisy

onAudioFocusChanged

onAudioTracks

onBandwidthUpdate

onBuffer

onEnd

onError

onExternalPlaybackChange

onFullscreenPlayerWillPresent

onFullscreenPlayerDidPresent

onFullscreenPlayerWillDismiss

onFullscreenPlayerDidDismiss

onLoad

onLoadStart

onPlaybackStateChanged

onPictureInPictureStatusChanged

onPlaybackRateChange

onProgress

onReadyForDisplay

onReceiveAdEvent

onRestoreUserInterfaceForPictureInPictureStop

onSeek

onTimedMetadata

onTextTracks

onVideoTracks

onVolumeChange

27 KiB

Raw Blame History

`onAudioBecomingNoisy`

`onAudioFocusChanged`

`onAudioTracks`

`onBandwidthUpdate`

`onBuffer`

`onEnd`

`onError`

`onExternalPlaybackChange`

`onFullscreenPlayerWillPresent`

`onFullscreenPlayerDidPresent`

`onFullscreenPlayerWillDismiss`

`onFullscreenPlayerDidDismiss`

`onLoad`

`onLoadStart`

`onPlaybackStateChanged`

`onPictureInPictureStatusChanged`

`onPlaybackRateChange`

`onProgress`

`onReadyForDisplay`

`onReceiveAdEvent`

`onRestoreUserInterfaceForPictureInPictureStop`

`onSeek`

`onTimedMetadata`

`onTextTracks`

`onVideoTracks`

`onVolumeChange`