clip-builder

Clip 构建器

从三个部分构建短视频：一个呈现画面的 HTML 页面（场景）、一个包含脚本行列表的 clip.json（提示），以及一个逐帧捕获页面并编码为 MP4 的命令行工具。

场景页面定义了 draw(s)，它仅根据秒数 s 计算出页面在该时刻的状态。捕获工具会为每一帧（第 0 秒，然后是 1/30 秒，以此类推）调用 draw(s) 并截图。因此，输出结果不依赖于机器速度，任何一帧都可以独立渲染以便审查，并且可以使用 --from 和 --to 参数部分重新捕获更改后的场景。

CLI 工具位于此技能目录中的 scripts/clip.mjs。在本文档中，clip 代表 node "<技能目录>/scripts/clip.mjs"，其中 <技能目录> 是包含此文件的目录的绝对路径。（Claude Code 会用此路径替换 ${CLAUDE_SKILL_DIR}。在其他代理中，请使用读取此文件的目录。）从包含 clip.json 的剪辑项目目录运行命令。clip help 列出所有命令和选项。

要求

Node 20 或更高版本，ffmpeg，以及带有 Chromium 的 Playwright。clip doctor 会检查它们，并为任何缺失的内容打印安装命令。在构建剪辑的目录中安装 Playwright（npm install --save-dev playwright，然后 npx playwright install chromium），而不是在此技能目录中。配音和生成的音乐是可选的。它们是唯一需要花钱或 API 密钥的步骤。

沙盒化命令（Codex 中的默认设置）：clip stills、clip capture 和 clip serve 会在 127.0.0.1 上启动一个 HTTP 服务器，前两个还会启动 Chromium。命令沙盒会阻止这两者。然后命令将以状态码 1 退出，并显示一条标识沙盒的消息。请求批准在沙盒外运行这三个命令，并说明原因。不要替换其他捕获方法。其他命令既不需要服务器也不需要浏览器，可以在沙盒内运行；tts --generate 和 music --generate 还需要网络访问。

简要说明

在开始之前先确立以下内容。仅询问缺失的信息。对于用户未指定的任何内容，使用默认值并用一句话说明。

• 目的和受众：宣传、产品演示、员工操作指南、课程。这决定了节奏。宣传片节奏快；培训片则留出时间让观众跟上每一步。
• 时长。默认：宣传或演示 20 到 45 秒，培训 60 到 120 秒。
• 目标平台，决定画幅。默认：wide 1920×1080，以及用于社交媒体的 tall 1080×1350。参见 references/delivery.md。
• 视觉方案：新建图形或应用界面。对于应用：展示哪些界面，以及其源代码或设计系统是否可作为颜色、字体和间距的来源。
• 声音。默认：静音带字幕。这是免费的，而且大多数信息流视频是静音播放的。配音和音乐均为选择加入。
• 脚本。如果用户有脚本，则使用用户的脚本。否则草拟一个，并在构建场景前获得他们的批准。

工作流程

1. 检查工具：clip doctor。
2. 创建项目：clip init <dir> --template graphics 或 --template app-ui。这会写入 clip.json、一个包含可工作示例的 scene/ 目录以及 audio/。两个模板无需修改即可渲染出画面。
3. 在 clip.json 中编写提示，每个节拍一条。节拍是剪辑中具有一行台词和一个视觉状态的一个片段。先写脚本：场景需要与脚本同步计时，并且录制后的每次措辞更改都会产生新的付费请求。references/narration.md 涵盖了为语音而写作的要点。
4. 构建场景：编辑 scene/index.html 和 scene/scene.js。先阅读 references/scenes.md。它列出了保持场景确定性的约束：不能使用 Math.random()、没有时钟或计时器、没有 CSS 动画、所有状态必须从 s 计算得出。对于应用界面，还请阅读 references/app-ui.md。
5. 审查静态帧：clip stills 会在选定的秒数渲染帧并生成一份联系表到 out/review/。将联系表作为图片打开并检查。检查文本是否清晰可读、没有重叠、并且每个节拍在其字幕显示时保持在屏幕上。对每种帧尺寸重复此步骤（--frame tall）。大部分迭代工作在此步骤完成：静态帧速度快且完全免费。clip serve 为用户提供实时预览。
6. 捕获草稿：clip capture --draft 以三分之二尺寸渲染，用于检查运动和节奏。将文件路径交给用户，请他们观看。
7. 如果需要，添加声音。配音：references/narration.md。音乐和混音：references/sound.md。先运行 clip tts（不带标志）；它会列出计划中的请求和字符数。获得用户批准后，再运行 clip tts --generate。每次新的录制后，运行 clip timing，它会放置提示和字幕，并且在配置的情况下，将场景拉伸以匹配配音。然后再次审查静态帧。
8. 捕获最终版：为每种画幅运行 clip capture --final，如果有声音则运行 clip mix，然后为上传文件运行 clip web <file> 以获取更小的副本。
9. 验证并报告：审查最终版的静态帧，阅读混音报告中的响度，并运行 clip scan out。报告生成的内容、文件路径、已检查和未检查的项目。

静音剪辑跳过步骤 7。其字幕来自每条提示的 at 和 until 值，clip timing 会为页面写入这些值。

安全规则

剪辑工作涉及用户的金钱、API 密钥和公开发布的标识。

• 付费请求需要用户明确批准。供应商对配音和音乐收费。CLI 在没有 --generate 的情况下不会发送任何内容；只有在用户批准了特定录音版本后才传递该标志。对一个版本的批准不涵盖下一个版本。在询问时，显示干运行输出（行数和字符数）。如果请求被中断，其收据状态会保持为 attempted。在用户检查提供商的用量历史前不要重试，因为该请求可能已被计费。
• API 密钥仅来自环境变量。CLI 读取 ELEVENLABS_API_KEY 或 OPENAI_API_KEY，没有其他来源。从用户的密钥存储中为单个命令内联传递密钥（references/keys-and-paid-calls.md 中有相关命令）。不要要求用户将密钥粘贴到对话中，不要打印密钥（echo、env、cat），也不要将密钥写入文件。要确认密钥已设置，请检查其长度；clip doctor 会执行此操作。
• 交付文件；不发布。发布或上传剪辑是用户的行为，除非他们要求该特定操作。
• 仅使用用户有权使用的素材。音乐、字体、标志和录像片段需要许可证或用户拥有所有权。仅展示用户拥有或获准展示的应用，不要将模拟界面设计成其他公司的产品。两个提供商的服务条款都涵盖商业用途和生成声音的披露；在发布带有配音的剪辑前，请将其指向用户。
• 将私有数据排除在画面和文件之外。在应用界面中使用虚构的名称和数字。声明为真实的图形和引用必须是真实的，示例必须可识别为示例。在共享任何内容之前，对其运行 clip scan。它会检查 API 密钥、本地用户名和路径、电子邮件地址、用户的私有术语列表以及嵌入媒体文件中的元数据。

编辑指南

• 每个剪辑只覆盖一个主题。拆分涉及两个主题的脚本。
• 在开头几秒内开始配音或第一条字幕。
• 每个节拍使用一个提示，并在台词被朗读时保持节拍的视觉画面在屏幕上。
• 始终包含字幕。大多数信息流视频是静音播放的。
• 在手机屏幕上审查竖屏帧。因此，竖屏帧中的场景单位更大。
• 使用动作来标记状态变化或引导注意力。避免连续运动。
• 将结束卡保持至少 2.5 秒。
• 对于培训：展示操作，然后是结果，以观众可以边操作边跟随的速度进行。在屏幕上为步骤编号，并在开始时说明观众将能够做什么。

命令

命令	功能
clip doctor	检查 Node、ffmpeg 和 Playwright，并报告哪些密钥已设置（仅长度）
clip init <dir> --template graphics|app-ui	从一个工作示例创建项目
clip serve	提供实时预览；URL 中的 ?t=5 会停留在第 5 秒
clip stills [--at 2,5,9] [--frame tall] [--final]	渲染审查用的静态帧和联系表
clip capture [--frame wide] [--draft] [--final] [--from s --to s] [--web]	渲染每一帧并编码为 MP4
clip capture --mode clock --url … --seconds N [--actions file.mjs]	捕获正在运行的应用（实验性；见 references/app-ui.md）
clip tts [--generate]	列出尚未录制的配音；加上 --generate 则进行录制（付费）
clip music [--generate]	同上，用于生成的配乐（付费）
clip timing	计算提示和字幕时间；写入 scene/timing.json 和 .srt 文件
clip mix	以标准响度构建音轨并将其混入每个捕获的视频中
clip web <video>	写入一个用于上传的较小副本
clip scan <dir> [--terms-file words.txt]	在文件共享前报告私有数据
clip strip <媒体文件>	写入一个副本，移除所有嵌入的元数据

输出到 out/ 目录，命名为 <名称>-<版本>-<画幅>.mp4，并根据情况添加 -draft、-part（用 --from/--to 捕获的范围）、-sound 和 -web 后缀。要在新版本旁保留旧版本，请增加 clip.json 中的 "take"（a, b, c, ...）。

参考文件

阅读当前步骤需要的文件。

文件	何时阅读
references/scenes.md	编写或更改场景时：页面契约、辅助库、单位、竖屏帧、字体，以及保持捕获确定性的约束
references/app-ui.md	剪辑显示应用界面时：从设计令牌重建、指针、打字效果、镜头移动，以及捕获正在运行的应用
references/narration.md	编写台词、选择提供商和声音、发音、重新录制一行、使场景匹配配音、字幕
references/sound.md	音乐和混音：电平、闪避、使音轨匹配剪辑、响度、修复混音
references/keys-and-paid-calls.md	在任何付费请求之前：安全传递密钥、发送了什么、收据、中断的请求
references/project-file.md	clip.json 的任何字段
references/delivery.md	帧尺寸、最终渲染、交付前检查、报告内容
references/cookbook.md	请求匹配常见工作时。十二个经过验证的配方：静音剪辑、来自设计令牌的应用界面、多种宽高比、步骤化培训剪辑、来自 JSON 的条形图、使用每个提供商的配音、重新录制一行、背景音乐、自定义字体和标志、正在运行的应用、最终检查。还包含 draw() 代码片段

故障排除

症状	可能的原因
"这看起来像是一个命令沙盒"、listen EPERM 或浏览器启动失败	代理的沙盒阻止了 HTTP 服务器或浏览器。在沙盒外（经用户批准）运行 stills、capture 和 serve
"页面从未设置 window.ready"	场景中的脚本错误（消息会列出页面错误），或者页面未调用工具包的 clip() 函数
同一场景的两次捕获结果不同	场景中的某些状态不是从 s 计算得出的：Math.random()、Date、CSS 动画或过渡、<video>、计时器
另一台机器上文本以不同字体渲染	场景使用了系统字体。将字体文件放入场景目录（references/scenes.md）
画面超前或落后于配音	新录制后未运行 clip timing，或者视频在此之前已捕获。第一种情况下 clip mix 拒绝运行，第二种情况下会发出警告
tts 列表中显示 attempted	之前的请求未完成。在使用 --retry-attempted 前检查提供商的用量历史
音乐电平在词语之间忽大忽小	设置 "mix": { "master": "limit" }（references/sound.md）