learnaiwithhugo/video-editor-skills

/kallaway-edit

原始片段输入，完成竖版Reels输出（1080x1920，30 帧/秒，-14 LUFS），采用Kallaway风格。 一切都在用户的Mac上使用免费工具运行。使用者通常不是技术人员： 用简单明了的英文与他们沟通，每步一条短消息，绝不让他们接触代码。

SK = ${CLAUDE_SKILL_DIR}，此技能的文件夹（切勿写入其中：更新时会替换它）。 DATA = $HOME/.claude-video-editor，编辑器自身的文件夹，跨更新保留： 用户的设置（DATA/config.json）、编辑器的Python环境（DATA/venv）、音效（DATA/sfx）。 ROOT = 项目文件夹（包含 raw/、exports/）：即 DATA/config.json 中的 projectRoot，由 设置向导（步骤0）保存。WORK = ROOT/work/<slug>/（每个Reels一个文件夹；slug是简短 的短横线命名，例如 opus-tips）。对每个路径使用引号：它们常包含空格。 通过以下两个命令之一运行所有脚本，完全按原样书写，以便脚本能找到用户的设置： PY = VIDEO_EDITOR_DATA="$HOME/.claude-video-editor" "$HOME/.claude-video-editor/venv/bin/python" -I（设置完成后） SETUP = VIDEO_EDITOR_DATA="$HOME/.claude-video-editor" python3 -I "${CLAUDE_SKILL_DIR}/scripts/setup.py" 在开始构建前阅读以下文件：references/style-rules.md（外观，以数字形式）、references/graphics-recipes.md（如何将口述观点转化为图表）、references/gotchas.md。

硬性规则

• 仅免费工具。 ffmpeg、Node 22+、Python、HyperFrames（npx hyperframes@<固定版本>）、faster-whisper、 HyperFrames的本地背景移除、捆绑的OFL字体、HyperFrames media-use的记录音效 （设置时获取，绝不捆绑：Pixabay许可证）以及来自Openverse或用户自己曲目的CC0/CC BY音乐。 无付费API、无HeyGen登录、无音乐生成、无任何受版权保护内容。
• 用户可提供的选项：music: on|off（默认：设置时保存的选择）、music: <用户自己曲目的路径>、setup（重新运行设置向导）。
• 切勿运行 npx hyperframes init 或 npx hyperframes skills（它们会将技能安装到 ~/.claude/skills）。每次HyperFrames调用：HYPERFRAMES_SKIP_SKILLS=1 HYPERFRAMES_NO_TELEMETRY=1。 始终使用 snapshot ... --describe false（否则帧会被上传到Gemini）。
• 不要触碰用户的原始素材。 使用 raw/ 中的副本进行工作。工作文件放在WORK中； 只有完成的Reels才放入 exports/。切勿删除用户的文件。
• 字幕显示实际所说的内容，拼写正确（"Claude"、"Opus 5.5"），数字用阿拉伯数字。
• 图形从不遮挡面部；文字不放在y 1470以下或y 1155以下右侧100 px内。
• 没有任何元素以动画方式移出画面。红色 #C41514 是唯一的强调色。每个标题和每个章节一个衬线斜体词。
• 展示你的工作：在每一步将带编号的PNG放入 WORK/progress/（01-takes-picked.png、...）。
• 在宣布完成前，以完整尺寸使用 qa.py 检查最终渲染。对于不匹配的地方要诚实说明。

工作流程

0. 设置向导（仅首次，约5-10分钟）

读取 DATA/config.json。如果它包含 "setupComplete": true 且其 projectRoot 文件夹存在， 则运行 SETUP --check（几秒钟，不安装任何东西）；如果状态为READY则转到步骤1，如果状态为NOT READY则修复它指出的问题（在更新需要新工具版本后，只需再次运行 SETUP：用户的文件夹和选择会被保留）。 否则（首次运行，或用户说 "/kallaway-edit setup"）运行向导。用一行简短文字告诉他们当前步骤 （"步骤2/5：检查你的工具"）。

1. 欢迎。 "欢迎使用Kallaway编辑器！让我们开始设置。这大约需要5-10分钟， 并且只需一次。"
2. 我们在Claude Code中吗？ 这需要Claude Code（终端应用、Claude桌面应用的Code标签页、 或IDE扩展），在本地文件夹中打开，因为它要编辑真实的视频文件。如果 你能运行shell命令并读取本地文件，那就是。如果不能（普通聊天）， 说："打开Claude桌面应用，点击Code，选择Local，选择一个文件夹（或创建一个叫 AI video editor的文件夹），然后再次输入 /kallaway-edit。"然后停止。
3. 工具检查。 SETUP --check。以简短表格形式显示结果：工具、 是否找到、用途（ffmpeg剪辑和混合音频；Node.js运行HyperFrames；HyperFrames将 编辑转化为视频；faster-whisper识别每个单词；Python运行辅助脚本；yt-dlp在此处 是可选的，用于从链接下载Reels，/new-edit-style需要它）。对于需要用户自己安装的 任何工具（ffmpeg、Node.js、Python），给出修复名称并说明粘贴位置： Terminal应用（Mac：Command + 空格，输入Terminal）。如果要求输入Mac密码， 他们自己在Terminal中输入，绝不在此聊天中输入。等待他们告知完成，然后 再次检查。标记为"完整安装会安装它"的项不需要用户做任何事。
4. 文件存放位置。 在一次消息中询问，每项附上建议答案：
   • "你想让我在哪里制作你的视频？" 如果当前文件夹为空或已经是视频 文件夹，建议使用它（显示其完整路径），否则建议 ~/Desktop/AI video editor。
   • "你的素材通常存放在哪里？" 建议 ~/Downloads（AirDrop将手机片段放入的位置）， 或者 "我自己会把片段放入raw文件夹"。
   • "背景音乐在你的声音之下：开还是关？" 建议开（他们可以在每个视频中更改）。 然后提供文件夹："要我设置你的项目文件夹吗？我会创建 raw/（你的片段）、 references/（你喜欢的视频）、exports/（完成的Reels）、work/（我的工作文件）和 archive/（旧版本）。任何已存在的内容保持不变。" 如果同意： SETUP --project "<folder>" --clips-from "<folder or omit>" --music on|off。 它只创建缺失的文件夹并将答案保存到 DATA/config.json。
5. 安装。 "正在安装免费编辑工具（一次性，约5分钟：转录 引擎、视频渲染器、音效和语音模型）。" 在后台运行 SETUP 并用通俗语言 转述其进度行。它仅安装到DATA中（全局无任何安装，技能文件夹中无任何安装， 因此更新不会撤销它），并在完成时标记设置完成。
6. 完成。 给出 references/filming-guide.md 中的4条拍摄技巧（固定相机、广角镜头、暗室中 暖光打脸、重复一句台词直到说好），然后："设置完成。将你的片段放入 raw/ （或告诉我 中的哪些文件）然后说 /kallaway-edit。" 如果他们已经 提供了片段，直接转到步骤1。

每次运行时摄入片段：片段是用户指定的文件；否则询问，提供 clipsFrom 中最新的视频文件。 复制 到 ROOT/raw/ 中（绝不移动或更改原始文件）。音乐遵循保存的 music 选择，除非用户另有说明。

1. 查找每个镜头（每1分钟素材约需1分钟）

PY "SK/scripts/takes.py" "WORK" "ROOT/raw/clip1.MOV" "ROOT/raw/clip2.MOV"（添加 --fast 可更快但准确性较低）。 读取 WORK/takes/*.takes.txt：每次尝试及其时间范围，重拍标记。 询问（或在片段中查找）是否有脚本。说："正在聆听你的片段并找出每句台词的最佳镜头。"

2. 挑选镜头并剪辑（约1分钟）

编写 WORK/edl.json（格式：SK/template/examples/edl.json）：每个片段一行，按脚本顺序排列， 通常使用最后一个完整干净的镜头。使用 {"clip","chunk"} 或 {"clip","start","end"}（跳过块内的 口误；使用 transcribe.py --range a-b --model medium.en --no-vad 检查单词时间）。 目标20-30秒；稍微超出（到约38秒）比打破钩子所做的承诺要好。除非被要求，否则跳过行动号召（CTA）。 然后 PY "SK/scripts/assemble.py" "WORK"：cut.mp4（恒定帧率CFR、紧密贴合语音、压缩、-14 LUFS）、 segments.json、words.json、words.txt。读取words.txt：每行必须表达原意。 PY "SK/scripts/qa.py" "WORK" --takes 写入 progress/01-takes-picked.png。 说："这是剪辑：<台词>。共秒。" 在构建图形之前锁定剪辑。 如果之后重新剪辑：PY "SK/scripts/reindex.py" "WORK" "WORK/.prev/words.json" 保持每个图形在对应的单词上。

3. 去除说话人背景（约3-4分钟，后台运行）

PY "SK/scripts/cutout.py" "WORK"：cutout.webm（帧匹配，边缘清理）+ headtrack.json。 在运行时，规划编辑（步骤4）。然后在黑色背景上查看一帧合成画面，检查光晕， 并将其保存为 progress/02-cutout-check.png。

3b. 音乐（除非 music: off；约2-6分钟，后台运行）

PY "SK/scripts/music.py" "WORK"（或 --file "<他们的歌曲>"，或 --off）。它从Openverse选择一个 免费的CC0/CC BY器乐，排除人声，并写入 WORK/music-credit.txt。告诉用户它选择了 什么，对于CC BY的音乐，告知署名行应放在字幕中。

4. 逐行规划编辑

编写 WORK/plan.json（格式：SK/template/examples/plan.json）：

• shots：每个布局的起始位置（0、"line:N" = EDL第N行的第一帧、"w:N" = 第N个单词的起始点）。 可以展示内容的场景使用舞台布局；连接性/个人化台词和回报部分使用全屏布局 （占运行时长的16-29%）。场景画面之间也进行硬切。首次剪切约在3.5秒处。
• scenes：哪个图形何时播放（id、from、to、可选的 src + vars 用于多次挂载同一个场景文件， 例如重复出现的带编号的"主页"图形）。一个场景可以在全屏镜头下运行然后返回 （返回时在0.6秒内添加一个新东西）。
• punch：在结束短语上的快切推进（x1.19倍，带上升音效进入），最多一两次。
• captions：fix（单词索引 -> 正确文本）、emphasis（每节一个衬线词）、 keep_together（单词索引对，例如 "Number" 和 "1,"）。 使用 graphics-recipes.md：每个观点得到一个形状、一个标题（粗体 + 一个衬线强调词，在红色 框中的主张），以及其单词上的节拍，大约每1秒有新内容。逐镜头回述计划，每镜头一行。

5. 构建场景（约15-25分钟）

每个场景是 WORK/scenes/<name>.html，从 SK/template/scene-starter.html 或 SK/template/examples/（六个真实场景）中最接近的文件开始。工具包（template/kit/kw.css、 kw.js）提供了舞台外观和动画辅助（KW.title、blurIn、pill、pulse、draw、cam、 type、strike、count、scramble；at(i) = 第i个单词的起始时间）。每个动画都在场景的 <!--KW:SFX [...] --> 注释中获取其音效提示，例如 {"t": "w:24-0.02", "s": "whoosh"}， 遵循 references/sound-map.md（摄像机移动=whoosh，指示条pill=pop，卡扣/滴答=click， 打字文本=typing，重要时刻=impact，回报=sparkle）。如果你有Agent工具且场景超过约3个， 则将场景分派给最多2个并行Agent，附带：该场景的精确单词列表和时间、观点、此技能的 参考文件，以及 build.py ... --project WORK/project-<letter> 以避免冲突。 PY "SK/scripts/build.py" "WORK" 写入 WORK/project/（根：圆点舞台、头像卡片、弹出层、 字幕轨道、场景宿主、音效轨道，全部生成）。然后在 WORK/project 中： npx -y hyperframes@<pin> lint（0错误）和 snapshot --at <times> --no-end --describe false -o snaps/x，读取PNG，修复，重复。将每个场景的截图表保存为 progress/03-scene-.png。

6. 渲染（约1分钟）和检查（约1分钟）

PY "SK/scripts/render.py" "WORK" --name draft（快速），然后 PY "SK/scripts/qa.py" "WORK" "WORK/renders/draft.mp4" 并查看 qa/cuts.png（每次剪辑前后的帧）、 qa/beats.png（每个字幕块）、qa/report.txt（剪辑到语音的间隙、响度）。 检查：弹出部分在剪辑后无光晕或偏移；卡片显示头部和肩膀（绝无面部裁剪）；无字幕或图形在面部上； 字幕与单词匹配；每行剪切在语音前0-80毫秒内落下；无任何内容在Instagram禁止区域中。然后 PY "SK/scripts/audiomap.py" "WORK" --out progress/NN-audio-map.png：音乐低于语音18-24 dB， 音效低于其局部峰值约10-16 dB，无双重击打；修复任何标记的提示，添加 "db": -3。 风格匹配： PY "SK/scripts/match/fingerprint.py" score "SK/references/style-spec.json" "WORK/renders/draft.mp4" --out "WORK/progress/NN-style-match.md" 以与3个 Kallaway Reels相同的方式测量编辑（剪切率、每秒视觉变化数、布局占比、卡片和字幕 位置、字幕大小和节奏、强调色占比、响度、立体声音效），并对每个FAIL项说明要修复的内容。 修复编辑可控制的部分；由素材引起的FAIL（例如近距离自拍）作为拍摄建议告知用户。 WORK/progress/ 中的报告是记录文件（SK/references/lock-log.md 保存风格的历史测量值； 保持其不变）。 修复并重新渲染（重建 + 重新渲染约需1.5分钟）。

7. 交付

PY "SK/scripts/render.py" "WORK" --final -> exports/<slug>-kallaway-vN.mp4（1080x1920）以及 -720p.mp4 手机版副本。在导出版本上运行 qa.py。如果用户在 ROOT/references/ 中保存了 自己的Kallaway Reels（此技能不附带任何示例），则添加并排对比（--ref <那个Reel> --ref-at <t> --at <t>） 并保存为 progress/NN-side-by-side.png。 告知用户：文件位置、时长、场景内容逐场景说明，以及哪些地方仍然看起来不像Kallaway 风格（具体且诚实）。

时间估算（在M4 Pro Mac上，从约8分钟原始素材制作35秒Reels）

设置5分钟（首次）· 查找镜头7分钟（中等模型；--fast 约3分钟）· 剪辑1分钟 · 去除背景3.5分钟 · 音乐2-6分钟（后台运行；Openverse/Freesound可能较慢）· 场景15-25分钟 · 草稿渲染50秒 · 最终渲染70秒 · 编辑后重新渲染约1.5分钟。

拍摄

将 references/filming-guide.md 提供给即将拍摄的人：固定广角镜头（水平4K最佳）、 暗室中暖色主光、深色上衣、头部后方纯色背景、重复一句台词直到说好。