papercut-build
Build and render a papercut episode from a storyboard with the library. Scaffolds the project, builds scenes with parallel agents, assets and audio, renders the mp4, then harvests reusables. Use for "build the reel", "scaffold an episode", "rebuild scene 4", "render it".
0xS4N4TG · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add 0xS4N4TG/papercut-explainer --skill papercut-build技能说明
name: papercut-build description: Build and render a papercut episode from a storyboard with the library. Scaffolds the project, builds scenes with parallel agents, assets and audio, renders the mp4, then harvests reusables. Use for "build the reel", "scaffold an episode", "rebuild scene 4", "render it".
Papercut build
Build every episode on the library instead of writing a Remotion project from scratch. Read library/README.md once.
Preflight
- Install: Standard or Full. Needs the library, node 20+, npm, ffmpeg, Python tools (numpy, Pillow, soundfile) and Chrome or Chromium for the audio render. Probe with the commands in
papercut-explainer; if something is missing, run./install.sh --doctorand hand over topapercut-setup. - Library:
$PAPERCUT_LIB, else thePAPERCUT_LIB=line in~/.config/papercut-explainer/config.env, else ask once. With no library at all, build from the sketches in../papercut-explainer/references/remotion-recipes.md. - Load the Remotion best-practices skill first (
remotion-best-practices, from the Remotion Claude Code plugin ornpx skills add remotion-dev/skills) and follow its routing for markup, captions and the Studio. - Needs
papercut/STORYBOARD.mdandnarration/script.jsonfrom the earlier stages. - Smoke test of the whole toolchain:
library/tools/selftest.shbuildsexamples/hello-reel/in a throwaway folder and renders one still.
1. Scaffold
$PAPERCUT_LIB/new_episode.sh <series-dir> NN-slug CompId [out-name]
It creates <series>/episodes/NN-slug/{research,narration/voice,papercut} with the template project and a synced copy of the kit in src/lib/. node_modules comes from $DONOR, else the newest sibling episode, else npm i. If <series>/papercut-assets/ exists, it is laid over the default textures and props.
The folder may already exist, because the earlier stages wrote research/, narration/script.json and papercut/STORYBOARD.md into it. The script merges into it and never overwrites a file that is there. It stops only if papercut/package.json exists (already scaffolded).
Never edit src/lib/ in a project. It is a snapshot, so an old episode renders the same after the library changes. Fix the library, then re-sync with papercut/sync_kit.sh.
2. Plan: episode.json, voice, timing
From the storyboard, fill papercut/episode.json:
scenes:[["S01Hook", "l1_hook", 0], ["S02Name", "l2_name", "called"], ...](scene id, narration line id, first word as an index or the exact word).banners:{"S01Hook": "TAKEAWAY IN CAPS"}.hook: seepapercut-hook.cuts: the Camera / Cut table's cut column.bed,whipScene,cutSfx,gaps(extra beat after a line, in seconds).
Then run papercut-voice through its timing step (it ends with build_vo.py and timing_md.py). Then, from papercut/:
python3 $PAPERCUT_LIB/papercut/stubs.py # src/scenes/index.ts + a stub per scene
build_vo.py flags any scene under 1.2 s; merge it into a neighbour. timing_md.py writes the Timing section of STORYBOARD.md (absolute frames and word cues), so agents never open plan.json.
3. Assets
Follow ../papercut-explainer/references/asset-prompts.md: an image tool (anything that outputs transparent PNGs) for backgrounds and complex static props, code for characters, all text, tags, gauges, buttons and UI. No text inside generated images. With no image tool, build every prop in code with the paper filter; the style holds up. Backdrops: use the library's <Backdrop> set (library/papercut/public/bg/backdrops/_sheet.jpg); generate a new one only when an episode needs a place the library lacks. The proof screenshot: node $PAPERCUT_LIB/tools/capture.mjs <url> public/proof/x.png, shown with the kit's RealShot.
4. Scenes
- Build
S01Hookyourself first, from the HOOK block. It is the reference scene the agents match (cue constants, the camera, clampedinterpolate). - Hand the rest to scene agents in parallel, grouped by scene (2-3 scenes each; more agents cost more startup context). Use the
papercut-sceneagent thatinstall.shlinks into.claude/agents(a general agent also works). The brief islibrary/papercut/AGENT_BRIEF.md. The spawn message gives the project path, each agent's scenes with absolute frame ranges, a QA folder name and the value of$PAPERCUT_LIB. - File ownership: an agent writes only
src/scenes/<Scene>.tsx, an optional<Scene>.parts.tsxandtools/cue_sheet.d/<Scene>.json. Neversrc/lib/**, other scenes,index.ts,plan.json,episode.jsonor the storyboard. - Agents read
library/papercut/CATALOG.mdandlibrary/audio/CATALOG.md, not the kit source, and reuse components, prop sets and scene templates (kit/scenes/, for exampleCtaPhoneDMfor the CTA) before drawing anything new.
Build rules: 1080x1920, 30 fps, scenes chained in the kit's transition series. Global layers: VO and music <Audio>, the taped banner with <Boil>, <WordTagCaptions>, <GrainOverlay>. Every prop is wrapped in <Paper>, entrances use <PopIn>, each scene runs inside its storyboard camera. No CSS animations. Keep the bottom 20% clear. Neighbouring scenes never share a backdrop. The default hero is a boxy orange critter (token C.hero #D67354, shade C.heroLo #A9553B, alias you); accessories and name pills tell the cast apart.
5. Sound
Pick SFX by name from library/audio/sfx/*.js and the bed by preset from library/audio/beds/*.json. From papercut/:
python3 $PAPERCUT_LIB/tools/cues.py && node $PAPERCUT_LIB/audio/render.mjs
cues.py merges the agents' rows into tools/cues.json and prints a note if air sounds exceed one per 2.5 s. render.mjs writes public/audio/music.wav and fx.wav.
6. Render
Preview in the Studio (npx remotion studio). Render only when asked:
$PAPERCUT_LIB/tools/render.sh # -> out/<out>.mp4
Flags: --workers N (default 3), --conc N, --force, --keep