react-native-tv-audio-description 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this package are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+While the version is `0.x`, a **minor** release may change the public API — the
+changelog says so under **Changed** whenever it does. A **patch** release never
+does.
+
+A version cannot be published without its section here: `prepublishOnly` checks.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-27
+
+First release: the TV-side audio description layer extracted from
+[Interstice](https://github.com/CesarRivasP/Interstice), with a Vega OS adapter.
+
+### Added
+
+- `MediaAdapter` — the one interface the layer uses to reach a platform: a
+  video player, a clip player, the app lifecycle and the video surface.
+- `CueScheduler` — fires each cue once, only inside its dialogue gap, and only
+  if the gap has room left for it to finish; skips a late cue with a
+  `reason=late` log line rather than speaking over the next scene. `resync()`
+  after a settled seek, `coalesce()` for a held D-pad direction.
+- `DescriptionAudio` — ducks the film to 25% over a 200 ms fade, plays the cue
+  as a second stream, restores to 100% — including when the clip fails, the
+  app is backgrounded, or description is switched off mid-cue.
+- `rampVolumePct` — the fade the platform does not have, timed by elapsed time
+  so late timers cannot stretch it.
+- `loadTrack` / `validateTrack` — one track file per verbosity level, validated
+  field by field, falling back to `standard` when a level is missing and
+  refusing to fall back when one is malformed. `ClipCache`, a bounded cache.
+- `ADControls` — the remote surface: an on/off switch and three verbosity
+  levels, every state announced to the screen reader, once. `stateMessage()`
+  for the same sentences outside React Native.
+- The word budget for track producers: `wordCeiling`, `wordTarget`,
+  `baseWordBudget`, `VERBOSITY_SCALES`.
+- `setLogger()` — every diagnostic line handed to the app, silent by default.
+- `react-native-tv-audio-description/vega` — `createVegaAdapter()` for Vega OS,
+  and `SegmentBuffer`, a buffer window of whole segments measured in time.
+  Handles, among the rest of [PLATFORM.md](PLATFORM.md): `srcObject` instead
+  of a URL, the surface arriving before the player is ready, `sourceopen`
+  firing again after the end of stream, a paused clip that never ends.
+- `npm run example` — a minute of film at 20x in a terminal, self-checking.
+- `example/vega` — a Vega app on a Tears of Steel excerpt, run on the Vega
+  Virtual Device.
+
+[Unreleased]: https://github.com/CesarRivasP/react-native-tv-audio-description/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/CesarRivasP/react-native-tv-audio-description/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 César Rivas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PLATFORM.md

@@ -0,0 +1,262 @@
+# Platform findings — Vega OS media
+
+What this library works around, and how each thing was found. Every entry was
+**measured**, most of them on the way to shipping
+[Interstice](#where-these-come-from) on the Vega Virtual Device; none of it was
+in the platform documentation at the time.
+
+**Stack measured against:** Vega SDK 0.24 (0.24.12112), Vega CLI 1.3.4,
+`@amazon-devices/react-native-w3cmedia` 2.3.2, React Native 0.83, the **Vega
+Virtual Device**. Nothing here has been re-measured on a physical Fire TV
+yet; the entries that can only be settled there say so.
+
+Each entry: what happens, how it was measured, what it costs you if you do not
+know, and where this library handles it.
+
+---
+
+## The six that shaped the design
+
+### url_mode_broken
+
+**Assigning a URL to `player.src` fails before a single byte is requested.**
+
+`MEDIA_ERR_SRC_NOT_SUPPORTED` (code 4), with an empty native message and no
+media log line, for a remote URL, for a packaged `file://` path, and for
+`AudioPlayer` as well as `VideoPlayer`. The HTTP server serving the file logs
+no request at all. `canPlayType()` answers `"probably"` for the same type it
+then refuses, so format negotiation is not where it stops. Same device, same
+session, same footage: `.src` fails, `MediaSource` plays.
+
+- **Measured:** 2026-09-25. Reproduced independently by another developer on
+  the same stack, in the
+  [Amazon developer forum](https://community.amazondeveloper.com/t/audioplayer-url-mode-fails-with-media-err-src-not-supported-on-vvd-app-never-connects-to-com-amazon-media-server-both-official-media-samples-also-fail/29117).
+- **Cost of not knowing:** about four days and six rounds of work, most of it
+  spent on hypotheses about codecs, containers and paths that the error message
+  invites and that are all wrong.
+- **Here:** every byte is fetched in JavaScript and appended to a
+  `MediaSource` attached through `srcObject`, for the film and for each
+  description clip (`src/vega/index.tsx`, `src/vega/SegmentBuffer.ts`). The
+  `MediaAdapter` interface says no implementation may assume the platform
+  fetches anything. A test fails if the adapter ever assigns `src`.
+
+### no_range_requests
+
+**A `Range` request returns `200` and the whole file.**
+
+A `fetch` of a packaged file with `Range: bytes=0-65535` came back with status
+`200`, **2,628,566 bytes** — the entire file — and no `Content-Range` header.
+
+- **Measured:** 2026-09-26, on the Virtual Device, against a packaged
+  `file:///pkg/...` path.
+- **Cost of not knowing:** a buffer window built on byte ranges *appears to
+  work* — playback is fine — while every "chunk" is the whole film. On a
+  32-bit Fire TV Stick that is the memory bound failing silently, in the one
+  place nobody is looking.
+- **Here:** the asset is cut into whole segments at build time, and
+  `SegmentBuffer` keeps a window of whole segments measured in **time, not in
+  count**: ffmpeg cuts on keyframes, so segments asked for at 6 s came out
+  9.94 s, 4.17 s, 5.29 s and 0.65 s, and "keep five segments" would mean
+  anything between 3 and 50 seconds of media.
+
+### surface_races_init
+
+**`initialize()` and the surface handle arrive in no guaranteed order.**
+
+The video surface was handed over **26 ms before** `VideoPlayer.initialize()`
+resolved. Calling `play()` from the surface callback alone plays a player with
+no source yet and yields `MEDIA_ERR_SRC_NOT_SUPPORTED` — which reads exactly
+like an unsupported file, and is not one.
+
+- **Measured:** 2026-09-22.
+- **Here:** the adapter tracks both signals; whichever lands second starts
+  playback. The surface is part of the adapter (`MediaAdapter.VideoSurface`)
+  precisely so a screen cannot wire it up on its own. Tests cover both orders.
+
+### waiting_fires_at_start
+
+**MSE emits `waiting` during normal startup.**
+
+2 ms after `play()` resolved, on a clip that then played to the end.
+
+- **Measured:** 2026-09-25. No fake emits a spurious `waiting`, so no unit test
+  could have found this; it took running on the device.
+- **Cost of not knowing:** a screen that treats a stall as terminal announces
+  "Buffering" over a film that is playing perfectly — to a viewer who cannot
+  see that it is.
+- **Here:** `onStalled` is a state playback can *leave*: the interface exposes
+  `onPlaying` as its exit and says so.
+
+### no_volume_ramp
+
+**The volume setter is instantaneous. There is no fade anywhere in the API.**
+
+- **Measured:** 2026-09-22, from the package's own type declarations: no
+  ramp parameter exists anywhere in the media surface.
+- **Cost of not knowing:** a duck that jumps from 100% to 25% in a single
+  step on every cue, because the platform will not fade it for you.
+- **Here:** the fade is stepped in JavaScript, once, in `src/duck.ts`, and is
+  cancellable so it cannot outlive the screen that started it.
+  `VideoPlayer.setVolumePct` deliberately takes no `rampMs`: accepting one
+  would invite every platform implementation to rewrite the same loop, and
+  imply a capability no platform here has.
+
+### no_js_console
+
+**There is no readable JavaScript console on the device.**
+
+`console.log` reaches `vega device start-log-stream` in neither Release nor
+Debug builds, and since React Native 0.73 Metro prints "JavaScript logs have
+moved" and routes them to React Native DevTools, which needs a browser. There
+is also no way to take a screenshot.
+
+- **Measured:** 2026-09-22.
+- **What works:** an HTTP beacon to the development host, over the reverse
+  port forwarding the device already uses for Metro
+  (`vega device start-port-forwarding --port 8099 --forward false`), with a
+  tiny server on the host printing each request.
+- **Here:** the library writes nothing by default; `setLogger()` hands you
+  every diagnostic line, and where they go is your app's decision.
+
+---
+
+## Found by running this package on the Virtual Device
+
+Measured 2026-09-27 with `example/vega`, on the stack above. None of these
+shows up in a unit test against a mock — each needed the device.
+
+### sourceopen_refires
+
+**`sourceopen` fires again after `endOfStream()`, whenever the buffer changes.**
+
+This one is the MSE specification, not a Vega defect: `appendBuffer()` or
+`remove()` on a source whose `readyState` is `ended` moves it back to `open`
+and fires `sourceopen` again. Evicting old media behind the playhead once the
+last segment is in does exactly that. A `sourceopen` handler that builds the
+`SourceBuffer` therefore runs twice. On the device that built a second buffer,
+re-appended the whole asset, evicted again, reopened again — a loop at the end
+of every film, with `endOfStream()` throwing *"exception when updating
+attribute is true"* as the two chains collided.
+
+- **Here:** the adapter handles `sourceopen` once per `open()`, and
+  `endOfStream()` is only called when no buffer operation is in flight.
+
+### coarse_timers
+
+**`setTimeout(fn, 16)` fires late.** A fade written as 13 steps of 16 ms took
+about **510 ms** instead of 200. With the fade down, the clip start and the
+fade back up all stretched, three of four cues brought the film back up after
+their window had closed — by up to 0.57 s.
+
+- **Here:** `rampVolumePct` sets each step's level from the time *elapsed*,
+  not from its step number, so the fade ends on time however late the timer
+  fires. Measured after the change: fades of 200–260 ms.
+
+### paused_never_ends
+
+**A paused `AudioPlayer` never emits `ended`.** Stopping a cue by pausing its
+clip player left the promise waiting for `ended` pending forever — so the
+player was never torn down: one leaked player per interrupted cue.
+
+- **Here:** `clips.stop()` settles the clip's promise itself, and teardown
+  (`deinitialize()`, ~120 ms on the device) runs without holding up the
+  restore of the film.
+
+### What a cue costs, end to end
+
+From the scheduler firing a cue to the film being back at full, on the
+Virtual Device with the changes above: **fade down + clip start 250–290 ms**,
+then the speech, then **fade up 200–260 ms**. `CueScheduler` will not fire a
+cue that its window cannot hold — reached late, say, because description was
+switched back on mid-gap — and skips it with a `reason=late` log line instead.
+
+---
+
+## Also measured, and worth knowing
+
+### concurrent_streams — a second stream over the film works
+
+A `VideoPlayer` fed by one `MediaSource` and an `AudioPlayer` built with
+`(CONTENT_TYPE_SPEECH, USAGE_ACCESSIBILITY)` fed by another played
+**simultaneously**: the cue ran its full 4.50 s while the video reported
+`paused=false` and zero dropped frames. Ducking the film to `volume = 0.25`
+disturbed neither. This is what makes the library possible.
+**Not measured:** that a listener *hears* it — there is no audio capture path
+off the Virtual Device. What is measured is that both pipelines ran and the
+volume was applied. Audible ducking needs a physical Fire TV.
+
+### mse_path — fragmented MP4, full codec string
+
+The media must be **fragmented MP4**
+(`ffmpeg -movflags +frag_keyframe+empty_moov+default_base_moof`), and
+`addSourceBuffer` rejects a bare `video/mp4`: it needs the full parameters,
+e.g. `video/mp4; codecs="avc1.42C01E,mp4a.40.2"`. Pass yours as
+`createVegaAdapter({ videoMime })`. An MP3 cannot be appended to a
+`SourceBuffer` at all, so description clips need repackaging as fragmented
+AAC.
+
+### media_process_is_separate — what JS can reach, the player may not
+
+JavaScript fetched `http://localhost:8100/clip.mp4` over the reverse port
+forward and got `200`; the player rejected the same URL and the server logged
+no request from it. The media pipeline runs in its own process
+(`com.amazon.media.server`). Host-localhost forwarding works for the app and
+not for playback, and the two look identical from JavaScript. (With
+`url_mode_broken` this is moot for this library — JS does all the fetching —
+but it will bite anything that hands the player a URL.)
+
+### manifest services — missing ones fail silently
+
+Media services must be declared under `[wants]` in `manifest.toml`. Missing,
+the result is no video **and no error**.
+
+### video_width_unreported — `videoWidth` stays 0
+
+`videoWidth` and `videoHeight` stay 0 through `loadedmetadata`, `playing` and
+beyond, and the platform's `resize` event carries `w=0 h=0` — while 253 frames
+decode with 0 dropped. Do not gate "is video playing" on the width; use
+`getVideoPlaybackQuality().totalVideoFrames`.
+
+### voiceview_not_enablable — screen reader testing needs hardware
+
+VoiceView cannot be turned on on the Virtual Device by any developer route:
+the config key is readable but `vdcm set` returns "No permission for
+operation" from both `vega device run-cmd` and `vega device shell`. Another
+developer on the same platform reports the other two documented routes failing
+too: the Virtual Device's Settings app has no Accessibility section, and the
+Back+Menu chord does not fire. So `ADControls`' accessibility contract is unit-tested by
+what it **announces**, and has not been exercised under VoiceView itself.
+
+### run_cmd_is_sandboxed — "does not exist" means nothing
+
+`vega device run-cmd` runs as an app user inside an app context: `ps` lists two
+processes and `/dev/input` "does not exist" while input injection through the
+same shell works. **Any probe run from there that reports a resource absent has
+reported nothing.** Key injection that does work:
+`vega device run-cmd -c 'inputd-cli button_press KEY_ENTER'`.
+
+### build_packages_assets_dir — `assets/` ships, all of it
+
+`react-native build-vega` copies the entire project-root `assets/` directory
+into the package whether or not anything references it. A 372 MB source video
+left there made a 497 MB package, with nothing in the build output to say so.
+Keep host-side media somewhere else.
+
+### Kepler types and `noUncheckedIndexedAccess`
+
+`@amazon-devices/react-native-kepler` ships `.ts` sources behind its type
+entry point, so `skipLibCheck` does not cover them, and
+`KeplerBackHandler.ts` fails with TS2722 under `noUncheckedIndexedAccess`. A
+project that imports the w3cmedia types with that flag on cannot type-check.
+This library leaves the flag off for that reason.
+
+---
+
+## Where these come from
+
+This library was extracted from **Interstice**, an AI audio description app
+for Fire TV built for the Amazon Developer Hackathon 2026. Its specification
+keeps every one of these as a measured entry with date and evidence, and the
+dates above are those measurements. If you re-measure any of them on another
+SDK version or on hardware and get a different answer, an issue saying so is
+the most useful contribution this file can get.

package/README.md

@@ -0,0 +1,324 @@
+# react-native-tv-audio-description
+
+Speak audio description in the gaps between dialogue, **on the TV itself**:
+lower the film, say what is on screen, bring the film back — before anyone
+speaks again. Driven from the remote, with three verbosity levels, and every
+state announced to the screen reader.
+
+For blind and low-vision viewers most films have no audio description track
+at all. Tracks can now be generated — subtitles give the dialogue gaps, a
+vision model describes the frames, text-to-speech voices it. What was missing
+is the part that plays such a track **on a television**, where the media stack
+is not a browser's and a remote is the only input. That is this library.
+
+It was extracted from **Interstice**, an entry to the Amazon Developer
+Hackathon 2026 (Fire TV, Vega OS), and ships a **Vega OS adapter** along with
+the [platform findings](PLATFORM.md) it took to make one work.
+
+```sh
+git clone https://github.com/CesarRivasP/react-native-tv-audio-description.git
+cd react-native-tv-audio-description
+npm install
+npm run example
+```
+
+`npm run example` plays a minute of film at 20x in your terminal — no device,
+no SDK — through the library's real scheduler, audio layer and track loader,
+and **checks what it shows**: it exits non-zero if a cue fires outside its
+gap, is still speaking when dialogue resumes, or leaves the film ducked.
+
+---
+
+## What it does
+
+```
+dialogue ██████████░░░░░░░░░░░░░░░░████████████░░░░░░░░░░░██████
+gaps               [    cue c1     )            [  cue c2  )
+film volume  100% ─╮                ╭─ 100% ───╮           ╭─ 100%
+                   ╰──── 25% ───────╯          ╰── 25% ────╯
+description        "A keeper climbs the stairs…" "Waves. An empty boat…"
+```
+
+- **Fires a cue only inside its own gap, and only if it can finish there.** A
+  cue whose gap has passed, or whose gap has too little left — description
+  switched back on mid-gap — is skipped, never played late: a late cue talks
+  over dialogue, which is worse than no description.
+- **Ducks, speaks, restores** — the film goes to 25% over a 200 ms fade, the
+  clip plays as a second stream over it, and the film always comes back to
+  100%, including when the clip fails and when the app is backgrounded.
+- **Seeks cleanly.** A held D-pad direction is collapsed into one settled
+  seek, and the scheduler resyncs once, so jumping through a film does not
+  fire a burst of descriptions for scenes the viewer skipped.
+- **Three verbosity levels**, one track file each, falling back to `standard`
+  when a level was never generated.
+- **Refuses to be silent.** A missing or malformed track produces a spoken
+  sentence — "Playback continues without description" — not a quiet screen
+  that a blind viewer cannot tell from a quiet scene.
+
+## Install
+
+Not on npm yet — `0.1.0` is on its way. Until then, from GitHub:
+
+```sh
+npm install github:CesarRivasP/react-native-tv-audio-description
+```
+
+Peer dependencies: `react` ^19.2 and `react-native` ^0.83. For the Vega
+adapter, also `@amazon-devices/react-native-w3cmedia ~2.3.2` and
+`@amazon-devices/react-native-kepler ~4.0.0` — pin those with `~`, not `^`:
+they are system-distributed libraries, and the Kepler linter fails the build
+when they float.
+
+## Usage
+
+On Vega OS, a player screen:
+
+```tsx
+import React, { useEffect, useMemo, useState } from 'react';
+import { View } from 'react-native';
+import {
+  ADControls,
+  CueScheduler,
+  DescriptionAudio,
+  loadTrack,
+  type ADState,
+  type AssetSource,
+  type Verbosity,
+} from 'react-native-tv-audio-description';
+import { createVegaAdapter } from 'react-native-tv-audio-description/vega';
+
+// Vega's player cannot be pointed at a path, but fetch can read a packaged file.
+const fetchJson = async (path: string): Promise<unknown> => (await fetch(path)).json();
+
+interface PlayerProps {
+  asset: AssetSource; // the film, cut into fragmented-MP4 segments
+  trackDir: string; // where <assetId>.<verbosity>.track.json live
+  assetId: string;
+  readJson?: (path: string) => Promise<unknown>; // how to read a track file
+}
+
+export function Player({ asset, trackDir, assetId, readJson = fetchJson }: PlayerProps) {
+  // One adapter, one audio layer, one scheduler per screen.
+  const media = useMemo(() => createVegaAdapter(), []);
+  const audio = useMemo(() => new DescriptionAudio(media), [media]);
+  const scheduler = useMemo(
+    () => new CueScheduler({ onFire: (cue) => void audio.speak(cue) }),
+    [audio],
+  );
+
+  const [verbosity, setVerbosity] = useState<Verbosity>('standard');
+  const [enabled, setEnabled] = useState(true);
+  const [state, setState] = useState<ADState>({ kind: 'missing', detail: 'loading' });
+
+  // Position drives the scheduler; a settled seek resyncs it.
+  useEffect(() => {
+    const offs = [
+      media.video.onPosition((ms) => scheduler.tick(ms)),
+      media.video.onSeek((ms) => scheduler.resync(ms)),
+    ];
+    void media.video.open(asset).then(() => media.video.play());
+    return () => {
+      offs.forEach((off) => off());
+      void audio.stop();
+      void media.video.destroy();
+    };
+  }, [media, audio, scheduler, asset]);
+
+  // A level switch loads that level's file, falling back to standard.
+  useEffect(() => {
+    void loadTrack(readJson, trackDir, assetId, verbosity).then((result) => {
+      if (!result.ok) {
+        scheduler.load([]);
+        setState({ kind: result.reason, detail: result.detail });
+        return;
+      }
+      scheduler.load(result.track.cues);
+      scheduler.resync(media.video.positionMs());
+      setState({
+        kind: 'ready',
+        enabled,
+        verbosity: result.loaded_verbosity,
+        cues: result.track.cues.length,
+      });
+    });
+    // `enabled` is applied separately below; reloading on a toggle is not needed
+  }, [media, scheduler, trackDir, assetId, verbosity, readJson]);
+
+  const onToggle = (on: boolean) => {
+    setEnabled(on);
+    scheduler.setEnabled(on); // the film is never touched by a toggle
+    if (!on) void audio.stop(); // cuts a cue mid-sentence and restores the film
+    setState((s) => (s.kind === 'ready' ? { ...s, enabled: on } : s));
+  };
+
+  return (
+    <View style={{ flex: 1 }}>
+      <media.VideoSurface style={{ flex: 1 }} />
+      <ADControls state={state} onToggle={onToggle} onVerbosity={setVerbosity} />
+    </View>
+  );
+}
+```
+
+This is [`example/vega/src/Player.tsx`](example/vega/src/Player.tsx), which
+`npm run typecheck` compiles against the library — if the API changes, this
+README's example stops compiling. A real screen will also want to say
+something on `media.video.onStalled` (and stop saying it on `onPlaying` —
+see [`waiting_fires_at_start`](PLATFORM.md#waiting_fires_at_start)).
+
+## The track
+
+One JSON file per verbosity level, named `<asset_id>.<verbosity>.track.json`:
+
+```json
+{
+  "version": "1",
+  "asset_id": "lighthouse",
+  "generated_at": "2026-09-27T00:00:00.000Z",
+  "source_subtitles": "lighthouse.en.srt",
+  "verbosity": "standard",
+  "model_id": "…",
+  "cues": [
+    {
+      "id": "c1",
+      "start_ms": 2000,
+      "end_ms": 6500,
+      "words": 10,
+      "text": "A lighthouse keeper climbs the spiral stairs, lantern in hand.",
+      "audio_uri": "audio/c1.standard.m4a",
+      "source_frames_ms": [4250],
+      "status": "ok"
+    }
+  ]
+}
+```
+
+- `start_ms`/`end_ms` is the dialogue gap the cue may speak in; `end_ms` is
+  exclusive.
+- A cue that could not be produced is **written** with `"status": "failed"`
+  and empty `text` and `audio_uri`, not dropped. It is never scheduled, but the
+  track still says the gap was considered.
+- The levels do **not** share a cue list: a gap that holds a useful sentence at
+  `detailed` may hold nothing useful at `concise`. In the film this was built
+  on, the three levels came out at 47, 55 and 60 cues.
+- `validateTrack` checks every field; `loadTrack` treats a missing file and a
+  malformed one differently — missing falls back to `standard`, malformed does
+  not, because silently loading a different file would hide a broken producer.
+
+Full examples in [`example/assets/`](example/assets/).
+
+### Producing tracks: the word budget
+
+A cue has to finish before dialogue resumes. At 160 words per minute, with
+300 ms kept back for the fade:
+
+```ts
+import { wordCeiling, wordTarget } from 'react-native-tv-audio-description';
+
+wordCeiling(4500);             // 11 — never exceed this, at any level
+wordTarget(4500, 'concise');   //  6 — what to ask a describer for
+wordTarget(4500, 'detailed');  // 11
+```
+
+Levels are fractions of the ceiling (0.6 / 0.85 / 1.0), never multipliers, so
+no level can ask for more words than the gap holds. `npm run example` checks
+its own track against this before playing it.
+
+## The adapter
+
+Everything above is written against one interface,
+[`MediaAdapter`](src/MediaAdapter.ts), and never against a platform package —
+a test fails if that stops being true. Two rules in it matter if you write
+your own:
+
+- **Do not assume the platform fetches anything.** On Vega it will not, so
+  the Vega adapter reads every byte itself. The interface takes an
+  `AssetSource` — a list of segments, even for a single file — so a short clip
+  and a feature film run the same code path.
+- **`setVolumePct` is immediate and takes no ramp.** The fade lives in the
+  library, once. An interface that took `rampMs` would make every platform
+  rewrite it.
+
+### `createVegaAdapter(options?)`
+
+| option | default | |
+|---|---|---|
+| `videoMime` | `video/mp4; codecs="avc1.42C01E,mp4a.40.2"` | **Set this to your asset's codecs.** A bare `video/mp4` is rejected. |
+| `clipMime` | `audio/mp4; codecs="mp4a.40.2"` | Description clips, fragmented AAC. |
+| `window` | `{ aheadMs: 30000, behindMs: 10000 }` | Media held around the playhead, in time. |
+
+It handles, so you do not have to: `srcObject` instead of `src`, the surface
+arriving before the player is ready, a buffer window of whole segments that
+never holds the whole film, one `SourceBuffer` operation at a time, and clips
+on an `AudioPlayer` built for accessibility speech. Each is explained in
+[PLATFORM.md](PLATFORM.md).
+
+Another platform: implement `MediaAdapter` (the simulated one in
+[`example/node/simAdapter.ts`](example/node/simAdapter.ts) is a complete,
+small example) and everything else works unchanged.
+
+## Seeing what it does on a device
+
+Nothing is logged by default. On Vega, `console.log` goes nowhere you can read
+([`no_js_console`](PLATFORM.md#no_js_console)), so the library hands every
+diagnostic line to you instead:
+
+```ts
+import { setLogger } from 'react-native-tv-audio-description';
+
+setLogger((line) => {
+  // e.g. "scheduler.fire id=c1 pos_ms=2004 window=[2000,6500)"
+  void fetch(`http://localhost:8099/?m=${encodeURIComponent(line)}`).catch(() => {});
+});
+```
+
+## Platform findings
+
+What the Vega adapter works around, each one measured — the short version:
+
+| | what happens | cost if you do not know |
+|---|---|---|
+| [`url_mode_broken`](PLATFORM.md#url_mode_broken) | `player.src = url` fails before a byte is requested | days, chasing codecs that are fine |
+| [`no_range_requests`](PLATFORM.md#no_range_requests) | a `Range` request returns `200` and the whole file | a "bounded" buffer that holds the entire film |
+| [`surface_races_init`](PLATFORM.md#surface_races_init) | the surface can arrive before `initialize()` resolves | an error that reads as "unsupported file" |
+| [`waiting_fires_at_start`](PLATFORM.md#waiting_fires_at_start) | MSE emits `waiting` 2 ms into normal playback | "Buffering" announced over a film that plays |
+| [`no_volume_ramp`](PLATFORM.md#no_volume_ramp) | volume changes are instantaneous, no fade exists | a duck that jumps instead of fading |
+| [`no_js_console`](PLATFORM.md#no_js_console) | no readable JS console, in Release or Debug | an app you cannot observe |
+
+And a dozen smaller ones — fragmented MP4 only, a separate media process,
+silent manifest failures, `videoWidth` stuck at 0, VoiceView unavailable on the
+Virtual Device — in [PLATFORM.md](PLATFORM.md).
+
+## What is verified, and what is not
+
+- **Unit tests** covering every component and the adapter against a
+  mock of the platform package. `npm test`.
+- **The example** — end to end on a simulated adapter, self-checking.
+- **On the Vega Virtual Device**, with [`example/vega`](example/vega): the
+  packaged library plays a segmented excerpt of Tears of Steel with four
+  cues, each firing inside its window, ducking to 25% and restoring before the
+  window closes; the remote switches description off mid-cue, on again, and
+  to `concise`. What those runs found — and fixed — is in
+  [PLATFORM.md § Found by running this package](PLATFORM.md#sourceopen_refires).
+- **Not yet verified, and needing a physical Fire TV:** that the duck is
+  *audible* (the Virtual Device has no audio capture path), the controls under
+  VoiceView (it cannot be enabled on the Virtual Device), and the memory bound
+  over a feature-length film (eviction has run once, at the end of the 20 s
+  excerpt — not across a film long enough for the bound to matter).
+
+## Versions
+
+[Semantic Versioning](https://semver.org), recorded in
+[CHANGELOG.md](CHANGELOG.md). While the version is `0.x`, a minor release may
+change the API and says so under **Changed**; a patch release never does.
+Every published version is a tagged commit (`v0.1.0` …): `npm publish` refuses
+to run unless HEAD carries the tag, the tree is clean, the changelog has the
+version's section, and the typecheck, tests and build pass.
+
+To release: move the **Unreleased** notes under a new dated heading, then
+`npm version <major|minor|patch>` (which checks the changelog, commits and
+tags), `git push --follow-tags`, `npm publish`.
+
+## License
+
+MIT © César Rivas

package/lib/ADControls.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+import { View } from 'react-native';
+import type { Verbosity } from './track';
+import { 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 declare function ADControls({ state, onToggle, onVerbosity, focusRef }: ADControlsProps): React.JSX.Element;