react-native-tv-audio-description 0.1.0

package/lib/ADControls.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stateMessage = void 0;
+exports.ADControls = ADControls;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const track_1 = require("./track");
+const log_1 = require("./log");
+const messages_1 = require("./messages");
+var messages_2 = require("./messages");
+Object.defineProperty(exports, "stateMessage", { enumerable: true, get: function () { return messages_2.stateMessage; } });
+function ADControls({ state, onToggle, onVerbosity, focusRef }) {
+    const lastSpoken = (0, react_1.useRef)('');
+    // Announce on entry and on every state change, once each. The guard is not
+    // an optimisation — re-announcing an unchanged state talks over the film for
+    // no reason, and this screen is already competing for the one channel its
+    // users have.
+    (0, react_1.useEffect)(() => {
+        const message = (0, messages_1.stateMessage)(state);
+        if (message === lastSpoken.current)
+            return;
+        lastSpoken.current = message;
+        react_native_1.AccessibilityInfo.announceForAccessibility(message);
+        (0, log_1.log)(`controls.announce kind=${state.kind}`);
+    }, [state]);
+    const toggle = (0, react_1.useCallback)(() => {
+        if (state.kind !== 'ready')
+            return;
+        (0, log_1.log)(`controls.toggle to=${!state.enabled}`);
+        onToggle(!state.enabled); // the scheduler flips; the video is untouched
+    }, [state, onToggle]);
+    if (state.kind !== 'ready') {
+        return ((0, jsx_runtime_1.jsx)(react_native_1.View, { accessible: true, accessibilityRole: "alert", accessibilityLabel: (0, messages_1.stateMessage)(state), children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { children: (0, messages_1.stateMessage)(state) }) }));
+    }
+    return ((0, jsx_runtime_1.jsxs)(react_native_1.View, { children: [(0, jsx_runtime_1.jsx)(react_native_1.Pressable, { ref: focusRef, accessible: true, accessibilityRole: "switch", accessibilityLabel: "Audio description", accessibilityState: { checked: state.enabled }, onPress: toggle, hasTVPreferredFocus: true, children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { children: state.enabled ? 'Description: on' : 'Description: off' }) }), track_1.VERBOSITY_LEVELS.map((level) => ((0, jsx_runtime_1.jsx)(react_native_1.Pressable, { accessible: true, accessibilityRole: "radio", accessibilityLabel: `${level} description`, accessibilityState: { selected: state.verbosity === level, disabled: !state.enabled }, disabled: !state.enabled, onPress: () => {
+                    (0, log_1.log)(`controls.verbosity to=${level}`);
+                    onVerbosity(level);
+                }, children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { children: level }) }, level)))] }));
+}
+//# sourceMappingURL=ADControls.js.map

package/lib/ADControls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ADControls.js","sourceRoot":"","sources":["../src/ADControls.tsx"],"names":[],"mappings":";;;AA6BA,gCA8DC;;AA3FD,iCAA8D;AAC9D,+CAAwE;AAExE,mCAA2C;AAC3C,+BAA4B;AAC5B,yCAAwD;AAExD,uCAAwD;AAA/C,wGAAA,YAAY,OAAA;AAsBrB,SAAgB,UAAU,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAmB;IACpF,MAAM,UAAU,GAAG,IAAA,cAAM,EAAS,EAAE,CAAC,CAAC;IAEtC,2EAA2E;IAC3E,6EAA6E;IAC7E,0EAA0E;IAC1E,cAAc;IACd,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,MAAM,OAAO,GAAG,IAAA,uBAAY,EAAC,KAAK,CAAC,CAAC;QACpC,IAAI,OAAO,KAAK,UAAU,CAAC,OAAO;YAAE,OAAO;QAC3C,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;QAC7B,gCAAiB,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC;QACpD,IAAA,SAAG,EAAC,0BAA0B,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAEZ,MAAM,MAAM,GAAG,IAAA,mBAAW,EAAC,GAAG,EAAE;QAC9B,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO;QACnC,IAAA,SAAG,EAAC,sBAAsB,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5C,QAAQ,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,8CAA8C;IAC1E,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;IAEtB,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC3B,OAAO,CACL,uBAAC,mBAAI,IAAC,UAAU,QAAC,iBAAiB,EAAC,OAAO,EAAC,kBAAkB,EAAE,IAAA,uBAAY,EAAC,KAAK,CAAC,YAChF,uBAAC,mBAAI,cAAE,IAAA,uBAAY,EAAC,KAAK,CAAC,GAAQ,GAC7B,CACR,CAAC;IACJ,CAAC;IAED,OAAO,CACL,wBAAC,mBAAI,eACH,uBAAC,wBAAS,IACR,GAAG,EAAE,QAAQ,EACb,UAAU,QACV,iBAAiB,EAAC,QAAQ,EAC1B,kBAAkB,EAAC,mBAAmB,EACtC,kBAAkB,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAC9C,OAAO,EAAE,MAAM,EACf,mBAAmB,kBAEnB,uBAAC,mBAAI,cAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,GAAQ,GAC3D,EAGX,wBAAgB,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAC/B,uBAAC,wBAAS,IAER,UAAU,QACV,iBAAiB,EAAC,OAAO,EACzB,kBAAkB,EAAE,GAAG,KAAK,cAAc,EAC1C,kBAAkB,EAAE,EAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,KAAK,KAAK,EAAE,QAAQ,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,EACrF,QAAQ,EAAE,CAAC,KAAK,CAAC,OAAO,EACxB,OAAO,EAAE,GAAG,EAAE;oBACZ,IAAA,SAAG,EAAC,yBAAyB,KAAK,EAAE,CAAC,CAAC;oBACtC,WAAW,CAAC,KAAK,CAAC,CAAC;gBACrB,CAAC,YAED,uBAAC,mBAAI,cAAE,KAAK,GAAQ,IAXf,KAAK,CAYA,CACb,CAAC,IACG,CACR,CAAC;AACJ,CAAC"}

package/lib/CueScheduler.d.ts

@@ -0,0 +1,49 @@
+import type { DescriptionCue } from './track';
+/**
+ * Playback position becomes "fire this cue now, once".
+ *
+ * The invariant this file exists to hold: a cue fires only while position is
+ * inside its own window. A cue whose window has already passed is DROPPED,
+ * never played late — a late cue is a cue playing over dialogue, which is the
+ * one thing worse than no description.
+ */
+export interface SchedulerEvents {
+    onFire: (cue: DescriptionCue) => void;
+}
+export interface SchedulerOptions {
+    /**
+     * How long a cue needs, from firing to the film being back at full. A cue
+     * is only fired if that much of its window is left. Default: its words at
+     * the narration pace plus the fade down and up — pass a better figure if you
+     * have the clips' real durations.
+     */
+    estimateMs?: (cue: DescriptionCue) => number;
+}
+/** words at the narration pace, plus the fade down and the fade back up */
+export declare function estimateCueMs(cue: DescriptionCue): number;
+export declare class CueScheduler {
+    private readonly events;
+    private cues;
+    private cursor;
+    private firing;
+    private enabled;
+    private readonly estimateMs;
+    constructor(events: SchedulerEvents, options?: SchedulerOptions);
+    /** `failed` cues carry no audio; they never enter the schedule. */
+    load(cues: DescriptionCue[]): void;
+    setEnabled(on: boolean): void;
+    /** Called on every position update from the platform. */
+    tick(positionMs: number): void;
+    /**
+     * Called with the SETTLED position after a seek — not with each
+     * intermediate position a held direction produces. Resets the cursor to the
+     * first cue that has not closed yet, so no backlog fires.
+     */
+    resync(positionMs: number): void;
+}
+/**
+ * The input half of seeking. A held D-pad direction emits a stream of key
+ * events; acting on each one produces a seek storm and a resync per event.
+ * This defers the action until the stream stops for `quietMs`.
+ */
+export declare function coalesce(fn: (value: number) => void, quietMs?: number): (value: number) => void;

package/lib/CueScheduler.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CueScheduler = void 0;
+exports.estimateCueMs = estimateCueMs;
+exports.coalesce = coalesce;
+const budget_1 = require("./budget");
+const log_1 = require("./log");
+/** words at the narration pace, plus the fade down and the fade back up */
+function estimateCueMs(cue) {
+    return (cue.words / budget_1.AD.SPEAKING_RATE_WPM) * 60000 + 2 * budget_1.AD.DUCK_RAMP_MS;
+}
+class CueScheduler {
+    constructor(events, options = {}) {
+        this.events = events;
+        this.cues = [];
+        this.cursor = 0;
+        this.firing = null;
+        this.enabled = true;
+        this.estimateMs = options.estimateMs ?? estimateCueMs;
+    }
+    /** `failed` cues carry no audio; they never enter the schedule. */
+    load(cues) {
+        this.cues = cues
+            .filter((c) => c.status === 'ok' && c.audio_uri !== '')
+            .sort((a, b) => a.start_ms - b.start_ms);
+        this.cursor = 0;
+        this.firing = null;
+        (0, log_1.log)(`scheduler.load cues=${this.cues.length}`);
+    }
+    setEnabled(on) {
+        this.enabled = on;
+        if (!on)
+            this.firing = null;
+    }
+    /** Called on every position update from the platform. */
+    tick(positionMs) {
+        if (!this.enabled)
+            return;
+        // Advance past every cue whose window closed while we were elsewhere.
+        while (this.cursor < this.cues.length && this.cues[this.cursor].end_ms <= positionMs) {
+            const skipped = this.cues[this.cursor];
+            if (skipped !== this.firing) {
+                (0, log_1.log)(`scheduler.skip id=${skipped.id} pos_ms=${positionMs}`);
+            }
+            this.cursor++;
+        }
+        const next = this.cues[this.cursor];
+        if (!next)
+            return;
+        // Fire only INSIDE the window, and only if the cue can FINISH there. A cue
+        // reached late — description switched back on, a seek into the middle of a
+        // gap — would otherwise still be speaking when dialogue resumes. Measured
+        // on the Vega Virtual Device: switched on 2.5 s before its window closed, a
+        // 2.6 s cue brought the film back up half a second into the next line.
+        if (positionMs >= next.start_ms && positionMs < next.end_ms && this.firing !== next) {
+            const remaining = next.end_ms - positionMs;
+            const needs = Math.round(this.estimateMs(next));
+            if (remaining < needs) {
+                this.cursor++;
+                (0, log_1.log)(`scheduler.skip id=${next.id} pos_ms=${positionMs} reason=late` +
+                    ` remaining_ms=${remaining} needs_ms=${needs}`);
+                return;
+            }
+            this.firing = next;
+            this.cursor++;
+            (0, log_1.log)(`scheduler.fire id=${next.id} pos_ms=${positionMs}` +
+                ` window=[${next.start_ms},${next.end_ms})`);
+            this.events.onFire(next);
+        }
+    }
+    /**
+     * Called with the SETTLED position after a seek — not with each
+     * intermediate position a held direction produces. Resets the cursor to the
+     * first cue that has not closed yet, so no backlog fires.
+     */
+    resync(positionMs) {
+        let lo = 0;
+        let hi = this.cues.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (this.cues[mid].end_ms <= positionMs)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        this.cursor = lo;
+        this.firing = null;
+        (0, log_1.log)(`scheduler.resync pos_ms=${positionMs} cursor=${this.cursor}`);
+    }
+}
+exports.CueScheduler = CueScheduler;
+/**
+ * The input half of seeking. A held D-pad direction emits a stream of key
+ * events; acting on each one produces a seek storm and a resync per event.
+ * This defers the action until the stream stops for `quietMs`.
+ */
+function coalesce(fn, quietMs = 250) {
+    let timer = null;
+    let pending = 0;
+    let events = 0;
+    return (value) => {
+        pending = value;
+        events++;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            (0, log_1.log)(`scheduler.coalesced events=${events} settled_ms=${pending}`);
+            events = 0;
+            timer = null;
+            fn(pending);
+        }, quietMs);
+    };
+}
+//# sourceMappingURL=CueScheduler.js.map

package/lib/CueScheduler.js.map

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

package/lib/DescriptionAudio.d.ts

@@ -0,0 +1,36 @@
+import type { MediaAdapter } from './MediaAdapter';
+import type { DescriptionCue } from './track';
+export interface DescriptionAudioOptions {
+    /** main track level while a cue speaks, % of full (default 25) */
+    duckTargetPct?: number;
+    /** fade length into and out of the duck (default 200) */
+    rampMs?: number;
+}
+/**
+ * Duck, speak, restore.
+ *
+ * The cue plays as a SECOND stream over the film rather than by switching to
+ * a pre-mixed track. On Vega that was measured to work: a video player and an
+ * audio player built for accessibility speech ran simultaneously with zero
+ * dropped frames (PLATFORM.md `concurrent_streams`).
+ */
+export declare class DescriptionAudio {
+    private readonly media;
+    private active;
+    /**
+     * Bumped by `stop()`. A cue in flight when the screen unmounts keeps running
+     * — its `await` chain does not know the component is gone — and its
+     * `finally` would then ramp the volume on a player that has been destroyed,
+     * after `stop()` already restored it.
+     */
+    private generation;
+    private readonly duckPct;
+    private readonly rampMs;
+    constructor(media: MediaAdapter, options?: DescriptionAudioOptions);
+    speak(cue: DescriptionCue): Promise<void>;
+    /**
+     * Stop the cue that is speaking, if any, and bring the film back to full.
+     * Safe to call at any time — turning description off, leaving the screen.
+     */
+    stop(): Promise<void>;
+}

package/lib/DescriptionAudio.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DescriptionAudio = void 0;
+const budget_1 = require("./budget");
+const duck_1 = require("./duck");
+const log_1 = require("./log");
+/**
+ * Duck, speak, restore.
+ *
+ * The cue plays as a SECOND stream over the film rather than by switching to
+ * a pre-mixed track. On Vega that was measured to work: a video player and an
+ * audio player built for accessibility speech ran simultaneously with zero
+ * dropped frames (PLATFORM.md `concurrent_streams`).
+ */
+class DescriptionAudio {
+    constructor(media, options = {}) {
+        this.media = media;
+        this.active = false;
+        /**
+         * Bumped by `stop()`. A cue in flight when the screen unmounts keeps running
+         * — its `await` chain does not know the component is gone — and its
+         * `finally` would then ramp the volume on a player that has been destroyed,
+         * after `stop()` already restored it.
+         */
+        this.generation = 0;
+        this.duckPct = options.duckTargetPct ?? budget_1.AD.DUCK_TARGET_PCT;
+        this.rampMs = options.rampMs ?? budget_1.AD.DUCK_RAMP_MS;
+        // Backgrounding during a cue must stop the clip and restore the main
+        // level, or the app returns to the foreground ducked and silent.
+        this.media.lifecycle.onBackground(() => {
+            if (!this.active)
+                return;
+            (0, log_1.log)('audio.background active=true');
+            void this.stop();
+        });
+    }
+    async speak(cue) {
+        if (this.active) {
+            // a cue already speaking is never interrupted by another — but the one
+            // that lost is said out loud in the log, not dropped in silence
+            (0, log_1.log)(`audio.busy id=${cue.id}`);
+            return;
+        }
+        this.active = true;
+        const mine = this.generation;
+        const stale = () => mine !== this.generation;
+        try {
+            (0, log_1.log)(`audio.duck id=${cue.id} to_pct=${this.duckPct}`);
+            await (0, duck_1.rampVolumePct)(this.media.video, 100, this.duckPct, this.rampMs, stale);
+            await this.media.clips.play(cue.audio_uri);
+            (0, log_1.log)(stale() ? `audio.interrupted id=${cue.id}` : `audio.spoke id=${cue.id} words=${cue.words}`);
+        }
+        catch (err) {
+            (0, log_1.log)(`audio.failed id=${cue.id} err=${err.message}`);
+        }
+        finally {
+            // The main track ALWAYS returns to full, including on failure. A cue
+            // that fails must not leave the film at 25% for the rest of the runtime.
+            //
+            // Unless stop() already did it: then this cue is stale, the player may
+            // be torn down, and ramping again is work against a dead object.
+            if (!stale()) {
+                await (0, duck_1.rampVolumePct)(this.media.video, this.duckPct, 100, this.rampMs, stale);
+                (0, log_1.log)(`audio.restored id=${cue.id}`);
+                this.active = false;
+            }
+        }
+    }
+    /**
+     * Stop the cue that is speaking, if any, and bring the film back to full.
+     * Safe to call at any time — turning description off, leaving the screen.
+     */
+    async stop() {
+        this.generation++; // anything in flight is now stale and must not restore
+        this.media.clips.stop();
+        // Nothing speaking means the film is already at full. Ramping "back" from
+        // the duck level anyway would first SET it to the duck level: an audible
+        // dip every time description is switched off between cues.
+        if (!this.active)
+            return;
+        (0, log_1.log)('audio.stopped');
+        await (0, duck_1.rampVolumePct)(this.media.video, this.duckPct, 100, this.rampMs);
+        this.active = false;
+        (0, log_1.log)('audio.restored after=stop');
+    }
+}
+exports.DescriptionAudio = DescriptionAudio;
+//# sourceMappingURL=DescriptionAudio.js.map

package/lib/DescriptionAudio.js.map

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

package/lib/MediaAdapter.d.ts

@@ -0,0 +1,123 @@
+import type { ComponentType } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+/**
+ * The only surface this library uses to reach a platform's media stack.
+ *
+ * Everything outside `src/vega/` is written against this interface and never
+ * against a platform package; a test fails if that stops being true. Bring
+ * your own implementation for another platform, or use the Vega one:
+ *
+ *   import { createVegaAdapter } from 'react-native-tv-audio-description/vega';
+ *
+ * Each platform defect the Vega implementation works around is kept OUT of
+ * this interface on purpose — a caller that had to know about them would leak
+ * one platform's defects into every other. They are listed in PLATFORM.md.
+ */
+export type Unsubscribe = () => void;
+/** one piece of an asset, with times read from the emitted playlist */
+export interface AssetSegment {
+    index: number;
+    start_ms: number;
+    end_ms: number;
+    uri: string;
+}
+/**
+ * What to play, and how it is cut up.
+ *
+ * ALWAYS A LIST, even for a single file — a whole-file asset is one segment
+ * with no init. One code path for both shapes means a short clip and a
+ * feature-length film exercise the same buffering logic, rather than the
+ * feature-length one taking a path nothing has ever run.
+ */
+export interface AssetSource {
+    /** appended once, before any segment; absent for a whole-file asset */
+    initUri?: string;
+    segments: AssetSegment[];
+}
+export interface VideoPlayer {
+    /**
+     * Point the player at an asset and get it ready to play.
+     *
+     * Implementations must NOT assume the platform will fetch anything. On Vega
+     * it will not (PLATFORM.md `url_mode_broken`) and the implementation reads
+     * the bytes itself — nor can it read PART of a file (`no_range_requests`),
+     * which is why the asset arrives already cut into segments.
+     */
+    open(source: AssetSource): Promise<void>;
+    play(): Promise<void>;
+    pause(): void;
+    /** current playback position, ms */
+    positionMs(): number;
+    durationMs(): number;
+    isPlaying(): boolean;
+    /**
+     * Set the main track volume as a percentage of full, EFFECTIVE IMMEDIATELY.
+     *
+     * There is no ramp parameter, and its absence is measured rather than
+     * chosen: the W3C volume setter is instantaneous and Vega exposes no fade
+     * (PLATFORM.md `no_volume_ramp`). The fade is implemented once, in JS, in
+     * `duck.ts`. An interface that accepted `rampMs` would invite every
+     * implementation to reimplement the same loop and would imply a capability
+     * no platform here has.
+     */
+    setVolumePct(pct: number): void;
+    /** fires on every position update the platform emits ('timeupdate') */
+    onPosition(cb: (ms: number) => void): Unsubscribe;
+    /** fires after a seek settles, with the new position ('seeked') */
+    onSeek(cb: (ms: number) => void): Unsubscribe;
+    /**
+     * Fires when playback cannot continue because the buffer ran dry
+     * ('waiting' / 'stalled').
+     *
+     * With the app owning byte delivery this is a REACHABLE state and it is NOT
+     * an error — no `error` event follows it. A UI that only listens for
+     * `onError` shows a frozen picture and says nothing, which for a blind
+     * viewer is indistinguishable from a quiet scene.
+     */
+    onStalled(cb: () => void): Unsubscribe;
+    /**
+     * Fires when playback is actually running ('playing').
+     *
+     * The counterpart to `onStalled`, and not optional: MSE emits `waiting` at
+     * the START of normal playback while the first frames decode, so a screen
+     * that treats stalling as terminal announces "Buffering" over a film that is
+     * playing fine (PLATFORM.md `waiting_fires_at_start`).
+     */
+    onPlaying(cb: () => void): Unsubscribe;
+    onEnded(cb: () => void): Unsubscribe;
+    onError(cb: (err: Error) => void): Unsubscribe;
+    /** release everything; safe to call twice */
+    destroy(): Promise<void>;
+}
+export interface ClipPlayer {
+    /**
+     * Plays one description clip to completion; rejects if it cannot be played.
+     * Same rule as `VideoPlayer.open`: no implementation may assume the
+     * platform fetches the URI.
+     */
+    play(uri: string): Promise<void>;
+    stop(): void;
+}
+export interface AppLifecycle {
+    /** fires when the app leaves the foreground */
+    onBackground(cb: () => void): Unsubscribe;
+}
+export interface VideoSurfaceProps {
+    style?: StyleProp<ViewStyle>;
+}
+export interface MediaAdapter {
+    video: VideoPlayer;
+    clips: ClipPlayer;
+    lifecycle: AppLifecycle;
+    /**
+     * The platform's own view that decoded pixels render into, already wired to
+     * `video`.
+     *
+     * It is part of the adapter rather than something a screen imports, because
+     * mounting it IS platform code: on Vega it is `KeplerVideoSurfaceView` and
+     * the handle it hands back has to reach the player — and it has to be
+     * tracked against `initialize()`, which races it (PLATFORM.md
+     * `surface_races_init`).
+     */
+    VideoSurface: ComponentType<VideoSurfaceProps>;
+}

package/lib/MediaAdapter.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=MediaAdapter.js.map

package/lib/MediaAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MediaAdapter.js","sourceRoot":"","sources":["../src/MediaAdapter.ts"],"names":[],"mappings":""}

package/lib/TrackLoader.d.ts

@@ -0,0 +1,48 @@
+import type { DescriptionTrack, Verbosity } from './track';
+/**
+ * Load a track file and refuse to believe it.
+ *
+ * Validation here is not defensive decoration. The loader does not trust that
+ * the producer was well-behaved, and a malformed or missing track must end in
+ * a STATED visible and spoken state, never in silence. A silent app with
+ * nothing to say is indistinguishable from a working app in a quiet scene.
+ */
+export type LoadResult = {
+    ok: true;
+    track: DescriptionTrack;
+    loaded_verbosity: Verbosity;
+} | {
+    ok: false;
+    reason: 'missing' | 'malformed';
+    detail: string;
+};
+export declare const CUE_KEYS: readonly ["id", "start_ms", "end_ms", "words", "text", "audio_uri", "source_frames_ms", "status"];
+export declare const TRACK_KEYS: readonly ["version", "asset_id", "generated_at", "source_subtitles", "verbosity", "model_id", "cues"];
+/** Validates a parsed track field for field. */
+export declare function validateTrack(raw: unknown): LoadResult;
+/**
+ * Resolve a level by `<asset_id>.<verbosity>.track.json` beside the asset,
+ * FALLING BACK to `standard`. The fallback is what stops a missing `detailed`
+ * file from turning the feature off.
+ *
+ * `readJson` is yours: on Vega a packaged file is read with `fetch`, and the
+ * platform's own player cannot be pointed at it (PLATFORM.md
+ * `url_mode_broken`), so there is no platform loader to delegate to.
+ */
+export declare function loadTrack(readJson: (path: string) => Promise<unknown>, assetDir: string, assetId: string, verbosity: Verbosity): Promise<LoadResult>;
+/**
+ * A bounded clip cache, oldest out first.
+ *
+ * It holds BYTES, not URIs, and on Vega that is forced rather than chosen:
+ * there is no URI a player will fetch (PLATFORM.md `url_mode_broken`), so
+ * every clip is read by the app and appended through a MediaSource.
+ */
+export declare class ClipCache {
+    private readonly max;
+    private order;
+    private held;
+    constructor(max?: number);
+    put(uri: string, bytes: ArrayBuffer): void;
+    get(uri: string): ArrayBuffer | undefined;
+    get size(): number;
+}

package/lib/TrackLoader.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClipCache = exports.TRACK_KEYS = exports.CUE_KEYS = void 0;
+exports.validateTrack = validateTrack;
+exports.loadTrack = loadTrack;
+const track_1 = require("./track");
+const budget_1 = require("./budget");
+const log_1 = require("./log");
+exports.CUE_KEYS = [
+    'id',
+    'start_ms',
+    'end_ms',
+    'words',
+    'text',
+    'audio_uri',
+    'source_frames_ms',
+    'status',
+];
+exports.TRACK_KEYS = [
+    'version',
+    'asset_id',
+    'generated_at',
+    'source_subtitles',
+    'verbosity',
+    'model_id',
+    'cues',
+];
+function validCue(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const c = v;
+    if (exports.CUE_KEYS.some((k) => !(k in c)))
+        return false;
+    return (typeof c.id === 'string' &&
+        typeof c.start_ms === 'number' &&
+        typeof c.end_ms === 'number' &&
+        typeof c.words === 'number' &&
+        typeof c.text === 'string' &&
+        typeof c.audio_uri === 'string' &&
+        Array.isArray(c.source_frames_ms) &&
+        c.source_frames_ms.every((n) => typeof n === 'number') &&
+        (c.status === 'ok' || c.status === 'failed'));
+}
+/** Validates a parsed track field for field. */
+function validateTrack(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        return { ok: false, reason: 'malformed', detail: 'not an object' };
+    }
+    const t = raw;
+    const missing = exports.TRACK_KEYS.filter((k) => !(k in t));
+    if (missing.length) {
+        return { ok: false, reason: 'malformed', detail: `missing ${missing.join(',')}` };
+    }
+    if (!track_1.VERBOSITY_LEVELS.includes(t.verbosity)) {
+        return { ok: false, reason: 'malformed', detail: `verbosity=${String(t.verbosity)}` };
+    }
+    if (!Array.isArray(t.cues) || !t.cues.every(validCue)) {
+        return { ok: false, reason: 'malformed', detail: 'cues' };
+    }
+    return {
+        ok: true,
+        track: raw,
+        loaded_verbosity: t.verbosity,
+    };
+}
+/**
+ * Resolve a level by `<asset_id>.<verbosity>.track.json` beside the asset,
+ * FALLING BACK to `standard`. The fallback is what stops a missing `detailed`
+ * file from turning the feature off.
+ *
+ * `readJson` is yours: on Vega a packaged file is read with `fetch`, and the
+ * platform's own player cannot be pointed at it (PLATFORM.md
+ * `url_mode_broken`), so there is no platform loader to delegate to.
+ */
+async function loadTrack(readJson, assetDir, assetId, verbosity) {
+    const levels = verbosity === 'standard' ? [verbosity] : [verbosity, 'standard'];
+    for (const level of levels) {
+        const path = `${assetDir}/${(0, track_1.trackFileName)(assetId, level)}`;
+        let raw;
+        try {
+            raw = await readJson(path);
+        }
+        catch {
+            (0, log_1.log)(`loader.miss path=${path}`);
+            continue;
+        }
+        const result = validateTrack(raw);
+        (0, log_1.log)(`loader.load path=${path} ok=${result.ok}` +
+            (result.ok ? ` cues=${result.track.cues.length}` : ` reason=${result.reason}`));
+        // A malformed file is an error, not a reason to fall back: something
+        // produced a file that is not a track, and silently loading a different
+        // one would hide it.
+        return result;
+    }
+    return { ok: false, reason: 'missing', detail: (0, track_1.trackFileName)(assetId, verbosity) };
+}
+/**
+ * A bounded clip cache, oldest out first.
+ *
+ * It holds BYTES, not URIs, and on Vega that is forced rather than chosen:
+ * there is no URI a player will fetch (PLATFORM.md `url_mode_broken`), so
+ * every clip is read by the app and appended through a MediaSource.
+ */
+class ClipCache {
+    constructor(max = budget_1.MAX_CLIPS_IN_MEMORY) {
+        this.max = max;
+        this.order = [];
+        this.held = new Map();
+    }
+    put(uri, bytes) {
+        if (this.held.has(uri))
+            this.order = this.order.filter((u) => u !== uri);
+        this.held.set(uri, bytes);
+        this.order.push(uri);
+        while (this.order.length > this.max) {
+            const evicted = this.order.shift();
+            this.held.delete(evicted);
+            (0, log_1.log)(`cache.evict uri=${evicted} size=${this.held.size}`);
+        }
+    }
+    get(uri) {
+        return this.held.get(uri);
+    }
+    get size() {
+        return this.held.size;
+    }
+}
+exports.ClipCache = ClipCache;
+//# sourceMappingURL=TrackLoader.js.map