@zezosoft/zezo-ott-react-native-video-player/README.md

React Native OTT Video Player for Android & iOS. Supports playlists, seasons, auto-next playback, subtitles, theming, analytics, fullscreen mode, and custom controls. 🚀 Powered by ZezoSoft.

# 🎬 ZezoOTT Video Player

The **ZezoOTT Video Player** is a powerful React Native component crafted for OTT platforms.  
It delivers a **seamless full-screen video playback experience**, powered by a centralized **VideoPlayer Store** for state management.

---

## ✨ Features

- 📺 **Episode navigation & Seasons support**
- 📊 **Watch progress tracking & analytics**
- 🎨 **Custom theming**
- 🔄 **Auto-next playback**
- 🎬 **Playlist & seasons integration**
- 🗄️ **Centralized store for playback state, tracks & UI**
- 📱 **Optimized for React Native OTT apps**
- 🛠 **Minimal configuration, production-ready**

---

## 📦 Installation

```bash
yarn add @zezosoft/zezo-ott-react-native-video-player
```

or

```bash
npm install @zezosoft/zezo-ott-react-native-video-player
```

---

## ⚙️ VideoPlayer Props

| Prop                | Type                                                                                | Description                                                                  |
| ------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **onClose**         | `() => void`                                                                        | Triggered when the player is closed.                                         |
| **isFocused**       | `boolean`                                                                           | Controls playback focus. Automatically pauses when the screen is not active. |
| **seekTime**        | `number \| null`                                                                    | Starts playback from a given time (in seconds).                              |
| **mode**            | `'fullscreen' \| 'normal'`                                                          | Sets the display mode of the player.                                         |
| **onSeek**          | `(time: number) => void`                                                            | Fired when the user manually seeks to a new playback position.               |
| **autoNext**        | `boolean`                                                                           | Automatically plays the next episode/video after completion.                 |
| **event**           | `{ onPressEpisode?: ({ episode }: { episode: MediaEpisode }) => Promise<boolean> }` | Event hooks (e.g. custom handling for episode selection).                    |
| **theme**           | `Partial<VideoPlayerTheme>`                                                         | Customize the look & feel of the player (colors, metrics, etc.).             |
| **onWatchProgress** | `(progress: ExtendedWatchProgress) => void`                                         | Reports playback analytics such as watch time, current time, and completion. |

---

## 🚀 Usage Examples

### ▶️ Basic Example

```tsx
import React from 'react';
import { VideoPlayer } from '@zezosoft/zezo-ott-react-native-video-player';

export default function App() {
  return (
    <VideoPlayer
      isFocused={true}
      onClose={() => console.log('Player closed')}
      autoNext={true}
      onWatchProgress={(progress) => {
        console.log('Watch Progress:', progress);
      }}
    />
  );
}
```

### 🔄 Auto-Next Episodes

```tsx
<VideoPlayer
  autoNext={true}
  event={{
    onPressEpisode: async ({ episode }) => {
      console.log('Next episode:', episode.title);
      return true; // return false to block playback
    },
  }}
/>
```

### 🎨 Theming Example

```tsx
<VideoPlayer
  theme={{
    colors: {
      primary: '#E50914',
      background: '#000000',
      onBackground: '#FFFFFF',
    },
    metrics: {
      controlButtonSize: 42,
    },
  }}
/>
```

### 📺 Playlist & Seasons Setup

```tsx
// ContentDetailsScreen.tsx
import { useVideoPlayerStore } from '@zezosoft/zezo-ott-react-native-video-player';
import { useNavigation } from '@react-navigation/native';

export default function ContentDetailsScreen({ contentData }) {
  const {
    resetStore,
    setPlayList,
    setContentSeasons,
    setActiveSeason,
    setCurrentTrackIndex,
    setActiveTrack,
  } = useVideoPlayerStore();
  const navigation = useNavigation();

  const handlePlay = () => {
    resetStore();
    setContentSeasons(contentData.seasons);
    setActiveSeason(contentData.seasons[0]);

    const playlist = contentData.seasons[0].episodes.map((ep) => ({
      id: ep.id,
      title: ep.name,
      contentId: contentData.id,
      sourceLink: ep.sourceLink,
      type: contentData.type,
    }));

    setPlayList(playlist);
    setCurrentTrackIndex(0);
    setActiveTrack(playlist[0]);

    navigation.navigate('VideoPlayerScreen');
  };

  return <Button title="Play" onPress={handlePlay} />;
}
```

```tsx
// VideoPlayerScreen.tsx
import { VideoPlayer } from '@zezosoft/zezo-ott-react-native-video-player';

export default function VideoPlayerScreen() {
  return <VideoPlayer isFocused={true} autoNext={true} />;
}
```

---

# 🗄️ Video Player Store

The **VideoPlayerStore** is a centralized state store that powers the ZezoOTT Video Player.  
It manages **playback state, tracks, UI controls, analytics, and content navigation**.

---

## 🚀 Store Features

- Manage **playback state**: current time, duration, buffering, playback rate
- Handle **tracks**: audio, subtitles, video quality
- Control **UI state**: controls visibility, settings modal, skip/next episode
- Track **content structure**: playlists, seasons, active season/episode
- Support **analytics**: watch time, view count, error handling

---

## ⚡ Store Usage Example

```tsx
import { useVideoPlayerStore } from '@zezosoft/zezo-ott-react-native-video-player';
import React from 'react';

export default function VideoPlayerExample() {
  const {
    setPlayList,
    setActiveSeason,
    setActiveTrack,
    setContentSeasons,
    setCurrentTrackIndex,
    resetStore,
    playList,
    activeTrack,
    activeSeason,
  } = useVideoPlayerStore();

  const contentData = {
    id: 'movie123',
    type: 'series',
    name: 'My Series',
    seasons: [
      {
        id: 'season1',
        name: 'Season 1',
        seasonNumber: 1,
        episodes: [
          {
            id: 'ep1',
            name: 'Episode 1',
            sourceLink: 'https://example.com/ep1.mp4',
          },
          {
            id: 'ep2',
            name: 'Episode 2',
            sourceLink: 'https://example.com/ep2.mp4',
          },
        ],
      },
    ],
  };

  const setupPlayer = () => {
    resetStore();
    setContentSeasons(contentData.seasons);
    setActiveSeason(contentData.seasons[0]);

    const playlist = contentData.seasons[0].episodes.map((ep) => ({
      id: ep.id,
      title: ep.name,
      contentId: contentData.id,
      sourceLink: ep.sourceLink,
      type: contentData.type,
    }));

    setPlayList(playlist);
    setCurrentTrackIndex(0);
    setActiveTrack(playlist[0]);
  };

  return (
    <div>
      <button onClick={setupPlayer}>Load Series</button>
      <h3>Active Season: {activeSeason?.name}</h3>
      <ul>
        {playList.map((track) => (
          <li key={track.id}>
            {track.title} {activeTrack?.id === track.id ? '(Playing)' : ''}
          </li>
        ))}
      </ul>
    </div>
  );
}
```

---

## 📝 Notes & Best Practices

- 🔄 **Always call `resetStore()`** before loading new content.
- 🎚️ **Playback rate** requires both `rate` and `label` in sync.
- 🕹️ **Controls auto-hide** is managed by `controlsTimer`.
- 🌐 **Track selections** depend on available `OnLoadData` — always null-check.
- 📊 **Analytics props** integrate with your analytics pipeline.
- ⚠️ **Error handling**: Use `setError` for surfacing playback issues.
- 🎬 **Seasons & episodes**: Update both `contentSeasons` and `activeSeason` before setting playlist.

---

## 📌 Fullscreen Notes

If fullscreen doesn’t work, ensure you install **react-native-orientation-locker**:

```bash
yarn add react-native-orientation-locker
# or
npm install react-native-orientation-locker
```

🔗 Known issues: [react-native-orientation-locker issues](https://github.com/wonday/react-native-orientation-locker/issues)

---

## 🔗 Demo App

👉 [Zezo OTT Demo App](https://github.com/Zezo-Soft/zezo-ott-demo-app)

---

## 👨‍💻 Developer

Made with passion by:

<p>
  <a href="https://github.com/Naresh-Dhamu" target="_blank">
    <img src="https://avatars.githubusercontent.com/u/89912059?v=4" width="80" height="80" alt="Naresh Dhamu" style="border-radius: 50%; margin-left:10px">
    <br />
    <strong>Naresh Dhamu</strong>
  </a>
</p>

---

## 📄 License

Licensed under the [MIT License](LICENSE).

---

<p align="center">
  ⚡ Powered by <a href="https://zezosoft.com" target="_blank"><strong>ZezoSoft</strong></a>
</p>