clapper

Clapper：简报 → 画面 + 声音 → 已审核的 MP4

亲自制作下一个有用的成品：场景计划、几张验证帧、可播放的初稿，或经过验证的成片。更新内容简短并编号。只询问会实质改变影片的决策；根据请求和现有项目推断常规制作选择。

1. 初始化，然后选择最短路径

如果评测作者的请求提供了可直接使用的运行时和工作区，请先阅读 作者交接契约 并按该流程操作。 否则，请先阅读 bootstrap.md。 安装此技能是用户唯一需要执行的设置步骤；其余设置由你完成。检测项目、操作系统／架构和已安装工具。如果有 Node/npm，使用已安装技能的绝对路径运行随附的 scripts/bootstrap.mjs。它会通过 npm 缓存安装固定版本的 CLI、准备托管运行时、创建／恢复项目、运行 doctor 并截取验证帧。如果没有 Node/npm，请按该参考中的已验证原生启动器流程操作。复用可正常工作的安装；绝不悄悄升级固定版本的项目。仅当工作区已使用某个框架或正在开发框架时，才使用源码流程。

在本技能的其余部分，clapper 指初始化期间确定的确切命令前缀（可能是 npm exec --yes --package=@archastro/clapper@<resolved-version> -- clapper，也可能是原生启动器的绝对路径）。这不代表全局可执行文件。运行命令时，将项目目录设为 workdir。独立流程不需要 pnpm、源码检出、系统 FFmpeg、浏览器安装或单独的采样器。

1. 阅读项目说明、clapper.json、package 脚本和 Git 状态；保留现有修改。请从已安装的运行时或现有源码检出中读取 API 导出，不要假定上次会话中的 API 仍然适用。初始化已验证首帧；检查该验证结果并继续，不要重复设置。
2. 选择模式：
   • 基准测试／技能或运行时比较： 阅读 technical-evals.md。使用隔离的评测器和独立证据；不要把回归测试或自我审查说成质量结论。
   • 技术／科学解说： 阅读 explainers.md。验证预期的主要来源，建立直观理解，并先在各个抽象层级解释完整流程，再深入细节。
   • 新影片： 使用已初始化的基础／漫画项目；根据简报选择视觉方向和相关的可用示例。
   • 重新剪辑： 保留先前的 composition ID；复用已导出的场景组件，并明确制定新场景计划。审核有改动的场景和两个衔接处，同时检查完整导出中的回归问题。
   • 语音旁白／对白： 阅读 narration.md，再阅读 audio.md。安装可选的本地引擎，试听声音，确定一组核心配音角色，并在准备场景前明确锁定。
   • 音频处理： 除非获得重新调整时间的授权，否则保持画面时序不变；阅读 audio.md。
   • 原创音乐／乐队／编舞： 阅读 music.md，再阅读 audio.md 以审核混音。仅涉及音乐的请求无需制作视频。
   • 仅预览／渲染： 使用现有入口和合成；不要强行重新设计或进行完整创意审核。
   • 润色／最终制作： 使用 visuals.md、audio.md 和 review.md。
3. 使用 clapper compositions 确定入口和合成；绝不要悄悄渲染 CLI 的第一个合成。根目录的 pnpm preview／pnpm render 目标是 intern-promo，并非用户提到的影片。 | 意图 | 查看最接近的具体示例 | | --- | --- | | 基础场景、数据、配乐、肖像画面变体 | videos/_template/src/index.tsx、data.ts、theme.css | | 编辑风格字体与计数器 | videos/showcase/src/ledger/ | | 活泼的弹簧效果与空间运动 | videos/showcase/src/orbit/ | | 终端、图表、摄像机与颗粒效果 | videos/showcase/src/nimbus/ | | 墨水沸腾风格的漫画与可复用的 rig | @archastro/clapper-core/rigs | | 采样的原创配乐、节拍驱动的编排、Music 检查器 | videos/cat-ballet/src/score.ts、src/index.tsx、clapper.json |

该表列出的是仓库示例，并非保证与已安装技能位于同一目录的文件。优先使用已安装运行时提供的模板以及 core/music 导出；如有需要，仅从匹配的官方发行标签获取相关示例。缺少检出的示例不应阻碍新影片的制作。发明替代方案前，先使用现有基础组件。之后仅本地提供的示例可能包含有用的新乐器；依赖它们前，请检查导出项和测试。源代码存在并不意味着它们已自动通过审核或随版本发布。

2. 获得可用画面

以下命令使用解析后的 clapper 前缀，并将项目根目录设为 workdir。从 bootstrap 或 compositions 获取实际的合成 ID；不要依赖持久的 cd 状态。这些是制作检查，不是第二套安装流程。

set -l clapper_id spot # replace with the requested/configured ID
clapper --help
clapper compositions --json
clapper still -c "$clapper_id" --frame 0,30 --out out/stills/first-look
clapper preview --port 4321

预览服务会持续运行。请使用它输出的 URL（端口可能会变化）。在用户的主要 Google Chrome 配置文件中打开交付给用户的预览；自动化浏览器检查使用隔离配置文件。空格键播放，方向键逐帧移动，[ / ] 跳转剪辑点，s 显示安全区域，c 显示文案框，i / o 设置循环范围。ScoreAudio 播放实际准备好的 WAV；合成提示音预览只是近似效果。请以导出的混音作为评判依据。

如果依赖或运行时检查失败，请返回 bootstrap.md 中相应的处理方式；不要自行尝试另一套安装流程。对于旧版工作区项目，传入其明确的入口并使用本地检出的 CLI；保留原有工作流，不要悄然转换。

3. 同步制作画面与声音

如需完整配乐，请遵循 music.md：使用 @archastro/clapper-music 作曲，选择真实的 SFZ 预设，通过 clapper.json 准备，并在影片中放置 ScoreAudio。工作室的 Music 标签页提供可点击的钢琴卷帘窗和精确源代码。合成提示音适用于拟音或其预期音色；若用户要求采样配乐，则使用采样乐器。

1. 编写精简的节拍计划：受众、承诺、时长、格式、风格参考、每个场景的一项动作、屏幕文案，以及预期的声音／静音节拍。对于用户要求的规格说明，请使用 HTML 任务 UI。否则，简短的场景表就足够；不要因为撰写规格说明而延误简单剪辑。
2. defineScenes 负责时长和重叠。将计划同时传给 <Composition scenes={SCENES}> 和 <Scenes plan={SCENES}>。使用 SCENES.start(name) 设置全局声音提示。在场景内部，useFrame() 是局部时间。数值时间以帧为单位；"0.4s" 表示秒。调整时长后，请重新计算帧引用。
3. 将事实性文案／数字放在一个 data.ts 中，将品牌专属设计令牌放在 theme.css 中，并将长篇音乐底轨放在根目录的一个 Score 中。局部动作拟音可以保留在场景中。添加新配乐前，检查复用的场景中是否已有旧底轨／音效。
4. 所有重要动态都通过 useFrame() 实现。使用带种子的随机数、useBoil 或 noise1d；不要使用挂钟、计时器或无种子的随机数。CSS 动画可能依赖工作线程历史：任何必须支持任意跳帧的动画，都应使用基于帧的运动。
5. 编写或润色画面前，请阅读 visuals.md。制作配乐或更改混音前，请阅读 audio.md。这些文档说明的是已验证的陷阱，并非强制要求遵循的统一风格。

配音旁白是独立的脚本

按照 narration.md 的说明，使用旁白 API 中的 defineNarration 和 NarrationAudio。只有通过 clapper voices install，CLI 才会下载可选的模型和运行时；常规设置仍然轻量。所有场景都复用同一个旁白 ID，并提交 clapper-voices.lock.json。切勿静默地重新锁定、为每个场景选择新的声音，或为了在镜头中塞入文案而更改语速。准备好配音后，检查实际时长，再调整文案或场景时长。将重复出现的旁白台词放在一起试听，并检查最终混流。

4. 使用合适的产物进行迭代

# For a scene named intro; replace with a name from the scene map.
clapper still -c "$clapper_id" --scene intro --every 6 -o out/stills/intro
clapper render -c "$clapper_id" --scene intro --draft -o out/intro-draft.mp4
clapper review -c "$clapper_id" --draft -o out/review/round-1

# Final encode, then review that exact file without another encode.
clapper render -c "$clapper_id" --crf 20 -o out/final.mp4
clapper review -c "$clapper_id" --video out/final.mp4 -o out/review/final

--scene 会将明确指定的静帧编号设为场景内编号。--range a-b 表示包含起始帧、不包含结束帧；使用 still --range 时，明确指定的帧编号也以范围起始帧为偏移量。两者都未指定时，--frame 使用绝对帧编号。最后一个有效帧为 durationInFrames - 1。

JPEG q96 是默认的中间格式，在处理颗粒时比 PNG 快得多。需要无损中间文件时选择 PNG。CRF 17 适合平面艺术；处理颗粒较多的内容时，CRF 20–22 很实用。请测量实际结果，不要把这些参数当作交付要求。使用较短的场景或范围进行试渲染，以排查渲染缓慢的问题。

**并发：**独立打包实现会为每次构建创建唯一的 .clapper/harness-*/build 目录；使用不同输出路径时，这些版本可以并发构建。较旧的 Clapper 版本会重新构建或删除同一个 .clapper/harness-build 目录：请串行执行其 harness 命令，或使用隔离的项目快照。检查已安装的版本或源码，不要想当然地认为目录彼此隔离。审阅者正在截取帧时，不要编辑源文件。

5. 必需的对抗性审核关卡

渲染成功并不意味着影片已完成。 对于新完成的影片、作品集展示、大幅润色或最终原创配乐，请阅读并遵循 review.md。请在最终编码前规划好审核者的访问权限。除非用户明确将任务限制为草稿、预览或诊断，否则必须通过此关卡。

1. 条件允许且获准时，必须安排独立审核者。 作者检查后，委托独立的视觉和音频审核者对冻结导出版本进行只读评审。对于原创音乐，还必须明确审核作曲与演奏（音频审核者可同时覆盖两者）。纯音乐作品需要音乐／音频审核，而不是虚构视觉交付物。社交信息流作品还需增加一名静音信息流／故事审核者。
2. 审核实际成品。 提供确切的导出路径／哈希值、简报、场景图、素材包和源文件快照。视觉审核必须包含播放／动态证据，不能只有联系表。音频审核必须评估最终混流的音轨；仅提供分轨、源文件和响度数值并不足够。审核者必须说明自己实际看到了／听到了什么，以及哪些内容仍未经验证。
3. 收集判定结果和问题清单。 每位必需的审核者须返回 SHIP / REVISE / BLOCKED 判定、已检查的帧／时间范围、有证据支撑的问题，以及对先前修复的验证。缺少报告、工具、播放或聆听证据均不算批准。自我审核和 clapper review 输出不能替代独立评审。
4. 修复 → 重新生成 → 独立复查。 复现审核发现、记录处理决定、修复已接受的阻塞问题／重大缺陷，并请审核者验证修改后的导出版本。任何画面、声音、时序、道具、格式或编码的变更，都会使受影响的批准失效。确保报告对应最终成品，而不是较早的草稿。
5. 未通过关卡时，不得宣布最终完成／已批准。 每个必需的审核领域都必须有充分证据、独立的 SHIP 判定，且没有未解决的阻塞问题／重大缺陷。如果无法进行独立审核或必需的媒体检查，只能交付明确标注为草稿／部分结果的内容，并注明 审核未完成，同时说明缺少哪项检查。请提出所需的具体能力，或请用户接受该限制；绝不能暗中降低要求。不要追求任意的数值评分，也不要进行无关的重新设计。

完成意味着：

1. 已按要求的条目／ID／格式完成渲染；已检查画面开头、剪辑点、动态问题区段和最终停留画面；事实文案与 CTA 一致。
2. 已检查导出文件中的声音。说明声音是否实际试听过，还是仅进行过测量。不得根据波形声称已试听。
3. 已完成所有必需的独立审核，并修复、复查所有已接受的阻塞问题／重大缺陷。记录剩余的轻微问题／偏好意见，以及用户接受的任何限制。评分只是辅助反馈，不能替代证据，也不代表能获奖或走红。
4. 最终 MP4 和素材包与最终源文件／道具／格式一致。提供可播放成品和审核报告的链接，说明作品内容／时长，并分别报告视觉、音频以及（如适用）音乐审核判定。绝不能将未经审核的替换版本描述为已批准文件。

提交、推送、上传和发布均须遵守用户要求的范围。此技能不授权执行这些操作。

有关这些规则的缘由以及被取代的旧建议，请参阅 session-evidence.md。