@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

``bash
npm install @connectedxm/stream-player
`

Requirements

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

Usage

`tsx
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 (



);
}
`

Props

$3

| 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 | ❌ | Custom hls.js configuration options |

$3

| 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

$3

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

`tsx
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:

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

Development

`bash


Install dependencies

npm install

Start dev server

npm run dev

Build library

npm run build

Run tests

npm test
``

License

MIT