Events

This page lists all available callbacks for handling player notifications.

Details

onAudioBecomingNoisy

Platforms: Android | iOS

Triggered when audio output changes (e.g., switching from headphones to speakers). It's recommended to pause the media when this event occurs.

Payload: none

onAudioFocusChanged

Platform: Android

Called when audio focus is gained or lost.

Payload:

Example:

{
  hasAudioFocus: true
}

onAudioTracks

Platforms: Android | iOS

Triggered when available audio tracks change.

Payload: Array of objects with track details

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

Called when available bandwidth changes.

Payload:

Example (iOS):

{
  bitrate: 1000000
}

Example (Android):

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

Note: On Android, set the reportBandwidth prop to enable this event.

onBuffer

Platforms: Android | iOS | web

Triggered when buffering starts or stops.

Payload:

Example:

{
  isBuffering: true
}

onControlsVisibilityChange

Platform: Android

Triggered when the video player controls become visible or hidden.

Payload:

Example:

{
  isVisible: true
}

onEnd

Platforms: All

Triggered when the media reaches the end.

Payload: none

onError

Platforms: All

Called when a playback error occurs.

Payload:

onExternalPlaybackChange

Platform: iOS

Called when external playback mode changes (e.g., Apple TV connection/disconnection).

Payload:

Example:

{
  isExternalPlaybackActive: true
}

onFullscreenPlayerWillPresent

Platforms: Android | iOS | visionOS

Called before entering fullscreen mode.

Payload: none

onFullscreenPlayerDidPresent

Platforms: Android | iOS | visionOS

Called when fullscreen mode is active.

Payload: none

onFullscreenPlayerWillDismiss

Platforms: Android | iOS | visionOS

Called before exiting fullscreen mode.

Payload: none

onFullscreenPlayerDidDismiss

Platforms: Android | iOS | visionOS

Called when fullscreen mode is exited.

Payload: none

onLoad

Platforms: All

Triggered when the media is loaded and ready to play.

Payload:

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",
}

Note: audioTracks, textTracks, and videoTracks are not available on the web.

onLoadStart

Platforms: All

Triggered when media starts loading.

Payload:

Example:

{
  isNetwork: true,
  type: '',
  uri: 'https://example.com/video.mp4'
}

onPlaybackStateChanged

Platforms: Android | iOS | visionOS | web

Triggered when playback state changes.

Payload:

Example:

{
  isPlaying: true,
  isSeeking: false
}

onPictureInPictureStatusChanged

Platforms: iOS | Android | web

Triggered when Picture-in-Picture (PiP) mode is activated or deactivated.

Payload:

Example:

{
  isActive: true
}

onPlaybackRateChange

Platforms: All

Triggered when playback speed changes.

Payload:

Example:

{
  playbackRate: 0  // indicates paused
}

onProgress

Platforms: All

Triggered every progressUpdateInterval milliseconds, providing information about the current playback position.

Payload:

Example:

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

onReadyForDisplay

Platforms: Android | iOS | Web

Triggered when the first video frame is ready to be displayed. This is when the poster is removed.

Payload: none

• iOS: readyForDisplay (opens in a new tab)
• Android: STATE_READY (opens in a new tab)

onReceiveAdEvent

Platforms: Android | iOS

Triggered when an AdEvent is received from the IMA SDK.

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

Payload:

Example:

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

onRestoreUserInterfaceForPictureInPictureStop

Platforms: iOS | visionOS

Corresponds to Apple's restoreUserInterfaceForPictureInPictureStopWithCompletionHandler (opens in a new tab). Call restoreUserInterfaceForPictureInPictureStopCompleted inside this function when the UI is restored.

Payload: none

onSeek

Platforms: Android | iOS | Windows UWP | web

Triggered when a seek operation completes.

Payload:

Example:

{
  currentTime: 100.5,
  seekTime: 100
}

Note: On iOS, this callback is not reported when native controls are enabled.

onTimedMetadata

Platforms: Android | iOS | visionOS

Triggered when timed metadata is available.

Payload:

Example:

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

onTextTrackDataChanged

Platforms: Android | iOS

Triggered when new subtitle data becomes available.

Payload:

Example:

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

onTextTracks

Platforms: Android | iOS

Triggered when available text (subtitle) tracks change.

Payload:

Example:

{
  textTracks: [
    {
      index: 0,
      title: 'English Subtitles',
      type: 'vtt',
      selected: true
    }
  ]
}

onVideoTracks

Platform: Android

Triggered when video tracks change.

Payload:

Example:

{
  videoTracks: [
    {
      index: 0,
      trackId: "1",
      codecs: "video/mp4",
      width: 1920,
      height: 1080,
      bitrate: 5000000,
      selected: true,
      rotation: 0
    }
  ]
}

onVolumeChange

Platforms: Android | iOS | visionOS | web

Triggered when the player volume changes.

Note: This event applies to the player's volume, not the device's system volume.

Payload:

Example:

{
  volume: 0.5
}