@videoplayernative/react-native-hls-player

A high-performance HLS and video player for React Native, powered by native engines (ExoPlayer on Android, AVPlayer on iOS). Designed for premium user experiences with built-in controls, smooth gestures, and extensive theming support.

🚀 Features

• 🏎️ Native Performance: Leverages Google Media3 ExoPlayer (Android) and AVPlayer (iOS) for the best possible playback stability.
• 📡 HLS & Adaptive Streaming: Optimized for high-bitrate streaming with automatic and manual quality switching.
• 📥 Offline Downloads: Full-featured download manager for HLS streams with progress tracking and storage management.
• 📺 Casting & PiP: Support for Google Cast (Chromecast), AirPlay, and Picture-in-Picture mode on both platforms.
• 🎨 Premium UI Themes: Includes beautiful presets like Kids, Ocean, Candy, and Iris with smooth micro-animations.
• 🖐️ Intuitive Gestures: Vertical swipes for brightness and volume; pinch-to-zoom for aspect ratio switching.
• 📱 Orientation Aware: Seamlessly transitions between portrait and landscape modes.
• 🔒 Screen Lock: Built-in "Child Lock" feature to prevent accidental interruptions.

📦 Installation

npm install @videoplayernative/react-native-hls-player react-native-svg react-native-safe-area-context

or

yarn add @videoplayernative/react-native-hls-player react-native-svg react-native-safe-area-context

Peer Dependencies

This package requires the following libraries to be installed in your project:

• react-native-svg (>= 13.0.0)
• react-native-safe-area-context (>= 4.0.0)

Native Setup

Android

In your android/build.gradle (Project level), ensure minSdkVersion is at least 24.

buildscript {
    ext {
        minSdkVersion = 24
    }
}

iOS

Install native dependencies using CocoaPods:

cd ios && pod install

🛠️ Usage

Quick Start

import React from 'react';
import { PlayKidsPlayer } from '@videoplayernative/react-native-hls-player';

const MyApp = () => {
  return (
    <PlayKidsPlayer
      video={{
        url: 'https://example.com/playlist.m3u8',
        title: 'Sintel - HLS Stream'
      }}
      onBack={() => console.log('Back pressed')}
    />
  );
};

Playlist & Auto-play

const myPlaylist = [
  { id: '1', url: '...', title: 'Episode 1', thumbnail: '...' },
  { id: '2', url: '...', title: 'Episode 2', thumbnail: '...' },
];

<PlayKidsPlayer
  video={myPlaylist[0]}
  playlist={myPlaylist}
  autoPlayNext={true}
  onVideoChange={(video, index) => console.log(`Playing ${video.title}`)}
/>

📥 Offline Downloads

The HLSDownloadManager provides a high-level API for managing offline content.

import { HLSDownloadManager } from '@videoplayernative/react-native-hls-player';

// Start a download
await HLSDownloadManager.startDownload('vid-123', 'https://...', 'Title');

// Listen for progress
const sub = HLSDownloadManager.addProgressListener(({ progress }) => {
  console.log(`Download progress: ${progress * 100}%`);
});

// Play offline
const localUrl = await HLSDownloadManager.getLocalUrl('vid-123');
if (localUrl) {
  // Use this URL in the player
}

📖 API Reference

PlayKidsPlayer Props

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | video | VideoItem | Required | Object with url and title. thumbnail and description are optional. | | playlist | VideoItem[] | [] | List of videos for navigation and auto-play. | | autoPlayNext | boolean | true | Automatically starts the next video in the playlist. | | theme | PlayerThemeConfig | DefaultTheme | UI customization object. | | onBack | () => void | undefined | Callback for the back button. | | onVideoChange | (video, index) => void| undefined | Called when navigating the playlist. | | onScreenLockChange| (locked: boolean) => void| undefined | Triggered when child lock is toggled. | | onPlaybackError | (error: string) => void | undefined | Called when a native error occurs. |

playerRef Methods

Access the underlying player engine via a ref:

• play() / pause()
• seekTo(ms: number)
• setSpeed(speed: number) (0.5 to 2.0)
• enterPiP() - Enters Picture-in-Picture mode.
• showCastDialog() - (Android) Opens Chromecast dialog.
• showAirPlayPicker() - (iOS) Opens AirPlay menu.

Built-in Themes

Import these presets to quickly change the look and feel:

• DefaultTheme: Sleek Dark/Red design.
• KidsTheme: Vibrant Indigo/Orange design.
• OceanTheme: Deep Blue/Cyan design.
• CandyTheme: Fun Pink/Magenta design.
• IrisTheme: Premium Purple/Gold design.

📜 License

Distributed under the MIT License. See LICENSE for more information.