@connectedxm/stream-player 0.0.1

package/README.md

@@ -0,0 +1,154 @@
+# @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](https://github.com/video-dev/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 (
+    <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:
+
+```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
+<StreamPlayer
+  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