react-native-tv-audio-description 0.1.0

package/lib/vega/index.d.ts

@@ -0,0 +1,33 @@
+import type { MediaAdapter } from '../MediaAdapter';
+import { type BufferWindow } from './SegmentBuffer';
+export { SegmentBuffer, DEFAULT_WINDOW, type AppendTarget, type BufferWindow, type SourceLike, } from './SegmentBuffer';
+/**
+ * The Vega OS implementation of `MediaAdapter`.
+ *
+ * EXTRACTED from code that already ran on the Vega Virtual Device, not written
+ * from the interface down. Each of the following is a bug somebody already
+ * paid for (details in PLATFORM.md):
+ *   - `srcObject`, never `src` — `url_mode_broken`: assigning a URL to `src`
+ *     fails before a single byte is requested;
+ *   - dual readiness tracking — `surface_races_init`: the surface can arrive
+ *     before `initialize()` resolves, and playing before both have landed
+ *     yields MEDIA_ERR_SRC_NOT_SUPPORTED, which reads exactly like an
+ *     unsupported file and is not one;
+ *   - fragmented MP4 through MediaSource only — `mse_path`;
+ *   - clips on an AudioPlayer built for accessibility speech, as a second
+ *     stream over the film — `concurrent_streams`.
+ */
+export interface VegaAdapterOptions {
+    /**
+     * The MSE type of YOUR asset, with full codec parameters. A bare
+     * 'video/mp4' is rejected at addSourceBuffer. Default: H.264 Constrained
+     * Baseline L3.0 + AAC-LC. Read yours with
+     * `ffprobe -show_streams` and build the RFC 6381 string.
+     */
+    videoMime?: string;
+    /** the MSE type of the description clips (default fragmented AAC-LC) */
+    clipMime?: string;
+    /** how much media to hold around the playhead */
+    window?: BufferWindow;
+}
+export declare function createVegaAdapter(options?: VegaAdapterOptions): MediaAdapter;

package/lib/vega/index.js

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_WINDOW = exports.SegmentBuffer = void 0;
+exports.createVegaAdapter = createVegaAdapter;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const react_native_w3cmedia_1 = require("@amazon-devices/react-native-w3cmedia");
+const SegmentBuffer_1 = require("./SegmentBuffer");
+const log_1 = require("../log");
+var SegmentBuffer_2 = require("./SegmentBuffer");
+Object.defineProperty(exports, "SegmentBuffer", { enumerable: true, get: function () { return SegmentBuffer_2.SegmentBuffer; } });
+Object.defineProperty(exports, "DEFAULT_WINDOW", { enumerable: true, get: function () { return SegmentBuffer_2.DEFAULT_WINDOW; } });
+const DEFAULT_VIDEO_MIME = 'video/mp4; codecs="avc1.42C01E,mp4a.40.2"';
+const DEFAULT_CLIP_MIME = 'audio/mp4; codecs="mp4a.40.2"';
+/** whole-file append, for description CLIPS — they are seconds long, not films */
+function fetchAndAppend(source, mime, uri) {
+    return new Promise((resolve, reject) => {
+        source.addEventListener('sourceopen', () => {
+            (async () => {
+                try {
+                    const buffer = source.addSourceBuffer(mime);
+                    const response = await fetch(uri);
+                    const bytes = new Uint8Array(await response.arrayBuffer());
+                    buffer.addEventListener('updateend', () => {
+                        if (source.readyState !== 'open')
+                            return;
+                        source.endOfStream();
+                        resolve(bytes.byteLength);
+                    });
+                    buffer.appendBuffer(bytes);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            })().catch(reject);
+        });
+    });
+}
+class VegaVideo {
+    constructor(mime, window) {
+        this.mime = mime;
+        this.window = window;
+        this.player = new react_native_w3cmedia_1.VideoPlayer();
+        this.ready = { player: false, surface: false };
+        this.pendingPlay = null;
+        this.listeners = new Map();
+        this.initialised = null;
+        this.lastError = null;
+        this.segments = null;
+    }
+    async initialize() {
+        if (!this.initialised) {
+            this.initialised = this.player.initialize().then(() => {
+                this.player.addEventListener('error', () => {
+                    const code = this.player.error?.code ?? -1;
+                    const msg = this.player.error?.message ?? 'none';
+                    (0, log_1.log)(`player.error code=${code} msg=${msg}`);
+                    this.lastError = new Error(`media error ${code}: ${msg}`);
+                    this.emit('error');
+                });
+                for (const type of ['timeupdate', 'seeked', 'waiting', 'stalled', 'playing', 'ended']) {
+                    this.player.addEventListener(type, () => this.emit(type));
+                }
+            });
+        }
+        return this.initialised;
+    }
+    emit(type) {
+        for (const cb of this.listeners.get(type) ?? [])
+            cb();
+    }
+    on(type, cb) {
+        const set = this.listeners.get(type) ?? new Set();
+        set.add(cb);
+        this.listeners.set(type, set);
+        return () => set.delete(cb);
+    }
+    /** called by the surface component when the platform hands over a handle */
+    attachSurface(handle) {
+        (0, log_1.log)(`player.surface created handle=${handle}`);
+        this.player.setSurfaceHandle(handle);
+        this.ready.surface = true;
+        this.release();
+    }
+    detachSurface(handle) {
+        (0, log_1.log)(`player.surface destroyed handle=${handle}`);
+        this.player.clearSurfaceHandle(handle);
+        this.ready.surface = false;
+    }
+    /** whichever of the two readiness signals lands second lets playback start */
+    release() {
+        if (!this.ready.player || !this.ready.surface)
+            return;
+        const go = this.pendingPlay;
+        this.pendingPlay = null;
+        go?.();
+    }
+    async open(asset) {
+        await this.initialize();
+        const source = new react_native_w3cmedia_1.MediaSource();
+        const opened = new Promise((resolve, reject) => {
+            let handled = false;
+            source.addEventListener('sourceopen', () => {
+                // ONCE. Per MSE, appendBuffer() or remove() on an 'ended' source
+                // reopens it and fires 'sourceopen' again — and evicting behind the
+                // playhead after the last segment is in does exactly that. Handling it
+                // twice builds a second SourceBuffer and re-appends the whole asset,
+                // which evicts, which reopens: a loop, measured on the Virtual Device
+                // at the end of a 20 s clip (PLATFORM.md `sourceopen_refires`).
+                if (handled)
+                    return;
+                handled = true;
+                (async () => {
+                    const buffer = source.addSourceBuffer(this.mime);
+                    this.segments = new SegmentBuffer_1.SegmentBuffer(source, buffer, asset, this.window);
+                    await this.segments.start();
+                    resolve();
+                })().catch(reject);
+            });
+        });
+        // srcObject, NOT src — see PLATFORM.md `url_mode_broken`.
+        this.player.srcObject = source;
+        await opened;
+        (0, log_1.log)(`player.opened segments=${asset.segments.length} init=${asset.initUri ? 'yes' : 'none'}`);
+        // Keep the window fed as the playhead moves. The bounded window is what
+        // stops a feature-length asset becoming a feature-length ArrayBuffer.
+        this.on('timeupdate', () => {
+            void this.segments?.ensure(this.positionMs());
+        });
+        this.ready.player = true;
+        this.release();
+    }
+    play() {
+        return new Promise((resolve, reject) => {
+            const start = () => {
+                this.player
+                    .play()
+                    .then(() => {
+                    (0, log_1.log)('player.play resolved');
+                    resolve();
+                })
+                    .catch(reject);
+            };
+            if (this.ready.player && this.ready.surface)
+                start();
+            else
+                this.pendingPlay = start; // the surface race, handled once, here
+        });
+    }
+    pause() {
+        this.player.pause();
+    }
+    positionMs() {
+        // currentTime is NaN until the player has media; a NaN position would
+        // reach the scheduler as a seek to nowhere
+        const t = this.player.currentTime;
+        return Number.isFinite(t) ? Math.round(t * 1000) : 0;
+    }
+    durationMs() {
+        const d = this.player.duration;
+        return Number.isFinite(d) ? Math.round(d * 1000) : 0;
+    }
+    isPlaying() {
+        return !this.player.paused;
+    }
+    setVolumePct(pct) {
+        this.player.volume = Math.max(0, Math.min(100, pct)) / 100;
+    }
+    onPosition(cb) {
+        return this.on('timeupdate', () => cb(this.positionMs()));
+    }
+    onSeek(cb) {
+        return this.on('seeked', () => cb(this.positionMs()));
+    }
+    onStalled(cb) {
+        const offWaiting = this.on('waiting', cb);
+        const offStalled = this.on('stalled', cb);
+        return () => {
+            offWaiting();
+            offStalled();
+        };
+    }
+    onPlaying(cb) {
+        return this.on('playing', cb);
+    }
+    onEnded(cb) {
+        return this.on('ended', cb);
+    }
+    onError(cb) {
+        return this.on('error', () => cb(this.lastError ?? new Error('media error')));
+    }
+    async destroy() {
+        this.segments?.dispose();
+        this.segments = null;
+        this.listeners.clear();
+        this.ready = { player: false, surface: false };
+        this.pendingPlay = null;
+        await this.player.deinitialize().catch(() => {
+            // best effort during teardown; must not throw into React's cleanup path
+        });
+    }
+}
+class VegaClips {
+    constructor(mime) {
+        this.mime = mime;
+        this.current = null;
+        /** settles the clip that is playing; set for exactly as long as one is */
+        this.interrupt = null;
+    }
+    async play(uri) {
+        const player = new react_native_w3cmedia_1.AudioPlayer(react_native_w3cmedia_1.AudioContentType.CONTENT_TYPE_SPEECH, react_native_w3cmedia_1.AudioUsageType.USAGE_ACCESSIBILITY);
+        this.current = player;
+        try {
+            await player.initialize();
+            if (!react_native_w3cmedia_1.MediaSource.isTypeSupported(this.mime)) {
+                throw new Error(`cue container unsupported: ${this.mime}`);
+            }
+            const source = new react_native_w3cmedia_1.MediaSource();
+            const appended = fetchAndAppend(source, this.mime, uri);
+            player.srcObject = source;
+            const bytes = await appended;
+            (0, log_1.log)(`cue.audio bytes=${bytes}`);
+            await new Promise((resolve, reject) => {
+                // A paused AudioPlayer never emits 'ended', so without this a stopped
+                // clip's promise never settles and its player is never torn down —
+                // one leaked player per interrupted cue, measured on the Virtual Device.
+                this.interrupt = () => {
+                    (0, log_1.log)('cue.audio state=stopped');
+                    resolve();
+                };
+                player.addEventListener('error', () => {
+                    const code = player.error?.code ?? -1;
+                    reject(new Error(`cue media error ${code}`));
+                });
+                player.addEventListener('ended', () => {
+                    (0, log_1.log)(`cue.audio state=ended t=${player.currentTime.toFixed(2)}`);
+                    resolve();
+                });
+                player.play().catch(reject);
+            });
+        }
+        finally {
+            this.current = null;
+            this.interrupt = null;
+            // Not awaited: tearing the clip player down took ~130 ms on the Virtual
+            // Device, and every one of them kept the film ducked after the speech
+            // had ended. A cue that cannot be torn down must not stop the film.
+            void player.deinitialize().catch(() => undefined);
+        }
+    }
+    stop() {
+        this.current?.pause();
+        this.interrupt?.();
+    }
+}
+class VegaLifecycle {
+    onBackground(cb) {
+        const sub = react_native_1.AppState.addEventListener('change', (state) => {
+            if (state !== 'active')
+                cb();
+        });
+        return () => sub.remove();
+    }
+}
+function createVegaAdapter(options = {}) {
+    const video = new VegaVideo(options.videoMime ?? DEFAULT_VIDEO_MIME, options.window ?? SegmentBuffer_1.DEFAULT_WINDOW);
+    function VideoSurface({ style }) {
+        const onCreated = (0, react_1.useCallback)((handle) => video.attachSurface(handle), []);
+        const onDestroyed = (0, react_1.useCallback)((handle) => video.detachSurface(handle), []);
+        return ((0, jsx_runtime_1.jsx)(react_native_w3cmedia_1.KeplerVideoSurfaceView, { style: style, scalingmode: "fit", onSurfaceViewCreated: onCreated, onSurfaceViewDestroyed: onDestroyed }));
+    }
+    return {
+        video,
+        clips: new VegaClips(options.clipMime ?? DEFAULT_CLIP_MIME),
+        lifecycle: new VegaLifecycle(),
+        VideoSurface,
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/vega/index.js.map

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

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "react-native-tv-audio-description",
+  "version": "0.1.0",
+  "description": "Speak AI-generated audio description in the gaps between dialogue, on the TV itself: duck the film, play the cue, restore — driven from the remote, with three verbosity levels.",
+  "license": "MIT",
+  "author": "César Rivas",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CesarRivasP/react-native-tv-audio-description.git"
+  },
+  "homepage": "https://github.com/CesarRivasP/react-native-tv-audio-description#readme",
+  "bugs": "https://github.com/CesarRivasP/react-native-tv-audio-description/issues",
+  "keywords": [
+    "react-native",
+    "tv",
+    "fire-tv",
+    "vega",
+    "accessibility",
+    "audio-description",
+    "a11y",
+    "mse"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./vega": {
+      "types": "./lib/vega/index.d.ts",
+      "default": "./lib/vega/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "PLATFORM.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "example": "tsx example/node/index.ts",
+    "release:check": "node scripts/check-release.mjs",
+    "version": "node scripts/check-release.mjs --changelog-only",
+    "prepublishOnly": "npm run release:check && npm run typecheck && npm test && npm run build",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "@amazon-devices/react-native-kepler": "~4.0.0",
+    "@amazon-devices/react-native-w3cmedia": "~2.3.2",
+    "react": "^19.2.0",
+    "react-native": "^0.83.0"
+  },
+  "peerDependenciesMeta": {
+    "@amazon-devices/react-native-kepler": {
+      "optional": true
+    },
+    "@amazon-devices/react-native-w3cmedia": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@amazon-devices/react-native-kepler": "~4.0.0",
+    "@amazon-devices/react-native-w3cmedia": "~2.3.2",
+    "@babel/core": "^7.29.7",
+    "@react-native/babel-preset": "0.83.0",
+    "@testing-library/react-native": "^13.3.3",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^24.13.6",
+    "@types/react": "^19.3.0",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
+    "react": "19.2.0",
+    "react-native": "0.83.0",
+    "react-test-renderer": "19.2.0",
+    "tsx": "^4.23.15",
+    "typescript": "~5.6"
+  }
+}

package/src/ADControls.tsx

@@ -0,0 +1,92 @@
+import React, { useCallback, useEffect, useRef } from 'react';
+import { AccessibilityInfo, Pressable, Text, View } from 'react-native';
+import type { Verbosity } from './track';
+import { VERBOSITY_LEVELS } from './track';
+import { log } from './log';
+import { stateMessage, type ADState } from './messages';
+
+export { stateMessage, type ADState } from './messages';
+
+/**
+ * The remote surface, and every failure said out loud.
+ *
+ * This is for blind and low-vision viewers. A control surface that shows an
+ * error and says nothing is the same as silence, so every assertion in its
+ * test suite is about what is ANNOUNCED, not about what is rendered.
+ *
+ * It is deliberately unstyled: bring your own look. What it guarantees is the
+ * accessibility contract — roles, labels, state, and one announcement per
+ * state change.
+ */
+
+export interface ADControlsProps {
+  state: ADState;
+  onToggle: (enabled: boolean) => void;
+  onVerbosity: (v: Verbosity) => void;
+  /** hand focus here when the player screen mounts */
+  focusRef?: React.Ref<View>;
+}
+
+export function ADControls({ state, onToggle, onVerbosity, focusRef }: ADControlsProps) {
+  const lastSpoken = useRef<string>('');
+
+  // 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.
+  useEffect(() => {
+    const message = stateMessage(state);
+    if (message === lastSpoken.current) return;
+    lastSpoken.current = message;
+    AccessibilityInfo.announceForAccessibility(message);
+    log(`controls.announce kind=${state.kind}`);
+  }, [state]);
+
+  const toggle = useCallback(() => {
+    if (state.kind !== 'ready') return;
+    log(`controls.toggle to=${!state.enabled}`);
+    onToggle(!state.enabled); // the scheduler flips; the video is untouched
+  }, [state, onToggle]);
+
+  if (state.kind !== 'ready') {
+    return (
+      <View accessible accessibilityRole="alert" accessibilityLabel={stateMessage(state)}>
+        <Text>{stateMessage(state)}</Text>
+      </View>
+    );
+  }
+
+  return (
+    <View>
+      <Pressable
+        ref={focusRef}
+        accessible
+        accessibilityRole="switch"
+        accessibilityLabel="Audio description"
+        accessibilityState={{ checked: state.enabled }}
+        onPress={toggle}
+        hasTVPreferredFocus
+      >
+        <Text>{state.enabled ? 'Description: on' : 'Description: off'}</Text>
+      </Pressable>
+
+      {/* three levels, each its own focusable, each announcing its state */}
+      {VERBOSITY_LEVELS.map((level) => (
+        <Pressable
+          key={level}
+          accessible
+          accessibilityRole="radio"
+          accessibilityLabel={`${level} description`}
+          accessibilityState={{ selected: state.verbosity === level, disabled: !state.enabled }}
+          disabled={!state.enabled}
+          onPress={() => {
+            log(`controls.verbosity to=${level}`);
+            onVerbosity(level);
+          }}
+        >
+          <Text>{level}</Text>
+        </Pressable>
+      ))}
+    </View>
+  );
+}

package/src/CueScheduler.ts

@@ -0,0 +1,145 @@
+import type { DescriptionCue } from './track';
+import { AD } from './budget';
+import { log } from './log';
+
+/**
+ * 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 function estimateCueMs(cue: DescriptionCue): number {
+  return (cue.words / AD.SPEAKING_RATE_WPM) * 60_000 + 2 * AD.DUCK_RAMP_MS;
+}
+
+export class CueScheduler {
+  private cues: DescriptionCue[] = [];
+  private cursor = 0;
+  private firing: DescriptionCue | null = null;
+  private enabled = true;
+
+  private readonly estimateMs: (cue: DescriptionCue) => number;
+
+  constructor(
+    private readonly events: SchedulerEvents,
+    options: SchedulerOptions = {},
+  ) {
+    this.estimateMs = options.estimateMs ?? estimateCueMs;
+  }
+
+  /** `failed` cues carry no audio; they never enter the schedule. */
+  load(cues: DescriptionCue[]): void {
+    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;
+    log(`scheduler.load cues=${this.cues.length}`);
+  }
+
+  setEnabled(on: boolean): void {
+    this.enabled = on;
+    if (!on) this.firing = null;
+  }
+
+  /** Called on every position update from the platform. */
+  tick(positionMs: number): void {
+    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) {
+        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++;
+        log(
+          `scheduler.skip id=${next.id} pos_ms=${positionMs} reason=late` +
+            ` remaining_ms=${remaining} needs_ms=${needs}`,
+        );
+        return;
+      }
+      this.firing = next;
+      this.cursor++;
+      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: number): void {
+    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;
+    log(`scheduler.resync pos_ms=${positionMs} cursor=${this.cursor}`);
+  }
+}
+
+/**
+ * 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 function coalesce(fn: (value: number) => void, quietMs = 250) {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let pending = 0;
+  let events = 0;
+
+  return (value: number): void => {
+    pending = value;
+    events++;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      log(`scheduler.coalesced events=${events} settled_ms=${pending}`);
+      events = 0;
+      timer = null;
+      fn(pending);
+    }, quietMs);
+  };
+}