VideoPlayer

The VideoPlayer class is the primary interface for controlling video playback. It provides methods for playback control, seeking, and managing player state, as well as properties for configuring audio, volume, and playback behavior.

Constructor

new VideoPlayer(source: VideoSource | VideoConfig | VideoPlayerSource)

Creates a new video player instance with the specified source.

source

VideoSource | VideoConfig | VideoPlayerSource

required

The video source to play. Can be:

string - URL to a video file
number - Require statement for local video file
VideoConfig - Configuration object with URI and additional options

Example

import { VideoPlayer } from 'react-native-video';

// Simple URL
const player = new VideoPlayer('https://example.com/video.mp4');

// Local file
const player = new VideoPlayer(require('./assets/video.mp4'));

// With configuration
const player = new VideoPlayer({
  uri: 'https://example.com/video.mp4',
  headers: {
    'Authorization': 'Bearer token'
  },
  metadata: {
    title: 'My Video',
    artist: 'Creator Name'
  }
});

Properties

source

VideoPlayerSource

The current video source. This property is immutable. To change the source, use the replaceSourceAsync() method.

status

VideoPlayerStatus

The current status of the player.Possible values:

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

duration

number

The total duration of the video in seconds (1.0 = 1 second). Returns NaN if duration is not available.

const totalDuration = player.duration; // e.g., 125.5

currentTime

number

The current playback position in seconds. Can be read to get the current position or set to seek to a specific time.

// Get current position
const position = player.currentTime;

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

volume

number

The playback volume from 0.0 to 1.0 (0% to 100%). If the player is muted, volume will return 0.0.

// Set volume to 50%
player.volume = 0.5;

// Set volume to maximum
player.volume = 1.0;

muted

boolean

Whether the player is muted. When true, audio is silenced regardless of volume setting.

player.muted = true;  // Mute audio
player.muted = false; // Unmute audio

loop

boolean

Whether the video should loop automatically when it reaches the end.

player.loop = true; // Enable looping

rate

number

The playback speed multiplier. Default is 1.0 (normal speed). Set to 0 to pause the video.

player.rate = 0.5;  // Half speed
player.rate = 1.0;  // Normal speed
player.rate = 2.0;  // Double speed
player.rate = 0;    // Paused

isPlaying

boolean

Whether the video is currently playing. This is a read-only property. Use play() and pause() methods to control playback.

if (player.isPlaying) {
  console.log('Video is playing');
}

mixAudioMode

MixAudioMode

Controls how this player’s audio mixes with other audio sources.Possible values:

'auto' - Uses default behavior for the player (default)
'mixWithOthers' - Mix with other audio players
'doNotMix' - Stop other audio when this player plays
'duckOthers' - Lower volume of other audio when this player plays

player.mixAudioMode = 'duckOthers';

ignoreSilentSwitchMode

IgnoreSilentSwitchMode

Controls whether the player respects the device’s silent switch. iOS only.Possible values:

'auto' - Uses default behavior (default)
'ignore' - Play audio even when silent switch is on
'obey' - Respect the silent switch

// Play audio even when silent switch is on (iOS)
player.ignoreSilentSwitchMode = 'ignore';

playInBackground

boolean

Whether the player should continue playing when the app is in the background. Default is false.

This can override playWhenInactive.

player.playInBackground = true;

playWhenInactive

boolean

Whether the player should continue playing when the app is inactive (e.g., when Control Center is opened). Default is false. iOS only.

This can be overridden by playInBackground.

player.playWhenInactive = true;

showNotificationControls

boolean

Whether to show playback controls in the system notification area.

player.showNotificationControls = true;

selectedTrack

TextTrack | undefined

The currently selected text/subtitle track, or undefined if no track is selected.

Show TextTrack Type

interface TextTrack {
  id: string;           // Unique identifier
  label: string;        // Display label
  language?: string;    // Language code (ISO 639-1 or ISO 639-2)
  selected: boolean;    // Whether currently selected
}

Methods

initialize()

Manually initialize the player. You don’t need to call this method unless you set initializeOnCreation to false in the VideoConfig.

initialize(): Promise<void>

Returns: Promise that resolves when initialization is complete.

const player = new VideoPlayer({
  uri: 'https://example.com/video.mp4',
  initializeOnCreation: false
});

// Initialize manually later
await player.initialize();

preload()

Preload the video to avoid delay when playback starts. This is useful for better user experience but preloading too many videos can lead to memory or performance issues.

preload(): Promise<void>

Returns: Promise that resolves when preloading is complete.

await player.preload();

play()

Start or resume video playback.

play(): void

player.play();

pause()

Pause video playback.

pause(): void

player.pause();

seekTo()

Seek to a specific time position in the video.

seekTo(time: number): void

time

number

required

The time position to seek to in seconds. Will be clamped to the valid range (0 to duration).

This has the same effect as setting the currentTime property.

// Seek to 30 seconds
player.seekTo(30);

// Seek to beginning
player.seekTo(0);

seekBy()

Seek forward or backward by a relative amount of time.

seekBy(time: number): void

time

number

required

The time to seek from the current position in seconds. Negative values seek backward. Will be clamped to valid range.

// Skip forward 10 seconds
player.seekBy(10);

// Rewind 5 seconds
player.seekBy(-5);

replaceSourceAsync()

Replace the current video source with a new one, or clear the source.

replaceSourceAsync(
  source: VideoSource | VideoConfig | VideoPlayerSource | null
): Promise<void>

source

VideoSource | VideoConfig | VideoPlayerSource | null

required

The new video source, or null to clear the current source and release resources.

Returns: Promise that resolves when the source has been replaced.

// Replace with new video
await player.replaceSourceAsync('https://example.com/new-video.mp4');

// Clear source and release resources
await player.replaceSourceAsync(null);

// Replace with configured source
await player.replaceSourceAsync({
  uri: 'https://example.com/video.mp4',
  headers: { 'Authorization': 'Bearer token' }
});

getAvailableTextTracks()

Get all available text/subtitle tracks for the current video.

getAvailableTextTracks(): TextTrack[]

Returns: Array of available text tracks.

const tracks = player.getAvailableTextTracks();
tracks.forEach(track => {
  console.log(`${track.label} (${track.language})`);
});

selectTextTrack()

Select a specific text/subtitle track to display, or clear the current selection.

selectTextTrack(textTrack: TextTrack | null): void

textTrack

TextTrack | null

required

The text track to select, or null to unselect the current track.

const tracks = player.getAvailableTextTracks();

// Select English subtitles
const englishTrack = tracks.find(t => t.language === 'en');
if (englishTrack) {
  player.selectTextTrack(englishTrack);
}

// Disable subtitles
player.selectTextTrack(null);

release()

Release the player’s native resources and destroy the player. After calling this method, the player is no longer usable and accessing any properties or methods will throw an error.

release(): void

After calling release(), the player cannot be used anymore. If you want to clean player resources but keep the player instance, use replaceSourceAsync(null) instead.

// Clean up when done
player.release();

// This will throw an error
player.play(); // Error: You can't access player after it's released

Complete Example

import { VideoPlayer } from 'react-native-video';

// Create player with configuration
const player = new VideoPlayer({
  uri: 'https://example.com/video.mp4',
  metadata: {
    title: 'Tutorial Video',
    artist: 'My Channel'
  },
  externalSubtitles: [
    {
      uri: 'https://example.com/subtitles_en.vtt',
      label: 'English',
      type: 'vtt',
      language: 'en'
    }
  ]
});

// Configure player
player.volume = 0.8;
player.loop = false;
player.playInBackground = true;
player.showNotificationControls = true;

// Initialize and start playback
await player.initialize();
player.play();

// Control playback
player.seekTo(30);
player.rate = 1.5; // 1.5x speed

// Manage subtitles
const tracks = player.getAvailableTextTracks();
const englishTrack = tracks.find(t => t.language === 'en');
if (englishTrack) {
  player.selectTextTrack(englishTrack);
}

// Check status
if (player.status === 'readyToPlay') {
  console.log(`Duration: ${player.duration}s`);
  console.log(`Current time: ${player.currentTime}s`);
  console.log(`Playing: ${player.isPlaying}`);
}

// Clean up when done
player.release();

Components

Classes

Hooks

Types

Events

Constructor

Example

Properties

source

status

duration

currentTime

volume

muted

loop

rate

isPlaying

mixAudioMode

ignoreSilentSwitchMode

playInBackground

playWhenInactive

showNotificationControls

selectedTrack

Methods

initialize()

preload()

play()

pause()

seekTo()

seekBy()

replaceSourceAsync()

getAvailableTextTracks()

selectTextTrack()

release()

Complete Example

See Also

Build docs developers (and LLMs) love

Components

Classes

Hooks

Types

Events

​Constructor

​Example

​Properties

​source

​status

​duration

​currentTime

​volume

​muted

​loop

​rate

​isPlaying

​mixAudioMode

​ignoreSilentSwitchMode

​playInBackground

​playWhenInactive

​showNotificationControls

​selectedTrack

​Methods

​initialize()

​preload()

​play()

​pause()

​seekTo()

​seekBy()

​replaceSourceAsync()

​getAvailableTextTracks()

​selectTextTrack()

​release()

​Complete Example

​See Also

Build docs developers (and LLMs) love

Constructor

Example

Properties

source

status

duration

currentTime

volume

muted

loop

rate

isPlaying

mixAudioMode

ignoreSilentSwitchMode

playInBackground

playWhenInactive

showNotificationControls

selectedTrack

Methods

initialize()

preload()

play()

pause()

seekTo()

seekBy()

replaceSourceAsync()

getAvailableTextTracks()

selectTextTrack()

release()

Complete Example

See Also