lunigui/kepu-video-pipeline

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 in out/ root)
• Comment feedback: <repo-root>/feedback/

Hard Rules Before Anything Else

1. Read the rules: Read the three documents in rules/ (project baseline / writing rules / visual style checklist). If they do not exist → initialize them from templates/rules-*.md into the repository, and show them to the user for confirmation.
2. Restore state: Identify the current episode (ask the user, or find the most recent unfinished one by updated_at in effects/*/status.json). Read effects/<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_on is not empty → handle pending items first; no skipping steps.
3. Completion condition is the artifact: Each step is done = artifact exists and passes checks, not verbal declaration. The status.json is only written by the main thread; sub-agents/external CLIs only return results or write specified files, never touch status.
4. 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 fills voiceover/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) (from timing.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).