playsvideo 0.2.0 → 0.3.0

package/README.md

@@ -67,6 +67,9 @@ engine.loadFile(file);
 // Or play from a URL (requires CORS + range request support)
 engine.loadUrl('https://example.com/video.mkv');
 
+// Or attach an external .srt/.vtt subtitle file after loading
+await engine.loadExternalSubtitle(subtitleFile);
+
 engine.destroy(); // clean up
 ```
 

package/dist/engine.d.ts

@@ -1,5 +1,6 @@
 import type { Source } from 'mediabunny';
 import type { FfmpegRunner, KeyframeIndex, SubtitleTrackInfo } from './pipeline/types.js';
+import type { TranscodeWorkerSnapshot } from './transcode-protocol.js';
 export type EnginePhase = 'idle' | 'demuxing' | 'ready' | 'error';
 export interface ReadyDetail {
     totalSegments: number;
@@ -14,6 +15,32 @@ export interface LoadingDetail {
     file?: File;
     url?: string;
 }
+export interface WasmWorkerState extends TranscodeWorkerSnapshot {
+    id: number;
+}
+export interface WorkerStateDetail {
+    workers: WasmWorkerState[];
+}
+export type SegmentPhase = 'requested' | 'queued' | 'prefetching' | 'processing' | 'ready' | 'cache-hit' | 'delivered' | 'canceled' | 'aborted' | 'error';
+export interface SegmentTimelineEvent {
+    phase: SegmentPhase;
+    atMs: number;
+    sizeBytes: number | null;
+    message: string | null;
+}
+export interface SegmentState {
+    index: number;
+    phase: SegmentPhase;
+    requestCount: number;
+    sizeBytes: number | null;
+    latencyMs: number | null;
+    error: string | null;
+    prefetched: boolean;
+    events: SegmentTimelineEvent[];
+}
+export interface SegmentStateDetail {
+    segments: SegmentState[];
+}
 export interface EngineOptions {
     /**
      * Number of internal audio transcode workers to create for worker-mode playback.
@@ -21,16 +48,25 @@ export interface EngineOptions {
      */
     transcodeWorkers?: number;
 }
+export interface ExternalSubtitleOptions {
+    label?: string;
+    language?: string;
+    kind?: 'subtitles' | 'captions';
+}
 interface EngineEventMap {
     ready: CustomEvent<ReadyDetail>;
     error: CustomEvent<ErrorDetail>;
     loading: CustomEvent<LoadingDetail>;
+    workerstatechange: CustomEvent<WorkerStateDetail>;
+    segmentstatechange: CustomEvent<SegmentStateDetail>;
 }
 export declare class PlaysVideoEngine extends EventTarget {
     readonly video: HTMLVideoElement;
     readonly options: Required<EngineOptions>;
     private worker;
     private transcodeWorkers;
+    private _transcodeWorkerStates;
+    private _segmentStates;
     private hls;
     private pendingSegments;
     private playlist;
@@ -38,7 +74,7 @@ export declare class PlaysVideoEngine extends EventTarget {
     private pendingInit;
     private pendingPlaylist;
     private segmentRequestTimes;
-    private subtitleBlobUrls;
+    private attachedSubtitleTracks;
     private _subtitleTracks;
     private _phase;
     private _totalSegments;
@@ -62,6 +98,8 @@ export declare class PlaysVideoEngine extends EventTarget {
     get durationSec(): number;
     get subtitleTracks(): SubtitleTrackInfo[];
     get passthrough(): boolean;
+    get transcodeWorkerStates(): WasmWorkerState[];
+    get segmentStates(): SegmentState[];
     constructor(video: HTMLVideoElement, options?: EngineOptions);
     loadFile(file: File, opts?: {
         keyframeIndex?: KeyframeIndex;
@@ -69,6 +107,8 @@ export declare class PlaysVideoEngine extends EventTarget {
     loadUrl(url: string, opts?: {
         keyframeIndex?: KeyframeIndex;
     }): void;
+    loadExternalSubtitle(file: File, options?: ExternalSubtitleOptions): Promise<void>;
+    clearExternalSubtitles(): void;
     /**
      * Load from an external Source (e.g. TorrentSource).
      *
@@ -91,6 +131,12 @@ export declare class PlaysVideoEngine extends EventTarget {
     destroy(): void;
     addEventListener<K extends keyof EngineEventMap>(type: K, listener: (ev: EngineEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
     addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    private dispatchWorkerStateChange;
+    private dispatchSegmentStateChange;
+    private handleTranscodeWorkerMessage;
+    private updateTranscodeWorkerState;
+    private noteSegmentState;
+    private handleWorkerSegmentState;
     private checkNativePlayback;
     private startPassthrough;
     private handleWorkerMessage;
@@ -102,6 +148,8 @@ export declare class PlaysVideoEngine extends EventTarget {
     private startHls;
     private addSubtitleTrack;
     private removeSubtitleTracks;
+    private showTextTrack;
+    private restoreDefaultTextTrack;
 }
 export {};
 //# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}

package/dist/engine.js

@@ -5,6 +5,7 @@ import { audioNeedsTranscode, createBrowserProber } from './pipeline/codec-probe
 import { demuxSource, getKeyframeIndex } from './pipeline/demux.js';
 import { generateVodPlaylist } from './pipeline/playlist.js';
 import { buildSegmentPlan } from './pipeline/segment-plan.js';
+import { parseSubtitleFile, subtitleDataToWebVTT } from './pipeline/subtitle.js';
 import { processSegmentWithAbort } from './pipeline/segment-processor.js';
 import { isAbortableSource } from './pipeline/source-signal.js';
 function defaultTranscodeWorkerCount() {
@@ -18,6 +19,8 @@ export class PlaysVideoEngine extends EventTarget {
     options;
     worker = null;
     transcodeWorkers = [];
+    _transcodeWorkerStates = [];
+    _segmentStates = new Map();
     hls = null;
     // Pending segment requests from hls.js custom loader
     pendingSegments = new Map();
@@ -28,7 +31,7 @@ export class PlaysVideoEngine extends EventTarget {
     pendingPlaylist = null;
     segmentRequestTimes = new Map();
     // Subtitle state
-    subtitleBlobUrls = [];
+    attachedSubtitleTracks = [];
     _subtitleTracks = [];
     // Public read-only state
     _phase = 'idle';
@@ -68,6 +71,17 @@ export class PlaysVideoEngine extends EventTarget {
     get passthrough() {
         return this._passthrough;
     }
+    get transcodeWorkerStates() {
+        return this._transcodeWorkerStates.map((worker) => ({ ...worker }));
+    }
+    get segmentStates() {
+        return Array.from(this._segmentStates.values())
+            .sort((a, b) => a.index - b.index)
+            .map((segment) => ({
+            ...segment,
+            events: segment.events.map((event) => ({ ...event })),
+        }));
+    }
     constructor(video, options = {}) {
         super();
         this.video = video;
@@ -91,6 +105,31 @@ export class PlaysVideoEngine extends EventTarget {
         this.worker.postMessage({ type: 'open-url', url });
         mlog(`open url=${url}`);
     }
+    async loadExternalSubtitle(file, options = {}) {
+        if (this._phase !== 'ready') {
+            throw new Error('Load a video before adding an external subtitle file');
+        }
+        const text = await file.text();
+        const data = parseSubtitleFile(text, file.name);
+        if (data.codec === 'ass' || data.codec === 'ssa') {
+            throw new Error('External .ass/.ssa subtitles are not supported yet');
+        }
+        const webvtt = subtitleDataToWebVTT(data);
+        this.clearExternalSubtitles();
+        this.addSubtitleTrack({
+            webvtt,
+            source: 'external',
+            label: options.label ?? file.name.replace(/\.[^.]+$/, ''),
+            language: options.language ?? 'und',
+            kind: options.kind ?? 'subtitles',
+            defaultTrack: true,
+            selectTrack: true,
+        });
+    }
+    clearExternalSubtitles() {
+        this.removeSubtitleTracks('external');
+        this.restoreDefaultTextTrack();
+    }
     /**
      * Load from an external Source (e.g. TorrentSource).
      *
@@ -135,9 +174,6 @@ export class PlaysVideoEngine extends EventTarget {
         this.initData = null;
         this.pendingSegments.clear();
         this.segmentRequestTimes.clear();
-        for (const url of this.subtitleBlobUrls)
-            URL.revokeObjectURL(url);
-        this.subtitleBlobUrls = [];
         this.removeSubtitleTracks();
         this._phase = 'demuxing';
         this._totalSegments = 0;
@@ -162,14 +198,12 @@ export class PlaysVideoEngine extends EventTarget {
         this._sourceAudioDecoderConfig = null;
         this._sourceInitSegment = null;
         this._sourceFfmpeg = null;
+        this._segmentStates.clear();
         this.dispatchEvent(new CustomEvent('loading', { detail }));
+        this.dispatchSegmentStateChange();
     }
     createWorker() {
-        // Variable indirection prevents Vite/Rollup from statically detecting this as a
-        // worker entry point. Consumers that only use loadSource() don't need the worker,
-        // but without this, bundlers try to resolve & bundle worker.js (which isn't in dist).
-        const workerPath = './worker.js';
-        this.worker = new Worker(new URL(workerPath, import.meta.url), { type: 'module' });
+        this.worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
         this.worker.onmessage = (e) => this.handleWorkerMessage(e);
         this.worker.onerror = (e) => {
             this._phase = 'error';
@@ -180,22 +214,44 @@ export class PlaysVideoEngine extends EventTarget {
         if (!this.worker || this.transcodeWorkers.length > 0 || this.options.transcodeWorkers <= 0) {
             return;
         }
-        const transcodeWorkerPath = './transcode-worker.js';
         for (let i = 0; i < this.options.transcodeWorkers; i++) {
-            const worker = new Worker(new URL(transcodeWorkerPath, import.meta.url), {
+            const worker = new Worker(new URL('./transcode-worker.js', import.meta.url), {
                 type: 'module',
             });
+            worker.onmessage = (event) => this.handleTranscodeWorkerMessage(i, event);
+            worker.onerror = (event) => {
+                this.updateTranscodeWorkerState(i, {
+                    phase: 'error',
+                    jobId: null,
+                    lastError: event.message || 'Transcode worker crashed',
+                });
+            };
             const channel = new MessageChannel();
             worker.postMessage({ type: 'connect' }, [channel.port2]);
             this.worker.postMessage({ type: 'transcode-port', id: i }, [channel.port1]);
             this.transcodeWorkers.push({ worker });
+            this._transcodeWorkerStates.push({
+                id: i,
+                phase: 'starting',
+                sourceCodec: null,
+                jobId: null,
+                inputBytes: null,
+                outputBytes: null,
+                totalMs: null,
+                ffmpegMs: null,
+                jobsCompleted: 0,
+                lastError: null,
+            });
         }
+        this.dispatchWorkerStateChange();
     }
     destroyTranscodeWorkers() {
         for (const handle of this.transcodeWorkers) {
             handle.worker.terminate();
         }
         this.transcodeWorkers = [];
+        this._transcodeWorkerStates = [];
+        this.dispatchWorkerStateChange();
     }
     destroy() {
         if (this.hls) {
@@ -215,18 +271,99 @@ export class PlaysVideoEngine extends EventTarget {
             this.video.removeAttribute('src');
             this.video.load();
         }
-        for (const url of this.subtitleBlobUrls)
-            URL.revokeObjectURL(url);
-        this.subtitleBlobUrls = [];
         this.removeSubtitleTracks();
         this.pendingSegments.clear();
         this.segmentRequestTimes.clear();
         this._phase = 'idle';
         this._passthrough = false;
+        this._segmentStates.clear();
+        this.dispatchSegmentStateChange();
     }
     addEventListener(type, listener, options) {
         super.addEventListener(type, listener, options);
     }
+    dispatchWorkerStateChange() {
+        this.dispatchEvent(new CustomEvent('workerstatechange', {
+            detail: {
+                workers: this.transcodeWorkerStates,
+            },
+        }));
+    }
+    dispatchSegmentStateChange() {
+        this.dispatchEvent(new CustomEvent('segmentstatechange', {
+            detail: {
+                segments: this.segmentStates,
+            },
+        }));
+    }
+    handleTranscodeWorkerMessage(id, event) {
+        const msg = event.data;
+        if (!msg || msg.type !== 'worker-state') {
+            return;
+        }
+        this.updateTranscodeWorkerState(id, msg.state);
+    }
+    updateTranscodeWorkerState(id, patch) {
+        const index = this._transcodeWorkerStates.findIndex((worker) => worker.id === id);
+        if (index === -1) {
+            return;
+        }
+        this._transcodeWorkerStates[index] = {
+            ...this._transcodeWorkerStates[index],
+            ...patch,
+            id,
+        };
+        this.dispatchWorkerStateChange();
+    }
+    noteSegmentState(index, phase, opts = {}) {
+        const existing = this._segmentStates.get(index);
+        const next = existing
+            ? {
+                ...existing,
+                events: [...existing.events],
+            }
+            : {
+                index,
+                phase,
+                requestCount: 0,
+                sizeBytes: null,
+                latencyMs: null,
+                error: null,
+                prefetched: false,
+                events: [],
+            };
+        next.phase = phase;
+        if (opts.incrementRequestCount) {
+            next.requestCount += 1;
+        }
+        if (opts.prefetched !== undefined) {
+            next.prefetched = opts.prefetched;
+        }
+        else if (phase === 'prefetching') {
+            next.prefetched = true;
+        }
+        if (opts.sizeBytes !== undefined) {
+            next.sizeBytes = opts.sizeBytes;
+        }
+        if (opts.latencyMs !== undefined) {
+            next.latencyMs = opts.latencyMs;
+        }
+        next.error = phase === 'error' ? (opts.message ?? next.error) : null;
+        next.events.push({
+            phase,
+            atMs: performance.now(),
+            sizeBytes: opts.sizeBytes ?? null,
+            message: opts.message ?? null,
+        });
+        this._segmentStates.set(index, next);
+        this.dispatchSegmentStateChange();
+    }
+    handleWorkerSegmentState(msg) {
+        this.noteSegmentState(msg.index, msg.phase, {
+            sizeBytes: msg.sizeBytes,
+            message: msg.message,
+        });
+    }
     checkNativePlayback(videoCodec, audioCodec) {
         const mime = this._pendingFileType;
         if (!mime)
@@ -327,18 +464,31 @@ export class PlaysVideoEngine extends EventTarget {
         }
         else if (msg.type === 'subtitle') {
             mlog(`subtitle arrived track=${msg.trackIndex} codec=${msg.codec} len=${msg.webvtt?.length}`);
-            this.addSubtitleTrack(msg.webvtt, msg.trackIndex);
+            this.addSubtitleTrack({
+                webvtt: msg.webvtt,
+                source: 'embedded',
+                trackIndex: msg.trackIndex,
+                defaultTrack: msg.trackIndex === 0,
+            });
+        }
+        else if (msg.type === 'segment-state') {
+            this.handleWorkerSegmentState(msg);
         }
         else if (msg.type === 'segment') {
             const pending = this.pendingSegments.get(msg.index);
             const reqTime = this.segmentRequestTimes.get(msg.index);
-            const latency = reqTime ? (performance.now() - reqTime).toFixed(1) : '?';
+            const latencyMs = reqTime ? performance.now() - reqTime : null;
+            const latency = latencyMs !== null ? latencyMs.toFixed(1) : '?';
             const size = msg.data?.byteLength ?? 0;
             this.segmentRequestTimes.delete(msg.index);
             if (pending) {
                 pending.resolve(msg.data);
                 this.pendingSegments.delete(msg.index);
             }
+            this.noteSegmentState(msg.index, 'delivered', {
+                sizeBytes: size,
+                latencyMs: latencyMs ?? undefined,
+            });
             mlog(`seg ${msg.index} arrived latency=${latency}ms size=${size} pending=${this.pendingSegments.size}`);
         }
         else if (msg.type === 'error') {
@@ -346,7 +496,8 @@ export class PlaysVideoEngine extends EventTarget {
             this._phase = 'error';
             this.dispatchEvent(new CustomEvent('error', { detail: { message: msg.message } }));
             // Reject all pending requests
-            for (const [, p] of this.pendingSegments) {
+            for (const [index, p] of this.pendingSegments) {
+                this.noteSegmentState(index, 'error', { message: msg.message });
                 p.reject(new Error(msg.message));
             }
             this.pendingSegments.clear();
@@ -371,6 +522,7 @@ export class PlaysVideoEngine extends EventTarget {
         }
         mlog(`req seg ${index} pending=${pendingCount}`);
         this.segmentRequestTimes.set(index, performance.now());
+        this.noteSegmentState(index, 'requested', { incrementRequestCount: true });
         return new Promise((resolve, reject) => {
             this.pendingSegments.set(index, { resolve, reject });
             this.worker.postMessage({ type: 'segment', index });
@@ -380,6 +532,7 @@ export class PlaysVideoEngine extends EventTarget {
         const pending = this.pendingSegments.get(index);
         if (pending) {
             mlog(`cancel seg ${index}`);
+            this.noteSegmentState(index, 'canceled');
             pending.reject(new DOMException('Segment aborted', 'AbortError'));
             this.pendingSegments.delete(index);
             this.segmentRequestTimes.delete(index);
@@ -631,36 +784,67 @@ export class PlaysVideoEngine extends EventTarget {
             mlog(`hls BUFFER_APPENDING type=${data.type}`);
         });
         this.hls.on(Hls.Events.ERROR, (_evt, data) => {
-            mlog(`hls ERROR fatal=${data.fatal} type=${data.type} details=${data.details}`);
+            const underlyingMessage = data.error?.message ?? data.reason ?? data.response?.text ?? data.err?.message ?? null;
+            mlog(`hls ERROR fatal=${data.fatal} type=${data.type} details=${data.details}${underlyingMessage ? ` message=${underlyingMessage}` : ''}`);
             if (data.fatal) {
                 console.error('hls.js fatal error:', data);
                 this._phase = 'error';
-                this.dispatchEvent(new CustomEvent('error', { detail: { message: `Playback error: ${data.details}` } }));
+                const message = underlyingMessage
+                    ? `Playback error: ${data.details} (${underlyingMessage})`
+                    : `Playback error: ${data.details}`;
+                this.dispatchEvent(new CustomEvent('error', { detail: { message } }));
             }
         });
         this.hls.loadSource('/virtual/playlist.m3u8');
         this.hls.attachMedia(this.video);
     }
-    addSubtitleTrack(webvtt, trackIndex) {
+    addSubtitleTrack({ webvtt, source, trackIndex, label, language, kind, defaultTrack = false, selectTrack = false, }) {
         const blob = new Blob([webvtt], { type: 'text/vtt' });
         const url = URL.createObjectURL(blob);
-        this.subtitleBlobUrls.push(url);
-        const info = this._subtitleTracks.find((t) => t.index === trackIndex);
+        const info = trackIndex === undefined
+            ? undefined
+            : this._subtitleTracks.find((t) => t.index === trackIndex);
         const track = document.createElement('track');
-        track.kind = info?.disposition.hearingImpaired ? 'captions' : 'subtitles';
+        track.kind = kind ?? (info?.disposition.hearingImpaired ? 'captions' : 'subtitles');
         track.src = url;
-        track.srclang = iso639_2to1(info?.language ?? 'und');
-        track.label = info?.name ?? languageLabel(info?.language ?? 'und', trackIndex);
-        if (trackIndex === 0) {
-            track.default = true;
-        }
+        track.srclang = normalizeSubtitleLanguageCode(language ?? info?.language ?? 'und');
+        track.label =
+            label ??
+                info?.name ??
+                languageLabel(info?.language ?? 'und', trackIndex ?? this.video.querySelectorAll('track').length);
+        track.default = defaultTrack;
         this.video.appendChild(track);
-        mlog(`subtitle track ${trackIndex} attached as <track kind=${track.kind} lang=${track.srclang}>`);
+        this.attachedSubtitleTracks.push({ element: track, url, source });
+        if (selectTrack) {
+            track.addEventListener('load', () => this.showTextTrack(track), { once: true });
+            queueMicrotask(() => this.showTextTrack(track));
+        }
+        mlog(`subtitle track ${trackIndex ?? 'external'} attached as <track kind=${track.kind} lang=${track.srclang}>`);
+    }
+    removeSubtitleTracks(source) {
+        const keep = [];
+        for (const attached of this.attachedSubtitleTracks) {
+            if (source && attached.source !== source) {
+                keep.push(attached);
+                continue;
+            }
+            attached.element.remove();
+            URL.revokeObjectURL(attached.url);
+        }
+        this.attachedSubtitleTracks = keep;
     }
-    removeSubtitleTracks() {
-        for (const track of Array.from(this.video.querySelectorAll('track'))) {
-            track.remove();
+    showTextTrack(track) {
+        for (let i = 0; i < this.video.textTracks.length; i++) {
+            this.video.textTracks[i].mode = 'disabled';
         }
+        track.track.mode = 'showing';
+    }
+    restoreDefaultTextTrack() {
+        const preferred = this.attachedSubtitleTracks.find((attached) => attached.element.default) ??
+            this.attachedSubtitleTracks[0];
+        if (!preferred)
+            return;
+        queueMicrotask(() => this.showTextTrack(preferred.element));
     }
 }
 /** Set to true to bypass native playback and force the remux pipeline (for testing). */
@@ -706,6 +890,11 @@ function iso639_2to1(code) {
     };
     return map[code] ?? code;
 }
+function normalizeSubtitleLanguageCode(code) {
+    if (code.length === 2)
+        return code;
+    return iso639_2to1(code);
+}
 function languageLabel(langCode, trackIndex) {
     const names = {
         eng: 'English',