mcpField
P
papercut-build

papercut-build

github.com/0xs4n4tg创意与媒体9952 次安装2 周前更新
代码仓库

关于 papercut-build

使用 Papercut 库构建 Remotion 单集的技能，无需从头创建项目。它按阶段指导从项目搭建、场景规划到素材、音频、渲染及单集完成后的库更新。

主要功能

  1. 01基于库搭建单集项目
  2. 02规划场景、旁白和时间
  3. 03使用可复用套件组件构建场景
  4. 04准备音效提示并渲染音频
  5. 05预览并渲染单集
  6. 06将可复用成果整理回库

适用场景

  1. 01根据分镜创建 Remotion 单集
  2. 02协调多个 Agent 并行构建场景
  3. 03渲染并修改单个场景
  4. 04制作完成后归档可复用素材

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/0xs4n4tg/papercut-explainer --skill papercut-build

安装后在 Claude Code 中输入/papercut-build确认已加载。

详细介绍

Papercut 构建

基于库构建每一集，而不是从头编写 Remotion 项目。请先阅读一次 library/README.md。

预检

  • 安装：Standard 或 Full。需要库、Node 20+、npm、ffmpeg、Python 工具（numpy、Pillow、soundfile），以及用于音频渲染的 Chrome 或 Chromium。使用 papercut-explainer 中的命令进行检测；如果缺少依赖，请运行 ./install.sh --doctor，然后交由 papercut-setup 处理。
  • 库：使用 $PAPERCUT_LIB；否则读取 ~/.config/papercut-explainer/config.env 中的 PAPERCUT_LIB= 行；否则只询问一次。如果完全没有库，请根据 ../papercut-explainer/references/remotion-recipes.md 中的草图构建。
  • 首先加载 Remotion 最佳实践技能（Remotion 插件中的 remotion-best-practices，或运行 npx skills add remotion-dev/skills -g -y -a <your harness id>；install.sh --mode standard 会执行此操作），并遵循其中关于标记、字幕和 Studio 的指引。
  • 需要前序阶段生成的 papercut/STORYBOARD.md 和 narration/script.json。
  • 整套工具链的冒烟测试：library/tools/selftest.sh 会在临时文件夹中构建 examples/hello-reel/ 并渲染一帧静图。

1. 搭建脚手架

$PAPERCUT_LIB/new_episode.sh <series-dir> NN-slug CompId [out-name]

它会创建 <series>/episodes/NN-slug/{research,narration/voice,papercut}，其中包含模板项目，以及同步到 src/lib/ 的工具包副本。node_modules 来自 $DONOR；如果没有，则使用最新的同级剧集；否则运行 npm i。如果存在 <series>/papercut-assets/，则会覆盖默认纹理和道具。

该文件夹可能已经存在，因为前序阶段已在其中写入 research/、narration/script.json 和 papercut/STORYBOARD.md。脚本会将内容合并到该文件夹中，且绝不会覆盖已有文件。只有在 papercut/package.json 已存在（即已搭建脚手架）时才会停止。

切勿在项目中编辑 src/lib/。它是一个快照，因此库发生变化后，旧剧集的渲染结果仍保持不变。修复库后，再使用 papercut/sync_kit.sh 重新同步。

2. 规划：episode.json、配音、时间安排

根据分镜表填写 papercut/episode.json：

  • scenes：[["S01Hook", "l1_hook", 0], ["S02Name", "l2_name", "called"], ...]（场景 ID、旁白行 ID、作为索引的首个单词或完全匹配的单词）。
  • banners：{"S01Hook": "TAKEAWAY IN CAPS"}。hook：参见 papercut-hook。cuts：Camera / Cut 表格中的 cut 列。bed、whipScene、cutSfx、gaps（每行之后增加的间隔拍数，以秒为单位）。

然后通过 papercut-voice 运行时间安排步骤（最后会执行 build_vo.py 和 timing_md.py）。然后在 papercut/ 中运行：

python3 $PAPERCUT_LIB/papercut/stubs.py        # src/scenes/index.ts + a stub per scene

如果任何场景短于 1.2 秒，build_vo.py 会标记该场景；请将它与相邻场景合并。timing_md.py 会将 Timing 部分（绝对帧数和单词提示）写入 STORYBOARD.md，因此 Agent 无需打开 plan.json。

3. 资源

遵循 ../papercut-explainer/references/asset-prompts.md：背景和复杂的静态道具使用图像工具（任何可输出透明 PNG 的工具），角色、所有文本、标签、仪表、按钮和 UI 使用代码制作。生成的图像中不得包含文本。没有图像工具时，使用纸张滤镜通过代码制作所有道具；成片依然能保持这种风格。背景：使用库中的 <Backdrop> 集合（library/papercut/public/bg/backdrops/_sheet.jpg）；只有当剧集需要的场景在库中不存在时，才生成新的背景。证明截图：运行 node $PAPERCUT_LIB/tools/capture.mjs <url> public/proof/x.png，并使用工具包的 RealShot 展示。

4. 场景

  1. 先根据 HOOK 区块自行构建 S01Hook。这是供各 Agent 对齐的参考场景（提示点常量、摄像机、带边界限制的 interpolate）。
  2. 将其余场景按场景分组（每组 2-3 个场景），并行交给场景 Agent。Agent 越多，启动时需要的上下文越多。使用 install.sh 为你的执行环境写入的 papercut-scene Agent（Claude Code ~/.claude/agents、OpenCode ~/.config/opencode/agents、Codex ~/.codex/agents、Gemini CLI ~/.gemini/agents）；通用 Agent 也可以。使用执行环境自身的机制启动它（Claude Code 中的 Task 工具、opencode 中的 subagent 工具、Codex 的子 Agent、Gemini 的 agent 工具）。如果你的执行环境没有子 Agent，就按相同顺序和任务说明逐个自行构建场景，只是更慢，流程并无不同。任务说明见 library/papercut/AGENT_BRIEF.md。启动消息会给出项目路径、各 Agent 负责的场景及其绝对帧范围、QA 文件夹名称，以及 $PAPERCUT_LIB 的值。
  3. 文件归属：Agent 只能写入 src/scenes/<Scene>.tsx、可选的 <Scene>.parts.tsx 和 tools/cue_sheet.d/<Scene>.json。绝不能写入 src/lib/**、其他场景、index.ts、plan.json、episode.json 或分镜脚本。
  4. Agent 应阅读 library/papercut/CATALOG.md 和 library/audio/CATALOG.md，而不是套件源码；绘制新内容前，应优先复用组件、道具集和场景模板（kit/scenes/，例如 CTA 的 CtaPhoneDM）。

构建规则：1080x1920，30 fps，场景按套件的转场序列串联。全局图层：VO 和音乐使用 <Audio>，贴胶带的横幅使用 <Boil>，以及 <WordTagCaptions>、<GrainOverlay>。每个道具都要套上 <Paper>，入场使用 <PopIn>，每个场景都在其分镜摄像机内运行。不要使用 CSS 动画。底部 20% 保持空白。相邻场景不能共用背景。默认主角是方块状的橙色小动物（令牌 C.hero #D67354，阴影色 C.heroLo #A9553B，别名 you）；通过配饰和姓名胶囊区分角色。

5. 音效

从 library/audio/sfx/*.js 中按名称选择音效，并从 library/audio/beds/*.json 中按预设选择背景音轨。在 papercut/ 中运行：

python3 $PAPERCUT_LIB/tools/cues.py && node $PAPERCUT_LIB/audio/render.mjs

cues.py 会将各 Agent 的条目合并到 tools/cues.json，如果气流声超过每 2.5 s 一次，还会打印提示。render.mjs 会写入 public/audio/music.wav 和 fx.wav。

6. 渲染

在 Studio 中预览（npx remotion studio）。只有收到要求时才进行渲染：

$PAPERCUT_LIB/tools/render.sh        # -> out/<out>.mp4

标志：--workers N（默认值为 3）、--conc N、--force、--keep。每个场景都会缓存，因此修复后只会重新渲染有改动的场景；更改套件、计划、语音或字幕则会重新渲染全部内容。首次运行会下载 Remotion 的无头 Chrome，out/cache 中的 ProRes 文件会占用数 GB 空间。

修复或重建单个场景：编辑 src/scenes/<Scene>.tsx，使用 papercut-qa 检查，然后再次运行 render.sh。

7. 收尾（剧集完成后）

python3 $PAPERCUT_LIB/tools/harvest.py .       # from papercut/; read-only report
python3 $PAPERCUT_LIB/tools/catalog.py         # regenerate both catalogs

按照 library/HARVEST.md 中的说明，将套件修复、可复用组件、新音效和反复出现的节奏点纳入成果，并在 library/CHANGELOG.md 中添加条目。

  • 动作显得僵硬或含糊时，请查看 ../papercut-explainer/references/motion-principles.md，找到对应原则及其套件辅助工具。

交接

接下来使用 papercut-qa，它会读取项目中的静帧和 STORYBOARD.md。构建期间按场景运行一次，并在最终渲染前对整部作品运行一次。发布后，由 papercut-strategy 进行复盘。

评论

支持 Markdown