zerorate-player-native

A React Native wrapper for the Zerorate Player SDK, enabling seamless HLS video playback with advanced features in your React Native apps via a WebView.

Features

• 📺 HLS Playback: Stream HLS video content with ease.
• 🎛️ Player Controls: Play, pause, set source, and destroy the player programmatically.
• 🔄 Event Handling: Listen to player events (play, pause, ended, errors, fullscreen, etc.).
• 🛠️ Customizable: Pass options directly to the Zerorate Player SDK.
• 📱 Cross-Platform: Works on both iOS and Android.

Installation

First, install the package and its peer dependencies in your React Native project:

npm install zerorate-player-native react-native-webview

Or with Yarn:

yarn add zerorate-player-native react-native-webview

Note:
react and react-native are peer dependencies. Make sure they are installed in your project.

Usage

import React, { useRef } from "react";
import ZeroratePlayerNative from "zerorate-player-native";

const playerOptions = {
  // Your Zerorate Player SDK options here
  source: "https://your-hls-url.m3u8",
  // ...other options
};

export default function VideoScreen() {
  const playerRef = useRef(null);

  // Example: Play the video programmatically
  const handlePlay = () => {
    playerRef.current?.play();
  };

  // Handle player events
  const handleEvent = (type, detail) => {
    console.log("Player event:", type, detail);
  };

  return (
    <>
      <ZeroratePlayerNative
        ref={playerRef}
        options={playerOptions}
        onEvent={handleEvent}
        style={{ flex: 1 }}
      />
      {/* Example control */}
      <Button title="Play" onPress={handlePlay} />
    </>
  );
}

Props

| Prop | Type | Required | Description | | --------- | -------- | -------- | -------------------------------------------------- | | options | object | Yes | Options to initialize the Zerorate Player SDK. | | onEvent | function | No | Callback for player events: (type, detail) => {} | | style | object | No | Style for the WebView container. |

Ref Methods

You can control the player via a ref:

| Method | Arguments | Description | | ---------------- | ------------- | --------------------------- | | play() | — | Play the video | | pause() | — | Pause the video | | destroy() | — | Destroy the player instance | | setSource(src) | src: string | Change the video source |

Example:

playerRef.current?.setSource("https://new-url.m3u8");

Player Events

The following events are sent to the onEvent callback:

• zerorate-sdk-error
• media-play
• media-pause
• media-ended
• volume-changed
• enter-fullscreen
• exit-fullscreen

Example:

const handleEvent = (type, detail) => {
  if (type === "media-play") {
    // Video started playing
  }
};

Troubleshooting

Invalid Hook Call / useRef of null

If you see errors like:

• Invalid hook call. Hooks can only be called inside of the body of a function component.
• Cannot read property 'useRef' of null

Make sure:

• You have only one version of react and react-native in your app.
• You have installed zerorate-player-native from npm, not via a local path or symlink (unless using yalc).
• You have cleared your app's node_modules, lock files, and Metro cache:

  rm -rf node_modules package-lock.json yarn.lock
  npm install
  npx react-native start --reset-cache

Contributing

1. Fork this repo and clone it.
2. Install dependencies: npm install
3. Make your changes and add tests if needed.
4. Open a pull request!

License

MIT

Author

Deji Busari