@connectedxm/stream-player

A React component for playing HLS live streams from Cloudflare Stream with built-in controls, quality selection, and multi-language support.

Features

• 🎬 HLS Playback — Powered by hls.js with optimized defaults for live streaming
• 🌐 Multi-language Streams — Switch between multiple stream inputs (e.g., different audio languages)
• 📺 Adaptive Quality — Automatic bitrate adaptation with manual quality override
• 🎛️ Built-in Controls — Play/pause, volume, quality selector, language selector, and fullscreen
• 🔄 Auto-reconnect — Automatically reloads when a stream comes back online
• 📱 Responsive — Works across desktop and mobile browsers
• 🎨 Styled with Tailwind — Modern, customizable UI

Installation

npm install @connectedxm/stream-player

Requirements

• React 19+
• A Cloudflare Stream account with live input(s)

Usage

import { StreamPlayer } from "@connectedxm/stream-player";
import "@connectedxm/stream-player/styles.css";

const CLOUDFLARE_STREAM_DOMAIN = "customer-xxxxx.cloudflarestream.com";

const streamInputs = [
  {
    id: "1",
    name: "English",
    cloudflareId: "your-cloudflare-stream-id",
    locale: "en",
  },
  {
    id: "2",
    name: "Spanish",
    cloudflareId: "your-spanish-stream-id",
    locale: "es",
  },
];

function App() {
  return (
    <div className="w-full aspect-video">
      <StreamPlayer
        streamInputs={streamInputs}
        cloudflareStreamDomain={CLOUDFLARE_STREAM_DOMAIN}
        preferredLocale="en"
        onError={(error) => console.error("Stream error:", error)}
      />
    </div>
  );
}

Props

StreamPlayerProps

| Prop | Type | Required | Description | | ------------------------ | ------------------------------ | -------- | --------------------------------------------- | | streamInputs | BaseStreamInput[] | ✅ | Array of stream inputs to play | | cloudflareStreamDomain | string | ✅ | Your Cloudflare Stream customer subdomain | | preferredLocale | string | ❌ | Preferred locale for initial stream selection | | onError | (error: StreamError) => void | ❌ | Callback when a stream error occurs | | hlsConfig | Partial<Hls.Config> | ❌ | Custom hls.js configuration options |

BaseStreamInput

| Property | Type | Required | Description | | -------------- | -------- | -------- | ----------------------------------------- | | id | string | ✅ | Unique identifier for the stream input | | name | string | ✅ | Display name (shown in language selector) | | cloudflareId | string | ✅ | Cloudflare Stream video/live input ID | | locale | string | ❌ | Locale code (e.g., "en", "es") |

Hooks

useStreamPlayer

For advanced use cases, you can use the underlying hook directly to build custom player UIs:

import { useStreamPlayer } from "@connectedxm/stream-player";

const {
  isLive,
  hasError,
  playing,
  volume,
  muted,
  qualities,
  currentQuality,
  handlePlayPause,
  handleVolumeChange,
  handleMuteToggle,
  handleQualityChange,
} = useStreamPlayer({
  cloudflareId: "your-stream-id",
  cloudflareStreamDomain: "customer-xxxxx.cloudflarestream.com",
  videoRef: videoRef,
  onError: (error) => console.error(error),
  hlsConfig: {},
});

HLS Configuration

The player comes with sensible defaults optimized for live streaming:

• Buffer: 60s max buffer, 15s back buffer
• Latency: 8s live sync, 20s max latency before seeking to live
• ABR: Aggressive downgrade (0.8), cautious upgrade (0.2)
• Resilience: 6 retry attempts, 20s timeouts

You can override any hls.js config option via the hlsConfig prop:

<StreamPlayer
  streamInputs={inputs}
  cloudflareStreamDomain={domain}
  hlsConfig={{
    lowLatencyMode: true,
    liveSyncDuration: 3,
  }}
/>

Development

# Install dependencies
npm install

# Start dev server
npm run dev

# Build library
npm run build

# Run tests
npm test

License

MIT