1# claude-code-video-toolkit
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with this video production toolkit.
4 
5## Overview
6 
7**claude-code-video-toolkit** is an AI-native video production workspace. It provides Claude Code with the skills, commands, and tools to create professional videos from concept to final render.
8 
9**Key capabilities:**
10- Programmatic video creation with Remotion (React-based)
11- AI voiceover generation with ElevenLabs or Qwen3-TTS
12- AI music generation with ACE-Step 1.5 (text-to-music, vocals, covers, stems)
13- Browser demo recording with Playwright
14- Asset processing with FFmpeg
15 
16## Directory Structure
17 
18```
19claude-code-video-toolkit/
20├── .claude/
21│   ├── skills/          # Domain knowledge for Claude
22│   └── commands/        # Guided workflows
23├── tools/               # Python CLI automation
24├── templates/           # Video templates
25│   ├── sprint-review/   # Sprint review video template
26│   └── product-demo/    # Marketing/product demo template
27├── brands/              # Brand profiles (colors, fonts, voice)
28├── projects/            # Your video projects go here (gitignored)
29├── examples/            # Curated showcase projects (shared)
30├── assets/              # Shared assets (voices, images)
31├── playwright/          # Browser recording infrastructure
32├── docs/                # Documentation
33└── _internal/           # Toolkit metadata & registry
34```
35 
36## Registry
37 
38`_internal/toolkit-registry.json` is the canonical source for all skills, commands, tools, templates, components, transitions, and cloud endpoints — including their paths, status, options, presets, and env vars. Consult it for structured data. This file focuses on **workflow guidance, patterns, and knowledge** that the registry can't capture.
39 
40## Quick Start
41 
42**First-time setup (optional, ~5 minutes):**
43```
44/setup
45```
46 
47Walks through cloud GPU, file transfer (R2), and voice configuration. Most features are free. Skip this if you just want to render videos with Node.js.
48 
49**Work on a video project:**
50```
51/video
52```
53 
54This command will:
551. Scan for existing projects (resume or create new)
562. Choose template (sprint-review, product-demo)
573. Choose brand (or create one with `/brand`)
584. Plan scenes interactively
595. Create project with VOICEOVER-SCRIPT.md
60 
61**Multi-session support:** Projects span multiple sessions. Run `/video` to resume where you left off. Each project tracks its phase, scenes, assets, and session history in `project.json`.
62 
63**Or manually:**
64```bash
65cp -r templates/sprint-review projects/my-video
66cd projects/my-video
67npm install
68npm run studio   # Preview
69npm run render   # Export
70```
71 
72> **Note:** After creating or modifying commands/skills, restart Claude Code to load changes.
73 
74## Templates
75 
76Templates live in `templates/`. Most are standalone Remotion projects; concept-explainer-short is pure Python. See registry `templates` section for the full list.
77 
78### sprint-review
79Config-driven sprint review videos with theme system, config-driven content (`sprint-config.ts`), pre-built slides (Title, Overview, Summary, Credits), demo components (single video, split-screen), and audio integration.
80 
81### product-demo
82Marketing/product demo videos with dark tech aesthetic, scene-based composition (title, problem, solution, demo, stats, CTA), animated background, Narrator PiP, browser/terminal chrome, and stats cards with spring animations.
83 
84### concept-explainer-short
859:16 vertical concept-explainer shorts (TikTok/Reels/YouTube Shorts). **Python/moviepy, not Remotion** — the whole video derives from `scenes.json` (per-scene narration + visual asset). Pipeline: `gen_vo.py` (per-scene TTS via voiceover.py, clone or built-in, `--max-wpm` pacing clamp) → `gen_captions.py` (whisper word timing force-aligned to script text, needs `pip install openai-whisper`) → `build.py` (audio-anchored composite: Ken Burns on stills, boomerang-looped clips, burned karaoke caption pills, ducked music). Renders at every stage — placeholder cards before assets, silent before audio. Visuals follow the FLUX/Ideogram/LTX split: Ideogram cards at `1440x2560` for anything text-bearing, LTX b-roll at `576x1024` for motion.
86 
87## Brand Profiles
88 
89Brands live in `brands/`. Each defines visual identity:
90 
91```
92brands/my-brand/
93├── brand.json    # Colors, fonts, typography
94├── voice.json    # ElevenLabs voice settings
95└── assets/       # Logo, backgrounds
96```
97 
98See `docs/creating-brands.md` for details.
99 
100## Shared Components
101 
102Reusable video components in `lib/components/`. See registry `components` section for the full list with descriptions. Import in templates via:
103 
104```tsx
105import { AnimatedBackground, SlideTransition, Label } from '../../../../lib/components';
106```
107 
108## Python Tools
109 
110Audio, video, and image tools in `tools/`. See registry `tools` section for the full catalog with descriptions, options, presets, and env vars. Every tool supports `--help`.
111 
112```bash
113# Setup
114pip install -r tools/requirements.txt
115```
116 
117**Important: always invoke tools from the toolkit root directory.** When working inside a project (`projects/my-video/`), tool paths like `python3 tools/upscale.py` will fail because `tools/` is relative. Always use:
118```bash
119cd /path/to/claude-code-video-toolkit && python3 tools/upscale.py ...
120```
121This is especially critical for background commands where the working directory may not be obvious.
122 
123### Tool Categories
124 
125| Type | Tools | When to Use |
126|------|-------|-------------|
127| **Project tools** | voiceover, music, music_gen, sfx, sync_timing | During video creation workflow |
128| **Utility tools** | redub, addmusic, notebooklm_brand, locate_watermark | Quick transformations on existing videos |
129| **Cloud GPU** | image_edit, upscale, dewatermark, sadtalker, qwen3_tts, music_gen, flux2 | AI processing via RunPod or Modal (`--cloud runpod\|modal`) |
130 
131Utility tools work on any video file without requiring a project structure.
132 
133### Voiceover Generation
134 
135```bash
136# Per-scene generation (recommended)
137python tools/voiceover.py --scene-dir public/audio/scenes --json
138 
139# Using Qwen3-TTS (self-hosted, free alternative to ElevenLabs)
140python tools/voiceover.py --provider qwen3 --tone warm --scene-dir public/audio/scenes --json
141 
142# Single file (legacy)
143python tools/voiceover.py --script SCRIPT.md --output out.mp3
144```
145 
146### Timing Sync (after voiceover)
147 
148```bash
149python3 tools/sync_timing.py                          # Dry run comparison
150python3 tools/sync_timing.py --apply                  # Update config (1s default padding)
151python3 tools/sync_timing.py --apply --padding 1.5    # Custom padding
152python3 tools/sync_timing.py --voiceover-json vo.json # Use voiceover.py output
153python3 tools/sync_timing.py --json                   # Machine-readable output
154```
155 
156### Qwen3-TTS (Standalone)
157 
158```bash
159python tools/qwen3_tts.py --text "Hello world" --speaker Ryan --output hello.mp3
160python tools/qwen3_tts.py --text "Hello world" --tone warm --output hello.mp3
161python tools/qwen3_tts.py --text "Hello" --instruct "Speak enthusiastically" --output excited.mp3
162python tools/qwen3_tts.py --text "Hello" --ref-audio sample.wav --ref-text "transcript" --output cloned.mp3
163python tools/qwen3_tts.py --list-voices   # 9 speakers: Ryan, Aiden, Vivian, etc.
164python tools/qwen3_tts.py --list-tones    # neutral, warm, professional, excited, etc.
165```
166 
167Temperature controls expressiveness: `--temperature 1.2` (more expressive) or `--temperature 0.4` (more consistent).
168 
169### Cloud GPU Providers
170 
171All cloud GPU tools support two providers via `--cloud runpod|modal`. RunPod is the default. Modal was added as a reliability fallback after RunPod outages, and offers faster cold starts.
172 
173```bash
174# --- RunPod setup (automated, one-time per tool) ---
175echo "RUNPOD_API_KEY=your_key_here" >> .env
176python tools/image_edit.py --setup
177python tools/upscale.py --setup
178python tools/qwen3_tts.py --setup
179python tools/music_gen.py --setup
180 
181# --- Modal setup (deploy each app you need) ---
182pip install modal && python3 -m modal setup
183modal deploy docker/modal-upscale/app.py        # Then save URL to .env
184modal deploy docker/modal-image-edit/app.py
185# See docs/modal-setup.md for full guide
186```
187 
188### AI Image Generation (FLUX.2 vs Ideogram 4)
189 
190The toolkit has **two** text-to-image generators. They barely overlap — the deciding factor is
191**whether the image needs legible baked-in text**.
192 
193```bash
194# FLUX.2 — text-FREE backgrounds + image editing (self-hosted, free, Apache-2.0/commercial-OK)
195python tools/flux2.py --preset title-bg --brand digital-samba   # background for Remotion text overlay
196python tools/flux2.py --prompt "Abstract tech background, no text"
197 
198# Ideogram 4 — legible IN-IMAGE text + exact color/layout (hosted API, ~$0.03-0.09/img, commercial-OK)
199python3 tools/ideogram4.py --json caption.json --output title.png   # text baked into the image
200python3 tools/ideogram4.py --prompt "Thumbnail: 'SHIP FASTER' bold" --output thumb.png
201```
202 
203**The key distinction — baked-in text vs. background-for-overlay:**
204 
205- **FLUX.2 presets deliberately produce text-*free* backgrounds** (`title-bg`, `cta`, `thumbnail`
206  all end with "no text, no words, no letters"). The intended pattern is **FLUX background →
207  Remotion renders the text on top**, so the text stays editable, animatable per-letter, and
208  frame-accurate. This is the right default for sprint-review **title cards / lower-thirds**.
209- **Ideogram 4 bakes legible designed text *into* a flat PNG.** Pixel-perfect typography + exact
210  hex colors in one shot, but static. Reach for it when **the text *is* the design**: YouTube/social
211  thumbnails (static anyway), quote/stat cards, in-scene signage/logos, stylized text effects that
212  Remotion overlays can't easily do. It fills a real gap — FLUX and LTX-2 both garble in-image text.
213 
214| Need | Use |
215|------|-----|
216| Animated/editable title text, lower-thirds, sprint-review title cards | **FLUX.2 bg + Remotion text** |
217| Atmospheric/abstract backgrounds, problem/solution illustrations, presenter backdrops | **FLUX.2** presets |
218| Finished graphic where typography is the design — thumbnails, quote cards, in-scene signage | **Ideogram 4** |
219| Edit an existing photo (clothing, reframe, style, background) | **image_edit** (neither generator edits) |
220 
221Ideogram 4 chains with the processors like any generator: `ideogram4 → upscale.py` (crisp 4K),
222`ideogram4 → ltx2.py --input` (animate the still), or drop the PNG straight into Remotion `<Img>`.
223Ideogram 4 is generate-only here (no editing). See `.claude/skills/ideogram4/` for the JSON caption
224format — Claude authors the caption as the "magic prompt" expander; needs `IDEOGRAM_API_KEY` in `.env`.
225 
226### AI Image Editing
227 
228```bash
229 
230# Image editing (Qwen-Image-Edit)
231python tools/image_edit.py --input photo.jpg --prompt "Add sunglasses"
232python tools/image_edit.py --input photo.jpg --prompt "Add sunglasses" --cloud modal
233python tools/image_edit.py --input photo.jpg --style cyberpunk
234python tools/image_edit.py --input photo.jpg --background office
235python tools/image_edit.py --list-presets  # Full preset list
236 
237# Upscaling (RealESRGAN)
238python tools/upscale.py --input photo.jpg --output photo_4x.png --cloud runpod
239python tools/upscale.py --input photo.jpg --scale 2 --model anime --face-enhance --cloud runpod
240```
241 
242See `docs/qwen-edit-patterns.md` and `.claude/skills/qwen-edit/` for prompting guidance.
243 
244### AI Music Generation (ACE-Step 1.5)
245 
246Default provider is **acemusic** (official cloud API, free key from [acemusic.ai/api-key](https://acemusic.ai/api-key)). Uses XL Turbo 4B model with 5Hz LM thinking mode. Falls back to Modal/RunPod for self-hosted 2B model.
247 
248```bash
249# Background music (acemusic cloud API by default)
250python tools/music_gen.py --prompt "Upbeat tech corporate" --duration 60 --bpm 128 --key "G Major" --output music.mp3
251 
252# Generate 4 variations, pick the best
253python tools/music_gen.py --prompt "Subtle corporate tech" --duration 60 --variations 4 --output bg.mp3
254 
255# Fast mode (disable thinking)
256python tools/music_gen.py --no-thinking --prompt "Quick draft" --duration 30 --output draft.mp3
257 
258# Scene presets for video production
259python tools/music_gen.py --preset corporate-bg --duration 60 --output bg.mp3
260python tools/music_gen.py --preset tension --duration 20 --output problem.mp3
261python tools/music_gen.py --preset cta --brand digital-samba --output cta.mp3
262 
263# Song with vocals and lyrics (use structure tags for sections)
264python tools/music_gen.py \
265  --prompt "Indie pop anthem, male vocal, bright guitar, studio polish" \
266  --lyrics "[Verse]\nWalking through the morning light\nCoffee in my hand feels right\n\n[Chorus - anthemic]\nWE KEEP MOVING FORWARD\nThrough the noise and doubt\n\n[Outro - fade]\n(Moving forward...)" \
267  --duration 60 --bpm 128 --key "G Major" --output song.mp3
268 
269# Cover / style transfer
270python tools/music_gen.py --cover --reference theme.mp3 --prompt "Jazz piano version" --output cover.mp3
271 
272# Repaint a weak section (acemusic only)
273python tools/music_gen.py --repaint --input track.mp3 --repaint-start 15 --repaint-end 25 --prompt "Guitar solo" --output fixed.mp3
274 
275# Continue from existing audio (acemusic only)
276python tools/music_gen.py --continuation --input track.mp3 --prompt "Continue with jazz piano" --output extended.mp3
277 
278# Stem extraction
279python tools/music_gen.py --extract vocals --input mixed.mp3 --output vocals.mp3
280 
281# Fall back to self-hosted
282python tools/music_gen.py --cloud modal --prompt "Background music" --duration 60 --output bg.mp3
283 
284# List presets
285python tools/music_gen.py --list-presets
286```
287 
2888 scene presets: `corporate-bg`, `upbeat-tech`, `ambient`, `dramatic`, `tension`, `hopeful`, `cta`, `lofi`. See `.claude/skills/acestep/` for prompt engineering patterns and video production integration guide.
289 
290### Watermark Removal
291 
292```bash
293# Locate watermark coordinates
294python tools/locate_watermark.py --input video.mp4 --grid --output-dir ./review/
295python tools/locate_watermark.py --input video.mp4 --preset notebooklm --verify
296 
297# Remove watermark (RunPod)
298python tools/dewatermark.py --input video.mp4 --region 1080,660,195,40 --output clean.mp4 --runpod
299python tools/dewatermark.py --setup  # One-time setup
300```
301 
302**Workflow:** grid overlay → note coordinates → verify with `--region` → remove with dewatermark.
303 
304**Local mode** requires NVIDIA GPU (8GB+ VRAM). Mac users should use `--runpod`.
305 
306### Talking Head Generation (SadTalker)
307 
308```bash
309# Basic usage
310python tools/sadtalker.py --image portrait.png --audio voiceover.mp3 --output talking.mp4
311 
312# For NarratorPiP integration (recommended settings)
313# CRITICAL: --preprocess full preserves image dimensions (otherwise outputs square crop)
314python tools/sadtalker.py \
315  --image presenter_16x9.png \
316  --audio voiceover.mp3 \
317  --preprocess full --still --expression-scale 0.8 \
318  --output narrator.mp4
319```
320 
321**Key flags for NarratorPiP:**
322- `--preprocess full` — **Critical!** Preserves input dimensions (default `crop` outputs square)
323- `--still` — Reduces head movement for professional look
324- `--expression-scale 0.8` — Calmer expression (default 1.0)
325 
326**Image requirements:** Face 30-70% of frame, front-facing, 16:9 for NarratorPiP, 512px+ recommended.
327 
328See `docs/sadtalker.md` for detailed options and troubleshooting.
329 
330### Redub Sync Mode
331 
332```bash
333python tools/redub.py --input video.mp4 --voice-id VOICE_ID --sync --output dubbed.mp4
334```
335 
336The `--sync` flag enables word-level time remapping — essential when TTS voice pacing differs from original. Without it, audio can drift 3-4+ seconds by the end.
337 
338**How it works:** Scribe transcribes original → TTS generates new audio with timestamps → segment mapping (15 words/segment) → FFmpeg variable speed per segment.
339 
340### NotebookLM Branding
341 
342Post-processes NotebookLM videos with custom branding. Solves the problem where redubbed TTS audio extends beyond the safe visual trim point.
343 
344```bash
345python tools/notebooklm_brand.py \
346    --input video_synced.mp4 \
347    --logo assets/logo.png \
348    --url "mysite.com" \
349    --output video_final.mp4
350```
351 
352Trims NotebookLM visuals, keeps full audio, bridges with freeze frame, adds branded outro.
353 
354## Video Production Workflow
355 
3561. **Create/resume project** - Run `/video`, choose template and brand (or resume existing)
3572. **Review script** - Edit `VOICEOVER-SCRIPT.md` to plan content
3583. **Gather assets** - Record demos with `/record-demo` or add external videos
3594. **Scene review** - Run `/scene-review` to verify visuals in Remotion Studio
3605. **Design refinement** - Use `/design` or the "Refine" option in scene-review to improve slide visuals
3616. **Generate audio** - Use `/generate-voiceover` for AI narration
3627. **Sync timing** - Run `python3 tools/sync_timing.py --apply` to update config durations
3638. **Preview** - `npm run studio` in project directory
3649. **Iterate** - Adjust timing, content, styling with Claude Code
36510. **Render** - `npm run render` for final MP4
366 
367## Project Lifecycle
368 
369Projects move through phases tracked in `project.json`:
370 
371```
372planning → assets → review → audio → editing → rendering → complete
373```
374 
375| Phase | Description |
376|-------|-------------|
377| `planning` | Defining scenes, writing script |
378| `assets` | Recording demos, gathering materials |
379| `review` | Scene-by-scene review in Remotion Studio (`/scene-review`) |
380| `audio` | Generating voiceover, music |
381| `editing` | Adjusting timing, previewing |
382| `rendering` | Final render in progress |
383| `complete` | Done |
384 
385See `lib/project/README.md` for details on the project system.
386 
387## Video Timing
388 
389Timing is critical. Keep these guidelines in mind:
390 
391### Pacing Rules
392- **Voiceover drives timing** — Narration length determines scene duration
393- **Reading pace** — ~150 words/minute (2.5 words/second) for standard narration
394- **Demo pacing** — Real-time demos often need 1.5-2x speedup (`playbackRate`)
395- **Transitions** — Add 1-2s padding between scenes
396- **FPS** — All videos use 30fps (frames = seconds × 30)
397 
398### Speaking Rate Tiers
399 
400| Pace | WPM | Use When |
401|------|-----|----------|
402| Slow | 120-130 | Technical explanations, complex concepts |
403| Standard | 140-160 | General narration, demos, overviews |
404| Fast | 160-180 | Energetic intros, recaps, CTAs |
405 
406### Narration Density by Scene Type
407 
408| Scene Type | Duration | Narration Density | Notes |
409|------------|----------|-------------------|-------|
410| Title | 3-5s | 0-10% | Logo + headline, let visuals breathe |
411| Overview | 10-20s | 70-90% | 3-5 bullet points, narration-heavy |
412| Demo | 10-30s | 30-50% | Let the demo speak, narrate key moments only |
413| Stats | 8-12s | 70-90% | Read out highlights, skip obvious numbers |
414| Credits | 5-10s | 0-20% | Quick fade, maybe a closing line |
415| Problem/Solution | 10-15s | 80-90% | Narration drives the story |
416| CTA | 5-10s | 60-80% | Clear call to action, leave a beat at end |
417 
418### Word Count Budgeting
419 
420Before writing scripts, budget words per scene:
421 
422```
423Target duration × 2.5 = word budget (at standard pace)
424Pause seconds × 2.5 = words to subtract from budget
425 
426Example: 15s scene with a 1s pause
427  15 × 2.5 = 37 words budget
428  1 × 2.5 = 3 words for pause
429  Available: ~34 words of narration
430```
431 
432Use `[pause 1.0s]` markers in scripts. Each second of pause costs ~2-3 words from the budget.
433 
434### Timing Calculations
435```
436Script words ÷ 150 = voiceover minutes (estimate)
437Raw demo length ÷ playbackRate = demo duration
438Sum of scenes + transitions = total video
439```
440 
441### When to Check Timing
442- **During scene planning** — Budget word counts per scene before writing
443- **After writing script** — Count words per scene, compare to budget
444- **After generating audio** — Run `sync_timing.py` to compare actual vs estimated
445- **Before rendering** — Ensure `durationInFrames` matches actual audio for each scene
446 
447### TTS Duration Drift (The Real Timing Problem)
448 
449TTS engines do NOT consistently produce 150 WPM output. In practice:
450- **ElevenLabs** tends to compress pauses and speed through short sentences. A 50s script may produce 40-45s of audio.
451- **Qwen3-TTS** varies by speaker and tone preset. Ryan at "professional" tone speaks ~10% faster than "warm."
452- **Short scenes drift more** — a 5-second scene might be off by 30%, while a 30-second scene is off by 10%.
453 
454**The feedback loop after TTS generation:**
455 
4561. Generate per-scene audio files
4572. Run `python3 tools/sync_timing.py` to compare actual vs config durations
4583. Run `python3 tools/sync_timing.py --apply` to update config automatically
4594. For demo scenes: recalculate `playbackRate = rawDemoDuration / actualNarrationDuration`
4605. Re-preview in Remotion Studio before rendering
461 
462**Common drift patterns and fixes:**
463 
464| Problem | Symptom | Fix |
465|---------|---------|-----|
466| Audio shorter than scene | Dead air / awkward silence at end | Reduce `durationInFrames` to match audio |
467| Audio longer than scene | Narration cut off | Increase `durationInFrames` or trim script |
468| Demo too fast for narration | Viewer can't follow | Decrease `playbackRate` or cut narration |
469| Demo too slow for narration | Waiting for demo to catch up | Increase `playbackRate` (1.5-2x typical) |
470| Pauses lost in TTS | Script felt spacious, audio feels rushed | Add explicit `<break time="1s"/>` in SSML or extend scene padding |
471| Cloned voice rushes | Scenes land >170 wpm; retakes also fast (temperature doesn't help) | Pace is inherited from the reference audio. Use `--max-wpm 165` (pitch-preserving atempo clamp, both voiceover.py and qwen3_tts.py), and record clone references as 12-25s of varied sentences *at narration pace* |
472 
473**Pacing QC:** voiceover.py and qwen3_tts.py report `wpm` and a `pacing` label
474(fast/slow/ok) per generated file — check these before composition. Comfortable
475narration is 140-160 wpm; flag anything over ~170. `--max-wpm` turns the check
476into an automatic fix.
477 
478### Fixing Mismatches
479- **Voiceover too long**: Speed up demos, trim pauses, cut content
480- **Voiceover too short**: Slow demos, add scenes, expand narration
481- **Demo too long**: Increase `playbackRate` (1.5x-2x typical)
482- **Demo too short**: Decrease `playbackRate`, or loop/extend
483 
484### Audio-Anchored Timelines (the prevention approach)
485 
486`sync_timing.py` is reactive — it fixes drift after the fact. You can prevent drift entirely by **generating the audio first, then anchoring visuals to known timestamps** instead of estimating durations upfront.
487 
488**The pattern:**
489 
4901. Write the script and split into per-scene segments
4912. Generate per-scene VO files: `voiceover.py --scene-dir public/audio/scenes --json`
4923. Read the actual durations from the JSON output
4934. Anchor every visual element to absolute timestamps in the timeline
494 
495This is especially clean for Python/moviepy builds where each clip carries its own `start=` parameter:
496 
497```python
498# Audio-anchored scene timeline (25s total):
499#   Scene 1 tired      0.3 → 3.74  (audio 3.44s)
500#   Scene 2 worries    4.0 → 8.88  (audio 4.88s)
501#   Scene 3 introduce  9.1 → 11.90 (audio 2.80s)
502 
503text_clip("TIRED OF",     start=0.5,  duration=1.2)
504text_clip("THIRD-PARTY",  start=1.0,  duration=1.8)
505vo_clip("01_tired.mp3",   start=0.3)
506vo_clip("02_worries.mp3", start=4.0)
507```
508 
509The comment block at the top is the source of truth. Every `start=` references it. Drift is impossible because durations aren't being estimated — they're being read from the rendered audio.
510 
511**Trade-off vs. `<Series>`-style auto-chaining:**
512 
513| Approach | Best for | Downside |
514|----------|----------|----------|
515| Audio-anchored absolute starts | Tight ad-style edits, sub-30s spots, anything with exact timing | Manual bookkeeping when re-timing a scene |
516| `<Series>` / auto-chained durations | Long-form sprint reviews where adjacent scenes flex | Drift compounds across the timeline; needs `sync_timing.py` to recover |
517 
518For Remotion projects you can mix the two: use `<Sequence from={...}>` with absolute frames for tight sections and let `<Series>` handle the rest. For pure-Python builds (`build.py` + moviepy), audio-anchored is the natural default.
519 
520## Key Patterns
521 
522### Animations (Remotion)
523```tsx
524const frame = useCurrentFrame();
525const opacity = interpolate(frame, [0, 20], [0, 1], { extrapolateRight: 'clamp' });
526```
527 
528### Sequencing
529```tsx
530<Series>
531  <Series.Sequence durationInFrames={150}><TitleSlide /></Series.Sequence>
532  <Series.Sequence durationInFrames={900}><DemoClip /></Series.Sequence>
533</Series>
534```
535 
536### Media
537 
538**Never use a raw HTML `<video>` tag** — Remotion requires its own component for frame-accurate rendering.
539 
540The toolkit's templates use `<OffthreadVideo>` and `<Audio>` from the `remotion` package. Stick with these for consistency with existing templates. Upstream Remotion now also documents `<Video>` and `<Audio>` from the newer `@remotion/media` package (see `.claude/skills/remotion-official/`) — those add trim props, pitch shifting via `toneFrequency`, and richer loop behavior. Migrate per-template only if you need those features; both APIs render correctly.
541 
542```tsx
543<OffthreadVideo src={staticFile('demo.mp4')} />
544<Audio src={staticFile('voiceover.mp3')} volume={1} />
545<Audio src={staticFile('music.mp3')} volume={0.15} />
546```
547 
548## Scene Transitions
549 
550The toolkit includes a transitions library at `lib/transitions/`. See registry `transitions` section for the full list with options and best-use descriptions.
551 
552### Using TransitionSeries
553 
554```tsx
555import { TransitionSeries, linearTiming } from '@remotion/transitions';
556import { glitch, lightLeak, zoomBlur } from '../../../lib/transitions';
557 
558<TransitionSeries>
559  <TransitionSeries.Sequence durationInFrames={90}>
560    <TitleSlide />
561  </TransitionSeries.Sequence>
562  <TransitionSeries.Transition
563    presentation={glitch({ intensity: 0.8 })}
564    timing={linearTiming({ durationInFrames: 20 })}
565  />
566  <TransitionSeries.Sequence durationInFrames={120}>
567    <ContentSlide />
568  </TransitionSeries.Sequence>
569</TransitionSeries>
570```
571 
572### Transition Options Examples
573 
574```tsx
575glitch({ intensity: 0.8, slices: 8, rgbShift: true })      // Tech/cyberpunk
576lightLeak({ temperature: 'warm', direction: 'right' })       // Warm celebration
577zoomBlur({ direction: 'in', blurAmount: 20 })                // High energy
578rgbSplit({ direction: 'diagonal', displacement: 30 })        // Chromatic aberration
579```
580 
581### Timing Functions
582 
583```tsx
584linearTiming({ durationInFrames: 30 })                                      // Constant speed
585springTiming({ config: { damping: 200 }, durationInFrames: 45 })            // Physics bounce
586```
587 
588### Transition Duration Guidelines
589 
590| Type | Frames | Notes |
591|------|--------|-------|
592| Quick cut | 10-15 | Fast, punchy |
593| Standard | 20-30 | Most common |
594| Dramatic | 40-60 | Slow reveals |
595| Glitch effects | 15-25 | Should feel sudden |
596| Light leak | 30-45 | Needs time to sweep |
597 
598Preview all transitions: `cd showcase/transitions && npm run studio`
599 
600See `lib/transitions/README.md` for full documentation.
601 
602## Design Refinement with frontend-design Skill
603 
604The `frontend-design` skill elevates slide visuals from generic to distinctive.
605 
606### Usage
607- **During scene review** (`/scene-review`): Choose "Refine" for visual improvements
608- **Focused sessions** (`/design`): Deep-dive on a specific scene — `/design title`, `/design cta`
609 
610### When to Use
611- Slide scenes that feel generic
612- When building visual contrast between scenes (e.g., calm title → harsh problem)
613- When animations feel too basic or too busy
614 
615### Visual Narrative Arc
616Consider how visual intensity builds across scenes:
617- **Title**: Set the mood, plant visual seeds
618- **Problem**: Create tension (harsh contrast)
619- **Solution**: Relief and hope return
620- **Demo**: Neutral, content-focused
621- **Stats**: Build credibility
622- **CTA**: Climax - maximum visual energy
623 
624## Toolkit vs Project Work
625 
626**Toolkit work** (evolves the toolkit itself):
627- Skills, commands, templates, tools
628- Tracked in `_internal/ROADMAP.md`
629 
630**Project work** (creates videos):
631- Lives in `projects/`
632- Each project has `project.json` (machine-readable state) and auto-generated `CLAUDE.md`
633 
634Keep these separate. Don't mix toolkit improvements with video production.
635 
636## Documentation
637 
638- `docs/getting-started.md` - First video walkthrough
639- `docs/creating-templates.md` - Build new templates
640- `docs/creating-brands.md` - Create brand profiles
641- `docs/optional-components.md` - Setup for optional ML-based tools (ProPainter, etc.)
642