Skip to content

Repository files navigation

react-native-nitro-video πŸŽ₯

npm version license Nitro Modules React Native

A high-performance, next-generation video player for React Native CLI (and bare Expo) powered by Nitro Modules (C++ JSI).

react-native-nitro-video is a 100% drop-in replacement for expo-video designed specifically for React Native CLI. It provides the exact same intuitive API (useVideoPlayer, <VideoView />, and <VideoAirPlayButton />) backed by AndroidX Media3 ExoPlayer (Android) and AVPlayer (iOS), completely eliminating @expo/modules-core / ExpoModulesCore runtime overhead while delivering instantaneous synchronous property reads and 60+ FPS playback.


⚑ Key Features

  • πŸš€ Zero-Bridge Nitro Architecture: Powered by C++ JSI bindings for synchronous property reads (player.playing, player.duration, player.currentTime) with zero serialization lag.
  • 🎯 100% expo-video Parity: Same hooks (useVideoPlayer, useEventListener), components (<VideoView />, <VideoAirPlayButton />), and types. Just swap your import!
  • πŸ€– AndroidX Media3 ExoPlayer: Latest Media3 engine with adaptive bitrate streaming (HLS, DASH, SmoothStreaming), custom load controls, and decoder optimizations.
  • 🍎 iOS AVPlayer Engine: Full AVKit & AVFoundation integration featuring the Apple QA1820 smooth seeking chase algorithm, avoiding frame drops during rapid scrubbing.
  • πŸ’Ύ Multi-Variant Offline Caching: RFC 9111 HTTP cache compliance with byte-range interval tracking across both Android (SimpleCache) and iOS (ResourceLoaderDelegate).
  • πŸ” Hardware DRM Protection: Widevine, ClearKey, and PlayReady on Android; FairPlay Streaming with asynchronous SPC/CKC exchanges on iOS.
  • πŸ–ΌοΈ Frame-Accurate Thumbnails: Asynchronous thumbnail generator (generateThumbnailsAsync) supporting both iOS 16+ async sequences and Android frame extractors.
  • πŸ“Ί Picture-in-Picture (PiP) & Fullscreen: Native PiP with Android 12+ automatic background transitions, multi-orientation fullscreen locking, and auto-exit on device rotation.
  • πŸ”” Lock Screen & Background Audio: Background audio playback policies with Lock Screen and Dynamic Island controls via MPNowPlayingInfoCenter and Android MediaSessionService.
  • πŸ“‘ AirPlay Support: Built-in <VideoAirPlayButton /> wrapping Apple's AVRoutePickerView.

πŸ“¦ Installation

bun add react-native-nitro-video react-native-nitro-modules
# or
npm install react-native-nitro-video react-native-nitro-modules
# or
yarn add react-native-nitro-video react-native-nitro-modules

iOS Setup

Run CocoaPods installation:

cd ios && bundle exec pod install

Android Setup

No additional setup needed! React Native autolinking automatically registers NitroVideoPackage.


πŸ”„ Migrating from expo-video

react-native-nitro-video was built to be a drop-in replacement. Simply replace your import statement:

- import { VideoView, useVideoPlayer, useEventListener } from 'expo-video';
+ import { VideoView, useVideoPlayer, useEventListener } from 'react-native-nitro-video';

All method signatures, props, callbacks, and event payloads are identical.


πŸš€ Quick Start

import React from 'react';
import { StyleSheet, View, Text, Pressable } from 'react-native';
import { useVideoPlayer, VideoView } from 'react-native-nitro-video';

export function VideoScreen() {
  const player = useVideoPlayer('https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4', (player) => {
    player.loop = true;
    player.muted = false;
    player.play();
  });

  return (
    <View style={styles.container}>
      <VideoView
        player={player}
        style={styles.video}
        contentFit="contain"
        nativeControls
        allowsPictureInPicture
        startsPictureInPictureAutomatically
      />

      <View style={styles.controls}>
        <Pressable
          onPress={() => (player.playing ? player.pause() : player.play())}
          style={styles.button}
        >
          <Text style={styles.buttonText}>{player.playing ? 'Pause' : 'Play'}</Text>
        </Pressable>

        <Pressable
          onPress={() => (player.muted = !player.muted)}
          style={styles.button}
        >
          <Text style={styles.buttonText}>{player.muted ? 'Unmute' : 'Mute'}</Text>
        </Pressable>

        <Pressable
          onPress={() => player.seekBy(10)}
          style={styles.button}
        >
          <Text style={styles.buttonText}>+10s</Text>
        </Pressable>
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#000',
    justifyContent: 'center',
  },
  video: {
    width: '100%',
    height: 300,
  },
  controls: {
    flexDirection: 'row',
    justifyContent: 'center',
    gap: 16,
    marginTop: 20,
  },
  button: {
    backgroundColor: 'rgba(255,255,255,0.2)',
    paddingHorizontal: 16,
    paddingVertical: 10,
    borderRadius: 8,
  },
  buttonText: {
    color: '#fff',
    fontWeight: '600',
  },
});

πŸ“– API Reference

useVideoPlayer(source, setup?, playerBuilderOptions?)

A React hook that creates and manages a VideoPlayer instance, automatically releasing native resources when the component unmounts.

const player = useVideoPlayer(source, (player) => {
  player.loop = true;
  player.play();
});
  • source: string | number | VideoSourceObject | null
    • URL string (e.g. 'https://...')
    • Local required asset (e.g. require('./assets/video.mp4'))
    • Source object with headers, caching, or DRM options:
      const player = useVideoPlayer({
        uri: 'https://example.com/stream.m3u8',
        useCaching: true,
        headers: { Authorization: 'Bearer token' },
        drm: {
          type: 'fairplay',
          licenseServer: 'https://license.example.com',
          certificateUrl: 'https://cert.example.com',
        },
      });
  • setup: (player: VideoPlayer) => void (Optional callback run once on player initialization)
  • playerBuilderOptions: PlayerBuilderOptions (Optional Android frame rate and seek increment options)

createVideoPlayer(source, playerBuilderOptions?)

Creates a standalone VideoPlayer instance outside of React component lifecycles. Remember to call player.release() when finished.


VideoPlayer

Properties

Property Type Access Description
playing boolean Readonly Whether the player is currently playing
duration number Readonly Total duration of the media in seconds
currentTime number Read / Write Current playback position in seconds (setting seeks the player)
status 'idle' | 'loading' | 'readyToPlay' | 'error' Readonly Current player lifecycle status
bufferedPosition number Readonly Buffered position in seconds
isLive boolean Readonly Whether the active source is a live stream
currentLiveTimestamp number | null Readonly Epoch timestamp from HLS EXT-X-PROGRAM-DATE-TIME
currentOffsetFromLive number | null Readonly Latency from the live stream edge in seconds
isExternalPlaybackActive boolean Readonly Whether the player is streaming via AirPlay
loop boolean Read / Write Whether the player should automatically loop
muted boolean Read / Write Audio mute state
volume number Read / Write Audio volume from 0.0 to 1.0
playbackRate number Read / Write Playback speed multiplier (e.g. 0.5, 1.0, 2.0)
preservesPitch boolean Read / Write Whether to maintain audio pitch during speed changes
audioMixingMode AudioMixingMode Read / Write 'auto' | 'mixWithOthers' | 'duckOthers' | 'doNotMix'
showNowPlayingNotification boolean Read / Write Enables Lock Screen / Dynamic Island controls
staysActiveInBackground boolean Read / Write Enables continuous background audio playback
keepScreenOnWhilePlaying boolean Read / Write Keeps device screen awake during playback
timeUpdateEventInterval number Read / Write Interval in seconds for timeUpdate events (0 = disabled)
availableSubtitleTracks SubtitleTrack[] Readonly Available subtitle/caption tracks
subtitleTrack SubtitleTrack | null Read / Write Active subtitle track
availableAudioTracks AudioTrack[] Readonly Available audio language tracks
audioTrack AudioTrack | null Read / Write Active audio track
availableVideoTracks VideoTrack[] Readonly Available video resolutions and bitrates
videoTrack VideoTrack | null Readonly Active video track

Methods

  • play(): void β€” Starts or resumes playback.
  • pause(): void β€” Pauses playback.
  • replay(): void β€” Seeks to 0 and resumes playback.
  • seekBy(seconds: number): void β€” Seeks relative to the current position.
  • replaceAsync(source: VideoSource): Promise<void> β€” Seamlessly swaps the video source without re-instantiating native player objects.
  • generateThumbnailsAsync(times: number | number[], options?: VideoThumbnailOptions): Promise<VideoThumbnail[]> β€” Generates frame-accurate thumbnails.
  • addListener(event, callback): { remove: () => void } β€” Subscribes to player events.
  • removeAllListeners(event?): void β€” Cleans up event listeners.
  • release(): void β€” Destroys the native player session.

<VideoView />

Prop Type Default Description
player VideoPlayer (required) VideoPlayer instance
contentFit 'contain' | 'cover' | 'fill' 'contain' Video aspect ratio scaling behavior
nativeControls boolean true Displays native platform playback controls
allowsPictureInPicture boolean false Enables Picture-in-Picture support
startsPictureInPictureAutomatically boolean false Automatically enters PiP when app is backgrounded
requiresLinearPlayback boolean false Disables scrubbing/seeking in native controls
showsTimecodes boolean true Shows/hides timecode labels in controls (iOS)
useExoShutter boolean false Uses ExoPlayer shutter view during loading (Android)
onPictureInPictureStart () => void undefined Callback fired when PiP starts
onPictureInPictureStop () => void undefined Callback fired when PiP exits
onFullscreenEnter () => void undefined Callback fired when fullscreen mode opens
onFullscreenExit () => void undefined Callback fired when fullscreen mode closes
onFirstFrameRender () => void undefined Callback fired when the first video frame is drawn

Imperative Ref Methods

const videoViewRef = useRef<VideoView>(null);

await videoViewRef.current?.enterFullscreen();
await videoViewRef.current?.exitFullscreen();
await videoViewRef.current?.startPictureInPicture();
await videoViewRef.current?.stopPictureInPicture();

<VideoAirPlayButton />

Displays Apple's native AVRoutePickerView AirPlay sink picker on iOS.

import { VideoAirPlayButton } from 'react-native-nitro-video';

<VideoAirPlayButton
  tint="#ffffff"
  activeTint="#007aff"
  prioritizeVideoDevices
  style={{ width: 32, height: 32 }}
/>

useEventListener(player, event, listener)

A React hook that attaches a typed listener to a VideoPlayer and automatically detaches it when the component unmounts.

useEventListener(player, 'playingChange', ({ isPlaying }) => {
  console.log('Is playing:', isPlaying);
});

useEventListener(player, 'timeUpdate', ({ currentTime, bufferedPosition }) => {
  console.log(`Progress: ${currentTime}s / Buffered: ${bufferedPosition}s`);
});

useEventListener(player, 'statusChange', ({ status, error }) => {
  if (status === 'error') {
    console.error('Playback error:', error?.message);
  }
});

Module-Level Cache Management

Manage offline video storage quotas across both platforms:

import {
  isPictureInPictureSupported,
  clearVideoCacheAsync,
  setVideoCacheSizeAsync,
  getCurrentVideoCacheSize,
} from 'react-native-nitro-video';

// Check PiP hardware support
const canPiP = isPictureInPictureSupported();

// Set cache limit to 2 GB
await setVideoCacheSizeAsync(2 * 1024 * 1024 * 1024);

// Get current disk usage in bytes
const bytesUsed = getCurrentVideoCacheSize();

// Purge all cached video files
await clearVideoCacheAsync();

πŸ“„ License

MIT Β© Anis Rangrez

Releases

Packages

Contributors

Languages