short-editing

短视频剪辑

输入一段原始视频，输出一条成片：video-agent/edits/short-<slug>/output/short-<slug>.mp4。

引擎位于此技能文件夹（下文称为 <skill>）：<skill>/engine/short.mjs。这是一个确定性的 Canvas 渲染器，每条短视频由一个文件驱动：source/spec.js。设计为上方是纸面舞台，下方是摄像头；使用一种强调色，弹簧动画不会过冲，不闪烁、不弹跳。所有操作都在创作者的电脑上运行，支持 macOS、Windows 或 Linux：Node 20+、ffmpeg、Chrome（或安装的无头 Chromium）以及 whisper.cpp。

编写 spec 前请先阅读：

• references/shorts-codes.md：格式、安全区域、钩子和节奏
• references/design-system.md：配色、动效、纸张效果和禁用事项
• references/scene-library.md：所有场景和元素、所有参数、时间键
• references/music.md：8 首背景音乐、分别适合哪些钩子以及从何处开始播放
• references/style.md：剪辑的基本规范
• examples/：使用此引擎制作的真实短视频（spec、组件、联系表）。规划前请打开最接近用户需求的示例：它是质量基准。

如何运行

• 使用创作者的语言（样式中的 creator.lang，否则使用 video-agent/voice.md，再否则使用英语）。每个耗时较长的步骤都用一行说明其作用和耗时。
• <slug>：使用小写字母和连字符，不含句点或空格。
• 所有命令都从项目根目录（包含 video-agent/ 的文件夹）运行。

0. 设置（仅首次运行；之后检查只需 1 秒）

node <skill>/engine/setup.mjs --check || node <skill>/engine/setup.mjs

此步骤会安装缺失的内容：引擎依赖包（15 MB）、未安装 Chrome 时安装 Chromium（100 MB）、whisper.cpp 及其语音模型（0.5 GB，仅需安装一次）、8 首背景音乐，以及在这台电脑上生成的图标。告知创作者首次运行需要 3 到 6 分钟。如果缺少 ffmpeg，会显示安装命令（brew install ffmpeg、winget install Gyan.FFmpeg）；征得对方同意后运行该命令，然后重新进行设置。

1. 原始视频

使用用户指定的文件，否则使用 video-agent/takes/ 中最新的文件。如果是 URL（YouTube、X、Instagram、Loom 或直接的 mp4 文件），先运行：yt-dlp -f "bv*+ba/b" --merge-output-format mp4 -o "video-agent/takes/<slug>.%(ext)s" "<url>"。

ffprobe -v error -show_entries format=duration:stream=codec_type,width,height -of compact "<take>"

如果没有音频流，请停止并说明情况。然后创建项目：

node <skill>/engine/short.mjs init video-agent/edits/short-<slug> --source "<take>" [--style <name>]

• 样式：请求中写有 style <name> 时，对应 video-agent/styles/<name>/style.json，并通过 --style <name> 传入（仅当该文件夹存在时：未知名称会导致 init 停止，因此应改为列出 video-agent/styles/）。如果没有指定样式，init 会采用默认样式（由 video-agent/style.json 指定）。如果完全没有样式，先创建 video-agent/styles/default/style.json，内容为 {"version": 1, "name": "default"}，再加上 <skill>/assets/looks.json 中 default 外观对应的 style（系统字体、全宽摄像头、黑色底栏上的等宽大写字幕）；然后创建 video-agent/style.json，内容为 {"default": "default"}。之后只需告知一次：运行 /studio-setup style，2 分钟即可完成个性化设置。
• init 会创建 assets/ files/ source/ output/ stills/，将原始视频复制到 assets/source.mp4，调整 cam 的取景框，使人物面部位于画面中，并写入初始的 source/spec.js，将样式快照保存为 source/style.json（引擎默认值 < 样式 < spec：spec 只需设置此条短视频中不同于默认值和样式的内容）。样式中的 assets/（徽标、图片）会复制到项目中。
• 格式：默认为 9:16。1:1 对应 format: 'square'（X 信息流），16:9 对应 spec 中的 format: 'wide'。

2. Words

node <skill>/engine/short.mjs words video-agent/edits/short-<slug> [lang]

这台电脑上的 whisper.cpp，速度约为实时（60 秒的录音约需一分钟），免费。使用 ElevenLabs 密钥（在 video-agent/.env、项目 .env 或环境变量中设置 ELEVENLABS_API_KEY= 或 ELEVEN_KEY=），则改用 ElevenLabs Scribe，单独运行：它能识别每次重录和口误，而 whisper 会把它们平滑掉；还会识别人名。每次录音只需几美分。录音中有重录时，推荐一次即可。绝不要在聊天中索要密钥，也绝不要打印密钥。

然后只需运行一次 prepare（步骤 4）：它会写入 files/words.md，列出每个词的 SOURCE 时间，以及剪辑后对应的 SHORT 时间。对于脚本中听错的词，用 captions.replace: [['clics cloud', 'skills Claude']] 修正，绝不要通过编辑时间来修正。

3. 规格

根据 files/words.md 编写 source/spec.js。所有时间均为 SOURCE 秒；引擎会将它们映射到缩短后的剪辑上。以 init 编写的初始规格和最接近的示例为起点。

先在规格顶部的注释块中规划各节拍：

• 钩子（前 2 s）：首帧就要清晰可读，t=0 时绝不能是空白纸面。它要补充口播钩子，而不是重复口播内容。
• 每 2 到 4 s 都要有变化：出现新白板、计数器开始计数、终端开始输入、徽标落下、文字被划掉。每个变化都要在它所表现的确切词语出现时发生（at = 该词的源时间）。
• 根据口播内容选择素材（均来自 scene-library）：人物 = counter（countFrom/countTo，消失时用 strikeAt）；命令或提示词 = term（typeFrom、typeTo、out 行）；文件夹或零件列表 = tree；提到的工具 = 其真实 logo；结果 = check；真实屏幕 = screen（缩放键 + 在读数上标注的圆圈）；推文 = tweet；前后对比 = 两块白板或 bars；重头戏 = stat 或带有一个巨大 text 和一个 emph 词的白板。
• 镜头：layout.keys: [[t, seam]]，seam 1160 = 分屏（上方是纸面，下方是镜头卡片），1920 = 仅纸面，0 = 全镜头。仅在直白表达的台词（故事、反应、CTA）以及 SHORT 时间达到 5 s 或更长时使用全镜头；固定 layout.seam 的样式会始终保持同一尺寸。
• 每个节拍都必须是动作，绝不能只展示一张静止图片。软件概念（源代码、隐私、价格、速度）要通过重现的 UI 来演绎：代码滚动，然后逐行变黑；锁闭合；价格下跌至 0，然后盖上印章。提到带数字的平台时，要重现并动态呈现其真实界面（GitHub 仓库页面、星标曲线最终停在真实数字上）。绝不能把截图直接贴成图片（即使缩放或画圈也不行），不能只展示徽标、文字卡片或静态插图：截图只能作为用 HTML 重建界面的参考。
• 钩子要下最多功夫：设计一个有反转的 2 或 3 幕迷你故事，让多个层次同时移动，并在每个关键词上加入冲击效果（盖章 + 重击），再用徽章呈现结果。例如：大应用用 REPLACED 印章压垮观众自己的应用；在转折词（“现在”）出现时，画面翻转，观众自己的应用变成巨人。只放置一个物体再让它滑动的钩子远远不够：要重做得更丰富，绝不能只做微调。
• 动态组件：凡是库无法妥善绘制的内容（真实应用自身的 UI、Instagram 评论页、通知、GitHub 仓库页面、软件概念、钩子的迷你故事、带有动作的插图），都要制作成带有 window.setT(t) 的 HTML 页面，并导出为视频片段（步骤 3b）。示例中有十几个可供参考。
• 字幕：默认开启，显示在分界线上。captions.emph = 使用强调色显示的词语；在包含相同词语的白板上方使用 captions.hide: [[a, b]]。
• 音乐：根据钩子的情绪，从 music.md 中选择一段背景音乐，使用 music: { bed: '<id>', offset }。不要与上一个短片使用相同的背景音乐。
• 音效：sfx: { swish: 0, accents: 0, extra: [[t, 'thud', -6]] }：不要添加动作噪音；只有在确实有结果时才使用 thud 或 pop。较大的场面（钩子切换、结果、碎裂）要使用 assets/sfx/ 中附带的音效文件（zhhh、impact-boom、riser、glass-shatter……），详见 references/sfx.md。除非创作者要求使用库中没有的音效，否则绝不要用 ElevenLabs 生成音效。
• 始终使用真实徽标：屏幕上提到的每个工具或应用，都要显示其位于 assets/logos/<name>.png 的真实图标（App Store 图标、官方网站或仓库中的图标）；绝不能用字母字形、表情符号或相似图标。将图标下载到项目中，并注明来源。
• 屏幕上的文字不得使用 em dash。

3b. 动效组件

每个组件在 source/<name>.html 中对应一个 HTML 文件，宽度为 1080（或卡片尺寸）。每段动画都必须是由 window.setT(t) 设置的 t 的纯函数（不使用 CSS 动画或计时器），叠加层使用透明背景。页面约定和提供给子 Agent 的提示词（每个组件使用一个子 Agent，并行处理；如果运行环境没有子 Agent，则依次构建）见 references/sub-agents.md。捕获：

node <skill>/engine/short.mjs capture video-agent/edits/short-<slug> source/<name>.html --dur 4.5 --alpha --out assets/<name>.mov

查看 stills/<name>-sheet.jpg，然后接入：添加 media: { x: { src: 'assets/<name>.mov', width: 1080, alpha: true } }，再添加一个 overlay 场景（或在画板上添加一个 actor），参见 examples/thinking-orbs/source/spec.js。

4. 准备

node <skill>/engine/short.mjs prepare video-agent/edits/short-<slug>

剪掉所有细微的静音，应用速度设置（默认为 1.15），拼接语音，提取摄像头和媒体帧（会缓存），写入 assets/timeline.json 和 files/words.md。更改 cut、cam 或 media 后重新运行。cut: [[a, b]]（源时间）会剪掉重录内容或错误开头：逐句检查脚本，每行保留最后一次完整录制。

5. 静帧，然后评审（主要循环）

node <skill>/engine/short.mjs stills video-agent/edits/short-<slug> 0.3 2.9s 6.4s 9s 12.9s

普通数字表示 SHORT 时间，带 s 后缀表示源时间。每个节拍截取一张静帧（内容完成的时刻），再加上开场钩子和最后一秒的静帧。查看 stills/contact.jpg，再放大查看全尺寸静帧，并检查下方的质量标准。修正规格后重新生成静帧。静帧只需几秒，渲染要几分钟：在这里反复迭代。

6. 渲染、声音、成片

node <skill>/engine/short.mjs all video-agent/edits/short-<slug>

一次性完成渲染 + 音频（压低背景音量的语音、音乐底轨、音效，与渲染并行混合）+ 成片（复用、封面、质检）。在 Apple Silicon Mac 上，36 秒的短片约需 5 秒（仅渲染约 4 秒，250 fps，Chrome 中使用 2 个 worker 运行 WebCodecs H.264）；较慢的机器耗时更长，因此请在后台运行并说明耗时。声音更改后，只需重新运行 audio 和 final。质检行必须显示 h264 1080 1920（或 1080 1080、1920 1080），时长与时间线一致，响度约为 -14 LUFS，真峰值不高于 -1 dBTP（否则在规格中设置 mix: { ceil: -2.2 }，然后再次运行 audio 和 final）。草稿：render ... --scale .5。

质量标准（适用于每张联系表）

• 第一帧就能看懂开场钩子。
• 每个节拍都要有动作。查看每个节拍的静帧时，问自己：「画面中有事情发生吗，还是只是一张静止的图？」静止画面（截图、静态插画、计数器旁的徽标、文字卡片）都是需要在渲染前重做的组件。
• 每块画板都要铺满画面：移动端文字要大（小于 34 px 的文字一律不要，字幕约 84 px），每屏 1 到 3 行，不要切到边缘，也不要放在 shorts-codes.md 所述的安全区域内。
• 字幕不得与卡片、CTA 或聊天输入框重叠（captions.hide）。
• 每个时刻只用一种强调色；强调词只能来自 captions.emph 和 emph。
• 卡片尺寸不得改变；摄像头卡片不得调整大小。摄像头全屏拉伸持续时间至少为 5 s。
• 新节拍下方不得残留旧节拍的影像，不得让计数器停在 0，也不得在同一栏中叠放两个值。
• 摄像头色彩要自然：肤色明亮温暖，不得发灰或泛绿（stills/grade.jpg）。
• 每个具名工具都必须显示其真实徽标。
• 声音：语音居前，背景音在句间自然起伏，音效只用于真正的重点，不要使用呼啸声。

7. 交付

在 video-agent/edits/short-<slug>/output/ 中放置：short-<slug>.mp4 和其海报。然后在它们旁边写入：

• short-<slug>.srt：根据 files/words.md（SHORT 时间），每条字幕最多 7 个词，每句话结束后新建一条字幕。
• post.md：发布文案（如下）。

打开视频，让他们立即观看：macOS 使用 open <mp4>，Windows 使用 start "" "<mp4>"，Linux 使用 xdg-open <mp4>。说明视频时长、删掉了什么、背景音乐及其原因，并提出一个可选修改（“换个开场？在另一个词上画板书？故事部分全程用摄像头画面？”）。如需修改：编辑 spec.js、静帧，然后再次运行 all。如果他们希望每条视频都采用某种修改（口音、字体、字幕、节奏），请将其添加到他们的风格文件（video-agent/styles/<name>/style.json，架构见 style-schema.md），而不是只添加到此 spec 中。下一步：/publish short-<slug>。

仅在他们的第一条成品视频中（也就是 video-agent/edits/ 下唯一的文件夹），用他们使用的语言在结尾加上一行：花一分钟评价这个免费工具包，有助于我们改进它：https://codelynx.dev/editing/feedbacks。之后不要再提。

发布文案

post.md，根据脚本和 voice.md 撰写，使用视频中的语言：

• 标题（YouTube Shorts）：少于 60 个字符，前 3 个词就要点明主题。
• 说明文字：前 125 个字符要能独立表达完整内容。然后写 1 或 2 行短句，并加上一条号召（该风格的 CTA）。
• 搜索词：观众会输入的 2 或 3 个词，直接写在标题或第一行中。
• 标签：3 至 5 个与主题相关的标签。不要使用 #fyp 或 #viral。
• 不要写视频中没有提到的内容。

如果已安装该技能，请运行 studio-script 的 humanize 流程（参见其 references/humanize.md）。

CapCut 或 Premiere

有些创作者更喜欢用自己的编辑器。先完成步骤 0 到 4（不包含场景的 spec），然后给他们 files/words.md（逐词列出的剪辑内容）和纯剪辑版本：运行 node <skill>/engine/short.mjs rough video-agent/edits/short-<slug>，会生成 output/short-<slug>-rough.mp4（剪掉所有静音，全画幅，无动态设计），供导入使用，并附上步骤 7 中的 .srt。

仅纸面制作（无录制）

在 spec 中设置 silent: true 和 duration: <s>，不带 --source 运行 init，跳过步骤 2。没有语音、摄像头或字幕；由音乐和屏幕文字来呈现，节奏规则不变。

诚实说明局限

• whisper.cpp 可能会听错姓名和专业术语：用 captions.replace 修正，并仔细核对数字。
• 剪辑可能会切掉换气声或轻柔的尾音：发布前完整看一遍成片。
• Claude 无法听取录制内容：它依赖时间戳。音频质量差（有音乐、回声或两个人同时说话）会导致时间戳更不准确。
• macOS 上的人脸构图十分精准（Apple Vision）；Windows 和 Linux 上则通过 Chrome 中的 MediaPipe 实现，请检查第一张静帧中的 cam。
• 付费套件 Editing IA Pro 包含评审工作室、Recorder、B-roll 库、无露脸吉祥物和缩略图。