Narrated video

Pipeline: script (Markdown) → voice + timing JSON → Remotion scenes timed to each line → checks → MP4 → optional YouTube. Free and local. All code lives in the template repo https://github.com/Carthavate/narrated-video-template (README there has the details).

Start a project

gh repo create <name> --template Carthavate/narrated-video-template --clone --private
cd <name> && npm install
python scripts/placeholder.py script/example.md example && npx remotion studio

If the project should not be a new repo: npx degit Carthavate/narrated-video-template <folder>.

Workflow (copy this checklist)

- [ ] 1. Brief: topic, audience, length, speakers, look, where it gets published
- [ ] 2. Script script/<id>.md (+ <id>.visuals.md: what each scene shows); hand it over for the voice
- [ ] 3. While the voice generates: python scripts/placeholder.py script/<id>.md <id>
- [ ] 4. Register <id> in src/videos/index.ts; scenes in src/videos/<id>/index.tsx (SceneMap)
- [ ] 5. Caption spellings in src/captions.ts ({said: "zero point three", shown: "0.3"})
- [ ] 6. npx tsc && npx eslint src; node scripts/stills.mjs <id> <seconds...>; tools/contact_sheet.py; fix layout
- [ ] 7. Voice done: diff its lines against the script; copy .json/.mp3 to public/<id>.*
- [ ] 8. python tools/check_narration.py <json> <wav>; re-take any bad line
- [ ] 9. Stills on real timing; npx remotion render <id> out/<name>.mp4 in the background (~10-15 min); verify; send
- [ ] 10. Publish only when asked

Script format

# Title

## 1. Scene title

WADI: First line.
GHASSEN: Second line.
BOTH: Said together.

• One idea per scene, 2-5 lines each; each line ≤ 250 characters.
• Write for the ear: short sentences, numbers as words ("zero point three"), acronyms spaced ("G P T four o"), no symbols or code. Add each spelling to src/captions.ts.
• Length: 0.38 s per word + 0.35 s per line; a real take is about 0.92x that.
• Reuse identical intro/outro lines across a series (cached audio, consistent sound).

Voice (on Wadi's PC)

• Duet app (Start menu) → Open file… → pick the script → Generate. Dialogue mode takes WADI:/GHASSEN:/BOTH:; single-voice modes read plain text in one voice.
• Output in C:\dev\arena-videos\voice\out\: <name>.wav, .mp3, .json. Opening a file names the output after it; pasted text becomes untitled-N.
• Still generating while <name>.pending.md exists. Wait in the background: until [ -f X.mp3 ] && [ -f X.json ] && [ ! -f X.pending.md ]; do sleep 20; done
• Re-take line 16 only (1-based): write {"16": 1} to out/X.takes.json, then from C:\dev\arena-videos\voice run ../.venv/Scripts/python.exe say.py --script out/X.script.md out/X.wav --takes out/X.takes.json.
• Elsewhere: any TTS works if it writes {duration, lines:[{scene, sceneTitle, speaker, text, start, end}]}.

Scenes

export const Points: React.FC<{ span: SceneSpan }> = ({ span }) => (
  <Stage gap={36}>
    <Pop at={lineAt(span, 0, 0.2)}><Title size={72}>Appears 20% into line 1</Title></Pop>
    <Pop at={lineAt(span, 1)}><Label>Appears when line 2 starts</Label></Pop>
  </Stage>
);

• lineAt(span, i, fraction) = frame within the scene; Phases swaps two layouts mid-scene.
• Blocks: ui.tsx (Stage 1680×700, Pop, Phases, Sticker, Title, Label, Node, Arrow, Check, Cross, useAppear), components/CodeCard, components/EndCard. Restyle via theme.ts.
• Gotchas: set color: C.ink on plain divs (default text is dark); mono text ≈ 0.6× font size per character, bold body ≈ 0.5×; labels near SVG edges get clipped; inline-style animation only; ES2015 libs (no matchAll/replaceAll).

Checks

• tools/check_narration.py flags lines whose transcription doesn't match. A short line heard "twice" is usually the transcriber: compare the line's duration before re-taking.
• Verify the MP4: ffprobe duration, ffmpeg -af volumedetect (≈ -18 dB mean), one extracted frame.

YouTube (when asked)

• Description: one-line intro, chapters (each scene's start − 0.3 s, first at 0:00), links, hashtags. Don't mention AI narration unless the user wants it; never answer the AI-disclosure question for the user.
• Studio upload in the user's Chrome. Files over 10 MB: explorer.exe /select,"<mp4>" and let the user drag it in.
• Title (ctrl+a, type) → description (focus #description-textarea #textbox via JS, type) → playlist (tick, Done, check) → audience → Show more → tags (focus aria-label="Tags" via JS, comma-separated, end with a comma).
• Click Next one screen at a time; the last step publishes. Stop at Visibility unless told to publish.

Rules

• Ask before anything public: uploads, publishing, repos, PRs.
• Check stills before every full render.