VideoPlayerEvents

Overview

The VideoPlayerEvents interface defines all event callbacks that are triggered by the video player during playback. These events allow you to monitor and respond to changes in playback state, loading progress, audio handling, and more.

Event Categories

Events related to video playback state and progress.

onPlaybackStateChange

Called when the player playback state changes.Callback Signature:

onPlaybackStateChange: (data: onPlaybackStateChangeData) => void

Event Data:

isPlaying

boolean

Whether the video is playing.

isBuffering

boolean

Whether the video is buffering.

Example:

<Video
  source={videoSource}
  onPlaybackStateChange={(data) => {
    console.log('Playing:', data.isPlaying);
    console.log('Buffering:', data.isBuffering);
  }}
/>

onPlaybackRateChange

Called when the player playback rate changes.Callback Signature:

onPlaybackRateChange: (rate: number) => void

Parameters:

rate - The new playback rate (e.g., 1.0 for normal speed, 2.0 for 2x speed)

Example:

<Video
  source={videoSource}
  onPlaybackRateChange={(rate) => {
    console.log('Playback rate changed to:', rate);
  }}
/>

onProgress

Called when the player progress changes.Callback Signature:

onProgress: (data: onProgressData) => void

Event Data:

currentTime

number

The current time of the video in seconds.

bufferDuration

number

The time that player is able to play with only buffer.

Example:

<Video
  source={videoSource}
  onProgress={(data) => {
    console.log('Current time:', data.currentTime);
    console.log('Buffer duration:', data.bufferDuration);
  }}
/>

onEnd

Called when the video ends.Callback Signature:

onEnd: () => void

Example:

<Video
  source={videoSource}
  onEnd={() => {
    console.log('Video has ended');
    // Navigate to next video or show replay button
  }}
/>

onSeek

Called when the player seeks.Callback Signature:

onSeek: (seekTime: number) => void

Parameters:

seekTime - The time in seconds that the player seeked to

Example:

<Video
  source={videoSource}
  onSeek={(seekTime) => {
    console.log('Seeked to:', seekTime);
  }}
/>

Events related to video loading and initialization.

onLoadStart

Called when the video starts loading.

The loading lifecycle: onLoadStart → initialize the player → onLoad

Callback Signature:

onLoadStart: (data: onLoadStartData) => void

Event Data:

sourceType

'local' | 'network'

The type of the source. local for local files, network for network sources.

source

VideoPlayerSource

The source of the video.

Example:

<Video
  source={videoSource}
  onLoadStart={(data) => {
    console.log('Loading started:', data.sourceType);
  }}
/>

onLoad

Called when the video is loaded.

The loading lifecycle: onLoadStart → initialize the player → onLoad

Callback Signature:

onLoad: (data: onLoadData) => void

Event Data:

currentTime

number

The current time of the video in seconds.

duration

number

The duration of the video in seconds. Returns NaN if the duration is unknown.

width

number

The width of the video in pixels.

height

number

The height of the video in pixels.

orientation

VideoOrientation

The orientation of the video. Possible values: 'portrait', 'landscape', 'portrait-upside-down', 'landscape-left', 'landscape-right', 'square', or 'unknown'.

Example:

<Video
  source={videoSource}
  onLoad={(data) => {
    console.log('Video loaded:');
    console.log('Duration:', data.duration);
    console.log('Dimensions:', data.width, 'x', data.height);
    console.log('Orientation:', data.orientation);
  }}
/>

onReadyToDisplay

Called when the video is ready to display.Callback Signature:

onReadyToDisplay: () => void

Example:

<Video
  source={videoSource}
  onReadyToDisplay={() => {
    console.log('Video is ready to display');
    // Hide loading spinner
  }}
/>

onBuffer

Called when the video is buffering.Callback Signature:

onBuffer: (buffering: boolean) => void

Parameters:

buffering - Whether the video is buffering

Example:

<Video
  source={videoSource}
  onBuffer={(buffering) => {
    if (buffering) {
      console.log('Video is buffering...');
      // Show loading indicator
    } else {
      console.log('Buffering complete');
      // Hide loading indicator
    }
  }}
/>

Events related to audio handling and focus.

onAudioBecomingNoisy

Called when the audio becomes noisy.

Platform: Android only

Callback Signature:

onAudioBecomingNoisy: () => void

Example:

<Video
  source={videoSource}
  onAudioBecomingNoisy={() => {
    console.log('Audio becoming noisy - pausing playback');
    // Typically pause the video when headphones are disconnected
  }}
/>

onAudioFocusChange

Called when the audio focus changes.

Platform: Android only

Callback Signature:

onAudioFocusChange: (hasAudioFocus: boolean) => void

Parameters:

hasAudioFocus - Whether the audio has focus

Example:

<Video
  source={videoSource}
  onAudioFocusChange={(hasAudioFocus) => {
    if (hasAudioFocus) {
      console.log('Audio focus gained');
    } else {
      console.log('Audio focus lost');
      // Pause or duck audio volume
    }
  }}
/>

onVolumeChange

Called when the volume of the player changes.Callback Signature:

onVolumeChange: (data: onVolumeChangeData) => void

Event Data:

volume

number

The volume of the player (0.0 = 0%, 1.0 = 100%).

muted

boolean

Whether the player is muted.

Example:

<Video
  source={videoSource}
  onVolumeChange={(data) => {
    console.log('Volume:', data.volume * 100 + '%');
    console.log('Muted:', data.muted);
  }}
/>

Events related to network bandwidth and streaming quality.

onBandwidthUpdate

Called when the bandwidth of the video changes.Callback Signature:

onBandwidthUpdate: (data: BandwidthData) => void

Event Data:

bitrate

number

The bitrate of the video in bits per second.

width

number

The width of the video in pixels.

height

number

The height of the video in pixels.

Example:

<Video
  source={videoSource}
  onBandwidthUpdate={(data) => {
    console.log('Bitrate:', data.bitrate / 1000000 + ' Mbps');
    if (data.width && data.height) {
      console.log('Quality:', data.width + 'x' + data.height);
    }
  }}
/>

Events related to subtitles and closed captions.

onTrackChange

Called when the selected text track changes.Callback Signature:

onTrackChange: (track: TextTrack | null) => void

Parameters:

track - The newly selected text track, or null if no track is selected

TextTrack Structure:

string

Unique identifier for the text track.

label

string

Display label for the text track.

language

string

Language code (ISO 639-1 or ISO 639-2), e.g., “en”, “es”, “fr”.

selected

boolean

Whether this track is currently selected.

Example:

<Video
  source={videoSource}
  onTrackChange={(track) => {
    if (track) {
      console.log('Subtitle track changed:', track.label);
      console.log('Language:', track.language);
    } else {
      console.log('Subtitles disabled');
    }
  }}
/>

onTextTrackDataChanged

Called when the text track (currently displayed subtitle) data changes.Callback Signature:

onTextTrackDataChanged: (texts: string[]) => void

Parameters:

texts - Array of currently displayed subtitle text strings

Example:

<Video
  source={videoSource}
  onTextTrackDataChanged={(texts) => {
    console.log('Current subtitles:', texts.join('\n'));
  }}
/>

onTimedMetadata

Called when player receives timed metadata.Callback Signature:

onTimedMetadata: (metadata: TimedMetadata) => void

Event Data:

metadata

Array<TimedMetadataObject>

The timed metadata of the video.

TimedMetadataObject Structure:

value (string) - The metadata value
identifier (string) - The metadata identifier

Example:

<Video
  source={videoSource}
  onTimedMetadata={(data) => {
    data.metadata.forEach((item) => {
      console.log(`${item.identifier}: ${item.value}`);
    });
  }}
/>

Other player events.

onStatusChange

Called when the player status changes.Callback Signature:

onStatusChange: (status: VideoPlayerStatus) => void

Parameters:

status - The new player status

VideoPlayerStatus Values:

'idle' - The player is idle (source is not loaded)
'loading' - The player is loading (source is loading)
'readyToPlay' - The player is ready to play (source is loaded)
'error' - The player has an error (source is not loaded)

Example:

<Video
  source={videoSource}
  onStatusChange={(status) => {
    console.log('Player status:', status);
    switch (status) {
      case 'idle':
        // Handle idle state
        break;
      case 'loading':
        // Show loading indicator
        break;
      case 'readyToPlay':
        // Hide loading, enable controls
        break;
      case 'error':
        // Show error message
        break;
    }
  }}
/>

onControlsVisibleChange

Called when the video view’s controls visibility changes.Callback Signature:

onControlsVisibleChange: (visible: boolean) => void

Parameters:

visible - Whether the video view’s controls are visible

Example:

<Video
  source={videoSource}
  onControlsVisibleChange={(visible) => {
    console.log('Controls visible:', visible);
  }}
/>

onExternalPlaybackChange

Called when the external playback state changes.

Platform: iOS only

Callback Signature:

onExternalPlaybackChange: (externalPlaybackActive: boolean) => void

Parameters:

externalPlaybackActive - Whether the external playback is active (e.g., AirPlay)

Example:

<Video
  source={videoSource}
  onExternalPlaybackChange={(isActive) => {
    if (isActive) {
      console.log('Playing on external device (AirPlay)');
    } else {
      console.log('Playing on device');
    }
  }}
/>

Complete Example

Here’s a comprehensive example showing how to use multiple player events:

import React, { useState } from 'react';
import { View, Text } from 'react-native';
import Video from 'react-native-video';

function VideoPlayer() {
  const [status, setStatus] = useState('idle');
  const [progress, setProgress] = useState(0);
  const [duration, setDuration] = useState(0);
  const [isBuffering, setIsBuffering] = useState(false);

  return (
    <View>
      <Video
        source={{ uri: 'https://example.com/video.mp4' }}
        onLoadStart={(data) => {
          console.log('Loading started:', data.sourceType);
        }}
        onLoad={(data) => {
          console.log('Video loaded');
          setDuration(data.duration);
        }}
        onStatusChange={(status) => {
          setStatus(status);
        }}
        onProgress={(data) => {
          setProgress(data.currentTime);
        }}
        onBuffer={(buffering) => {
          setIsBuffering(buffering);
        }}
        onPlaybackStateChange={(data) => {
          console.log('Playing:', data.isPlaying);
        }}
        onEnd={() => {
          console.log('Video ended');
        }}
      />
      
      <Text>Status: {status}</Text>
      <Text>Progress: {progress.toFixed(2)}s / {duration.toFixed(2)}s</Text>
      {isBuffering && <Text>Buffering...</Text>}
    </View>
  );
}

Error Handling

For error handling, see the onError event in the JSVideoPlayerEvents interface:

<Video
  source={videoSource}
  onError={(error) => {
    console.error('Video error:', error);
  }}
/>

Components

Classes

Hooks

Types

Events

Overview

Event Categories

onPlaybackStateChange

onPlaybackRateChange

onProgress

onEnd

onSeek

onLoadStart

onLoad

onReadyToDisplay

onBuffer

onAudioBecomingNoisy

onAudioFocusChange

onVolumeChange

onBandwidthUpdate

onTrackChange

onTextTrackDataChanged

onTimedMetadata

onStatusChange

onControlsVisibleChange

onExternalPlaybackChange

Complete Example

Error Handling

See Also

Build docs developers (and LLMs) love

Components

Classes

Hooks

Types

Events

Documentation Index

​Overview

​Event Categories

​onPlaybackStateChange

​onPlaybackRateChange

​onProgress

​onEnd

​onSeek

​onLoadStart

​onLoad

​onReadyToDisplay

​onBuffer

​onAudioBecomingNoisy

​onAudioFocusChange

​onVolumeChange

​onBandwidthUpdate

​onTrackChange

​onTextTrackDataChanged

​onTimedMetadata

​onStatusChange

​onControlsVisibleChange

​onExternalPlaybackChange

​Complete Example

​Error Handling

​See Also

Build docs developers (and LLMs) love

Overview

Event Categories

onPlaybackStateChange

onPlaybackRateChange

onProgress

onEnd

onSeek

onLoadStart

onLoad

onReadyToDisplay

onBuffer

onAudioBecomingNoisy

onAudioFocusChange

onVolumeChange

onBandwidthUpdate

onTrackChange

onTextTrackDataChanged

onTimedMetadata

onStatusChange

onControlsVisibleChange

onExternalPlaybackChange

Complete Example

Error Handling

See Also