@stinkycomputing/web-live-player 0.1.1 → 0.1.3

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/index.d.ts

@@ -12,7 +12,7 @@ export * from './sources/stream-source';
 export { BasePlayer } from './player/base-player';
 export type { BasePlayerConfig } from './player/base-player';
 export { LiveVideoPlayer, createPlayer } from './player/live-player';
-export type { PlayerConfig, PlayerStats, PlayerState } from './player/live-player';
+export type { PlayerConfig, PlayerStats, PlayerState, BandwidthStats } from './player/live-player';
 export { FileVideoPlayer, createFilePlayer } from './player/file-player';
 export type { FilePlayerConfig, FilePlayerState, FilePlayerStats, FilePlayMode } from './player/file-player';
 export { createStandaloneMoQSource, StandaloneMoQSource } from './sources/standalone-moq-source';
@@ -30,6 +30,6 @@ export { FileAudioPlayer } from './audio/file-audio-player';
 export { LiveAudioPlayer } from './audio/live-audio-player';
 export type { LiveAudioConfig } from './audio/live-audio-player';
 export { FrameScheduler } from './scheduling/frame-scheduler';
-export type { FrameTiming, LatencyStats, SchedulerStatus, SchedulerConfig } from './scheduling/frame-scheduler';
+export type { FrameTiming, LatencyStats, SchedulerStatus, SchedulerConfig, PacketTimingEntry } from './scheduling/frame-scheduler';
 export { SesameBinaryProtocol } from './protocol/sesame-binary-protocol';
 export type { ParsedData, HeaderData, HeaderCodecData } from './protocol/sesame-binary-protocol';

package/dist/player/live-player.d.ts

@@ -21,6 +21,14 @@ export interface PlayerConfig {
  * Player state
  */
 export type PlayerState = 'idle' | 'playing' | 'paused' | 'error';
+/**
+ * Bandwidth statistics
+ */
+export interface BandwidthStats {
+    videoBytesPerSecond: number;
+    audioBytesPerSecond: number;
+    totalBytesPerSecond: number;
+}
 /**
  * Player statistics
  */
@@ -36,6 +44,7 @@ export interface PlayerStats {
     streamHeight: number;
     frameRate: number;
     latency: LatencyStats | null;
+    bandwidth: BandwidthStats | null;
 }
 /**
  * Player event types
@@ -84,6 +93,13 @@ export declare class LiveVideoPlayer extends BasePlayer<PlayerState> {
     private ownsAudioContext;
     private audioCodecData;
     private arrivalTimes;
+    private keyframeStatus;
+    private videoBytesReceived;
+    private audioBytesReceived;
+    private lastBandwidthUpdateTime;
+    private lastVideoBytesReceived;
+    private lastAudioBytesReceived;
+    private currentBandwidth;
     constructor(config?: PlayerConfig);
     /**
      * Enable or disable debug logging at runtime
@@ -164,6 +180,14 @@ export declare class LiveVideoPlayer extends BasePlayer<PlayerState> {
      * Get player statistics
      */
     getStats(): PlayerStats;
+    /**
+     * Update bandwidth statistics
+     */
+    private updateBandwidthStats;
+    /**
+     * Get packet timing history for visualization/debugging
+     */
+    getPacketTimingHistory(): import('..').PacketTimingEntry[];
     /**
      * Subscribe to player events (typed overload)
      */

package/dist/scheduling/frame-scheduler.d.ts

@@ -42,6 +42,23 @@ export interface SchedulerStatus {
     driftCorrections: number;
     latency: LatencyStats | null;
 }
+/**
+ * Packet timing entry for visualization
+ */
+export interface PacketTimingEntry {
+    /** Time packet arrived (performance.now()) */
+    arrivalTime: number;
+    /** Time since previous packet (ms) */
+    intervalMs: number;
+    /** Stream timestamp (us) */
+    streamTimestampUs: number;
+    /** Whether this was a keyframe */
+    isKeyframe: boolean;
+    /** Decode latency (ms) */
+    decodeLatencyMs: number;
+    /** Whether frame was dropped */
+    wasDropped: boolean;
+}
 export interface SchedulerConfig<T> {
     /** Target buffer delay in milliseconds (0 = bypass mode, always return latest) */
     bufferDelayMs?: number;
@@ -81,6 +98,9 @@ export declare class FrameScheduler<T> {
     private dequeueCount;
     private latencyHistory;
     private latencyHistorySize;
+    private packetTimingHistory;
+    private packetTimingHistorySize;
+    private lastPacketArrivalTime;
     private stats;
     private logger;
     private onFrameDropped?;
@@ -90,7 +110,7 @@ export declare class FrameScheduler<T> {
     /** Effective drift threshold - scales with buffer target for low-latency mode */
     private get effectiveDriftThresholdMs();
     /** Enqueue a decoded frame with timing information */
-    enqueue(frame: T, timestampUs: number, timing: FrameTiming): void;
+    enqueue(frame: T, timestampUs: number, timing: FrameTiming, isKeyframe?: boolean): void;
     /** Dequeue frame for rendering at given real time (milliseconds) */
     dequeue(realTimeMs: number): T | null;
     /** Bypass mode: return latest frame, drop rest */
@@ -119,4 +139,6 @@ export declare class FrameScheduler<T> {
     logStatus(): void;
     /** Reset statistics */
     resetStats(): void;
+    /** Get packet timing history for visualization */
+    getPacketTimingHistory(): PacketTimingEntry[];
 }

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

@@ -18,6 +18,7 @@ export interface MP4FileInfo {
     bitrate?: number;
     audioChannels?: number;
     audioSampleRate?: number;
+    isMoovAtStart?: boolean;
 }
 /**
  * Sample ready for decoding
@@ -54,6 +55,7 @@ export declare class MP4FileSource {
     private totalVideoSamples;
     private totalAudioSamples;
     private samplesRequested;
+    private isProgressiveLoading;
     private fileSize;
     private loadedBytes;
     private videoDescription;
@@ -73,9 +75,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)
      */