playsvideo 0.2.1 → 0.4.0

package/dist/engine.js

@@ -1,10 +1,11 @@
 import Hls from 'hls.js';
 import { WasmFfmpegRunner } from './adapters/wasm-ffmpeg.js';
+import { createBrowserPlaybackCapabilities, evaluatePlaybackOptions, } from './playback-selection.js';
 import { createLocalAudioTranscoder, makeAacDecoderConfig } from './pipeline/audio-transcode.js';
-import { audioNeedsTranscode, createBrowserProber } from './pipeline/codec-probe.js';
 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';
@@ -38,6 +41,13 @@ export class PlaysVideoEngine extends EventTarget {
     _passthrough = false;
     _blobUrl = null;
     _pendingFileType = null;
+    _codecPath = {
+        mode: 'pipeline',
+        sourceVideo: { short: null, full: null },
+        sourceAudio: { short: null, full: null },
+        outputVideo: { short: null, full: null },
+        outputAudio: { short: null, full: null },
+    };
     // Pre-built keyframe index (e.g. from MKV cues) to skip mediabunny scan
     _keyframeIndex = null;
     // Main-thread pipeline state (used by loadSource)
@@ -68,6 +78,26 @@ export class PlaysVideoEngine extends EventTarget {
     get passthrough() {
         return this._passthrough;
     }
+    get codecPath() {
+        return {
+            mode: this._codecPath.mode,
+            sourceVideo: { ...this._codecPath.sourceVideo },
+            sourceAudio: { ...this._codecPath.sourceAudio },
+            outputVideo: { ...this._codecPath.outputVideo },
+            outputAudio: { ...this._codecPath.outputAudio },
+        };
+    }
+    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 +121,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 +190,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;
@@ -146,6 +198,13 @@ export class PlaysVideoEngine extends EventTarget {
         this._passthrough = false;
         this._pendingFileType = null;
         this._keyframeIndex = null;
+        this._codecPath = {
+            mode: 'pipeline',
+            sourceVideo: { short: null, full: null },
+            sourceAudio: { short: null, full: null },
+            outputVideo: { short: null, full: null },
+            outputAudio: { short: null, full: null },
+        };
         // Source pipeline cleanup
         if (this._sourceSegmentAbort) {
             this._sourceSegmentAbort.abort();
@@ -162,7 +221,9 @@ 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() {
         this.worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
@@ -180,17 +241,40 @@ export class PlaysVideoEngine extends EventTarget {
             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) {
@@ -210,29 +294,172 @@ 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);
     }
-    checkNativePlayback(videoCodec, audioCodec) {
-        const mime = this._pendingFileType;
-        if (!mime)
-            return false;
-        const codecs = audioCodec ? `${videoCodec}, ${audioCodec}` : videoCodec;
-        const fullMime = `${mime}; codecs="${codecs}"`;
-        const result = this.video.canPlayType(fullMime);
-        mlog(`canPlayType("${fullMime}") = "${result}"`);
-        if (FORCE_REMUX)
-            return false;
-        return result === 'probably' || result === 'maybe';
+    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,
+        });
+    }
+    createPlaybackCapabilities() {
+        const capabilities = createBrowserPlaybackCapabilities(this.video);
+        if (FORCE_REMUX) {
+            return {
+                ...capabilities,
+                canPlayType: () => '',
+            };
+        }
+        return capabilities;
+    }
+    evaluateInitialPlayback(media) {
+        const options = this._blobUrl
+            ? [
+                { mode: 'direct-bytes', mimeType: this._pendingFileType, url: this._blobUrl },
+                { mode: 'hls' },
+            ]
+            : [{ mode: 'hls' }];
+        return evaluatePlaybackOptions({
+            options: [...options],
+            media,
+            capabilities: this.createPlaybackCapabilities(),
+        });
+    }
+    evaluateHlsPlayback(media) {
+        return evaluatePlaybackOptions({
+            options: [{ mode: 'hls' }],
+            media,
+            capabilities: this.createPlaybackCapabilities(),
+        }).evaluations[0];
+    }
+    logPlaybackDiagnostics(context, evaluation) {
+        for (const entry of evaluation.evaluations) {
+            for (const diagnostic of entry.diagnostics) {
+                mlog(`${context}: mode=${entry.option.mode} ${diagnostic.code} ${diagnostic.message}`);
+            }
+        }
+        if (!evaluation.recommended) {
+            mlog(`${context}: no-supported-option`);
+        }
+    }
+    throwPlaybackSelectionError(context, diagnostics) {
+        const detail = diagnostics.length > 0
+            ? diagnostics.map((diagnostic) => diagnostic.message).join(' ')
+            : 'No supported playback option.';
+        throw new Error(`${context}: ${detail}`);
+    }
+    failPlaybackSelection(context, diagnostics) {
+        const detail = diagnostics.length > 0
+            ? diagnostics.map((diagnostic) => diagnostic.message).join(' ')
+            : 'No supported playback option.';
+        this._phase = 'error';
+        this.dispatchEvent(new CustomEvent('error', { detail: { message: `${context}: ${detail}` } }));
+    }
+    makeCodecPathFromSource(media, mode, outputAudio = {
+        short: media.sourceAudioCodec,
+        full: media.audioCodec,
+    }) {
+        return {
+            mode,
+            sourceVideo: {
+                short: media.sourceVideoCodec,
+                full: media.videoCodec,
+            },
+            sourceAudio: {
+                short: media.sourceAudioCodec,
+                full: media.audioCodec,
+            },
+            outputVideo: {
+                short: media.sourceVideoCodec,
+                full: media.videoCodec,
+            },
+            outputAudio,
+        };
     }
     startPassthrough(src) {
         this._passthrough = true;
@@ -251,6 +478,7 @@ export class PlaysVideoEngine extends EventTarget {
                     durationSec: this._durationSec,
                     subtitleTracks: [],
                     passthrough: true,
+                    codecPath: this.codecPath,
                 },
             }));
         };
@@ -265,23 +493,44 @@ export class PlaysVideoEngine extends EventTarget {
         const msg = event.data;
         if (msg.type === 'probed') {
             // Worker finished demux — decide passthrough vs pipeline
-            const canPlay = this.checkNativePlayback(msg.videoCodec, msg.audioCodec);
+            const media = {
+                sourceVideoCodec: msg.sourceVideoCodec ?? null,
+                sourceAudioCodec: msg.sourceAudioCodec ?? null,
+                videoCodec: msg.videoCodec ?? null,
+                audioCodec: msg.audioCodec ?? null,
+            };
+            const evaluation = this.evaluateInitialPlayback(media);
+            this.logPlaybackDiagnostics('playback selection', evaluation);
             this._subtitleTracks = msg.subtitleTracks ?? [];
-            if (canPlay && this._blobUrl) {
-                mlog(`passthrough: canPlayType accepted codecs=${msg.videoCodec}/${msg.audioCodec}`);
-                this.startPassthrough(this._blobUrl);
+            const blobUrl = this._blobUrl;
+            const usePassthrough = evaluation.recommended?.option.mode === 'direct-bytes' && blobUrl !== null;
+            this._codecPath = this.makeCodecPathFromSource(media, usePassthrough ? 'passthrough' : 'pipeline');
+            if (usePassthrough && blobUrl) {
+                mlog(`passthrough: selected direct playback codecs=${msg.videoCodec}/${msg.audioCodec}`);
+                this.startPassthrough(blobUrl);
                 this.worker.postMessage({ type: 'passthrough-pipeline' });
+                if (this._subtitleTracks.length > 0) {
+                    this.dispatchSubtitleStatus(`Extracting ${this._subtitleTracks.length} subtitle track(s)...`);
+                }
+                else {
+                    this.dispatchSubtitleStatus('No embedded subtitles');
+                }
                 for (const track of this._subtitleTracks) {
                     mlog(`requesting subtitle track=${track.index} lang=${track.language} codec=${track.codec}`);
                     this.worker.postMessage({ type: 'subtitle', trackIndex: track.index });
                 }
             }
             else {
+                const hlsEvaluation = evaluation.evaluations.find((entry) => entry.option.mode === 'hls');
+                if (evaluation.recommended?.option.mode !== 'hls') {
+                    this.failPlaybackSelection('Playback selection failed', hlsEvaluation?.diagnostics ?? []);
+                    return;
+                }
                 if (this._blobUrl) {
                     URL.revokeObjectURL(this._blobUrl);
                     this._blobUrl = null;
                 }
-                mlog(`pipeline: canPlayType rejected, proceeding with remux pipeline`);
+                mlog('pipeline: selected remux/HLS playback');
                 this.ensureTranscodeWorkers();
                 const remuxMsg = { type: 'remux-pipeline' };
                 if (this._keyframeIndex)
@@ -296,6 +545,25 @@ export class PlaysVideoEngine extends EventTarget {
             this._durationSec = msg.durationSec;
             this._subtitleTracks = msg.subtitleTracks ?? [];
             this._phase = 'ready';
+            this._codecPath = {
+                mode: 'pipeline',
+                sourceVideo: {
+                    short: msg.sourceVideoCodec ?? this._codecPath.sourceVideo.short,
+                    full: msg.sourceVideoCodecFull ?? this._codecPath.sourceVideo.full,
+                },
+                sourceAudio: {
+                    short: msg.sourceAudioCodec ?? this._codecPath.sourceAudio.short,
+                    full: msg.sourceAudioCodecFull ?? this._codecPath.sourceAudio.full,
+                },
+                outputVideo: {
+                    short: msg.outputVideoCodec ?? this._codecPath.outputVideo.short,
+                    full: msg.outputVideoCodecFull ?? this._codecPath.outputVideo.full,
+                },
+                outputAudio: {
+                    short: msg.outputAudioCodec ?? this._codecPath.outputAudio.short,
+                    full: msg.outputAudioCodecFull ?? this._codecPath.outputAudio.full,
+                },
+            };
             mlog(`ready segments=${msg.totalSegments} dur=${msg.durationSec.toFixed(1)}s`);
             // Resolve any pending requests
             if (this.pendingPlaylist) {
@@ -307,6 +575,12 @@ export class PlaysVideoEngine extends EventTarget {
                 this.pendingInit = null;
             }
             // Request subtitle extraction for all embedded tracks
+            if (this._subtitleTracks.length > 0) {
+                this.dispatchSubtitleStatus(`Extracting ${this._subtitleTracks.length} subtitle track(s)...`);
+            }
+            else {
+                this.dispatchSubtitleStatus('No embedded subtitles');
+            }
             for (const track of this._subtitleTracks) {
                 mlog(`requesting subtitle track=${track.index} lang=${track.language} codec=${track.codec}`);
                 this.worker.postMessage({ type: 'subtitle', trackIndex: track.index });
@@ -316,24 +590,44 @@ export class PlaysVideoEngine extends EventTarget {
                     totalSegments: this._totalSegments,
                     durationSec: this._durationSec,
                     subtitleTracks: this._subtitleTracks,
+                    codecPath: this.codecPath,
                 },
             }));
             this.startHls();
         }
         else if (msg.type === 'subtitle') {
             mlog(`subtitle arrived track=${msg.trackIndex} codec=${msg.codec} len=${msg.webvtt?.length}`);
-            this.addSubtitleTrack(msg.webvtt, msg.trackIndex);
+            const info = this._subtitleTracks.find((t) => t.index === msg.trackIndex);
+            const lang = info?.language ?? '?';
+            const cueMatch = msg.webvtt?.match(/\d\d:\d\d/g);
+            const cueCount = cueMatch ? Math.floor(cueMatch.length / 2) : 0;
+            this.dispatchSubtitleStatus(`Subtitle track ${msg.trackIndex}: ${lang} ${msg.codec} ${cueCount} cues, ${msg.webvtt?.length ?? 0} bytes`);
+            this.addSubtitleTrack({
+                webvtt: msg.webvtt,
+                source: 'embedded',
+                trackIndex: msg.trackIndex,
+                defaultTrack: msg.trackIndex === 0,
+                selectTrack: 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') {
@@ -341,7 +635,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();
@@ -366,6 +661,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 });
@@ -375,6 +671,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);
@@ -402,14 +699,36 @@ export class PlaysVideoEngine extends EventTarget {
                 durationSec: index.duration,
                 targetSegmentDurationSec: this._sourceTargetSegDuration,
             });
-            // Check transcode
-            const codecProber = createBrowserProber();
-            this._sourceDoTranscode =
-                demux.audioCodec !== null &&
-                    audioNeedsTranscode(codecProber, demux.audioCodec, demux.audioDecoderConfig?.codec);
+            const media = {
+                sourceVideoCodec: demux.videoCodec,
+                sourceAudioCodec: demux.audioCodec,
+                videoCodec: demux.videoDecoderConfig.codec,
+                audioCodec: demux.audioDecoderConfig?.codec ?? null,
+            };
+            const hlsEvaluation = this.evaluateHlsPlayback(media);
+            this.logPlaybackDiagnostics('source playback selection', {
+                recommended: hlsEvaluation.status === 'supported'
+                    ? {
+                        option: hlsEvaluation.option,
+                        reason: hlsEvaluation.diagnostics[hlsEvaluation.diagnostics.length - 1] ?? {
+                            code: 'selected-hls',
+                            message: 'Recommended HLS playback.',
+                        },
+                    }
+                    : null,
+                evaluations: [hlsEvaluation],
+            });
+            if (hlsEvaluation.status !== 'supported') {
+                this.throwPlaybackSelectionError('Source playback selection failed', hlsEvaluation.diagnostics);
+            }
+            this._sourceDoTranscode = hlsEvaluation.pipelineAudioRequiresTranscode === true;
             this._sourceAudioDecoderConfig = this._sourceDoTranscode
                 ? makeAacDecoderConfig(demux.audioDecoderConfig)
                 : demux.audioDecoderConfig;
+            this._codecPath = this.makeCodecPathFromSource(media, 'pipeline', {
+                short: this._sourceDoTranscode ? 'aac' : demux.audioCodec,
+                full: this._sourceAudioDecoderConfig?.codec ?? null,
+            });
             // Pre-process segment 0
             const seg0Result = await processSegmentWithAbort(this.makeSourceProcessorConfig(), 0);
             if (seg0Result.initSegment) {
@@ -438,6 +757,7 @@ export class PlaysVideoEngine extends EventTarget {
                     totalSegments: this._totalSegments,
                     durationSec: this._durationSec,
                     subtitleTracks: this._subtitleTracks,
+                    codecPath: this.codecPath,
                 },
             }));
             this.startHls();
@@ -526,8 +846,12 @@ export class PlaysVideoEngine extends EventTarget {
             context = null;
             stats = makeStats();
             currentSegmentIndex = null;
+            callbacks = null;
+            aborted = false;
             load(context, _config, callbacks) {
                 this.context = context;
+                this.callbacks = callbacks;
+                this.aborted = false;
                 const url = context.url;
                 if (url.includes('init.mp4')) {
                     this.loadInit(context, callbacks);
@@ -571,22 +895,36 @@ export class PlaysVideoEngine extends EventTarget {
                     : engine.requestSegment(index);
                 segmentPromise
                     .then((data) => {
+                    if (this.aborted) {
+                        return;
+                    }
                     this.currentSegmentIndex = null;
                     this.stats.loaded = data.byteLength;
                     this.stats.loading.end = performance.now();
                     callbacks.onSuccess({ url: context.url, data }, this.stats, context, null);
                 })
                     .catch((err) => {
+                    if (this.aborted) {
+                        return;
+                    }
                     this.currentSegmentIndex = null;
                     if (err instanceof DOMException && err.name === 'AbortError') {
                         this.stats.aborted = true;
+                        callbacks.onAbort?.(this.stats, context, null);
                         return;
                     }
                     callbacks.onError({ code: 0, text: err.message }, context, null, this.stats);
                 });
             }
             abort() {
+                if (this.aborted) {
+                    return;
+                }
+                this.aborted = true;
+                this.stats.aborted = true;
+                let abortedActiveSegment = false;
                 if (this.currentSegmentIndex !== null) {
+                    abortedActiveSegment = true;
                     if (engine._source) {
                         // Source mode: abort the in-flight main-thread processing
                         engine._sourceSegmentAbort?.abort();
@@ -597,9 +935,14 @@ export class PlaysVideoEngine extends EventTarget {
                     }
                     this.currentSegmentIndex = null;
                 }
+                if (abortedActiveSegment && this.callbacks && this.context) {
+                    this.callbacks.onAbort?.(this.stats, this.context, null);
+                }
             }
             destroy() {
                 this.abort();
+                this.callbacks = null;
+                this.context = null;
             }
         }
         this.hls = new Hls({
@@ -626,36 +969,71 @@ 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';
+    }
+    dispatchSubtitleStatus(message) {
+        mlog(`subtitle-status: ${message}`);
+        this.dispatchEvent(new CustomEvent('subtitle-status', { detail: { message } }));
+    }
+    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). */
@@ -701,6 +1079,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',