Skip to main content
The VideoPlayer class is the central playback controller in React Native Video. It manages video source loading, playback state, and provides methods to control video playback.

​
Creating a Player

Use the useVideoPlayer hook to create and manage a VideoPlayer instance: 
import { useVideoPlayer } from 'react-native-video';

const player = useVideoPlayer(
  { uri: 'https://example.com/video.mp4' },
  (player) => {
    // Setup callback - called when player starts loading
    player.volume = 0.5;
    player.loop = true;
  }
);

​
Constructor

new VideoPlayer(source: VideoSource | VideoConfig | VideoPlayerSource)
In most cases, you should use the useVideoPlayer hook instead of creating instances directly. The hook handles lifecycle management automatically.

​
Parameters

  • source: The video source to play. Can be:
    • VideoSource: Simple source object with URI
    • VideoConfig: Full configuration object with source and options
    • VideoPlayerSource: Native source object

​
Properties

​
source

get source(): VideoPlayerSource
The current video source being played.

​
status

get status(): VideoPlayerStatus
The current status of the player. Possible 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)

​
duration

get duration(): number
The total duration of the video in seconds. Returns NaN if duration is unknown.

​
currentTime

get currentTime(): number
set currentTime(value: number)
The current playback position in seconds. Setting this property seeks to the specified time. 
// Get current time
const time = player.currentTime;

// Seek to 30 seconds
player.currentTime = 30;

​
volume

get volume(): number
set volume(value: number)
The playback volume (0.0 to 1.0, where 0.0 is silent and 1.0 is maximum volume). 
player.volume = 0.5; // 50% volume

​
muted

get muted(): boolean
set muted(value: boolean)
Whether the player is muted. 
player.muted = true;

​
loop

get loop(): boolean
set loop(value: boolean)
Whether the video should loop when playback reaches the end. 
player.loop = true;

​
rate

get rate(): number
set rate(value: number)
The playback rate (speed). 1.0 is normal speed, 0.5 is half speed, 2.0 is double speed. 
player.rate = 1.5; // 1.5x speed

​
isPlaying

get isPlaying(): boolean
Whether the video is currently playing (read-only). 
if (player.isPlaying) {
  console.log('Video is playing');
}

​
playInBackground

get playInBackground(): boolean
set playInBackground(value: boolean)
Whether the video should continue playing when the app is in the background. 
player.playInBackground = true;

​
playWhenInactive

get playWhenInactive(): boolean
set playWhenInactive(value: boolean)
Whether the video should play when the app is inactive (iOS only).

​
mixAudioMode

get mixAudioMode(): MixAudioMode
set mixAudioMode(value: MixAudioMode)
Controls how the player’s audio mixes with other audio. Possible values:
  • 'mixWithOthers' - Mix with other audio
  • 'doNotMix' - Do not mix with other audio
  • 'duckOthers' - Lower volume of other audio
  • 'auto' - Automatically determine mix mode

​
ignoreSilentSwitchMode

get ignoreSilentSwitchMode(): IgnoreSilentSwitchMode
set ignoreSilentSwitchMode(value: IgnoreSilentSwitchMode)
Controls whether the player respects the device’s silent switch (iOS only). Possible values:
  • 'auto' - Automatically determine behavior
  • 'ignore' - Ignore the silent switch
  • 'obey' - Respect the silent switch
This property only works on iOS. Setting it on other platforms will have no effect.

​
showNotificationControls

get showNotificationControls(): boolean
set showNotificationControls(value: boolean)
Whether to show media controls in the notification area. 
player.showNotificationControls = true;

​
selectedTrack

get selectedTrack(): TextTrack | undefined
The currently selected text track (subtitle/caption), or undefined if none selected.

​
Methods

​
play()

play(): void
Starts or resumes video playback. 
player.play();

​
pause()

pause(): void
Pauses video playback. 
player.pause();

​
seekTo()

seekTo(time: number): void
Seeks to a specific time position in the video. Parameters:
  • time - The target position in seconds
player.seekTo(30); // Seek to 30 seconds

​
seekBy()

seekBy(time: number): void
Seeks relative to the current position. Parameters:
  • time - The number of seconds to seek (positive for forward, negative for backward)
player.seekBy(10);  // Seek forward 10 seconds
player.seekBy(-5);  // Seek backward 5 seconds

​
initialize()

initialize(): Promise<void>
Initializes the player and starts loading the source. This is usually called automatically. 
await player.initialize();

​
preload()

preload(): Promise<void>
Preloads the video source without starting playback. Useful for improving start time. 
await player.preload();

​
replaceSourceAsync()

replaceSourceAsync(
  source: VideoSource | VideoConfig | VideoPlayerSource | null
): Promise<void>
Replaces the current video source with a new one. Pass null to clear the current source. Parameters:
  • source - The new video source, or null to clear
// Replace with new source
await player.replaceSourceAsync({
  uri: 'https://example.com/new-video.mp4'
});

// Clear source
await player.replaceSourceAsync(null);

​
release()

release(): void
Releases the player’s native resources. After calling this, the player is no longer usable.
Accessing any properties or methods after calling release() will throw an error. If you want to clean up player resources while keeping the player usable, use replaceSourceAsync(null) instead.
player.release();

​
getAvailableTextTracks()

getAvailableTextTracks(): TextTrack[]
Returns an array of all available text tracks (subtitles/captions). 
const tracks = player.getAvailableTextTracks();
tracks.forEach(track => {
  console.log(`${track.label} (${track.language})`);
});

​
selectTextTrack()

selectTextTrack(textTrack: TextTrack | null): void
Selects a text track to display. Pass null to disable text tracks. Parameters:
  • textTrack - The text track to select, or null to disable
const tracks = player.getAvailableTextTracks();
if (tracks.length > 0) {
  player.selectTextTrack(tracks[0]); // Select first track
}

// Disable text tracks
player.selectTextTrack(null);

​
Events

The VideoPlayer supports various events through the addEventListener method. For detailed information about events, see the Events documentation. 
const subscription = player.addEventListener('onLoad', (data) => {
  console.log('Video loaded:', data.duration);
});

// Remove listener when done
subscription.remove();
Common events:
  • onLoad - Video loaded and ready to play
  • onLoadStart - Video started loading
  • onProgress - Playback progress update
  • onEnd - Video playback ended
  • onError - An error occurred
  • onBuffer - Buffering state changed
  • onStatusChange - Player status changed

​
Example

import { useVideoPlayer, VideoView } from 'react-native-video';
import { View } from 'react-native';

function VideoPlayer() {
  const player = useVideoPlayer(
    { uri: 'https://example.com/video.mp4' },
    (player) => {
      player.volume = 0.8;
      player.loop = false;
    }
  );

  return (
    <VideoView
      player={player}
      style={{ width: '100%', height: 300 }}
    />
  );
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us