video-edit

/video-edit

原始片段导入，成片短视频导出。用户无需打开编辑器：他们查看手机上的副本并提供修改意见；每轮重新渲染约需 2 分钟。

开始制作前请先阅读：references/looks.md（三种风格及其精确参数）、references/layout.md（安全区、位置、人物头部后方的计算公式）、references/gotchas.md（已遇到过的所有陷阱）。如果脚本需要动画插入内容，请阅读 references/overlays.md。

适用于 macOS、Linux 和 Windows。setup.py 会在每次运行开始时检测机器，以下每条命令都基于检测结果，因此切勿猜测路径或 shell：请参阅第 0 步后紧接着的“This machine”。

第 0 步：首次设置（仅运行一次）

SK 是此技能的文件夹（即存放此 SKILL.md 的文件夹）的完整路径。通常为 ~/.claude/skills/video-edit；在 Windows 上为 C:/Users/<name>/.claude/skills/video-edit。

查找 SK/config.json。

**如果文件存在：**加载其中的信息（姓名、Instagram 用户名、默认风格、文件夹），严格按照下面第 3 步的说明运行设置脚本（只需几秒钟：脚本只会检查环境，并在更新后修复环境），阅读“This machine”，等脚本打印 READY 后进入第 1 步。

如果文件不存在：

1. 说：“欢迎使用 /video-edit！我们来完成设置吧。这大约需要 2 分钟，而且只需设置一次。”
2. 在一条消息中询问：
   • 你的姓名（用于 Instagram 个人资料插入内容）
   • 你的 Instagram 用户名（用于个人资料插入内容，以及抓取你的短视频以实现环绕效果）
   • 默认风格：bold（动态文字出现在你头部后方）、cool girl（暖黄色衬线斜体，你的短视频环绕着你），或 cool dude（暗色编辑风格、加宽字距的大写字母 + 衬线字体）。如果对方不确定，请推荐 bold。
   • 原始片段通常存放的位置（默认 ~/Downloads），以及项目存放的位置（默认 ~/reel-edits）
3. 使用机器上可用的 Python 运行设置脚本。按以下顺序尝试，直到某条命令打印 STATUS 行： python3 "SK/scripts/setup.py"，然后是 python "SK/scripts/setup.py"，再然后是 py -3 "SK/scripts/setup.py"。 （在 Windows 上，python3 常常是 Microsoft Store 占位程序，会打印“Python was not found”：直接尝试下一条即可。） 如果这些命令都无法运行，说明缺少 Python。提供适用于其系统的安装命令，然后停止（Windows： winget install --id Python.Python.3.12 -e，Mac：brew install python，Linux：sudo apt install python3 python3-venv）。 然后阅读 STATUS 行：
   • ffmpeg / node / python venv 显示 MISSING：该行末尾会提供适用于这台机器的确切修复命令（Windows 使用 winget，Mac 使用 brew，Linux 使用 apt）。把命令发给用户，并停止操作，直到脚本打印 READY。
   • Windows：用户需要将 winget 命令粘贴到自己的 PowerShell 窗口中（首次运行 winget 时会要求他们同意条款），然后完全退出 Claude Code 并重新打开，否则无法找到新安装的程序。
   • 脚本会自行下载 6 种音效。如果仍显示 MISSING（离线时），这项内容为可选：在添加音效前，成片只是没有音效。
4. 可选，Apify（自动抓取短视频和个人资料数据）：尝试调用简单的 Apify MCP。如果未连接，请说明它是可选的，并告知如何添加：
   1. 在 https://apify.com 创建免费账号，并从 Settings > API & Integrations 复制 API token。
   2. 在终端中粘贴以下命令，并将 YOUR_TOKEN 替换为 token： claude mcp add apify -e APIFY_TOKEN=YOUR_TOKEN -- npx -y @apify/actors-mcp-server （注意：Claude Code 会将 token 以纯文本形式存储在 ~/.claude.json 中；请妥善保管该文件。）
   3. 重新打开 Claude，然后再次运行 /video-edit。 如果没有 Apify，此技能会要求用户将短视频文件放入项目目录。
5. 保存 SK/config.json（绝不包含机密信息）：

   {"name": "...", "instagram": "handle-without-@", "defaultLook": "bold", "clipsDir": "~/Downloads",
    "projectsDir": "~/reel-edits", "setupComplete": true, "setupDate": "YYYY-MM-DD"}
   

6. 说：“设置完成！现在运行 /video-edit……”并继续。

本机信息（每次运行时读取）

读取 SK/.platform.json，该文件由 setup.py 写入，记录了操作系统（os：macos、linux 或 windows）、CPU，以及这台电脑的准确命令：

• PY = 其中的 python 值：此技能专用的 Python（Mac 和 Linux 上为 .venv/bin/python，Windows 上为 .venv/Scripts/python.exe）。运行此技能的每个 Python 脚本时都使用它，绝不要直接使用 python3。
• HF = PY "SK/scripts/hf.py"：在任何操作系统上，使用正确的 Node 启动固定版本的 HyperFrames（npx --yes [email protected] ...）。无需运行 nvm use，也不会遇到 npx.cmd 的问题。
• cutout：CoreML（Apple Silicon）或 CPU（Windows、Linux、Intel Mac：没有 GPU 加速，因此抠像步骤最慢；说明这一点，在后台运行该步骤，同时继续制作）。

setup.py 每次运行时都会重写此文件（步骤 0），所以文件内容始终是最新的。文件缺失或 PY 已不存在：说明 setup 尚未运行或未能完成并达到 READY；按步骤 0.3 运行 setup，并按其中的修复说明操作。

以下命令写法适用于 zsh、bash、Git Bash 和 PowerShell：

• 双引号括起完整路径，并使用正斜杠（Windows 上也适用）："PY" "SK/scripts/ingest.py" "<project>"。
• 在 PowerShell 中（Windows 上未安装 Git for Windows，或使用 PowerShell 工具时），请在命令前加上 &：& "PY" "SK/scripts/ingest.py" "<project>"。
• 每次调用只运行一条命令。不要使用 &&、VAR=1 command、参数中的 ~、source 或 zsh。
• 所有操作系统的 PATH 中都已包含 ffmpeg 和 ffprobe（setup 会检查），因此各系统上的临时 ffmpeg 命令写法相同。

硬性规则

1. 所有内容必须位于 Reels 安全区域内：顶部 220，底部 450（不得低于 y 1470），两侧 35，从 y 1155 起右侧留出 100。
2. 文字或卡片绝不能遮住脸部。人物头部后方的文字，每个字母至少要露出约 70%。
3. 字幕必须与实际说出的内容一致：修正 Whisper 对名称和关键词的误听（“Claude”常被听成“cloud”或“claws”，“skill”常被听成“scale”）。屏幕文字中不要使用 em dash。
4. 音效要轻柔（模板中的 SFX_GAIN = 0.75，相对于基础音量），绝不能盖过人声。
5. 其他创作者的 Reels 出现时，必须在屏幕上标注其账号（@handle）。用户本人主页上的数字必须真实；其他任何内容（评论者、聊天记录）都使用通用占位内容，绝不能指向真实人物，也绝不能伪造证据。
6. 通过最终渲染成片证明剪辑效果，不要用快照证明。
7. 绝不要删除用户的文件。原始文件只读取，绝不修改。

工作流

1. 收集素材

• 视频片段：使用用户指定的文件；若未指定，则使用 clipsDir 中最新的视频文件。创建 <projectsDir>/<short-slug>/。 （config.json 中的 ~ 代表用户主目录；Windows 上为 C:/Users/<name>。此技能的脚本会展开该路径。）
• 参考链接（IG Reels、Pinterest Pin）：开始设计前先下载并查看帧（获取方法参见 overlays.md）。

2. 导入素材

PY SK/scripts/ingest.py <project> <clips or folder> [--newest 5]

查看 work/sheets.jpg（镜头布置和角度），并阅读 transcript.txt（每段视频对应的台词、带时间戳的词语、语音映射）。

3. 选择片段 -> <project>/edl.json

• 根据拍摄片段重新整理脚本：说话者可能会重复一句台词，直到表达满意。除非用户另有说明，否则使用最后一段完整、干净的拍摄（“更好的部分从 0:47 开始”表示从该处开始使用一个连续片段）。
• 根据语音映射确定入点和出点：在第一个词前约 0.05-0.07 秒开始，在最后一个词之后的静音开始处结束。剪掉各段之间的空白；裁切前用 silencedetect 确认短暂停顿（Whisper 可能会虚构剪切点处的开头词语）。
• 连续两段来自同一机位时：放大其中一段（使用 4K 原片，缩放 1.3-1.9，cx/cy 对准胸部）。
• 不确定的词语（关键词、CTA 触发词）：使用 medium.en 重新转写该片段，并在提示词中包含名称。
• 格式：[{"id": "hook", "clip": "c1", "in": 12.66, "out": 15.72, "zoom": 1.0, "cx": 0.5, "cy": 0.5, "line": "..."}]
• 将 EDL 以简短表格发给用户（按片段列出台词、机位），然后继续操作；不要等待回复。

4. 拼接、转录、抠像

PY SK/scripts/assemble.py <project>                 # aroll.mp4 clean 30fps CFR + segments.json with exact frames
PY SK/scripts/transcribe_cut.py <project> "<names and keywords in the script>"
PY SK/scripts/cutout.py <project>                   # run in background; asserts cutout frames == aroll frames
PY SK/scripts/headpos.py <project>                  # after the cutout: head/body position per segment

一次抠一个像（约占用 1.5 GB 内存）。每 30 秒打印一行进度。

5. 并行制作插入片段（EDL 锁定后即可开始）

对于脚本要求的每个动画插入片段（屏幕上的应用、CTA 中的个人资料关注动画、文件滚动）， 使用 references/overlays.md 中的简报模板，在后台启动一个子 Agent：尺寸固定、时长固定、 节拍与词语时间点锁定，输出透明背景的 webm。它们制作期间，继续构建主剪辑。

6. 构建

将 SK/assets/template/ 复制到项目中（build.py、hyperframes.json、package.json、assets/fonts、assets/sfx）， 然后调整 build.py。这是一个真实短视频的完整构建版本：保留构建机制，重写内容（docstring 中列出了各部分的用途）。

• 在何处使用哪种风格：defaultLook 控制整个短视频；提到某种风格的行会切换其所在部分的风格。
• Orbit 和个人资料网格使用用户自己的短视频（overlays.md：通过 Apify 帖子抓取工具抓取用户的账号内容，或使用他们放入 assets/reels/ 的文件）。
• 在项目文件夹中迭代：运行 HF lint（0 个错误），然后运行 PY build.py --safe，再运行 HF snapshot --at <10-20 moments> --no-end --describe false。查看联系表，修复布局、可读性 和安全区。（HF 会自动选择合适的 Node，因此无需运行 nvm use。） 从此技能旧版本复制的 build.py 会忽略 --safe：如果快照中没有红色参考线，就按旧方式构建该项目，运行 SAFE=1 "PY" build.py（此类项目仅存在于 Mac 和 Linux 上）。

7. 渲染与质量检查

PY build.py           # without --safe
HF render -o renders/<slug>-vN.mp4 --quality high      # ~1.5-2 min for a 25s reel on Apple Silicon
PY SK/scripts/check_cuts.py <project> renders/<slug>-vN.mp4 --phone

检查 work/cut_check.jpg：每个切点之后的画面都应清晰显示新镜头。检查音频峰值（volumedetect， 最大值约为 -2 至 -5 dB）以及各部分连接处的静音。

8. 交付

发送或提供手机版本（720p）和全质量渲染版。用通俗的话说明做了哪些改动，以及哪些事项需要用户决定。在重新 组装之前，将每个版本保存在 renders/ 中，并将 assets/ + segments.json 备份到 work/vN/。

根据实际反馈得出的默认规则（不要重新争论）

• 调整调色和字幕来塑造风格；不要用 AI 生成的房间替换背景。
• 不要添加胶片颗粒。画面可以暗，但要保证主体光线充足，并避免肤色偏红。
• 将开场字幕居中放在说话者前方，比固定在左边缘的文字更易读。
• 将文字放在头部后方是标志性手法，但前提是文字清晰可读。

---

由 @tenfoldmarc 制作。关注账号，获取每日 AI 自动化构建内容，分享真实系统，而非理论。