@stinkycomputing/web-live-player 0.1.1 → 0.1.2

package/README.md

@@ -9,6 +9,7 @@ A framework-agnostic video streaming library for playing back **Sesame** video s
 - **MoQ support** - Native Media over QUIC protocol support via `stinky-moq-js`
 - **Pluggable stream sources** - Use dependency injection to provide video data from any transport
 - **Frame scheduling** - Automatic buffering and drift correction for smooth playback
+- **Optimized file loading** - Range-based chunked loading for fast playback of large MP4 files
 - **No framework dependencies** - Works with vanilla JS, React, Three.js, or any other framework
 
 ## Installation
@@ -17,12 +18,6 @@ A framework-agnostic video streaming library for playing back **Sesame** video s
 npm install @stinkycomputing/web-live-player
 ```
 
-For MoQ support, also install:
-
-```bash
-npm install stinky-moq-js
-```
-
 ## Quick Start
 
 ### Using with MoQ (Standalone)
@@ -33,7 +28,7 @@ import { createPlayer, createStandaloneMoQSource } from '@stinkycomputing/web-li
 // Create player
 const player = createPlayer({
   preferredDecoder: 'webcodecs-hw',
-  bufferSizeFrames: 3,
+  bufferDelayMs: 100,
 });
 
 // Create MoQ source
@@ -42,6 +37,7 @@ const moqSource = createStandaloneMoQSource({
   namespace: 'live/stream',
   subscriptions: [
     { trackName: 'video', streamType: 'video' },
+    { trackName: 'audio', streamType: 'audio' },
   ],
 });
 
@@ -62,23 +58,6 @@ function render(timestamp) {
 requestAnimationFrame(render);
 ```
 
-### Using with Elmo's MoQSession
-
-```typescript
-import { createPlayer } from '@stinkycomputing/web-live-player';
-import { MoQDiscoveryUtils } from '@elmo/core';
-
-// Find session from Elmo's node tree
-// MoQSessionNode implements IStreamSource directly
-const session = MoQDiscoveryUtils.findMoQSession(currentNode, 'my-session');
-
-// Create and configure player - session can be used directly as stream source
-const player = createPlayer();
-player.setStreamSource(session);
-player.setTrackFilter('video-track');
-player.play();
-```
-
 ### Custom Stream Source
 
 ```typescript
@@ -109,6 +88,60 @@ player.setStreamSource(source);
 player.play();
 ```
 
+### File Playback
+
+For playing MP4 files from URLs or local files:
+
+```typescript
+import { createFilePlayer } from '@stinkycomputing/web-live-player';
+
+const filePlayer = createFilePlayer({
+  preferredDecoder: 'webcodecs-hw',
+  enableAudio: true,
+  debugLogging: false,
+  playMode: 'once', // or 'loop' for continuous playback
+});
+
+// Load from URL (with optimized chunked loading)
+await filePlayer.loadFromUrl('https://example.com/video.mp4');
+
+// Or load from File object (e.g., from file input)
+const file = fileInput.files[0];
+await filePlayer.loadFromFile(file);
+
+// Play the file
+filePlayer.play();
+
+// Render loop
+function render() {
+  const frame = filePlayer.getVideoFrame();
+  if (frame) {
+    ctx.drawImage(frame, 0, 0);
+    frame.close();
+  }
+  requestAnimationFrame(render);
+}
+requestAnimationFrame(render);
+
+// Seek to position (in seconds)
+await filePlayer.seek(30);
+
+// Listen to events
+filePlayer.on('ready', (info) => {
+  console.log(`Video loaded: ${info.width}x${info.height}, ${info.duration}s`);
+});
+
+filePlayer.on('progress', (loaded, total) => {
+  console.log(`Loading: ${(loaded / total * 100).toFixed(1)}%`);
+});
+```
+
+**Optimized Loading**: The file player uses HTTP Range requests to load large files in chunks (1MB each). This means:
+- Playback starts as soon as metadata is available (~1-2MB typically)
+- Remaining file loads in the background during playback
+- 10-30x faster time-to-first-frame for large files
+- Automatic fallback to full download if server doesn't support ranges
+
 ## API Reference
 
 ### `createPlayer(config?)`
@@ -116,10 +149,51 @@ player.play();
 Creates a new player instance.
 
 **Config options:**
-- `preferredDecoder`: `'webcodecs-hw'` | `'webcodecs-sw'` | `'wasm'` - Decoder preference
-- `bufferSizeFrames`: `number` - Target buffer size (default: 3)
+- `preferredDecoder`: `'webcodecs-hw'` | `'webcodecs-sw'` | `'wasm'` - Decoder preference (default: `'webcodecs-sw'`). Note: WASM decoder only supports H.264 Baseline profile.
+- `bufferDelayMs`: `number` - Buffer delay in milliseconds (default: 100)
+- `enableAudio`: `boolean` - Enable audio playback (default: true)
+- `videoTrackName`: `string | null` - Video track name for MoQ streams (default: `'video'`)
+- `audioTrackName`: `string | null` - Audio track name for MoQ streams (default: `'audio'`)
+- `debugLogging`: `boolean` - Enable debug logging
+
+### `createFilePlayer(config?)`
+
+Creates a file player instance for MP4 playback.
+
+**Config options:**
+- `preferredDecoder`: `'webcodecs-hw'` | `'webcodecs-sw'` | `'wasm'` - Decoder preference (default: `'webcodecs-sw'`)
+- `enableAudio`: `boolean` - Enable audio playback (default: true)
+- `audioContext`: `AudioContext` - Optional audio context (creates one if not provided)
+- `playMode`: `'once'` | `'loop'` - Play mode (default: `'once'`)
 - `debugLogging`: `boolean` - Enable debug logging
 
+### `FileVideoPlayer`
+
+File player class.
+
+**Methods:**
+- `loadFromUrl(url: string)` - Load MP4 from URL (uses range-based chunked loading)
+- `loadFromFile(file: File)` - Load MP4 from File object
+- `play()` - Start playback
+- `pause()` - Pause playback
+- `seek(timeSeconds: number)` - Seek to position
+- `getVideoFrame()` - Get current video frame for rendering
+- `getPosition()` - Get current position in seconds
+- `getDuration()` - Get duration in seconds
+- `getStats()` - Get playback statistics
+- `setVolume(volume: number)` - Set audio volume (0-1)
+- `setPlayMode(mode: 'once' | 'loop')` - Set play mode
+- `dispose()` - Clean up resources
+
+**Events:**
+- `ready` - Emitted when file is loaded and ready to play
+- `progress` - Emitted during file loading with (loaded, total) bytes
+- `statechange` - Emitted when player state changes
+- `ended` - Emitted when playback ends (in 'once' mode)
+- `loop` - Emitted when video loops (in 'loop' mode)
+- `seeked` - Emitted after seeking completes
+- `error` - Emitted on errors
+
 ### `LiveVideoPlayer`
 
 Main player class.
@@ -127,10 +201,13 @@ Main player class.
 **Methods:**
 - `setStreamSource(source: IStreamSource)` - Set the stream data source
 - `setTrackFilter(trackName: string)` - Filter for specific track
+- `connectToMoQRelay(relayUrl, namespace, options?)` - Connect directly to a MoQ relay
 - `play()` - Start playback
 - `pause()` - Pause playback
 - `getVideoFrame(timestampMs: number)` - Get frame for current render timestamp
 - `getStats()` - Get playback statistics
+- `setVolume(volume: number)` - Set audio volume (0-1)
+- `setDebugLogging(enabled: boolean)` - Enable/disable debug logging at runtime
 - `dispose()` - Clean up resources
 
 **Events:**
@@ -210,6 +287,8 @@ function render(timestamp: number) {
 
 ### Handling YUV Frames (WASM Decoder)
 
+> **Note:** The WASM decoder only supports **H.264 Baseline profile**. For Main or High profile streams, use `'webcodecs-hw'` or `'webcodecs-sw'` instead.
+
 When using the WASM decoder, the library automatically converts YUV frames to `VideoFrame` objects using the browser's native I420 support. The GPU handles YUV→RGB conversion, so you can use the same rendering code regardless of decoder:
 
 ```typescript
@@ -298,7 +377,6 @@ const player = createPlayer({
 Run the demo application:
 
 ```bash
-cd video-player
 npm install
 npm run dev
 ```

package/dist/sources/mp4-file-source.d.ts

@@ -54,6 +54,7 @@ export declare class MP4FileSource {
     private totalVideoSamples;
     private totalAudioSamples;
     private samplesRequested;
+    private isProgressiveLoading;
     private fileSize;
     private loadedBytes;
     private videoDescription;
@@ -73,9 +74,14 @@ export declare class MP4FileSource {
      */
     getAudioDescription(): Uint8Array | null;
     /**
-     * Load an MP4 file from a URL
+     * Load an MP4 file from a URL using range-based loading for better performance.
+     * Automatically falls back to full download if server doesn't support ranges.
      */
     loadFromUrl(url: string): Promise<MP4FileInfo>;
+    /**
+     * Continue loading remaining chunks in background after initial metadata is ready
+     */
+    private continueLoadingInBackground;
     /**
      * Load an MP4 file from a File object (e.g., from file input)
      */