@broadcastingplatforms/player 0.0.0-dev.3802fed → 0.0.0-dev.7888976

package/README.md

@@ -0,0 +1,157 @@
+# @broadcastingplatforms/player
+
+Universal video player web component built with Lit. Supports HLS, WebRTC (via nanoStream), and LiveKit.
+
+## Installation
+
+```bash
+npm install @broadcastingplatforms/player
+# or
+pnpm add @broadcastingplatforms/player
+```
+
+## Standalone vs Non-Standalone
+
+### Standalone Bundle
+
+Use the standalone bundle when you want a single file with all dependencies (HLS.js, etc.) bundled. Ideal for CDN usage or simple HTML pages.
+
+```html
+<script type="module" src="https://unpkg.com/@broadcastingplatforms/player/dist/bp-player.standalone.mjs"></script>
+
+<bp-player
+  source='{"sources":[{"type":"video","url":"https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"}]}'
+  muted
+  autoplay
+></bp-player>
+```
+
+### Non-Standalone (Bundler)
+
+Use the standard import when using a bundler (Vite, webpack, etc.). Dependencies are external and tree-shakeable.
+
+```ts
+import '@broadcastingplatforms/player';
+```
+
+```html
+<bp-player
+  source='{"sources":[{"type":"video","url":"https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"}]}'
+  muted
+  autoplay
+></bp-player>
+```
+
+## Basic Usage
+
+### HLS Video (Big Buck Bunny)
+
+```html
+<bp-player
+  source='{"sources":[{"type":"video","url":"https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"}],"poster":"https://peach.blender.org/wp-content/uploads/bbb-splash.png"}'
+  muted
+  autoplay
+></bp-player>
+```
+
+### With Default UI
+
+```html
+<bp-default-ui
+  source='{"sources":[{"type":"video","url":"https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8"}]}'
+></bp-default-ui>
+```
+
+### Programmatic Control
+
+```ts
+import { BPPlayer, type SourceDescription } from '@broadcastingplatforms/player';
+
+const player = document.querySelector('bp-player') as BPPlayer;
+
+// Set source via property (object)
+player.source = {
+  sources: [{ type: 'video', url: 'https://example.com/stream.m3u8' }],
+  poster: 'https://example.com/poster.jpg'
+};
+
+player.addEventListener('ready', (e) => {
+  const core = e.detail; // PlayerCore instance
+  
+  core.play();
+  core.pause();
+  core.seek(30); // seek to 30 seconds
+  core.setVolume(0.5);
+  core.setMuted(true);
+  
+  // Access current state
+  console.log(core.state.currentTime);
+  console.log(core.state.duration);
+  console.log(core.state.paused);
+});
+```
+
+## Attributes
+
+Attributes can be set as JSON strings or as JavaScript properties.
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `source` | `SourceDescription` (JSON) | Source description with `sources` array and optional `poster` |
+| `config` | `ProviderConfig` (JSON) | Provider configuration (HLS, NanoPlayer, LiveKit, BPLive) |
+| `autoplay` | `boolean` | Auto-start playback |
+| `muted` | `boolean` | Start muted |
+| `loop` | `boolean` | Loop playback |
+
+### SourceDescription
+
+```ts
+interface SourceDescription {
+  sources: PlayerSource[];
+  poster?: string;
+}
+```
+
+### Analytics
+
+Connect analytics via the `ready` event using `@broadcastingplatforms/web-connectors`:
+
+```html
+<bp-player
+  id="player"
+  source='{"sources":[{"type":"video","url":"..."}]}'
+></bp-player>
+
+<script type="module">
+  import { createMuxConnector } from '@broadcastingplatforms/web-connectors/mux';
+
+  document.getElementById('player').addEventListener('ready', (e) => {
+    // Auto-destroys when player is destroyed
+    createMuxConnector(e.detail, {
+      envKey: 'your-mux-env-key',
+      data: { video_title: 'My Video' }
+    });
+  });
+</script>
+```
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `ready` | `PlayerCore` | Fired when player is ready |
+| `play` | - | Playback started |
+| `pause` | - | Playback paused |
+| `ended` | - | Playback ended |
+| `timeupdate` | - | Current time updated |
+| `error` | - | Playback error occurred |
+
+## Custom Video Elements
+
+For advanced use cases, you can use the custom video elements directly:
+
+```ts
+import { HlsVideoElement, NanoVideoElement, LiveKitVideoElement } from '@broadcastingplatforms/player/elements';
+```
+
+These are [media-chrome](https://www.media-chrome.org/) compatible custom elements.