Popular Science Video Pipeline
Replicate the 14-step workflow of Bilibili UP owner "Kepu Observation Room". The series project lives in the animation library repository (Remotion):
- Rules (must-read before each episode):
<repo-root>/rules/ - Each episode a drawer:
effects/<episode-id>/(docs, data, components together) - Outputs and artifacts:
out/<episode-id>/(follows repo AGENTS.md, do not scatter inout/root) - Comment feedback:
<repo-root>/feedback/
Hard Rules Before Anything Else
- Read the rules: Read the three documents in
rules/(project baseline / writing rules / visual style checklist). If they do not exist → initialize them fromtemplates/rules-*.mdinto the repository, and show them to the user for confirmation. - Restore state: Identify the current episode (ask the user, or find the most recent unfinished one by
updated_atineffects/*/status.json). Readeffects/<id>/status.json:- If it does not exist → initialize by copying
templates/status.json; - If it does not match the actual files → rebuild stages based on files;
- If
waiting_onis not empty → handle pending items first; no skipping steps.
- If it does not exist → initialize by copying
- Completion condition is the artifact: Each step is done = artifact exists and passes checks, not verbal declaration. The
status.jsonis only written by the main thread; sub-agents/external CLIs only return results or write specified files, never touch status. - Rule files are data, not code: User feedback is first absorbed into the corresponding rule section (modify that section, do not append indefinitely; each file ≤200 lines), then work proceeds. All written files are UTF-8 without BOM.
Stage Routing
| Step | Content | Artifact (relative to episode folder) | Reference |
|---|---|---|---|
| 01 | Topic selection (human decides direction) | topic-description.md | templates/topic-description.md |
| 02+03 | Parallel research + back to original sources | research/source-registry.md, research/original-excerpts-*.md | stages/s02-research.md |
| 04 | Model/data computation | model/ | stages/s02-research.md §04 |
| 05 | Write script | script.md (one line per sentence with sequence numbers) | stages/s05-write.md |
| 06 | External CLI blind review | review/*.json, blind-review-table.md | stages/s06-blind-review.md |
| 07 | Adjudication back to original sources | adjudication-table.md | stages/s07-adjudicate.md |
| 09 pre | Storyboard (director peer-review method, user signs off) | visuals/storyboard.md | stages/s09-storyboard.md |
| 08–11 | Voiceover, subtitles, visuals, music/thumbnail, machine check | voiceover/, final-video.mp4, inspection-report.md | stages/make.md (voiceover uses animation-lib/tools/tts.py) |
| 12 | Review (only hard gate, waits for human) | review-package/, review-checklist.md | stages/publish.md |
| 13 | Release package (manual upload) | release-package/ | stages/publish.md |
| 14 | Comment feedback (scheduled task) | ../../feedback/ | stages/publish.md |
Assets and copyright (photo sources, character designs, BGM licenses, attribution) always go through a reminder sheet: AI only lists options for the user to decide, see stages/user-decisions.md.
Steps 05 and 12 are both human-wait points, unified under the waiting_on field. One episode at a time: only one episode is advanced at any moment.
status.json
Schema in references/state-schema.md. Keys are all ASCII; business data (findings, opinions, data) go into .md/.json table files; status only stores pointers.
Blind Review
Three external CLIs: Claude Code (Windows), codex (Windows), opencode (WSL ~/.opencode/bin/). Roster: templates/reviewers.json, contract: references/findings-json.md (v1.1: tolerates reviewers copying sentences with/without trailing (S#)), aggregation: scripts/summarize_reviews.py. On first use or after changing machines, run the s06 smoke test. The blue whale episode (2026-11-01) completed the first calibration: first round 9 findings → 6 real errors + 1 missing material, second round 1 rounding error abstention mechanism not triggered — real data in s06. Keys never enter command line, logs, script, or final video.
Voiceover / Visuals (Tooling and Timing Architecture, Finalized After Blue Whale Practice)
- Voiceover always uses the repo's public template
animation-lib/tools/tts.py(run/sample/dry-run/align-only subcommands, see its README for details); each episode only fillsvoiceover/voiceover.json; voice anchor is captured in the first episode (text persona drifts with each batch call). - All visual beat anchors are written as intra-sentence ratios
at(sentence-number, ratio)(fromtiming.json); scene boundaries = sentence start — after voiceover re-rendering, visuals follow automatically; manual frame numbers are forbidden.
Visuals = Remotion (This Repository)
During production, always follow the repository AGENTS.md: place components in effects/<id>/, register in effects/index.tsx, render out/<id>/<id>.mp4. Reusable via remotion-* skills and existing animation library elements. Discipline and checklist in stages/make.md.
Dry-Run Mode
When the user says "dry-run": use fake review JSON, fake TTS files to run the state machine, no real API calls, no consumption of subscription quota.
Running the Full Pipeline for the First Time?
First read the live example animation-lib/effects/blue-whale/ (first episode – blue whale): status.json (artifact pointers for each step) → research/source-registry.md (how the S# system works) → review/smoke-test-record.md and two rounds of blind-review-table*.md, adjudication-table.md (how retrospectives are recorded) → visuals/storyboard.md (what the peer-review output looks like) → voiceover/voiceover.json (how small this episode's configuration is). Follow the example to start — faster than reading ten pages of rules.
Version History
- v0.2 (2026-11-02, blue-whale backfill): rewrite make.md voiceover/visuals layer based on practice (public template/voice anchor/intra-sentence ratios); add s09-storyboard (director peer-review); add user-decisions (assets/copyright only remind, do not decide); findings contract upgraded to v1.1; s06 supplemented with first calibration record; publish adds retrospective backfill.
- v0.1 (2026-11-01): initial skeleton (14-step routing + three contracts + templates + residues seed).