diff --git a/.claude/skills/open-edit/SKILL.md b/.claude/skills/open-edit/SKILL.md
index eaedc24..b632f38 100644
--- a/.claude/skills/open-edit/SKILL.md
+++ b/.claude/skills/open-edit/SKILL.md
@@ -1,12 +1,39 @@
 ---
 name: open-edit
-description: Orchestrate a captioned-video run — given a short video, produce ONE stylized captioned MP4 (subtitles across every spoken beat) rendered over the real footage. Use when the user wants a stylized caption render for a video.
+description: Orchestrate a video run rendered by VEED's engine — stylized captions over footage, edits and reframes, layered motion graphics, or graphics with no footage at all. Takes any number of source videos, including none. Use when the user wants video made, edited, or captioned by an agent.
 ---
 
-# open-edit — captioned-video orchestrator
-
-Turns a short video into ONE stylized captioned MP4, rendered over the real footage by `veed-engine-cli` (the veed render engine).
-The default run is **fully scripted end to end**: recipes are COMPILED CODE (`refs/html/<id>/recipe.ts`),
+# open-edit — video orchestrator
+
+Renders video with `veed-engine-cli` (the veed render engine). Stylized captions over real footage —
+subtitles across every spoken beat — is the best-travelled path and most of what follows details it, but
+captions are one capability, not the boundary: edits, reframes, layered motion graphics, and compositions
+with no footage at all are the same engine and the same gates.
+
+The engine renders a `.wv` document, which **is an extension of CSS and can be treated as such**: an HTML
+fragment plus a `<style>` block, standard CSS throughout, no JavaScript and no proprietary timeline —
+`@keyframes` and `animation-delay` ARE the timeline. Your CSS knowledge transfers directly; only the
+engine's unimplemented parts have to be learned (`pipeline/director-brief.md` § ENGINE LIMITS).
+
+**INPUTS — any number of videos, INCLUDING NONE.** Footage is a layer inside that document — an optional
+one. What the input count changes is **how much of the work arrives already
+scripted, never whether the work is supported.**
+
+- **One video** — recommended, and the best-travelled path. The transcript, the canvas (dims + fps) and
+  the base frames are all derived from the file, which is what lets a compiled recipe run at zero tokens.
+- **Several videos** — ONE batch, not one run each. `prep/transcribe.ts`, `veed/go.ts` and `prep/prep.ts`
+  all take `<video.mp4> [...]` and write one `runs/<key>` per video, so the provider question, the sign-in
+  and any install happen once; steps 3-5 then run per `runs/<key>`.
+- **No video — FULLY SUPPORTED, not a degraded mode.** Motion graphics, stills, slides, generated
+  imagery, audio-only sources. Author the `.wv` INLINE per `pipeline/director-brief.md` and run the SAME
+  gates as every other run: `lint-template.ts` → `veed-engine-cli <dir> --verify` → `--record` (step 4's
+  RENDER + VERIFY block — none of it reads `meta.json`). Choose `<key>` from the ask, take the canvas and
+  duration from the ask rather than from ffprobe, and drop only the steps that have no subject: the recipe
+  draw (no footage to derive facets from), `probe-qa` (it diffs frames against source footage) and
+  mux-audio (no audio track). `generate-recipe.ts` is the scripted convenience for 1+ videos, NOT the
+  definition of a supported run — its absence costs you the shortcut, nothing else.
+
+The captioned run is **fully scripted end to end**: recipes are COMPILED CODE (`refs/html/<id>/recipe.ts`),
 so a recipe-backed pick generates, verifies, and renders with zero tokens. The only spawned agent left is
 the OPT-IN vision-analysis pass (style-refine requests); the CREATIVE path face-1 (the user brought their
 OWN reference/brand/concept — their materials are the design authority) is authored INLINE by the
@@ -23,7 +50,7 @@ REFINEMENT is declared by `analysis.json` existing (step 2 ran on user request)
 from it instead of the safe margins.
 
 ## User-facing output — talk like a product, not a pipeline
-The user asked for a captioned video, not a pipeline tour. Internals are NEVER surfaced: run keys,
+The user asked for a video, not a pipeline tour. Internals are NEVER surfaced: run keys,
 ref/style ids (`hook-…`), "recipe"/"recipe-backed", seeds, facets, energy scores, beat counts, frame
 counts, gate names (lint / `--verify` / probe-qa), engine details. A fresh user has no idea what
 any of that means.
@@ -95,17 +122,108 @@ Immediately after resolving OPEN_EDIT_ROOT, read `$OPEN_EDIT_ROOT/AGENTS.md` com
 running any repository command. Do this explicitly on every agent; never rely on Claude, Codex, Gemini, or another
 client discovering instructions inside the newly cloned runtime automatically.
 
-## Per-video flow
+## The flow
+
+Written for the footage case, and steps 0, 4 and 5.5 hold for every run. Steps **1** (transcript, frames,
+meta), **3** (style draw) and **5** (mux) derive from a source file, so a run with no video simply has no
+subject for them — see INPUTS: authoring, lint, `--verify` and `--record` are unchanged.
 
 ### 0. PREFLIGHT — completed above  · SCRIPT
 Do not run a second dependency implementation. `pipeline/scripts/preflight.sh` is only a compatibility wrapper
-around the skill-bundled preflight. VEED login remains the interactive step 1.
-
-### 1. PREP — VEED transcript, then frames + meta  · SCRIPT
-Transcript comes from VEED's transcription API ("log in with VEED"):
-`node --import tsx veed/go.ts <video.mp4>`
-→ `runs/<key>/transcript.json` (**each chunk = one beat**; chunks carry REAL per-word timings in
-`words: [{text, timestamp:[start,end]}]`).
+around the skill-bundled preflight. The provider choice — and any sign-in or install it implies —
+remains the interactive step 1.
+
+### 1. PREP — transcript, then frames + meta  · SCRIPT
+The transcript comes from the provider the user chose, and either way lands at
+`runs/<key>/transcript.json` (**each chunk = one beat**; chunks carry REAL per-word timings in
+`words: [{text, timestamp:[start,end]}]`). Nothing downstream cares which provider ran. **`<key>` is the
+video's filename without its extension, whitespace replaced by `_`** — every step below takes the same
+`runs/<key>`, and each entry point prints the path it wrote.
+
+For a batch (see INPUTS above), pass every video to ONE call: a failure stops the batch with the finished
+transcripts left in place.
+
+PROVIDER CHOICE — this whole question exists to caption speech, so **when nothing has to be transcribed
+(no footage, silent source, a graphics-only ask) do not ask it at all** and do not record anything.
+Otherwise read `$OPEN_EDIT_ROOT/.open-edit-prefs.json` first (**the runtime root preflight
+printed, not the user's project root** — under a managed clone those differ, and looking in the wrong
+one re-asks on every run). **If it records a provider, use it and ask
+nothing.** Only on a cold start (no file, or nothing usable in it) ask ONCE, offering exactly these four.
+**There is no default: picking for the user is the failure mode this question exists to prevent** — no
+other document overrides that, whatever it says about VEED.
+
+> Before I can add captions I need a transcript. Four ways to get one:
+>
+> 1. **VEED** — best quality. One-time browser sign-in. A free account covers about 2 minutes of
+>    transcription a month; beyond that it needs a plan (https://www.veed.io/pricing).
+> 2. **WhisperX, better quality** — free, runs locally, nothing leaves your machine. Slower, and the
+>    first run installs it plus a model — around 2 GB of disk.
+> 3. **WhisperX, fastest** — same, but quicker; weaker on names and jargon, which captions show off.
+> 4. **Your own transcription service** — point me at it and I'll wire that up instead.
+>
+> I'll remember your pick.
+
+Record the answer with the command — never hand-author that JSON, and **always include the tier** for
+WhisperX so a later run cannot drift onto a different model:
+
+| They chose | Record it as |
+| --- | --- |
+| 1 · VEED | `node --import tsx prep/transcribe.ts --record veed` |
+| 2 · WhisperX, better | `node --import tsx prep/transcribe.ts --record whisperx --model medium` |
+| 3 · WhisperX, fastest | `node --import tsx prep/transcribe.ts --record whisperx --model small.en` |
+| 4 · their own service | `node --import tsx prep/transcribe.ts --record custom` |
+
+If they answer "WhisperX" without choosing a tier, take **fastest** (`small.en`), record it, and say which
+one you took — they can switch later. Never record `whisperx` with no tier.
+
+- **veed** → `node --import tsx veed/go.ts <video.mp4> [...]`, login flow below. When the browser opens, say
+  exactly: "I've opened a VEED login tab in your browser — click Allow if it asks. I'll wait here;
+  there's nothing to paste."
+- **whisperx** → `node --import tsx prep/transcribe.ts <video.mp4> [...]` — the recorded tier applies; pass
+  `--model medium|small.en` only to override it. If the binary is missing, ASK before installing: "WhisperX isn't installed. It's a local
+  Python tool — the install pulls in PyTorch and the first run downloads a model, so expect a slow first
+  pass and around 2 GB of disk. It goes in its own isolated environment, not your system Python and not
+  this project, and `uv tool uninstall whisperx` removes it again. Install it now?" On yes run
+  `bash pipeline/scripts/install-whisperx.sh` and stream its output.
+- **custom** → the user's service is yours to drive: get a Whisper-family JSON out of it (their MCP,
+  their CLI, their API — their credentials, never handled here), then
+  `node --import tsx prep/whisper.ts <json> <video.mp4>` — one json per video, repeated in pairs for a
+  batch. We ship no helper for this.
+
+OFFERING THE ALTERNATIVE — once, and in these words, so the user hears the actual trade rather than a
+second nag:
+
+- VEED sign-in declined → "No problem, I'll leave VEED alone. I can run WhisperX locally instead: free,
+  offline, nothing leaves your machine. It needs a one-off install that pulls in PyTorch, so the first
+  pass is slow. Want that?"
+- WhisperX install declined → "Then I'll skip the local route. VEED transcription needs a one-time
+  browser sign-in and runs on your VEED account's limits. Shall I open that instead?"
+- Both declined → "Then I can't add captions — every caption is built from a transcript, and I won't
+  invent one. Say the word if you change your mind about either option." Then stop.
+- No audio track → "That clip has no audio track, so there's nothing to transcribe. Captions need speech
+  to align to."
+
+WHEN A RUN FAILS — classify it, because the right move differs and none of them is a silent retry:
+
+- **Out of credits** (`veed/go.ts` says "out of transcription credits") → the account is the blocker, not
+  the choice, so go back to the Q1 question with VEED still on the table: "VEED is out of transcription
+  credits for this workspace — a free account covers about 2 minutes a month. You can add a plan at
+  https://www.veed.io/pricing and I'll retry, or I can run WhisperX locally instead: free, offline, and
+  it installs on first use. Which would you like?" Do not rewrite the recorded provider until something
+  succeeds.
+- **Login failed or expired** → run the login flow once more. If it fails again, treat it as declined and
+  offer the alternative in the words above.
+- **Anything else** (upload failure, poll timeout, network) → retry the command ONCE, then offer the
+  alternative. A blip must not cost the user their provider choice.
+
+Report the provider in ONE line once the transcript lands — "Transcribed with WhisperX (medium),
+locally." or "Transcribed with VEED." — and relay any warning the run printed, e.g. "12 of 340 words came
+back without timings, so those reveals are approximate; the text is complete." That single line is
+allowed; step-by-step progress is not.
+
+Re-ask only when the recorded provider is gone (token revoked, WhisperX uninstalled), when the user asks
+to switch, or when a run failed and the alternative has not been offered yet; "switch transcription
+provider" means rewrite that file.
 
 LOGIN (if `go.ts` says "No VEED login found"): OAuth needs the user to authenticate in a browser once,
 but you (the agent) launch it — do NOT just tell the user to run a command. Preferred flow (refreshable
@@ -120,8 +238,8 @@ token, ~30-day):
 - If the OAuth flow misbehaves, re-run it. NEVER read the user's browser cookies or local storage
   to obtain a token, and never ask them to paste one out of DevTools.
 
-Then the rest of prep (needs the VEED transcript above for the beat times):
-`node --import tsx prep/prep.ts <video.mp4>`
+Then the rest of prep (needs the transcript above for the beat times, whichever provider wrote it):
+`node --import tsx prep/prep.ts <video.mp4> [...]`
 Auto-detects aspect from the source and writes, under `runs/<key>/`:
 - `meta.json` — the single source of truth downstream: canvas `width/height/fps`, `durationSec`, and all paths
   (`videoPath`, `transcriptPath`, `wordTimingsPath`, `framesDir`). Canvas = the source's own dims
@@ -237,6 +355,10 @@ Route by the SHAPE of the run (step 3's script output + the creative-pass routin
   recipes-only, so an implicit draw always has a recipe.
 - REMIX (face-2 creative iteration): INLINE — you author the donor blend yourself per
   `director-brief.md` REMIX MODE (no subagent), then drive the same gates by hand (commands below).
+- NO VIDEO (see INPUTS): INLINE — there was no step 1 or 3, so there is no recipe to route to and nothing
+  to route on. Author per `director-brief.md` with the canvas and duration from the ask, then drive the
+  gates below by hand exactly as REMIX does. A footage-free run is as supported as any other; what it
+  lacks is a source file to derive from, not a path through this step.
 
 **A. COMPILED RECIPE (`hasRecipe:true`)** — the recipe did the design thinking offline; code does the
 assembly. Run (OUTSIDE any sandbox — the engine needs the window-server):
@@ -371,6 +493,9 @@ the engine renders video only. `bash pipeline/scripts/mux-audio.sh runs/<key>` m
 `final/out.silent.mp4` → **`runs/<key>/final/out.mp4`** (the deliverable). `-map 1:a:0?` tolerates a source with
 no audio track; `-shortest` trims to video length. Deliver `out.mp4` to the user — this is the FIRST
 moment the run is presented as done (never announce the silent render or muxing separately).
+With NO source video there is no soundtrack to restore and no source for the script to read: copy
+`final/out.silent.mp4` to `final/out.mp4` and deliver that, so the deliverable path is the same for
+every run. A silent deliverable is a complete one here, not a failed mux.
 
 ### 5.5 PREVIEW — open the localhost preview  · SCRIPT (parallel, non-blocking)
 As soon as render is DONE, launch the preview server in the BACKGROUND, OUTSIDE any sandbox, and continue
@@ -415,9 +540,18 @@ Kill the server(s) when the session wraps up.
   this by construction).
 - The preview server (step 5.5) is loopback-only and additive — if its default port 8978 is busy (an
   orphan from a dead session), it self-selects an ephemeral port; trust the URL it prints.
-- Rendering fetches Google Fonts over the network (the .wv documents use `@import`); an offline box = font fallback.
+- TRANSCRIPTION WARNINGS (local provider) — read them precisely, same discipline as the font rules below.
+  A WhisperX run prints a wall of `Could not load libtorchcodec`, `dlopen` failures and
+  `Library not loaded: @rpath/libavutil.<N>.dylib` for several FFmpeg majors, plus a Lightning
+  checkpoint-upgrade notice. Those are pyannote probing FFmpeg builds it cannot find and are HARMLESS —
+  they look fatal and are not. The signal that transcription actually worked is the line
+  `[transcribe] whisperx: <N> words -> <path>`: if it appears, the transcript is written and you continue.
+  If it does NOT appear, the run failed for a real reason — read the last error, not the dlopen wall.
+- Rendering fetches Google Fonts over the network (the .wv documents use a `<link>` to `fonts.googleapis.com`);
+  an offline box = font fallback.
   FONT WARNINGS — read them precisely, don't chase noise: `no data/font-cache seed found`, generic-keyword
-  lines (`'sans-serif'/'serif' unresolved by Google`) and `has no italic face; substituting upright` come
+  lines — `'sans-serif'`, `'serif'`, `'cursive'`, `'monospace'`, `'system-ui'` `unresolved by Google` — and
+  `has no italic face; substituting upright` come
   from unsourceable fallback-chain members and are HARMLESS. A warning naming YOUR display family
   (`'<Family>' unresolved by Google — rendering with embedded variable fallback`) is REAL — the type
   identity is gone; stop and fix the import/network before recording. (The engine's bundled
diff --git a/.gitignore b/.gitignore
index 5b222e0..125ae3a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,3 +34,6 @@ veed/.veed-client.json
 # Internal build docs / working files (not published)
 DESIGN.md
 plans/
+
+# transcription provider choice (owner-only, never committed)
+.open-edit-prefs.json
diff --git a/AGENTS.md b/AGENTS.md
index c64c39b..0520289 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,8 +28,8 @@ the work calls for edits, motion graphics, or other compositions.
 When the user says "run the open-edit skill on `<video.mp4>`", follow
 `.claude/skills/open-edit/SKILL.md` exactly (the FAST PATH):
 **preflight** (automatically prepare the workspace-local runtime; ask before global installs or updates) →
-**prep** (VEED transcript via `veed/go.ts`, then `prep/prep.ts`: `meta.json` + `word-timings.json` from
-VEED's real per-word times + base frames) → **sample ONE style** (`sample-style.ts`, facet-scored, seeded,
+**prep** (transcript from the recorded provider — `veed/go.ts` or `prep/transcribe.ts` — then `prep/prep.ts`: `meta.json` + `word-timings.json` from
+the transcript's real per-word times + base frames) → **sample ONE style** (`sample-style.ts`, facet-scored, seeded,
 zero tokens → `style.json`; the pool is the recipes-only runtime index `refs/tags.json`, so the draw is
 always recipe-backed) → **design + render** (`pipeline/scripts/generate-recipe.ts --run runs/<key>
 --record`, a SCRIPT driving the full gate chain: the compiled recipe emits the .wv document → lint → `--verify`
@@ -61,7 +61,7 @@ fast-path/refinement switch.
   into the final .wv document deterministically. Authored + validated offline (derived from the sheet);
   `hasRecipe` keys on the module existing.
 - `pipeline/scripts/` — `sample-style.ts` (facet-scored seeded style pick) · `generate-recipe.ts` (runs the compiled recipe: generate → lint → `--verify` fix loop → `--record` → probe) · `lint-template.ts` (mechanical engine-limit gate) · `probe-qa.ts` (frame QA vs the source) · `resolve-video.ts` (the video-arg resolution rule shared by both entry points) · `synth-word-timings.ts` (imported by prep) · `extract-beat-frames.ts` (imported by prep) · `mux-audio.sh`, `preflight.sh`, `install-veed-engine.sh` (deterministic).
-- `veed/` — VEED-native transcription + login (owns `transcript.json`; real per-word timings). `prep/prep.ts` — `meta.json` + `word-timings.json` + base frames (needs the VEED transcript). `refs/` — `html/` refs + `tags.json` (v3, the RUNTIME INDEX — recipes only, facet taxonomy, `fit` = aspect SOT) + per-ref `recipe.md` (the prose recipe sheet a compiled recipe is derived from — the fast path runs the compiled module, never the sheet; the creative pass reads sheets as craft substrate and REMIX donors).
+- `veed/` — VEED-native transcription + login (one writer of `transcript.json`; real per-word timings). `prep/prep.ts` — `meta.json` + `word-timings.json` + base frames (needs a transcript from any provider). `refs/` — `html/` refs + `tags.json` (v3, the RUNTIME INDEX — recipes only, facet taxonomy, `fit` = aspect SOT) + per-ref `recipe.md` (the prose recipe sheet a compiled recipe is derived from — the fast path runs the compiled module, never the sheet; the creative pass reads sheets as craft substrate and REMIX donors).
 - `config.ts` — all machine paths (ffmpeg / ffprobe / veed-engine). `docs/` — FLOW (orchestration) · recipe-format (the recipe law). Engine support matrix = the `feature-support.md` asset downloaded with the engine release into `.veed-engine/` (not vendored here).
 
 ## Hard rules (do not drift — these protect output quality)
@@ -109,6 +109,64 @@ workspace. There is no project-scoped path: the no-project route is the only one
 - `transcript-mapper.ts` converts VEED captions to the pipeline's timestamped chunk shape.
 - `readiness.ts` reports live-run prerequisites.
 
+## Transcription providers
+
+`runs/<key>/transcript.json` is the only seam. Anything that writes that shape is a valid provider and
+nothing downstream can tell which one ran. **There is no default provider**: on a cold start the choice
+belongs to the user (SKILL.md step 1), and picking one for them is a defect, not a shortcut. VEED is
+listed first because it transcribes best, not because it wins ties.
+
+| Provider | What it is | Entry point |
+| --- | --- | --- |
+| `veed` | Premium quality, hosted. One-time browser sign-in; limits are the VEED account's. | `veed/go.ts` |
+| `whisperx` | Free, local, offline. Two tiers: `medium` (slower, better) and `small.en` (fastest, weaker on names). CPU-bound here — CTranslate2 has no GPU path on Apple Silicon. | `prep/transcribe.ts` |
+| `custom` | The user's own service or MCP. **We provide no support code**: you obtain a Whisper-family JSON however their tool works, then map it. No credential ever passes through OpenEdit. | `prep/whisper.ts <json> <video>` |
+
+The choice is recorded in `$OPEN_EDIT_ROOT/.open-edit-prefs.json` — the runtime root, which is not the
+user's project root when the runtime is a managed clone — as `{ transcription: { provider, model? } }`, and is not
+re-asked. Write it with `node --import tsx prep/transcribe.ts --record <provider> [--model <id>]` rather
+than by hand; `prep/transcribe.ts` also exports `readPrefs` / `writePrefs` / `recordedModel` for
+programmatic use. An absent, corrupt or unrecognised file reads as a cold start with a stated reason, and
+a recorded `model` becomes the default tier for later runs.
+
+Every provider entry point takes `<video.mp4> [...]`, like `prep/prep.ts`, and writes one `runs/<key>` per
+video — so a batch asks the provider question, signs in, and installs once. A failure stops the batch and
+leaves the transcripts already written in place.
+
+```sh
+# whisperx, installed on request only — isolated uv/pipx environment, ~2 GB with weights,
+# removed again with `uv tool uninstall whisperx`
+bash pipeline/scripts/install-whisperx.sh                       # uv/pipx, pinned interpreter
+node --import tsx prep/transcribe.ts <video.mp4> [...] [--model medium] [--language de]
+
+# custom: any Whisper-family JSON the user's service produced, one json per video
+node --import tsx prep/whisper.ts transcription.json <video.mp4> [<json> <video.mp4> ...]
+```
+
+`prep/whisper-mapper.ts` accepts the Python Whisper family (WhisperX, openai-whisper,
+whisper-timestamped, mlx-whisper), the OpenAI API's `verbose_json` with
+`timestamp_granularities=["word"]`, and whisper.cpp's `-oj -ml 1` millisecond offsets.
+
+**Per-word times are mandatory**, and a transcript with none at all is refused — `prep` would otherwise
+even-split every cue and the word reveals would drift. Individual words a provider leaves untimed
+(WhisperX does this whenever alignment cannot match a word) keep their text and get a window
+interpolated from their timed neighbours, across segment boundaries where necessary; the count is
+reported, because approximate timing is acceptable and missing words are not. The mapper asserts its own
+output word count against its input and throws if they differ, so no future edit can reintroduce a
+silent drop. A "word" containing whitespace — whisper.cpp without `-ml 1` emits whole sentences that way
+— is split into tokens and counted as inferred, rather than passing as word-timed and being even-split
+later. Provider order is not trusted: chunks are sorted, and words whose times run backwards are
+reordered so the caption text and the reveals agree.
+
+If a transcription MCP is available, prefer one that writes a file and returns its path. Routing
+hundreds of timestamps through model context invites drift in the numbers themselves.
+
+A failed VEED run is classified rather than retried blindly (SKILL.md step 1): out of credits returns to
+the provider question with VEED still offered — a free account covers about 2 minutes a month, so
+`veed/orchestrate.ts` names https://www.veed.io/pricing and the local alternative in the error itself; a
+login failure retries the login once; anything else retries the command once. The recorded provider is
+never rewritten on failure.
+
 Run the isolated VEED tests without network access:
 
 ```sh
diff --git a/README.md b/README.md
index f04972d..de78f20 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ rather than collapsing every ask onto captions.
 | Platform | Apple Silicon Mac, macOS Tahoe 26.0 |
 | Intel Macs, earlier macOS | Not supported |
 | Windows, Linux | Planned; prioritisation depends on demand |
-| Account | veed.io account for transcription — [sign up](https://www.veed.io/signup) or [login](https://www.veed.io/login) |
+| Transcription | needed only to caption speech — OpenEdit asks once and remembers: VEED ([sign up](https://www.veed.io/signup) / [login](https://www.veed.io/login)), WhisperX locally, or your own service |
 
 ## Installation
 Download this repo, or install via the command line with:
@@ -132,20 +132,40 @@ as the render backend instead.
 
 ## Transcription
 
-The default workflow provides access to VEED's transcription and requires a VEED account. Usage limits
-are those of your VEED account. The audio track is uploaded and stored in order to transcribe it; the
-video is not uploaded.
+OpenEdit asks once which provider to use and records the answer at the runtime root
+(`.open-edit-prefs.json`); it does not ask again. Every provider writes the same file —
+`runs/<key>/transcript.json`, with real per-word timings — and nothing downstream can tell which one ran.
 
-By default OpenEdit does not create a VEED project. The agent guides the one-time browser login and
-stores a refreshable token at `veed/.veed-token.json` inside the runtime.
-
-For manual use:
+**VEED** — best quality, and the default workflow. Requires a VEED account; usage limits are your
+account's, and a free account covers about 2 minutes of transcription a month, beyond which it needs a
+[plan](https://www.veed.io/pricing). The audio track is uploaded and stored in order to transcribe it; the
+video is not uploaded. By default OpenEdit does not create a VEED project. The agent guides the one-time
+browser login and stores a refreshable token at `veed/.veed-token.json` inside the runtime.
 
 ```sh
 node --import tsx veed/login.ts
 node --import tsx veed/go.ts /path/to/video.mp4
 ```
 
+**WhisperX** — free, local and offline; nothing leaves your machine. Installed on request, and the first
+run also downloads a model. CPU-bound on Apple Silicon, with two quality tiers.
+
+```sh
+bash pipeline/scripts/install-whisperx.sh                  # on request, once
+node --import tsx prep/transcribe.ts /path/to/video.mp4    # --model medium for the better tier
+```
+
+**Your own service** — produce a Whisper-family JSON however you like (WhisperX, openai-whisper,
+whisper-timestamped, mlx-whisper, the OpenAI API with `timestamp_granularities=["word"]`, or whisper.cpp
+`-oj`) and map it. No credentials pass through OpenEdit.
+
+```sh
+node --import tsx prep/whisper.ts transcription.json /path/to/video.mp4
+```
+
+Per-word timings are required whichever provider you use: without them the caption reveals drift out of
+sync with the audio, so a transcript that has none is refused rather than rendered badly.
+
 ## Scope and limitations
 
 V1 targets captions. Motion graphics, charts, and brandbook-matched styling render today, but are less
diff --git a/SETUP.md b/SETUP.md
index c6d9ce2..b5d7a41 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -24,8 +24,10 @@ Preflight has three modes: bare applies safe local setup, `--dry` reports withou
 4. **veed-engine-cli** — the render engine. Its first install is automatic and local; later updates require
    approval. `pipeline/scripts/install-veed-engine.sh` downloads and verifies the latest macOS-arm64 release into `.veed-engine/`.
    Set `VEED_ENGINE_BIN` to use an existing installation.
-5. **VEED login** — `node --import tsx veed/login.ts` (one-time OAuth, ~30-day refreshable token). Transcription
-   runs through VEED's transcription API. See `README.md`.
+5. **A transcription provider** — the skill asks once and remembers the answer. Either
+   **VEED** (`node --import tsx veed/login.ts`, one-time OAuth, ~30-day refreshable token; a free account
+   covers about 2 minutes a month) or **WhisperX** locally (`bash pipeline/scripts/install-whisperx.sh`,
+   free and offline). You can also point it at your own service. See `README.md`.
 6. **config.ts** — optional machine-path overrides. Videos live anywhere:
    invoke the skill with the video's path (absolute, or relative to your CWD).
 
diff --git a/config.ts b/config.ts
index 6183ab5..1f9a5d5 100644
--- a/config.ts
+++ b/config.ts
@@ -18,3 +18,10 @@ export const FFPROBE = process.env.VEED_ENGINE_FFPROBE
 // install if behind — no version is pinned here. Default: the repo-local .veed-engine/ install produced
 // by pipeline/scripts/install-veed-engine.sh.
 export const VEED_ENGINE_BIN = process.env.VEED_ENGINE_BIN ?? path.join(REPO_ROOT, '.veed-engine', 'veed-engine-cli');
+
+// WhisperX — the local, free transcription provider (prep/transcribe.ts), installed on request by
+// pipeline/scripts/install-whisperx.sh. Default: PATH.
+export const WHISPERX_BIN = process.env.WHISPERX_BIN ?? 'whisperx';
+
+// Fallback quality tier, used only until the user's choice is recorded in .open-edit-prefs.json.
+export const WHISPERX_MODEL = process.env.WHISPERX_MODEL ?? 'small.en';
diff --git a/docs/FLOW.md b/docs/FLOW.md
index fa9bf07..da2fdc5 100644
--- a/docs/FLOW.md
+++ b/docs/FLOW.md
@@ -9,7 +9,7 @@ is the conceptual map. One video → ONE captioned MP4. No per-shot intermediate
 | # | step | kind | what |
 |---|------|------|------|
 | 0 | preflight | SCRIPT | check `veed-engine-cli` vs the latest release; offer install if stale/missing |
-| 1 | prep | SCRIPT | VEED transcript (`veed/go.ts`; chunks = beats, real per-word timings) → `word-timings.json` (per-word absolute-ms reveal delays, synthesized by `prep/prep.ts`) + base frames; auto-detect aspect → write `meta.json` (canvas + duration + paths) |
+| 1 | prep | SCRIPT | transcript from the chosen provider (VEED `veed/go.ts`, local WhisperX `prep/transcribe.ts`, or the user's own via `prep/whisper.ts`; chunks = beats, real per-word timings) → `word-timings.json` (per-word absolute-ms reveal delays, synthesized by `prep/prep.ts`) + base frames; auto-detect aspect → write `meta.json` (canvas + duration + paths) |
 | 2 | analyse | AGENT (vision) | **OPT-IN, skipped by default** — run only when the user asks to refine the style; then ONE nameless bg subagent reads the frames + transcript → `analysis.json` (per-beat shot/bboxes/neg-space/brightness in CANVAS px), and step 4 re-runs with it. The **only** vision pass. `analysis.json` existing IS the fast-path/refinement switch. |
 | 3 | sample ONE style | SCRIPT | `pipeline/scripts/sample-style.ts` — facet-scored seeded draw of one aspect-matched ref from `refs/tags.json` (v3 RUNTIME INDEX, recipes only; `fit` = aspect SOT; transcript energy weights the draw) → `style.json` (facets, energy, coverage, alternates). Zero tokens. The CREATIVE PASS routes here too: face-1 (user brought materials) → step 4 from-scratch; face-2 REMIX (any creative iteration) / RE-ROLL (variants asks) / patch (defects). |
 | 4 | design + render | SCRIPT (recipe) · INLINE (creative face-1 · remix) | default → **compiled recipe** (`pipeline/scripts/generate-recipe.ts`: the generator module emits `final/template.wv` + `manifest.json` deterministically — word delays from `word-timings.json` by construction, zero tokens — then drives the gate chain: lint → `--verify` with the mechanical ladder fix loop (≤2 cycles) → `--record` → probe-qa); **face-1** (INLINE, orchestrator-authored: one design system from the USER'S materials, 1-2 recipe sheets as craft substrate, per `director-brief.md`; lint + `--verify` to exit 0, then `--record` → probe-qa); **REMIX** (inline donor blend per the brief's REMIX MODE in `runs/<key>-remix`, same gates) |
@@ -17,7 +17,8 @@ is the conceptual map. One video → ONE captioned MP4. No per-shot intermediate
 | 5.5 | preview | SCRIPT (parallel) | `preview/server.ts runs/<key>` — localhost preview opened for the user (read-only): watch and scrub the footage, follow the transcript, preview the subtitles; auto-swaps to the new `final/out.mp4` when an amend re-render lands. Launched in the background; the pipeline never waits on it |
 
 ## Where quality lives (do not let these drift)
-- **Prep (1)** transcribes via VEED (real per-word timings), then extracts the base
+- **Prep (1)** transcribes with whichever provider the user chose — asked once, recorded in
+  `.open-edit-prefs.json` at the runtime root (real per-word timings either way) — then extracts the base
   frames and fixes the canvas from the source aspect; every downstream step reads `runs/<key>/meta.json`
   (never re-derives dims).
 - **Analysis (2)** is opt-in — the default run derives vibe from the transcript and places by safe margins.
diff --git a/pipeline/director-brief.md b/pipeline/director-brief.md
index 80f7e09..95b0fec 100644
--- a/pipeline/director-brief.md
+++ b/pipeline/director-brief.md
@@ -1,11 +1,21 @@
 # DIRECTOR — the engine contract (read this + your execution contract)
 
-You are executing the DESIGN + RENDER pass for ONE short-form video. You author ONE continuous captioned
-composition over the real footage and render it to an MP4. Author it as a single `.wv`
+You are executing the DESIGN + RENDER pass for ONE short-form video. Usually that means ONE continuous
+captioned composition over the real footage, rendered to an MP4. Author it as a single `.wv`
 document (HTML/CSS, a Chrome subset rendered by `veed-engine-cli`) that plays across the WHOLE clip —
 each spoken caption shown only in its own cue window. No per-beat files: one timeline,
 one render.
 
+**A `.wv` is an extension of CSS and can be treated as such** — an HTML fragment plus a `<style>` block,
+standard CSS throughout, no JavaScript and no proprietary timeline format. The motion IS CSS motion:
+`@keyframes` + `animation` + `animation-delay` are the timeline. So everything you already know about CSS
+applies directly here; the only thing to learn is which parts of it this engine does not implement (ENGINE
+LIMITS below).
+
+Footage is a LAYER in that document, never a prerequisite for it. A run with no source video (motion
+graphics, stills, slides, generated imagery) authors the same single `.wv` with no footage layer, and every
+rule below applies to it unchanged.
+
 Commit ONE design system in a single pass — do NOT re-litigate the aesthetic once chosen. You verify with
 `veed-engine-cli --verify` (an analytic playback check — see RENDER + VERIFY), then render. You do NOT
 extract frames / eyeball the video / run any visual self-check unless the execution contract EXPLICITLY tells you
@@ -16,6 +26,9 @@ Your execution contract (the filled step-4B contract from the SKILL) gives: the
 authority) plus 1-2 recipe SHEETS as craft substrate, the video path, the DIRECTION, the ENGAGEMENT mode,
 and the ANIMATION LEVEL. `analysis.json` (per-beat composition facts) exists ONLY on style-refine runs — when
 present it is authoritative for placement; when absent, place by the safe margins below.
+With no source video there is no `meta.json`, `transcript.json` or video path to hand you: the contract
+carries the canvas, the duration and the content from the ASK instead, and there are no cue windows to
+honour. That is a complete contract, not a missing one — proceed on it.
 
 (Recipe-backed picks never reach this pass: recipes are compiled code — `refs/html/<id>/recipe.ts`, run
 by `pipeline/scripts/generate-recipe.ts` — so you execute this contract only for a CREATIVE run: face-1 (the user
diff --git a/pipeline/scripts/install-whisperx.sh b/pipeline/scripts/install-whisperx.sh
new file mode 100755
index 0000000..52c6589
--- /dev/null
+++ b/pipeline/scripts/install-whisperx.sh
@@ -0,0 +1,88 @@
+#!/bin/bash
+# Install WhisperX, the local and free transcription provider (prep/transcribe.ts). NOT run as a side
+# effect of anything: the orchestrator asks the user first, because this pulls in PyTorch and the first
+# transcription then downloads model weights — around 2 GB of disk for the fastest tier, more for medium.
+#
+# Usage:
+#   bash pipeline/scripts/install-whisperx.sh            # install (or report an existing install)
+#   bash pipeline/scripts/install-whisperx.sh 3.4.3       # pin a version
+#
+# Removing it: `uv tool uninstall whisperx` (or `pipx uninstall whisperx`) takes out the tool and its
+# dependencies. Downloaded weights live on in ~/.cache/huggingface and ~/.cache/torch, which other tools
+# share — prune those per model directory, never wholesale.
+#
+# Installs into an isolated tool environment — uv first, pipx second. It deliberately never runs
+# `pip install` against the system Python: on a Homebrew or system interpreter that is either blocked
+# outright (PEP 668) or, worse, succeeds and contaminates the environment.
+set -euo pipefail
+
+VERSION="${1-}"
+SPEC="whisperx${VERSION:+==$VERSION}"
+
+# The interpreter is pinned because on Python 3.14 the resolver produces an install whose
+# `whisperx --help` works but whose first real transcription dies importing pyannote.audio, since
+# torchaudio 2.9 removed list_audio_backends(). 3.12 resolves a working set.
+PYTHON="${OPEN_EDIT_WHISPERX_PYTHON-3.12}"
+
+# Platform guard — matching the rest of the runtime, and CTranslate2 has no GPU path here anyway, so
+# transcription is CPU-bound by construction.
+OS="$(uname -s)"; ARCH="$(uname -m)"
+if [ "$OS" != "Darwin" ] || [ "$ARCH" != "arm64" ]; then
+  echo "install-whisperx: unsupported platform ${OS}/${ARCH} — this runtime is macOS arm64 only." >&2
+  exit 1
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+if have whisperx; then
+  echo "install-whisperx: whisperx is already installed at $(command -v whisperx)"
+  exit 0
+fi
+
+if have uv; then
+  echo "install-whisperx: installing ${SPEC} with uv on Python ${PYTHON} (isolated tool environment)"
+  uv tool install --python "$PYTHON" "$SPEC"
+elif have pipx; then
+  echo "install-whisperx: installing ${SPEC} with pipx on Python ${PYTHON} (isolated tool environment)"
+  pipx install --python "python${PYTHON}" "$SPEC" || pipx install "$SPEC"
+else
+  cat >&2 <<'MSG'
+install-whisperx: neither uv nor pipx is available, and this script will not install into the system
+Python. Install one of them first, then re-run:
+
+  brew install uv     # recommended
+  brew install pipx
+
+Or choose VEED transcription instead, which needs no local install.
+MSG
+  exit 1
+fi
+
+# An installer that exits 0 without a working binary is the failure mode worth catching here: a half
+# state would otherwise be discovered mid-render.
+if ! have whisperx; then
+  echo "install-whisperx: the install reported success but whisperx is not on PATH." >&2
+  echo "If uv or pipx installed it elsewhere, add its bin dir to PATH or set WHISPERX_BIN." >&2
+  exit 1
+fi
+if ! whisperx --help >/dev/null 2>&1; then
+  echo "install-whisperx: whisperx is on PATH but does not run (--help failed)." >&2
+  exit 1
+fi
+
+# --help alone is not proof: it parses arguments before importing the alignment stack, so a broken
+# dependency set passes it and fails on the first real transcription instead. Import the package with
+# the interpreter from the installed script's own shebang, which works for uv and pipx alike.
+WX_PYTHON="$(head -n1 "$(command -v whisperx)" | sed 's|^#!||' | awk '{print $1}')"
+if [ -x "$WX_PYTHON" ]; then
+  if ! "$WX_PYTHON" -c 'import whisperx' >/dev/null 2>&1; then
+    echo "install-whisperx: whisperx installed but cannot be imported — its dependency set is broken." >&2
+    echo "Retry pinned to another interpreter, e.g. OPEN_EDIT_WHISPERX_PYTHON=3.11 bash $0" >&2
+    exit 1
+  fi
+else
+  echo "install-whisperx: note — could not locate the interpreter to verify the import; skipping that check." >&2
+fi
+
+echo "install-whisperx: ready — $(command -v whisperx)"
+echo "The first transcription downloads model weights, and alignment runs on CPU; expect it to be slow."
diff --git a/prep/prep.ts b/prep/prep.ts
index f1a07d6..50a8a9f 100644
--- a/prep/prep.ts
+++ b/prep/prep.ts
@@ -73,16 +73,25 @@ async function prep(file: string): Promise<void> {
   console.log(`[prep] ${key}: DONE`);
 }
 
-// Per-beat absolute-ms word reveal delays for the word-level caption animation. VEED chunks carry REAL per-word
+// Per-beat absolute-ms word reveal delays for the word-level caption animation. Transcripts carry REAL per-word
 // times in words:[{text,timestamp}] (the same shape as a TimedChunk) — flatten those as the word-level
-// source; even split only when a transcript has no word arrays at all.
+// source; even split only when a transcript has no word arrays at all. Every provider supplies real
+// times, so an even split means the transcript itself is deficient.
 async function ensureWordTimings(dir: string, transcriptPath: string, key: string): Promise<void> {
   const t = JSON.parse(await readFile(transcriptPath, 'utf8')) as { chunks?: (TimedChunk & { words?: TimedChunk[] })[] };
   const chunks = Array.isArray(t.chunks) ? t.chunks : [];
   const wordChunks = chunks.flatMap((c) => Array.isArray(c.words) ? c.words : []);
   const wt = synthWordTimings(chunks, wordChunks.length ? wordChunks : undefined);
   await writeFile(join(dir, 'word-timings.json'), JSON.stringify(wt, null, 2));
-  console.log(`[prep] ${key}: word-timings.json (${wordChunks.length ? 'VEED per-word times' : 'even split'})`);
+  if (wordChunks.length) {
+    console.log(`[prep] ${key}: word-timings.json (real per-word times)`);
+  } else {
+    // An even split desynchronises the word reveals, so it must not read like a routine log line.
+    console.warn(
+      `[prep] ${key}: WARNING word-timings.json is an EVEN SPLIT — ${transcriptPath} carries no ` +
+      'per-word times, so word reveals will drift out of sync with the audio.',
+    );
+  }
 }
 
 async function run(): Promise<void> {
diff --git a/prep/transcribe.ts b/prep/transcribe.ts
new file mode 100644
index 0000000..2384bce
--- /dev/null
+++ b/prep/transcribe.ts
@@ -0,0 +1,300 @@
+// Transcription providers, and the one flow they all end in.
+//
+//   resolve video -> derive key -> extract 16k mono WAV -> provider(audio) -> WhisperJson
+//     -> mapWhisperTranscript -> validate -> runs/<key>/transcript.json
+//
+// VEED (veed/go.ts) writes that file itself and is not reimplemented here. WhisperX is a command
+// template, run locally and free. A "custom" provider is deliberately not code: the agent obtains a
+// Whisper-family JSON however the user's service works and feeds it to prep/whisper.ts, so no
+// credential ever passes through OpenEdit.
+//
+//   node --import tsx prep/transcribe.ts <video.mp4> [...] [--model small.en|medium|...] [--language en]
+//
+// Device and compute are fixed to cpu/int8: the platform is Apple Silicon only, where CTranslate2 has
+// no GPU path.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, extname, join } from 'node:path';
+import { FFMPEG, FFPROBE, REPO_ROOT, WHISPERX_BIN, WHISPERX_MODEL } from '../config.ts';
+import { resolveVideoArg } from '../pipeline/scripts/resolve-video.ts';
+import { mapWhisperTranscript, type Transcript, type WhisperJson } from './whisper-mapper.ts';
+
+export const PREFS_PATH = join(REPO_ROOT, '.open-edit-prefs.json');
+export const PROVIDERS = ['veed', 'whisperx', 'custom'] as const;
+export type Provider = (typeof PROVIDERS)[number];
+
+// small.en has no multilingual weights; anything but English must fall back to `small`.
+const ENGLISH_ONLY = /\.en$/;
+
+export interface Prefs {
+  provider: Provider;
+  model?: string;
+}
+
+// stdout and stderr stay SEPARATE: a probe's answer must never be read out of its error output.
+export type Run = (
+  cmd: string,
+  args: string[],
+  opts?: { inherit?: boolean },
+) => Promise<{ code: number; out: string; err: string }>;
+
+export const realRun: Run = (cmd, args, opts = {}) =>
+  new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: opts.inherit ? ['ignore', 'inherit', 'inherit'] : ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    let err = '';
+    child.stdout?.on('data', (d: Buffer) => { out += d.toString(); });
+    child.stderr?.on('data', (d: Buffer) => { err += d.toString(); });
+    child.on('error', (e) => resolve({ code: 127, out, err: `${err}${(e as Error).message}` }));
+    child.on('close', (code) => resolve({ code: code ?? 1, out, err }));
+  });
+
+// A missing, unreadable, or invalid file is a COLD START, never a crash: the caller then asks the
+// user which provider to use. The reason is returned so it can be said out loud rather than guessed at.
+export async function readPrefs(path = PREFS_PATH): Promise<{ prefs?: Prefs; reason?: string }> {
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch {
+    return { reason: 'no provider recorded yet' };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { reason: `${path} is not valid JSON` };
+  }
+  const t = (parsed as { transcription?: { provider?: unknown; model?: unknown } })?.transcription;
+  const provider = t?.provider;
+  if (typeof provider !== 'string' || !(PROVIDERS as readonly string[]).includes(provider)) {
+    return { reason: `${path} records no usable provider (expected one of ${PROVIDERS.join(', ')})` };
+  }
+  const model = typeof t?.model === 'string' && t.model.trim() !== '' ? t.model : undefined;
+  return { prefs: { provider: provider as Provider, model } };
+}
+
+export async function writePrefs(prefs: Prefs, path = PREFS_PATH): Promise<void> {
+  await writeFile(path, `${JSON.stringify({ transcription: prefs }, null, 2)}\n`);
+}
+
+/** The recorded quality tier, so a chosen `medium` is honoured without repeating --model every run. */
+export async function recordedModel(path = PREFS_PATH): Promise<string | undefined> {
+  return (await readPrefs(path)).prefs?.model;
+}
+
+// Garbage that happens to map without throwing still must not reach the pipeline.
+export function validateTranscript(t: Transcript): void {
+  if (t.chunks.length === 0) throw new Error('transcript has no chunks');
+  let previousStart = -Infinity;
+  for (const [i, c] of t.chunks.entries()) {
+    for (const [from, to] of [c.timestamp, ...c.words.map((w) => w.timestamp)]) {
+      if (!Number.isFinite(from) || !Number.isFinite(to)) throw new Error(`chunk ${i} has a non-finite timestamp`);
+      if (from < 0 || to < 0) throw new Error(`chunk ${i} has a negative timestamp`);
+      if (to < from) throw new Error(`chunk ${i} ends before it starts`);
+    }
+    // A word whose midpoint escapes its chunk makes synth-word-timings discard every real time for
+    // that beat and even-split it instead — a silent timing regression, so it is an error here.
+    for (const w of c.words) {
+      const mid = (w.timestamp[0] + w.timestamp[1]) / 2;
+      if (mid < c.timestamp[0] || mid > c.timestamp[1]) {
+        throw new Error(`chunk ${i}: word "${w.text}" falls outside its chunk window — its timings would be discarded`);
+      }
+    }
+    if (c.timestamp[0] < previousStart) throw new Error(`chunk ${i} starts before chunk ${i - 1} — chunks must be in order`);
+    previousStart = c.timestamp[0];
+  }
+}
+
+export async function assertHasAudio(video: string, run: Run = realRun): Promise<void> {
+  const { code, out, err } = await run(FFPROBE, [
+    '-v', 'error', '-select_streams', 'a', '-show_entries', 'stream=index', '-of', 'csv=p=0', video,
+  ]);
+  // A probe that failed says nothing about the audio, so it must not be read as "there is some".
+  if (code !== 0) {
+    throw new Error(`ffprobe could not inspect ${video} (exit ${code})\n${err.trim() || out.trim()}`);
+  }
+  if (out.trim() === '') throw new Error(`${video} has no audio track — there is nothing to transcribe`);
+}
+
+/** 16 kHz mono WAV: what every Whisper implementation wants, cut with the repo's own ffmpeg. */
+export async function extractAudio(video: string, dir: string, run: Run = realRun): Promise<string> {
+  const wav = join(dir, 'audio.wav');
+  const { code, out, err } = await run(FFMPEG, [
+    '-nostdin', '-y', '-i', video, '-vn', '-ac', '1', '-ar', '16000', '-c:a', 'pcm_s16le', wav,
+  ]);
+  // ffmpeg reports on stderr; quoting stdout here would print nothing useful.
+  if (code !== 0 || !existsSync(wav)) {
+    throw new Error(`ffmpeg could not extract audio from ${video}\n${err.trim() || out.trim()}`);
+  }
+  return wav;
+}
+
+export function whisperxModel(model: string | undefined, language: string | undefined): string {
+  const chosen = model ?? WHISPERX_MODEL;
+  if (language && !/^en/i.test(language) && ENGLISH_ONLY.test(chosen)) {
+    return chosen.replace(ENGLISH_ONLY, '');
+  }
+  return chosen;
+}
+
+export function whisperxArgs(audio: string, outDir: string, model: string, language?: string): string[] {
+  return [
+    audio,
+    '--model', model,
+    '--device', 'cpu',
+    '--compute_type', 'int8',
+    '--output_format', 'json',
+    '--output_dir', outDir,
+    ...(language ? ['--language', language] : []),
+  ];
+}
+
+/** The flags we are about to pass must exist in this build's --help. Guards CLI drift. */
+export async function assertWhisperxUsable(run: Run = realRun): Promise<void> {
+  const help = await run(WHISPERX_BIN, ['--help']);
+  const { code } = help;
+  const out = `${help.out}${help.err}`; // some CLIs print usage on stderr
+  if (code !== 0) {
+    throw new Error(
+      `${WHISPERX_BIN} is not available. Install it with pipeline/scripts/install-whisperx.sh ` +
+      '(or choose VEED transcription instead).',
+    );
+  }
+  const missing = ['--model', '--device', '--compute_type', '--output_format', '--output_dir']
+    .filter((flag) => !out.includes(flag));
+  if (missing.length > 0) {
+    throw new Error(
+      `this build of ${WHISPERX_BIN} does not accept ${missing.join(', ')} — its CLI has changed. ` +
+      'Reinstall with pipeline/scripts/install-whisperx.sh, or use VEED transcription.',
+    );
+  }
+}
+
+export async function runWhisperx(
+  audio: string,
+  outDir: string,
+  opts: { model?: string; language?: string; run?: Run } = {},
+): Promise<WhisperJson> {
+  const run = opts.run ?? realRun;
+  await assertWhisperxUsable(run);
+  const model = whisperxModel(opts.model, opts.language);
+  const { code, out, err } = await run(WHISPERX_BIN, whisperxArgs(audio, outDir, model, opts.language), { inherit: true });
+  if (code !== 0) throw new Error(`whisperx failed (exit ${code})\n${err.trim() || out.trim()}`);
+  const produced = join(outDir, `${basename(audio, extname(audio))}.json`);
+  if (!existsSync(produced)) throw new Error(`whisperx exited 0 but wrote no JSON at ${produced}`);
+  return JSON.parse(await readFile(produced, 'utf8')) as WhisperJson;
+}
+
+export function runKeyOf(video: string): string {
+  return basename(video, extname(video)).replace(/\s+/g, '_');
+}
+
+export async function transcribeLocally(
+  videoArg: string,
+  opts: { model?: string; language?: string; run?: Run } = {},
+): Promise<{ path: string; interpolated: number; reordered: number; words: number }> {
+  const run = opts.run ?? realRun;
+  const video = resolveVideoArg(videoArg);
+  if (!existsSync(video)) throw new Error(`video not found: ${video}`);
+  await assertHasAudio(video, run);
+
+  const key = runKeyOf(video);
+  const outDir = join(REPO_ROOT, 'runs', key);
+  await mkdir(outDir, { recursive: true });
+  const work = await mkdtemp(join(tmpdir(), 'open-edit-asr-'));
+
+  try {
+    const audio = await extractAudio(video, work, run);
+    const model = opts.model ?? await recordedModel();
+    const raw = await runWhisperx(audio, work, { ...opts, model, run });
+    const { transcript, interpolated, reordered } = mapWhisperTranscript(raw);
+    validateTranscript(transcript);
+
+    const path = join(outDir, 'transcript.json');
+    await writeFile(path, JSON.stringify(transcript, null, 2));
+    const words = transcript.chunks.reduce((n, c) => n + c.words.length, 0);
+    return { path, interpolated, reordered, words };
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+export const USAGE = 'usage: node --import tsx prep/transcribe.ts <video.mp4> [...] [--model <id>] [--language <code>]\n'
+  + `   or: node --import tsx prep/transcribe.ts --record <${PROVIDERS.join('|')}> [--model <id>]`;
+
+export interface Args {
+  /** In the order given, like prep/prep.ts. Empty only when recording a choice. */
+  videos: string[];
+  model?: string;
+  language?: string;
+  /** Write the provider choice and exit — the "record the choice" step of the flow. */
+  record?: Provider;
+}
+
+// Both `--flag value` and `--flag=value`. An unknown flag is an ERROR: a misspelled --language would
+// otherwise leave English-only weights on non-English audio, transcribing it as confident nonsense.
+export function parseArgs(argv: string[]): Args {
+  const known = ['--model', '--language', '--record'];
+  const videos: string[] = [];
+  const out: Record<string, string> = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      videos.push(token);
+      continue;
+    }
+    const eq = token.indexOf('=');
+    const flag = eq === -1 ? token : token.slice(0, eq);
+    if (!known.includes(flag)) throw new Error(`unknown flag ${flag}\n${USAGE}`);
+    const value = eq === -1 ? argv[++i] : token.slice(eq + 1);
+    if (value === undefined || value === '') throw new Error(`${flag} needs a value\n${USAGE}`);
+    out[flag.slice(2)] = value;
+  }
+  if (out.record !== undefined && !(PROVIDERS as readonly string[]).includes(out.record)) {
+    throw new Error(`unknown provider "${out.record}" — expected one of ${PROVIDERS.join(', ')}\n${USAGE}`);
+  }
+  // Recording a choice is not a transcription run, so it needs no video.
+  if (out.record === undefined && videos.length === 0) throw new Error(`no video given\n${USAGE}`);
+  return {
+    videos,
+    ...(out.record === undefined ? {} : { record: out.record as Provider }),
+    ...(out.model === undefined ? {} : { model: out.model }),
+    ...(out.language === undefined ? {} : { language: out.language }),
+  };
+}
+
+async function main(): Promise<void> {
+  const { videos, model, language, record } = parseArgs(process.argv.slice(2));
+
+  if (record) {
+    await writePrefs({ provider: record, ...(model === undefined ? {} : { model }) });
+    console.log(`[transcribe] recorded provider=${record}${model ? ` model=${model}` : ''} -> ${PREFS_PATH}`);
+    return;
+  }
+
+  // Sequential, and a failure stops the batch: the videos share one provider, so a missing binary or
+  // an exhausted account fails all of them, and the transcripts already written stay valid.
+  for (const video of videos) {
+    const { path, interpolated, reordered, words } = await transcribeLocally(video, { model, language });
+    console.log(`[transcribe] whisperx: ${words} words -> ${path}`);
+    const key = runKeyOf(video);
+    if (interpolated > 0) {
+      console.warn(
+        `[transcribe] ${key}: WARNING ${interpolated} of ${words} word(s) arrived without usable timings; their ` +
+        'windows were interpolated from neighbours. The text is complete, those reveals are approximate.',
+      );
+    }
+    if (reordered > 0) {
+      console.warn(
+        `[transcribe] ${key}: WARNING ${reordered} word(s) had times running backwards and were reordered so ` +
+        'the caption text matches the reveal order.',
+      );
+    }
+  }
+}
+
+if (process.argv[1] && import.meta.url.endsWith(basename(process.argv[1]))) {
+  main().catch((e) => { console.error((e as Error).message); process.exit(1); });
+}
diff --git a/prep/whisper-mapper.ts b/prep/whisper-mapper.ts
new file mode 100644
index 0000000..eb874ec
--- /dev/null
+++ b/prep/whisper-mapper.ts
@@ -0,0 +1,318 @@
+// Maps a Whisper-family transcription JSON into the editor's on-disk transcript shape
+// ({ text, chunks:[{ text, timestamp:[startSec,endSec], words:[...] }] }) — the same shape
+// veed/transcript-mapper.ts produces, so downstream (prep, extract-beat-frames, synth-word-timings)
+// cannot tell which provider ran. This is the path for every provider except VEED itself.
+//
+// Accepted inputs:
+//   - the Python Whisper family — WhisperX, openai-whisper, whisper-timestamped, mlx-whisper:
+//     { segments:[{ start, end, text, words:[{ word|text, start, end }] }] }
+//   - the OpenAI API's verbose_json with timestamp_granularities:["word"]:
+//     { segments:[{ start, end, text }], words:[{ word, start, end }] }
+//   - a flat word list, including whisper.cpp `-oj`:
+//     { transcription:[{ offsets:{ from, to }, text }] }  (offsets are MILLISECONDS)
+//
+// ONE PIPELINE, because a branch per family is a branch per way of losing a word:
+//
+//   normalise → flat Pending[] (+ segment bounds)   every family, one shape, multi-word entries split
+//     → time     interpolate untimed words from their neighbours ACROSS segment boundaries
+//     → group    one chunk per provider segment, or prosody grouping when there is no segmentation
+//     → order    sort chunks, and words within a chunk, since provider order is not guaranteed
+//     → assert   output word count === input word count, or throw
+//
+// Words a provider left untimed keep their text and get an interpolated window, counted in
+// `interpolated`. Only a transcript with no timed word anywhere is refused: nothing to interpolate from.
+
+import type { Transcript, TranscriptChunk, TranscriptWord } from '../veed/transcript-mapper.ts';
+
+export type { Transcript, TranscriptChunk, TranscriptWord };
+
+// `word` is openai/WhisperX/mlx; `text` is whisper-timestamped. Times are seconds.
+export interface WhisperWord {
+  word?: string;
+  text?: string;
+  start?: number;
+  end?: number;
+}
+
+export interface WhisperSegment {
+  start?: number;
+  end?: number;
+  text?: string;
+  words?: WhisperWord[];
+}
+
+// whisper.cpp --output-json: offsets are integer milliseconds from the start of the media.
+export interface WhisperCppEntry {
+  text?: string;
+  offsets?: { from?: number; to?: number };
+}
+
+export interface WhisperJson {
+  text?: string;
+  segments?: WhisperSegment[];
+  words?: WhisperWord[];
+  transcription?: WhisperCppEntry[];
+}
+
+export interface GroupOptions {
+  /** Start a new cue when the silence before a word is at least this long. */
+  gapSec?: number;
+  /** Hard cap on words per cue, so a pauseless monologue still yields beats. */
+  maxWords?: number;
+}
+
+export interface MapResult {
+  transcript: Transcript;
+  /** Words the provider left untimed, whose windows were inferred. */
+  interpolated: number;
+  /** Words whose times ran backwards and were reordered to match their reveals. */
+  reordered: number;
+}
+
+const DEFAULT_GAP_SEC = 0.6;
+const DEFAULT_MAX_WORDS = 8;
+
+const finite = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n);
+
+/** One token on its way to becoming a word. `inferred` marks a window we made up. */
+interface Pending {
+  text: string;
+  start?: number;
+  end?: number;
+  inferred?: boolean;
+  /** Index of the provider segment this came from; undefined when there is no segmentation. */
+  group?: number;
+}
+
+// A provider "word" containing whitespace is a segment in disguise — whisper.cpp without `-ml 1`
+// emits whole sentences this way. Splitting marks the windows inferred, so such a transcript reports a
+// large interpolation count instead of passing as word-timed.
+function tokenize(p: Pending): Pending[] {
+  const parts = p.text.split(/\s+/).filter((t) => t !== '');
+  if (parts.length <= 1) return parts.length === 1 ? [{ ...p, text: parts[0] }] : [];
+  if (!finite(p.start) || !finite(p.end)) {
+    return parts.map((text) => ({ text, group: p.group, inferred: true }));
+  }
+  // Proportional to token length: longer words take longer to say than shorter ones.
+  const total = parts.reduce((n, t) => n + t.length, 0) || parts.length;
+  const span = Math.max(0, p.end - p.start);
+  let cursor = p.start;
+  return parts.map((text) => {
+    const width = (span * text.length) / total;
+    const word = { text, start: cursor, end: cursor + width, inferred: true, group: p.group };
+    cursor += width;
+    return word;
+  });
+}
+
+function pendingFromWords(words: WhisperWord[], group?: number): Pending[] {
+  return words
+    .map((w) => ({ text: (w.word ?? w.text ?? '').trim(), start: w.start, end: w.end, group }))
+    .flatMap((p) => tokenize(p));
+}
+
+function pendingFromCpp(entries: WhisperCppEntry[]): Pending[] {
+  return entries
+    .map((e) => {
+      const from = e.offsets?.from;
+      const to = e.offsets?.to;
+      return {
+        text: (e.text ?? '').trim(),
+        start: finite(from) ? from / 1000 : undefined,
+        end: finite(to) ? to / 1000 : undefined,
+      };
+    })
+    .flatMap((p) => tokenize(p));
+}
+
+/** Spreads `count` windows evenly across [from,to]; a zero-width span yields zero-width windows. */
+function spread(from: number, to: number, count: number): [number, number][] {
+  const lo = Math.min(from, to);
+  const hi = Math.max(from, to);
+  const step = count > 0 ? (hi - lo) / count : 0;
+  return Array.from({ length: count }, (_, i) => [lo + step * i, lo + step * (i + 1)]);
+}
+
+// Timing runs over the WHOLE transcript, not per segment: a segment whose alignment failed entirely
+// then borrows the gap between its neighbours' anchors instead of vanishing for want of a window.
+function timeAll(
+  pending: Pending[],
+  bounds: { start?: number; end?: number }[],
+): { words: TranscriptWord[]; groups: (number | undefined)[]; interpolated: number } {
+  const anchored = pending.map((p) => finite(p.start) && finite(p.end));
+  const firstAnchor = anchored.indexOf(true);
+  const lastAnchor = anchored.lastIndexOf(true);
+  if (firstAnchor === -1) {
+    return { words: [], groups: [], interpolated: 0 };
+  }
+
+  const words: TranscriptWord[] = [];
+  const groups: (number | undefined)[] = [];
+  let interpolated = 0;
+  let i = 0;
+  while (i < pending.length) {
+    if (anchored[i]) {
+      words.push({ text: pending[i].text, timestamp: [pending[i].start as number, pending[i].end as number] });
+      groups.push(pending[i].group);
+      if (pending[i].inferred) interpolated += 1;
+      i += 1;
+      continue;
+    }
+    let j = i; // [i, j) is a maximal run of untimed words
+    while (j < pending.length && !anchored[j]) j += 1;
+    const groupStart = bounds[pending[i].group ?? -1]?.start;
+    const groupEnd = bounds[pending[j - 1].group ?? -1]?.end;
+    const from = i > firstAnchor
+      ? (pending[i - 1].end as number)
+      : (finite(groupStart) ? groupStart : (pending[firstAnchor].start as number));
+    const to = j <= lastAnchor
+      ? (pending[j].start as number)
+      : (finite(groupEnd) ? groupEnd : (pending[lastAnchor].end as number));
+    const windows = spread(from, to, j - i);
+    for (let k = i; k < j; k += 1) {
+      words.push({ text: pending[k].text, timestamp: windows[k - i] });
+      groups.push(pending[k].group);
+      interpolated += 1;
+    }
+    i = j;
+  }
+  return { words, groups, interpolated };
+}
+
+/** The window must cover its own words: synth-word-timings discards a beat whose words fall outside. */
+function chunkOf(words: TranscriptWord[], start?: number, end?: number): TranscriptChunk | undefined {
+  if (words.length === 0) return undefined;
+  const firstWord = words[0].timestamp[0];
+  const lastWord = words[words.length - 1].timestamp[1];
+  const from = Math.min(finite(start) ? start : firstWord, firstWord);
+  const to = Math.max(finite(end) ? end : lastWord, lastWord);
+  return { text: words.map((w) => w.text).join(' '), timestamp: [from, to], words };
+}
+
+// Cue boundaries from prosody, not from the model: sentence-ending punctuation, a real pause, or the
+// word cap. Used only when the provider gave no segmentation of its own.
+export function groupWordsIntoChunks(words: TranscriptWord[], opts: GroupOptions = {}): TranscriptChunk[] {
+  const gapSec = opts.gapSec ?? DEFAULT_GAP_SEC;
+  const maxWords = Math.max(1, opts.maxWords ?? DEFAULT_MAX_WORDS);
+  const chunks: TranscriptChunk[] = [];
+  let current: TranscriptWord[] = [];
+
+  const flush = (): void => {
+    const chunk = chunkOf(current);
+    if (chunk) chunks.push(chunk);
+    current = [];
+  };
+
+  for (const word of words) {
+    const previous = current[current.length - 1];
+    if (previous && word.timestamp[0] - previous.timestamp[1] >= gapSec) flush();
+    current.push(word);
+    if (current.length >= maxWords || /[.!?…]["')\]]?$/.test(word.text)) flush();
+  }
+  flush();
+  return chunks;
+}
+
+// Assigns a flat word list to wordless segments by midpoint. Words past the last segment stay with
+// the last one rather than being discarded: provider word times routinely run past a segment's end.
+function assignToSegments(segments: WhisperSegment[], pending: Pending[]): Pending[] {
+  // Where one segment stops claiming words. A segment with no `end` is bounded by the NEXT segment's
+  // start — using a later segment's end instead would let it swallow that segment's words.
+  const cuts: (number | undefined)[] = segments.map((s, i) => {
+    if (finite(s.end)) return s.end;
+    const nextStart = segments[i + 1]?.start;
+    return finite(nextStart) ? nextStart : undefined;
+  });
+  for (let i = cuts.length - 2; i >= 0; i -= 1) {
+    if (cuts[i] === undefined) cuts[i] = cuts[i + 1];
+  }
+
+  let group = 0;
+  return pending.map((p) => {
+    const mid = finite(p.start) && finite(p.end) ? (p.start + p.end) / 2 : undefined;
+    if (mid !== undefined) {
+      while (group < segments.length - 1) {
+        const cut = cuts[group];
+        if (cut === undefined || mid <= cut) break;
+        group += 1;
+      }
+    }
+    return { ...p, group };
+  });
+}
+
+// Provider order is not guaranteed (veed/transcript-mapper.ts sorts for the same reason). Overlapping
+// word windows are normal in ASR and left alone; starts that run BACKWARDS are not, and are sorted so
+// the caption text and the reveal order agree — the text is rebuilt from the sorted order.
+function orderWords(words: TranscriptWord[]): { words: TranscriptWord[]; reordered: number } {
+  let reordered = 0;
+  for (let i = 1; i < words.length; i += 1) {
+    if (words[i].timestamp[0] < words[i - 1].timestamp[0]) reordered += 1;
+  }
+  if (reordered === 0) return { words, reordered };
+  return { words: [...words].sort((a, b) => a.timestamp[0] - b.timestamp[0]), reordered };
+}
+
+export function mapWhisperTranscript(input: WhisperJson, opts: GroupOptions = {}): MapResult {
+  const segments = Array.isArray(input.segments) ? input.segments : [];
+  const flatWords = Array.isArray(input.words) ? input.words : [];
+  const cppEntries = Array.isArray(input.transcription) ? input.transcription : [];
+
+  // 1. normalise every family to one flat list, tagged with its provider segment where there is one
+  const segmentsCarryWords = segments.some((s) => Array.isArray(s.words) && s.words.length > 0);
+  let pending: Pending[];
+  if (segmentsCarryWords) {
+    pending = segments.flatMap((s, i) => pendingFromWords(Array.isArray(s.words) ? s.words : [], i));
+  } else {
+    const loose = flatWords.length > 0 ? pendingFromWords(flatWords) : pendingFromCpp(cppEntries);
+    pending = segments.length > 0 ? assignToSegments(segments, loose) : loose;
+  }
+  const inputWords = pending.length;
+
+  // 2. time it, crossing segment boundaries so a wholly-unaligned segment still gets windows
+  const bounds = segments.map((s) => ({ start: s.start, end: s.end }));
+  const { words, groups, interpolated } = timeAll(pending, bounds);
+
+  if (words.length === 0) {
+    throw new Error(
+      'mapWhisperTranscript: no per-word timings found. Re-run the transcription with word timestamps ' +
+      '(WhisperX emits them by default · openai-whisper/mlx-whisper: --word_timestamps True · ' +
+      'whisper.cpp: -oj -ml 1 · OpenAI API: timestamp_granularities=["word"]). ' +
+      'Without them the caption animation desynchronises.',
+    );
+  }
+
+  // 3. group into chunks: one per provider segment, else by prosody
+  let chunks: TranscriptChunk[];
+  let reordered = 0;
+  if (segments.length > 0) {
+    chunks = segments
+      .map((s, i) => {
+        const mine = words.filter((_, k) => groups[k] === i);
+        const ordered = orderWords(mine);
+        reordered += ordered.reordered;
+        // An absent end borrows the next segment's start rather than swallowing the rest of the words.
+        const end = finite(s.end) ? s.end : segments.slice(i + 1).map((n) => n.start).find(finite);
+        return chunkOf(ordered.words, s.start, end);
+      })
+      .filter((c): c is TranscriptChunk => c !== undefined);
+  } else {
+    const ordered = orderWords(words);
+    reordered += ordered.reordered;
+    chunks = groupWordsIntoChunks(ordered.words, opts);
+  }
+
+  // 4. chunks in transcript order, whatever order the provider used
+  chunks.sort((a, b) => a.timestamp[0] - b.timestamp[0]);
+
+  // 5. the invariant that makes silent word loss impossible, wherever it might be introduced
+  const outputWords = chunks.reduce((n, c) => n + c.words.length, 0);
+  if (outputWords !== inputWords) {
+    throw new Error(
+      `mapWhisperTranscript: internal error — ${inputWords} words in, ${outputWords} out. ` +
+      'A word was lost while mapping; this is a bug in the mapper, not in your transcript.',
+    );
+  }
+
+  return { transcript: { text: chunks.map((c) => c.text).join(' '), chunks }, interpolated, reordered };
+}
diff --git a/prep/whisper.ts b/prep/whisper.ts
new file mode 100644
index 0000000..19e3c5a
--- /dev/null
+++ b/prep/whisper.ts
@@ -0,0 +1,76 @@
+// The "custom provider" entrypoint: converts a Whisper-family JSON that something else produced into
+// runs/<key>/transcript.json, the same artefact veed/go.ts writes. This is the seam a user's own
+// service or MCP plugs into — no transcription is run here, and no credential is handled here.
+// For the built-in local provider use prep/transcribe.ts, which drives WhisperX itself.
+//
+//   node --import tsx prep/whisper.ts <whisper.json> <video.mp4> [<whisper.json> <video.mp4> ...]
+//
+// Producing the input, word timings included (they are required):
+//   whisperx     video.mp4 --output_format json --output_dir .        # emits word times by default
+//   openai-whisper / mlx-whisper   --word_timestamps True --output_format json --output_dir .
+//   whisper.cpp  main -m models/ggml-base.en.bin -f audio.wav -oj -ml 1
+//   OpenAI API   response_format=verbose_json, timestamp_granularities=["word"]
+//
+// The key is derived from the video filename exactly as veed/go.ts and prep/prep.ts derive it, so
+// prep picks the transcript up with no further arguments.
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+import { REPO_ROOT } from '../config.ts';
+import { resolveVideoArg } from '../pipeline/scripts/resolve-video.ts';
+import { validateTranscript } from './transcribe.ts';
+import { mapWhisperTranscript, type WhisperJson } from './whisper-mapper.ts';
+
+const USAGE = 'usage: node --import tsx prep/whisper.ts <whisper.json> <video.mp4> [<whisper.json> <video.mp4> ...]';
+
+async function mapOne(jsonArg: string, videoArg: string): Promise<void> {
+  if (!existsSync(jsonArg)) {
+    console.error(`transcription json not found: ${jsonArg}`);
+    process.exit(1);
+  }
+  const video = resolveVideoArg(videoArg);
+  if (!existsSync(video)) {
+    console.error(`video not found: ${video}`);
+    process.exit(1);
+  }
+
+  const raw = JSON.parse(await readFile(jsonArg, 'utf8')) as WhisperJson;
+  const { transcript, interpolated, reordered } = mapWhisperTranscript(raw);
+  validateTranscript(transcript);
+
+  const key = basename(video, extname(video)).replace(/\s+/g, '_');
+  const outDir = join(REPO_ROOT, 'runs', key);
+  await mkdir(outDir, { recursive: true });
+  const out = join(outDir, 'transcript.json');
+  await writeFile(out, JSON.stringify(transcript, null, 2));
+
+  const words = transcript.chunks.reduce((n, c) => n + c.words.length, 0);
+  console.log(`[whisper-transcribe] ${key}: ${transcript.chunks.length} chunks, ${words} words -> ${out}`);
+  if (interpolated > 0) {
+    console.warn(
+      `[whisper-transcribe] ${key}: WARNING ${interpolated} of ${words} word(s) arrived without usable timings; ` +
+      'their windows were interpolated from neighbours. The text is complete, those reveals are approximate.',
+    );
+  }
+  if (reordered > 0) {
+    console.warn(
+      `[whisper-transcribe] ${key}: WARNING ${reordered} word(s) had times running backwards and were reordered ` +
+      'so the caption text matches the reveal order.',
+    );
+  }
+}
+
+async function run(): Promise<void> {
+  const args = process.argv.slice(2);
+  // Each video carries its own transcription, so the arguments are pairs; an odd count means one is
+  // missing, and guessing which would map a transcript onto the wrong video.
+  if (args.length === 0 || args.length % 2 !== 0) {
+    console.error(args.length === 0
+      ? USAGE
+      : `every video needs its own json — got ${args.length} argument(s), which do not pair up\n${USAGE}`);
+    process.exit(1);
+  }
+  for (let i = 0; i < args.length; i += 2) await mapOne(args[i], args[i + 1]);
+}
+
+run().catch((e) => { console.error((e as Error).message); process.exit(1); });
diff --git a/veed/go.ts b/veed/go.ts
index f38b43a..8dbf7a1 100644
--- a/veed/go.ts
+++ b/veed/go.ts
@@ -3,7 +3,7 @@
 // editor pipeline already consumes (prep.ts then cuts the base frames from it).
 //
 //   1. Log in once:  node --import tsx veed/login.ts
-//   2. Run:          node --import tsx veed/go.ts <video.mp4>
+//   2. Run:          node --import tsx veed/go.ts <video.mp4> [...]
 //
 // Env: VEED_ORIGIN (default https://www.veed.io), VEED_ACCESS_TOKEN (optional,
 // overrides the stored login).
@@ -36,7 +36,7 @@ function noTokenHelp(): void {
       'It opens your browser once and stores a refreshable token, owner-only, at',
       `  ${DEFAULT_TOKEN_PATH}`,
       '',
-      'then re-run:  node --import tsx veed/go.ts <video.mp4>',
+      'then re-run:  node --import tsx veed/go.ts <video.mp4> [...]',
     ].join('\n'),
   );
 }
@@ -51,28 +51,35 @@ async function main(): Promise<void> {
     noTokenHelp();
     process.exit(1);
   }
-  const videoArg = process.argv[2];
-  if (!videoArg) {
-    console.error('usage: node --import tsx veed/go.ts <video.mp4>');
+  const videoArgs = process.argv.slice(2);
+  if (videoArgs.length === 0) {
+    console.error('usage: node --import tsx veed/go.ts <video.mp4> [...]');
     process.exit(1);
   }
-  const video = resolveVideoArg(videoArg);
-  if (!existsSync(video)) {
-    console.error(`video not found: ${video}`);
+  // Resolve and check every path before uploading any of them: a typo in the last argument should not
+  // be discovered after the earlier videos have already spent transcription credits.
+  const videos = videoArgs.map(resolveVideoArg);
+  const missing = videos.filter((v) => !existsSync(v));
+  if (missing.length > 0) {
+    console.error(missing.map((v) => `video not found: ${v}`).join('\n'));
     process.exit(1);
   }
-  const key = basename(video, extname(video)).replace(/\s+/g, '_');
-  const outDir = join(REPO_ROOT, 'runs', key);
-  await mkdir(outDir, { recursive: true });
 
-  console.log(`[veed-transcribe] ${video}`);
-  const transcript = await transcribeWithVeed(
-    { http: realHttp(token), readVideoBytes, log: (m) => console.log(`  ${m}`) },
-    { videoPath: video },
-  );
-  const out = join(outDir, 'transcript.json');
-  await writeFile(out, JSON.stringify(transcript, null, 2));
-  console.log(`wrote ${out} (${transcript.chunks.length} beats)`);
+  const http = realHttp(token);
+  for (const video of videos) {
+    const key = basename(video, extname(video)).replace(/\s+/g, '_');
+    const outDir = join(REPO_ROOT, 'runs', key);
+    await mkdir(outDir, { recursive: true });
+
+    console.log(`[veed-transcribe] ${video}`);
+    const transcript = await transcribeWithVeed(
+      { http, readVideoBytes, log: (m) => console.log(`  ${m}`) },
+      { videoPath: video },
+    );
+    const out = join(outDir, 'transcript.json');
+    await writeFile(out, JSON.stringify(transcript, null, 2));
+    console.log(`wrote ${out} (${transcript.chunks.length} beats)`);
+  }
 }
 
 main().catch((e: unknown) => {
diff --git a/veed/orchestrate.ts b/veed/orchestrate.ts
index e3dc0b4..8e09858 100644
--- a/veed/orchestrate.ts
+++ b/veed/orchestrate.ts
@@ -99,8 +99,11 @@ export async function transcribeWithVeed(deps: TranscribeDeps, opts: TranscribeO
     (s) => (s.status === 'error' ? 'failed' : s.status === 'active' ? 'done' : 'wait'),
     'transcription',
     (s) =>
+      // The likeliest failure by far, so it carries the allowance and the fix rather than a reason code.
       s.errorReason === 'outOfCredits'
-        ? 'VEED: transcription failed - this workspace has no transcription credits left'
+        ? 'VEED: this workspace is out of transcription credits. A free account covers about 2 minutes '
+          + 'a month; more needs a plan — https://www.veed.io/pricing. Or transcribe locally instead: '
+          + 'node --import tsx prep/transcribe.ts <video.mp4>'
         : `VEED: transcription failed (${s.errorReason ?? 'unknown'})`,
   );
   if (!subtitle.subtitles) throw new Error('VEED: transcription active but returned no subtitles track');
diff --git a/veed/readiness.ts b/veed/readiness.ts
index a57ac24..7a820f8 100644
--- a/veed/readiness.ts
+++ b/veed/readiness.ts
@@ -40,10 +40,12 @@ add('VEED API base', true, VEED_API_BASE, false);
 
 const tokenPath = DEFAULT_TOKEN_PATH;
 const tokenEnv = (process.env.VEED_ACCESS_TOKEN ?? '').trim() !== '';
+// Optional, not blocking: only the VEED provider reads this token.
 add(
   'VEED login token',
   tokenEnv || existsSync(tokenPath),
-  tokenEnv ? 'VEED_ACCESS_TOKEN set' : existsSync(tokenPath) ? `cached at ${tokenPath}` : 'not logged in yet; run: node --import tsx veed/login.ts',
+  tokenEnv ? 'VEED_ACCESS_TOKEN set' : existsSync(tokenPath) ? `cached at ${tokenPath}` : 'not logged in yet; needed ONLY for the VEED provider — run: node --import tsx veed/login.ts',
+  false,
 );
 
 // --- report ---
@@ -55,7 +57,7 @@ for (const c of checks) {
 const blockingMisses = checks.filter((c) => !c.ok && c.blocking);
 console.log('='.repeat(40));
 if (blockingMisses.length === 0) {
-  console.log('All blocking checks pass. Items marked "opt" only matter for the render step.');
+  console.log('All blocking checks pass. Items marked "opt" are needed only by the step or provider named beside them.');
 } else {
   console.log(`${blockingMisses.length} blocking item(s) to resolve: ${blockingMisses.map((c) => c.label).join(', ')}`);
 }