rsc-universal 0.1.1

package/skills/remotion-video/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: remotion-video
+description: "Use when you need to render an actual video file with Remotion — React compositions, slide/fade transitions, burned-in word-by-word captions from a transcript, automatic silence removal, b-roll overlays, and a final MP4/MOV out of `npx remotion render`. Covers project scaffold, the Composition/Sequence/TransitionSeries graph, the Whisper.cpp → toCaptions → createTikTokStyleCaptions pipeline, and headless CI renders. Triggers: 'render my script and voiceover into an MP4 with Remotion', 'burn TikTok-style word-by-word captions from a Whisper transcript', 'add slide and fade transitions between scenes programmatically', 'genera el vídeo final con subtítulos quemados', 'quita los silencios del recording automáticamente', 'renderitza la composició a MP4 amb Remotion'. NOT writing the script, hook, beats, or caption text (that is video-shorts), NOT mastering audio to LUFS or building an RSS feed (that is podcast), NOT structuring the narrative arc (that is course-storytelling)."
+tags: [remotion, video-rendering, react, captions, ffmpeg, whisper, youtube]
+recommends: [video-shorts, podcast, course-storytelling, youtube-packaging, nextjs]
+origin: risco
+---
+
+# Remotion Video — Encode the Actual Frames
+
+*You are the encoder and renderer.* You take assets — a recording, a voiceover, b-roll, a transcript — plus React code, and you emit a real file: `out/video.mp4`. Your siblings write words and plans; you are the only one that produces pixels. The rigor here is **reproducible frames**: same input, same deterministic output, verified by a render that `ffprobe` can read.
+
+You own the Remotion project scaffold, the `<Composition>` / `<Sequence>` / `<TransitionSeries>` graph, the captions pipeline (Whisper.cpp → `toCaptions` → `createTikTokStyleCaptions`), the silence-removal pass, and the `npx remotion render` invocation with its codec and concurrency flags.
+
+## The one decision: frames or words?
+
+If the ask is to produce a file, you are in the right place. If it is to produce text or a plan, route out before writing a single `.tsx`.
+
+| The ask | Goes to | Why |
+|---|---|---|
+| Produce an MP4/MOV, transitions, burned captions, render | **here** | These are pixels and frames |
+| Write the script, hook, beats, on-screen caption *text*, edit decision sheet | `../video-shorts/SKILL.md` | Those are words; the cut decisions, not the cut execution |
+| Master audio to a LUFS target, produce chapters + RSS `<item>` | `../podcast/SKILL.md` | Audio mastering and feed, not video encode |
+| Structure the lesson/video narrative arc and flow | `../course-storytelling/SKILL.md` | Narrative architecture, not rendering |
+| Design the thumbnail image | `../youtube-thumbnails/SKILL.md` | A still image, not a video |
+
+Boundary in one line: **video-shorts decides the cuts and writes the caption text; you execute the cuts in code and burn the captions into frames.**
+
+## Scaffold the project
+
+```bash
+npx create-video@latest --yes --blank my-video
+cd my-video
+npm i
+npm run dev        # opens Remotion Studio in the browser
+```
+
+Remotion's current stable line is **4.0.471**; it needs Node 16+ (or Bun 1.0.3+), and local rendering targets macOS 15 (Sequoia)+. Since **January 2026** Remotion ships Agent Skills — `npx skills add remotion-dev/skills` wires Remotion-aware guidance into Claude Code. Run it inside a Remotion project when you want the framework's own skill loaded alongside this one.
+
+**Pin fps and dimensions on `<Composition>` first, and never change them mid-project.** *Why: every duration downstream is measured in frames, and `frames = seconds * fps`. Change fps after you have written durations and every timing silently shifts.* Vertical shorts are `1080×1920 @ 30`; landscape is `1920×1080 @ 30`.
+
+## The composition graph
+
+```tsx
+// src/Root.tsx
+import { Composition } from "remotion";
+import { MyVideo } from "./MyVideo";
+
+export const RemotionRoot: React.FC = () => {
+  return (
+    <Composition
+      id="MyVideo"            // the id you pass to `remotion render`
+      component={MyVideo}
+      durationInFrames={300}  // 10s at 30fps
+      fps={30}
+      width={1080}
+      height={1920}
+    />
+  );
+};
+```
+
+```tsx
+// src/MyVideo.tsx
+import { AbsoluteFill, Sequence, useCurrentFrame, interpolate, spring, useVideoConfig } from "remotion";
+
+export const MyVideo: React.FC = () => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
+  const scale = spring({ frame, fps, config: { damping: 200 } });
+  return (
+    <AbsoluteFill style={{ backgroundColor: "black" }}>
+      <Sequence from={0} durationInFrames={90}>
+        <AbsoluteFill style={{ opacity, transform: `scale(${scale})` }}>{/* scene 1 */}</AbsoluteFill>
+      </Sequence>
+      <Sequence from={90} durationInFrames={210}>{/* scene 2 */}</Sequence>
+    </AbsoluteFill>
+  );
+};
+```
+
+Animate off `useCurrentFrame()` with `interpolate()` and `spring()` only. **Never read wall-clock time (`Date.now()`) or call `Math.random()` unseeded inside a composition.** *Why: rendering is parallel and frame-addressable — each frame is computed independently, so any non-frame input produces a different pixel on re-render and breaks the "same input, same output" guarantee.* If you need randomness, use Remotion's `random(seed)`.
+
+## Transitions
+
+Use `@remotion/transitions` (available since **v4.0.53**). `<TransitionSeries>` interleaves `.Sequence` (a clip, with `durationInFrames`) and `.Transition` (a `presentation` + a `timing`). The transition duration is *subtracted* from the total, so adjacent sequences overlap during the wipe.
+
+```tsx
+import { TransitionSeries, linearTiming, springTiming } from "@remotion/transitions";
+import { slide } from "@remotion/transitions/slide";
+import { fade } from "@remotion/transitions/fade";
+import { Easing } from "remotion";
+
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={90}>{/* scene A */}</TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={slide({ direction: "from-left" })}
+    timing={springTiming({ config: { damping: 200 }, durationInFrames: 30, durationRestThreshold: 0.001 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={120}>{/* scene B */}</TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15, easing: Easing.inOut(Easing.ease) })}
+  />
+  <TransitionSeries.Sequence durationInFrames={90}>{/* scene C */}</TransitionSeries.Sequence>
+</TransitionSeries>
+```
+
+Each presentation is a sub-import (`@remotion/transitions/slide`, `/fade`, `/wipe`, `/flip`, `/clockWipe`, `/none`).
+
+| Presentation | Feel / when |
+|---|---|
+| `slide` | Scene pushes the next in; directional momentum between beats |
+| `fade` | Soft crossfade; calm, neutral scene change |
+| `wipe` | A hard edge sweeps across; energetic, "next topic" |
+| `flip` | 3D card flip; playful, for reveals |
+| `clockWipe` | Radial sweep; countdowns, "time passing" |
+| `none` | A hard cut with no motion, but still as a TransitionSeries node |
+
+**`linearTiming` for predictable, frame-exact cuts; `springTiming` for organic motion.** *Why: linear is deterministic in duration so you can budget frames exactly; spring overshoots and settles, which reads as natural but needs `durationRestThreshold` so the render knows when it has finished.*
+
+## Animated burned-in captions
+
+The native `@remotion/captions` package shipped in **v4.0.216** (the same release that deprecated the old `convertToCaptions()` helper). The pipeline runs once on a Node server, then the composition reads the captions:
+
+1. **Transcribe.** `@remotion/install-whisper-cpp` downloads Whisper.cpp and a model (`medium.en` is ~1.5 GB) and transcribes the audio on a Node server to Whisper JSON.
+2. **Convert.** `toCaptions()` from `@remotion/install-whisper-cpp` turns that JSON into a `Caption[]` with per-token timestamps. *(`convertToCaptions()` is the legacy alias — deprecated as of v4.0.216; use `toCaptions()`.)*
+3. **Segment into pages.** `@remotion/captions` `createTikTokStyleCaptions({ captions, combineTokensWithinMilliseconds })` groups tokens into "pages" that appear together.
+
+**The `combineTokensWithinMilliseconds` value is the page-size dial.** *Why: a low value (~200ms) keeps each word on its own page → word-by-word pop animation; a high value (~1200ms) packs a phrase per page.* Low ms = TikTok word-by-word energy; high ms = readable phrases. Pick by the format, not by default.
+
+Full Whisper.cpp install, the transcribe server, and the token-highlight caption renderer component (with safe-zone styling) live in `references/captions-pipeline.md` — read it before building the captions layer.
+
+## Automatic silence removal
+
+**The silence pass runs on the source audio/video BEFORE it enters Remotion**, not inside a composition. *Why: Remotion renders frames you give it; trimming dead air is an upstream edit on the asset, and doing it first means every downstream frame number already reflects the tightened timeline.*
+
+Use `auto-editor` (a Python + ffmpeg engine) for a first pass that cuts dead space by audio loudness:
+
+```bash
+auto-editor input.mp4 --margin 0.2s --edit audio:threshold=4% -o tightened.mp4
+```
+
+- `--margin` pads each kept region so cuts do not clip speech.
+- `--edit audio:threshold=4%` sets the loudness floor below which a region is "silence".
+- `--export premiere` emits an EDL/XML instead of a file, to re-import into an NLE.
+
+**pip distribution is stale/discontinued — install via the official binary or `pipx`, not `pip install`.** *Why: the PyPI package lags behind and may not match the documented flags.* When `auto-editor` is unavailable, the low-level fallback is ffmpeg's `silencedetect` / `silenceremove` filters. Both, with the full flag matrix, are in `references/render-and-pipeline.md`.
+
+## B-roll overlays
+
+Stack the overlay above the main video by layering `<OffthreadVideo>` (or `<Img>`) inside an `<AbsoluteFill>`, gated by a `<Sequence from>`:
+
+```tsx
+import { AbsoluteFill, Sequence, OffthreadVideo, staticFile } from "remotion";
+
+const fps = 30;
+const broll = { start: 4.0, duration: 3.0 }; // seconds
+<AbsoluteFill>
+  <OffthreadVideo src={staticFile("main.mp4")} />        {/* base layer */}
+  <Sequence from={Math.round(broll.start * fps)} durationInFrames={Math.round(broll.duration * fps)}>
+    <AbsoluteFill style={{ /* e.g. inset for picture-in-picture */ }}>
+      <OffthreadVideo src={staticFile("broll.mp4")} />    {/* overlay layer */}
+    </AbsoluteFill>
+  </Sequence>
+</AbsoluteFill>
+```
+
+**Convert every timecode to frames with `Math.round(seconds * fps)`, once, at the edge.** *Why: a b-roll cue at 4.0s is frame 120 at 30fps but frame 240 at 60fps — keep seconds in your data and multiply by `fps` from `useVideoConfig()` so changing fps never desyncs overlays.* Use `<OffthreadVideo>` (not the DOM `<video>` or `<Video>`) for frame-accurate decoding during render.
+
+## Render
+
+```bash
+# region test first: 1-2 seconds, validates the pipeline cheaply
+npx remotion render MyVideo out/test.mp4 --frames=0-45
+
+# then the full render
+npx remotion render MyVideo out/video.mp4
+```
+
+Omit the composition id to get an interactive picker. Configure via `@remotion/cli/config` in `remotion.config.ts`, or pass flags on the CLI (flags win):
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+Config.setConcurrency(8);
+Config.setCodec("h264");
+```
+
+| Codec | Use | Flag |
+|---|---|---|
+| `h264` | Default for web/YouTube; broad compatibility | (default) |
+| `h265` | Smaller files, same quality; less universal playback | `--codec=h265` |
+| `prores` | Edit-grade master, large files, re-import to an NLE | `--codec=prores --prores-profile=4444 --pixel-format=yuva444p10le --image-format=png` |
+| `vp8` / `gif` | Web-alpha or looping previews | `--codec=vp8` / `--codec=gif` |
+
+**Always render a 1–2s region (`--frames=0-45`) before the full render.** *Why: a full render of a minutes-long composition costs real time and CPU; a region test surfaces a broken caption layer or missing asset in seconds.* For headless/CI renders, deterministic-output rules, and the codec/quality matrix in full, see `references/render-and-pipeline.md`.
+
+## Anti-patterns
+
+| Bad | Why it breaks | Good |
+|---|---|---|
+| Hardcoding durations in seconds inside JSX | Remotion thinks in frames; seconds desync the moment fps changes | Store seconds in data, `Math.round(seconds * fps)` at the edge |
+| `Date.now()` / unseeded `Math.random()` in a composition | Frames render in parallel and on re-render → non-deterministic pixels | Drive everything off `useCurrentFrame()`; use `random(seed)` |
+| Changing `fps` after writing durations | Every frame-count downstream silently shifts | Pin fps + dimensions on `<Composition>` up front, leave them |
+| Re-downloading the Whisper model every run | The ~1.5 GB `medium.en` download repeats and stalls the pipeline | Download once, cache the model path, reuse it |
+| Committing the 1.5 GB Whisper model to git | Bloats the repo; the model is a build asset | `.gitignore` the model dir; fetch it in setup/CI |
+| Rendering the full video to test a change | Minutes of wasted render to find a broken layer | `--frames=0-45` region test, then full render |
+| Writing the caption *copy* or hook here | That is the script, not the encode | Route to `../video-shorts/SKILL.md`; you only burn it in |
+| Plain `<video>` / `<Video>` for b-roll in a render | Not frame-accurate; tears or skips on render | `<OffthreadVideo>` for frame-exact decode |
+| Running silence removal inside the composition | Trimming dead air is an upstream asset edit | `auto-editor` on the source file before Remotion |
+
+## Verify & references
+
+- `bash scripts/verify.sh <project-dir>` — checks the Remotion project is well-formed and renders. With Node + ffmpeg present it runs `npx remotion compositions` to confirm a composition id exists, does a short region render to a temp MP4, and uses `ffprobe` to confirm a video stream with the expected dimensions/fps. With neither, it falls back to a static check: at least one composition `.tsx` exists and the render script references a real composition id and an output path. Read-only by default; exits 0 on an empty/clean target.
+- `references/captions-pipeline.md` — full Whisper.cpp install + transcribe server, `toCaptions`, the token-highlight caption renderer component, and caption styling/safe-zone notes.
+- `references/render-and-pipeline.md` — `auto-editor` + ffmpeg silence commands, the full render flag matrix, headless/CI render, the codec table, and `ffprobe` verification.

package/skills/remotion-video/evals/README.md

@@ -0,0 +1,23 @@
+# Evals — remotion-video
+
+`cases.yaml` is a routing-and-capability spec, not an automated test suite. To run it,
+load a model with the skill catalog available and replay each prompt:
+
+- **should_trigger** — each prompt must select `remotion-video`. These cover the core
+  render, the captions pipeline, the upstream silence pass, transitions, CI/headless
+  render, plus Spanish and Catalan phrasings and the non-obvious "remove silences
+  before render" cue.
+- **should_not_trigger** — each prompt must route to the named sibling instead
+  (`video-shorts`, `podcast`, `youtube-thumbnails`, `youtube-packaging`,
+  `course-storytelling`). They probe the frames-vs-words boundary.
+- **capability** — load the skill and have it produce the scenario; grade the output
+  against the `must_include` rubric line by line. A pass means every rubric item is
+  present (pinned fps/dimensions, frames=seconds*fps math, a TransitionSeries with a
+  timing, the toCaptions → createTikTokStyleCaptions pipeline, the silence pass
+  located before Remotion, the b-roll overlay, an explicit render command, the
+  determinism note, and a region test before the full render).
+
+There is no harness script here; judge by reading the model's selection and output
+against the YAML. The runnable artifact check lives in `../scripts/verify.sh`, which
+validates an emitted Remotion project (compositions list + a region render that
+`ffprobe` confirms, with a static fallback when Node/ffmpeg are absent).

package/skills/remotion-video/evals/cases.yaml

@@ -0,0 +1,64 @@
+skill: remotion-video
+
+# Prompts that MUST load `remotion-video`. The skill owns the ENCODE: turning React
+# code + assets into a real MP4/MOV via Remotion — the composition/Sequence/
+# TransitionSeries graph, the Whisper.cpp → toCaptions → createTikTokStyleCaptions
+# captions pipeline, the upstream silence pass, b-roll overlays, and `npx remotion render`.
+# It does NOT write the script/hook/caption text (video-shorts), master audio or build
+# an RSS feed (podcast), structure narrative (course-storytelling), design the thumbnail
+# image (youtube-thumbnails), or write title/description/tags (youtube-packaging).
+should_trigger:
+  - prompt: "Render my script and voiceover into an MP4 with Remotion."
+    why: "Core ask — producing the actual file from code + assets is exactly this skill's deliverable."
+
+  - prompt: "Burn animated word-by-word captions onto this video from the Whisper transcript."
+    why: "Non-obvious — names a transcript and burned captions; this is the toCaptions → createTikTokStyleCaptions pipeline, not caption copywriting."
+
+  - prompt: "Automatically remove the silences from my recording before I render it."
+    why: "Non-obvious — the silence pass (auto-editor/ffmpeg) sits upstream of Remotion and is owned here, not by a script skill."
+
+  - prompt: "Add slide and fade transitions between scenes in my Remotion composition."
+    why: "Programmatic transitions via @remotion/transitions <TransitionSeries> — pixels and frames, this skill."
+
+  - prompt: "Quita los silencios y genera el vídeo final con subtítulos quemados."
+    why: "Spanish for 'remove the silences and generate the final video with burned-in subtitles' — the full silence-pass + captions + render pipeline."
+
+  - prompt: "Set up a headless Remotion render in CI that outputs a checkable MP4."
+    why: "Non-obvious — CI/headless render with a verifiable artifact is the rendering half of this skill."
+
+  - prompt: "Renderitza la composició a MP4 amb transicions i overlay de b-roll."
+    why: "Catalan for 'render the composition to MP4 with transitions and a b-roll overlay' — composition graph + transitions + overlay encode."
+
+should_not_trigger:
+  - prompt: "Write the hook and shot-by-shot script for a 30-second Reel."
+    route_to: video-shorts
+    why: "The words, beats and caption text are the script craft; this skill only encodes them into frames."
+
+  - prompt: "Master my podcast audio to -16 LUFS and write the RSS item."
+    route_to: podcast
+    why: "Audio mastering to a loudness spec and feed generation are audio-first, not a video render."
+
+  - prompt: "Design a clickable thumbnail image for this video."
+    route_to: youtube-thumbnails
+    why: "A still image design, not a rendered video file."
+
+  - prompt: "Write the YouTube title, description and tags for the upload."
+    route_to: youtube-packaging
+    why: "Metadata copy for the listing, not encoding pixels."
+
+  - prompt: "Structure the narrative arc and lesson flow for my course video."
+    route_to: course-storytelling
+    why: "Narrative architecture decides what story to tell; this skill renders it, it does not structure it."
+
+capability:
+  - scenario: "Given a voiceover MP4, b-roll clips and a transcript, produce a Remotion project that renders a 1080x1920 video with two scenes, a fade transition between them, a b-roll overlay at a timecode, and burned-in TikTok-style captions, then render it."
+    must_include:
+      - "Pinned fps + dimensions on the <Composition> up front (e.g. 1080x1920 @ 30)"
+      - "frames = seconds * fps math applied with Math.round at the edge for any timecode→frame conversion"
+      - "<TransitionSeries> with a presentation (fade) and a timing (linearTiming or springTiming)"
+      - "Captions pipeline: Whisper.cpp → toCaptions → createTikTokStyleCaptions with combineTokensWithinMilliseconds"
+      - "A silence-removal step (auto-editor or ffmpeg) located on the source BEFORE Remotion, not inside the composition"
+      - "B-roll overlay via <OffthreadVideo> inside an <AbsoluteFill> gated by a <Sequence from>"
+      - "`npx remotion render <id> out/video.mp4` with an explicit output path"
+      - "A deterministic-render note (no Date.now()/unseeded Math.random; drive off useCurrentFrame)"
+      - "A short region test (e.g. --frames=0-45) before the full render"

package/skills/remotion-video/references/captions-pipeline.md

@@ -0,0 +1,163 @@
+# Captions pipeline — Whisper.cpp → toCaptions → createTikTokStyleCaptions
+
+The captions layer is built once on a Node server (transcribe + convert) and then
+consumed by a composition at render time. The native `@remotion/captions` package
+shipped in Remotion **v4.0.216** — the same release that deprecated the old
+`convertToCaptions()` helper in favor of `toCaptions()`. This file holds the full
+install, the transcribe step, and the token-highlight renderer component referenced
+from `SKILL.md`.
+
+## 1. Install Whisper.cpp and a model
+
+`@remotion/install-whisper-cpp` downloads the Whisper.cpp binary and a model. The
+`medium.en` model is ~1.5 GB — download it **once** to a cached path and reuse it.
+Never commit it to git.
+
+```ts
+// scripts/install-whisper.ts  (run with: npx tsx scripts/install-whisper.ts)
+import { installWhisperCpp, downloadWhisperModel } from "@remotion/install-whisper-cpp";
+import path from "node:path";
+
+const to = path.join(process.cwd(), "whisper.cpp"); // .gitignore this dir
+
+await installWhisperCpp({ to, version: "1.5.5" });
+await downloadWhisperModel({ folder: to, model: "medium.en" });
+```
+
+```gitignore
+# .gitignore
+whisper.cpp/
+```
+
+## 2. Transcribe audio to captions
+
+The audio must be 16 kHz WAV for Whisper.cpp. Convert with ffmpeg, then transcribe,
+then `toCaptions()` turns the Whisper token stream into a `Caption[]` with
+per-token start/end timestamps.
+
+```ts
+// scripts/transcribe.ts
+import { transcribe, toCaptions } from "@remotion/install-whisper-cpp";
+import path from "node:path";
+import { execSync } from "node:child_process";
+
+const whisperPath = path.join(process.cwd(), "whisper.cpp");
+const src = "public/voiceover.mp4";
+const wav = "public/voiceover.wav";
+
+// Whisper.cpp wants 16kHz mono WAV
+execSync(`npx remotion ffmpeg -i ${src} -ar 16000 ${wav} -y`);
+
+const whisperOutput = await transcribe({
+  inputPath: wav,
+  whisperPath,
+  model: "medium.en",
+  tokenLevelTimestamps: true, // required for word-by-word
+});
+
+const { captions } = toCaptions({ whisperCppOutput: whisperOutput });
+// persist captions.json next to the composition
+import { writeFileSync } from "node:fs";
+writeFileSync("public/captions.json", JSON.stringify(captions, null, 2));
+```
+
+On a pre-v4.0.216 Remotion you will only have the legacy `convertToCaptions()` (from
+`@remotion/install-whisper-cpp/convert-to-captions`) — it produces the same
+`Caption[]` but is deprecated; prefer `toCaptions()` on any current version. A
+`Caption` is roughly `{ text, startMs, endMs, timestampMs, confidence }`.
+
+## 3. Segment into pages
+
+`@remotion/captions` `createTikTokStyleCaptions()` groups tokens into "pages" — the
+chunks that appear on screen together. The `combineTokensWithinMilliseconds` value is
+the page-size dial:
+
+- **~200 ms** → roughly one word per page → word-by-word pop (TikTok energy).
+- **~1200 ms** → a phrase per page → calmer, more readable.
+
+```ts
+import { createTikTokStyleCaptions } from "@remotion/captions";
+
+const { pages } = createTikTokStyleCaptions({
+  captions,                              // the Caption[] from step 2
+  combineTokensWithinMilliseconds: 1200, // phrase pages; drop to ~200 for word-by-word
+});
+```
+
+## 4. The caption renderer component
+
+Render the current page and highlight the active token by comparing each token's
+timestamp against the current time in ms (`frame / fps * 1000`).
+
+```tsx
+// src/Captions.tsx
+import { AbsoluteFill, useCurrentFrame, useVideoConfig } from "remotion";
+import type { TikTokPage } from "@remotion/captions";
+
+export const Captions: React.FC<{ pages: TikTokPage[] }> = ({ pages }) => {
+  const frame = useCurrentFrame();
+  const { fps } = useVideoConfig();
+  const nowMs = (frame / fps) * 1000;
+
+  const page = pages.find((p) => nowMs >= p.startMs && nowMs < p.startMs + p.durInMs());
+  if (!page) return null;
+
+  return (
+    <AbsoluteFill
+      style={{
+        justifyContent: "flex-end",
+        alignItems: "center",
+        // safe zone: keep text clear of the platform UI margins
+        paddingBottom: 320,
+        paddingLeft: 80,
+        paddingRight: 80,
+      }}
+    >
+      <div style={{ display: "flex", flexWrap: "wrap", justifyContent: "center", gap: "0 16px" }}>
+        {page.tokens.map((t, i) => {
+          const active = nowMs >= t.fromMs && nowMs < t.toMs;
+          return (
+            <span
+              key={i}
+              style={{
+                fontFamily: "Inter, sans-serif",
+                fontWeight: 800,
+                fontSize: 72,
+                color: active ? "#FFE600" : "white",
+                // high-contrast stroke so it survives a bright background
+                WebkitTextStroke: "8px black",
+                paintOrder: "stroke fill",
+                transform: active ? "scale(1.06)" : "scale(1)",
+              }}
+            >
+              {t.text}
+            </span>
+          );
+        })}
+      </div>
+    </AbsoluteFill>
+  );
+};
+```
+
+Mount it as the top layer of the composition, above the video and b-roll:
+
+```tsx
+<AbsoluteFill>
+  <OffthreadVideo src={staticFile("voiceover.mp4")} />
+  {/* ...b-roll sequences... */}
+  <Captions pages={pages} />
+</AbsoluteFill>
+```
+
+## Styling and safe-zone notes
+
+- **High contrast + a thick stroke or box.** Captions must read on a bright phone
+  outdoors; a thin font with no stroke vanishes over light footage.
+- **Respect safe zones.** Keep caption text clear of the bottom and right-rail
+  platform UI. For 1080×1920 vertical, a ~320 px bottom inset keeps text above the
+  caption/CTA bar.
+- **One highlight color, consistent.** The active-token color is a brand decision;
+  pick one and reuse it — flicker between colors reads as a glitch.
+- **Page size matches format.** Word-by-word for high-energy shorts; phrase pages for
+  explainers where the viewer is reading, not just feeling rhythm.

package/skills/remotion-video/references/render-and-pipeline.md

@@ -0,0 +1,131 @@
+# Render and pipeline — silence removal, render flags, CI, verification
+
+This file holds the upstream silence pass, the full render flag matrix, headless/CI
+render, and `ffprobe` verification referenced from `SKILL.md`.
+
+## Silence removal (upstream, before Remotion)
+
+The silence pass edits the **source asset**, not a composition. Run it first so every
+downstream frame number already reflects the tightened timeline.
+
+### auto-editor
+
+`auto-editor` is a Python + ffmpeg engine. **pip distribution is stale/discontinued
+— install via the official binary or `pipx`, not `pip install`.**
+
+```bash
+pipx install auto-editor        # or grab the official binary from auto-editor.com
+```
+
+First pass — cut dead space by audio loudness:
+
+```bash
+auto-editor input.mp4 \
+  --margin 0.2s \                  # pad each kept region so cuts don't clip speech
+  --edit audio:threshold=4% \      # loudness floor below which a region is "silence"
+  -o tightened.mp4
+```
+
+Other useful flags:
+
+- `--cut-out 0,30` — force-remove a frame/time range regardless of loudness.
+- `--export premiere` — emit an EDL/XML for an NLE re-import instead of a rendered file
+  (also `resolve`, `final-cut-pro`, `shotcut`).
+- `--edit motion:threshold=2%` — cut by visual stillness instead of audio.
+
+### ffmpeg fallback (no auto-editor)
+
+Detect silence to inspect where the gaps are:
+
+```bash
+ffmpeg -i input.mp4 -af silencedetect=noise=-30dB:d=0.5 -f null - 2>&1 | grep silence_
+```
+
+Remove silence inline with the `silenceremove` filter (trim leading + internal gaps):
+
+```bash
+ffmpeg -i input.mp4 \
+  -af "silenceremove=start_periods=1:start_duration=0.3:start_threshold=-30dB:\
+detection=peak,silenceremove=stop_periods=-1:stop_duration=0.3:stop_threshold=-30dB" \
+  tightened.mp4
+```
+
+`silenceremove` is bluntter than `auto-editor` (it does not pad cuts the same way),
+so prefer `auto-editor` when available and treat ffmpeg as the no-dependency fallback.
+
+## Render flag matrix
+
+```bash
+npx remotion render <CompositionId> [out/video.mp4] [flags]
+```
+
+Omit `<CompositionId>` for an interactive picker. Config lives in `remotion.config.ts`
+via `@remotion/cli/config`; CLI flags override the config file.
+
+```ts
+// remotion.config.ts
+import { Config } from "@remotion/cli/config";
+Config.setConcurrency(8);             // parallel render workers
+Config.setCodec("h264");
+Config.setPixelFormat("yuv420p");     // yuv444p / yuva444p10le for higher-fidelity / alpha
+```
+
+| Goal | Flags |
+|---|---|
+| Web / YouTube default | `--codec=h264` (default) |
+| Smaller file, same quality | `--codec=h265` |
+| Edit-grade master with alpha | `--codec=prores --prores-profile=4444 --pixel-format=yuva444p10le --image-format=png` |
+| Looping preview / web-alpha | `--codec=vp8` or `--codec=gif` |
+| Region test (cheap validation) | `--frames=0-45` |
+| Higher quality (h264/h265) | `--crf=18` (lower CRF = higher quality, bigger file) |
+| Throughput | `--concurrency=8` |
+
+**Region test before every full render:** `npx remotion render MyVideo out/test.mp4
+--frames=0-45`. A full render of a minutes-long composition is expensive; a region
+test surfaces a broken layer in seconds.
+
+## Deterministic output
+
+- Drive all animation off `useCurrentFrame()`; never `Date.now()` or unseeded
+  `Math.random()` — frames render in parallel and on re-render, so non-frame inputs
+  produce different pixels. Use Remotion's `random(seed)` when you need noise.
+- Pin `fps` + `width` + `height` on `<Composition>` and leave them. Changing fps after
+  durations are written silently shifts every frame count.
+- Same input + same code → byte-comparable frames. That is the artifact contract this
+  skill verifies.
+
+## Headless / CI render
+
+CI has no display and no Whisper model cached, so:
+
+1. Cache the Whisper model between runs (it is ~1.5 GB; do not re-download each run,
+   do not commit it).
+2. Install ffmpeg (or rely on `npx remotion ffmpeg`).
+3. Run the render headless and fail the job if the output is empty or has no video
+   stream.
+
+```bash
+npm ci
+npx remotion render MyVideo out/video.mp4 --concurrency=4
+test -s out/video.mp4 || { echo "empty render"; exit 1; }
+ffprobe -v error -select_streams v:0 -show_entries stream=codec_type,width,height \
+  -of csv=p=0 out/video.mp4
+```
+
+## ffprobe verification
+
+Confirm the render is a real video with the dimensions/fps you expect:
+
+```bash
+# video stream present + dimensions
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height,r_frame_rate,codec_name \
+  -of default=noprint_wrappers=1 out/video.mp4
+
+# duration in seconds
+ffprobe -v error -show_entries format=duration -of csv=p=0 out/video.mp4
+```
+
+`r_frame_rate` reports as a fraction (`30/1` = 30 fps). If `ffprobe` reports no video
+stream, zero dimensions, or the file is empty, the render failed regardless of exit
+code — that is exactly what `scripts/verify.sh` asserts.