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.

Running Locally

To run the example app or your project locally:

Android:

npx expo run:android

iOS:

npx expo run:ios

Features

Shared (Android & iOS)

• 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.

Android

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

iOS

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

Installation

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

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 (
    <View style={{ flex: 1 }}>
      <CmcdPlayerView
        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}
      />
      <Button title="Play" onPress={playVideo} />
    </View>
  );
}

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