react-native-cmcd-player

An advanced React Native video player with built-in CMCD (Common Media Client Data) support, utilizing ExoPlayer (Android) and AVPlayer (iOS) for high-performance streaming.

> Note: CMCD (Common Media Client Data) enables media players to communicate playback health and status to CDNs, helping improve QoS and network efficiency.

---

Status

| Platform | Engine | Status |
| :--- | :--- | :--- |
| Android | ExoPlayer (Media3) | Supported |
| iOS | AVFoundation (AVPlayer) | Supported |

---

Prerequisites

This library includes custom native code and does not work with Expo Go.

- Android: Requires a bare React Native project or Expo Development Build.
- iOS: Requires a bare React Native project or Expo Development Build. macOS is required for iOS development.

$3

To run the example app or your project locally:

Android:
``bash
npx expo run:android
`

iOS:
`bash
npx expo run:ios
`

---

Features

$3


- CMCD Support: Automatically injects CMCD headers (CMCD-Request, CMCD-Object, etc.) into HLS/DASH requests.
- Real-time Data: Exposes raw CMCD data to JavaScript via onCmcdData event.
- Adaptive Quality: Events for onTracksAvailable to build custom quality selectors.

$3

- Media3 ExoPlayer: Built on the latest androidx.media3 stack (v1.9.0).
- Cleartext Support: Enabled for playing HTTP streams during development.

$3

- Native AVPlayer: Seamless integration with the standard iOS media framework.
- Smart Interception: Uses AVAssetResourceLoaderDelegate for efficient CMCD header injection.

---

Installation

`bash
npx expo install react-native-cmcd-player
`

> Tip: For standard React Native projects:
> npm install react-native-cmcd-player or yarn add react-native-cmcd-player

---

Usage

`tsx
import { useCallback, useRef } from "react";
import { View, findNodeHandle, Button } from "react-native";
import CmcdPlayerModule, {
CmcdPlayerView,
CmcdDataEvent,
} from "react-native-cmcd-player";

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

const handleCmcdData = useCallback(
(event: { nativeEvent: CmcdDataEvent }) => {
console.log("CMCD Data Received:", event.nativeEvent);
},
[],
);

const playVideo = () => {
const viewTag = findNodeHandle(playerRef.current);
if (viewTag) {
CmcdPlayerModule.play(viewTag);
}
};

return (

ref={playerRef}
style={{ flex: 1, width: "100%", height: 300 }}
sourceUrl="https://example.com/playlist.m3u8"
contentId="my-content-id"
sessionId="my-session-id"
onCmcdData={handleCmcdData}
showControls={true}
/>


);
}
`

---

Props (CmcdPlayerView)

| Prop | Type | Description |
| :--- | :--- | :--- |
| sourceUrl | string | The URL of the HLS (.m3u8) or DASH (.mpd) stream. |
| contentId | string | Custom Content ID for CMCD (cid). |
| sessionId | string | Custom Session ID for CMCD (sid). |
| showControls | boolean | Whether to show the native player controls. Default: true. |
| paused | boolean | Control playback state. |
| muted | boolean | Control audio mute state. |
| seekToPosition | number | Seek to a specific timestamp (in seconds). |
| onCmcdData | function | Event callback when a CMCD header is sent. |
| onTracksAvailable | function | Fired when track info (video qualities, audio, subs) is ready. |
| onProgress | function | Updates current playback time and buffer. |
| onPlayerError | function | Fired when playback fails. |

---

Methods (CmcdPlayerModule)

Methods require viewTag obtained via findNodeHandle(ref).

- play(viewTag)
- pause(viewTag)
- togglePlayPause(viewTag)
- seekTo(viewTag, seconds)
- seekToLive(viewTag)
- setMuted(viewTag, muted)
- toggleMute(viewTag)
- selectVideoQuality(viewTag, index, trackIndex)
- selectAudioTrack(viewTag, index, trackIndex)
- selectSubtitleTrack(viewTag, index, trackIndex)`

---

License

MIT © nunoazevedo