@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.
• 🎨 Premium UI Themes: Includes beautiful presets like Kids, Ocean, and Candy 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://bitdash-a.akamaihd.net/content/sintel/hls/playlist.m3u8',
        title: 'Sintel - HLS Stream'
      }}
      onBack={() => console.log('Back pressed')}
    />
  );
};

Custom Theming

import { PlayKidsPlayer, CandyTheme, createTheme } from '@videoplayernative/react-native-hls-player';

// Create a custom theme based on the Candy preset
const MyCustomTheme = createTheme({
  primaryColor: '#6200EE',
  seekProgressColor: '#03DAC6',
}, CandyTheme);

const ThemedVideo = () => (
  <PlayKidsPlayer
    video={{ url: "...", title: "Custom Theme" }}
    theme={MyCustomTheme}
  />
);

📖 API Reference

PlayKidsPlayer Props

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | video | object | Required | Contains url (string) and title (string). | | theme | PlayerThemeConfig | DefaultTheme | UI customization object. | | onBack | () => void | undefined | Callback for the back button in the overlay. | | onScreenLockChange | (locked: boolean) => void | undefined | Triggered when the screen is locked/unlocked. |

Built-in Themes

You can import and use these presets directly:

• DefaultTheme (Sleek Dark/Red)
• KidsTheme (Vibrant Indigo/Orange)
• OceanTheme (Deep Blue/Cyan)
• CandyTheme (Fun Pink/Magenta)

📜 License

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