Seagey/edit-reel

编辑一条短视频 (Reel)

一切都在用户自己的 Mac 上运行。无需付费服务。完成工作的脚本是仓库根目录下的 scripts/edit.sh，它会调用此文件旁的 scripts/edit_reel.py。

用户不懂技术。请使用简单的普通话陈述句，短句，避免术语。执行前告知将要做什么，执行后汇报结果。永远不要使用破折号。

目录

• 快速路径
• 获取视频
• 一次编辑完成什么
• 用户可以要求更改的设置
• 交给用户前的检查
• 向用户汇报结果
• 可能出现的错误
• 硬性规则

快速路径

1. 检查环境是否配置完成：scripts/setup.sh --check。如果显示 NOT READY，请遵循 CLAUDE.md（入门指南），不要自行安装。
2. 获取视频（见下文），然后运行：
   • 单个命名文件：scripts/edit.sh "<视频路径>"
   • Inbox 文件夹中最新的 N 个：scripts/edit.sh --latest 3
3. 执行下面的检查，查看图片，阅读字幕，然后汇报。

在 Apple 芯片 Mac 上，30 到 60 秒的片段大约需要一到两分钟，旧款 Mac 则更久。

获取视频

按以下顺序，使用第一个成功的方法：

1. 用户命名或拖拽的文件。 原地使用。永远不要移动或删除用户的原始文件。
2. Inbox 文件夹。 用户通过 AirDrop 发送或拖入 Inbox/（仓库文件夹内）的任何内容。
3. iCloud 照片库。 仅当 iCloud 已配置（docs/ICLOUD.md）。用户的 Apple ID 邮箱在 config.json 的 icloud_apple_id 字段中。运行 scripts/icloud-fetch.sh <apple id> 30。
   • 成功时输出 ICLOUD_FETCH_OK。最新视频会被放入 Inbox/。
   • 登录过期（大约持续两个月）或从未登录时输出 ICLOUD_FETCH_FAILED。不要自行尝试修复：告知用户，并指导他们按照 docs/ICLOUD.md 的“重新登录”步骤操作。用户在自己电脑的终端中输入密码和六位验证码，永远不要在聊天中发送。
   • “最新”指最近拍摄的视频。刚拍摄的视频可能需要几分钟才能同步到 iCloud，如果用户提到的视频未出现，请告知用户并建议一分钟后再试。
   • 在编辑前，列出最新视频及其长度（使用 ffprobe 查看时长），如有疑问，请确认用户指的是哪一个。
4. 均无效。 提供备用方案：用户通过 AirDrop 将视频发送到 Mac，或拖入 Inbox 文件夹。

一次编辑完成什么

按顺序：

1. 根据声音进行剪切。 通过音频响度而非字幕时间（片段开头的语音转文字时间可能位于静音内部，隐藏无声部分）来确定语音真正开始和结束的位置。修剪开头和结尾的静音，缩短长停顿。剪切点放在附近最安静的时刻，每个接缝处有 15 毫秒的淡入淡出，因此不会剪掉任何词语。句子保持完整；仅删除无声部分。
2. 镜像检查。 前置摄像头拍摄的片段通常是镜像的。通过 OCR 读取帧内文字（标志、屏幕、衬衫）的正常和翻转版本，仅当翻转后能正确读取真实词语时才翻转视频。绝不通过肉眼判断。如果没有可读文字，则保持视频不变，并在报告中说明。
3. 裁剪为 9:16 并缩放至 1080×1920（横屏片段裁剪中间部分）。
4. 调色。 测量几帧画面，应用轻微的曝光、对比度和饱和度校正，设置上限以防止过度处理，并输出调色前后对比图。HDR iPhone 片段会先映射到标准色彩。
5. 录音室级音质。 降噪、人声均衡器、齿音消除器、压缩器、限制器，最终响度标准化至 -14 LUFS。此设定经过测量调校。以耳朵感受为准：如果听起来刺耳、单薄或处理过度，将 audio.strength 设为 light。
6. 字幕。 转录处理后的音频，然后使用 Pillow 绘制字幕。字幕位于手机安全区域内（在 1080×1920 帧上为 x 90 至 960，y 250 至 1520），以免被按钮或应用自身文字遮挡。当前活跃单词会变色。轮廓保持深色。单词背后无彩色背景框，因为背景框在人脸上会显得模糊。
7. 输出。 Edited/<原名>-edited.mp4，以及 Edited/checks/<原名>/ 目录下的：contact-sheet.jpg、colour-before-after.jpg、caption-frame.png、captions-words.txt、report.json。

用户可以要求更改的设置

所有设置均在仓库根目录的 config.json 中（由 config.default.json 创建，后者永不修改）。用户从不直接编辑文件。他们用自然语言提出要求，你进行修改，重新运行编辑并展示结果。设置与词语的完整对照表：docs/STYLE.md。

示例：

• “把字幕改成黄色” 设置 captions.highlight_color（当前词）或 captions.color（所有词）。如果不明确，请询问用户。
• “字幕变大” 将 captions.size 提高约 12（默认值 78）。确保结果仍在安全区域内：脚本会报告 inside_safe_zone。
• “把字幕往上移” 将 captions.position 设置为 middle 或 upper。
• “一次一个字” 将 captions.style 设置为 word。“一行字” 则改回 line。
• “不要字幕” 将 captions.enabled 设为 false。
• “少一点调色” 将 grade.strength 降低 0.2。“不要调色” 将 grade.enabled 设为 false。
• “剪得更紧凑” 将 cuts.tightness 设为 tight。“留更多呼吸空间”：gentle。
• “声音处理过度了”：将 audio.strength 设为 light。
• “靠近我的脸一点”：framing.zoom 设为 1.15（最大合理值 1.4）。
• 字幕中名字拼写错误：将其添加到 vocabulary（帮助听写器正确识别），如果仍然错误，则添加到 replacements 中，格式为 {"听到的": "正确拼写"}。

更改后，对同一视频重新运行编辑，并展示新的结果。使用 Edited/ 中的文件；重新运行会替换之前同名编辑的结果。

交给用户前的检查

脚本会输出摘要并写入 report.json。你仍需检查。

1. 数据。 loudness_ok、start_ok、end_ok 应均为 true。开头静音应 ≤ 0.45 秒，结尾静音应 ≤ 0.75 秒。如果不满足，请告知用户并使用 --tightness tight 重新运行。
2. 查看图片（使用 Read 工具）：contact-sheet.jpg（人脸是否在画面内，画面是否自然，字幕是否在屏幕内）、colour-before-after.jpg（左侧为原始画面，右侧为调色后：肤色自然，不偏橙或灰，白色不过曝，黑色不丢失细节）以及 caption-frame.png（放大查看每一个字，检查每个字在背景上是否可读）。
3. 阅读字幕。 打开 captions-words.txt。语音转文字可能会听错姓名和本地词汇（例如品牌名）。使用 vocabulary 和 replacements 修正，然后重新运行。检查报告中的 caption_vs_sound_match：低于 0.9 表示有问题，请调查。
4. 镜像。 查看 report.json 中的 mirror。如果 decision 为 unknown 且画面中有文字（标志、屏幕），请查看一帧画面并检查文字是否可读。如果文字是反的，将 framing.mirror_fix 设为 always 并重新运行。
5. 根据声音判断无声部分。 脚本会在最终混音上运行 silencedetect。不要依赖字幕时间来判断。

你无法监听。请如实告知：声音已调校和测量，但最终由用户的耳朵决定。

向用户汇报结果

简短、通俗，格式如下：

• 文件位置，以及如何打开（Finder，Reel 编辑器文件夹内的 Edited 文件夹）。
• 剪掉了什么（“开头去掉了 1.1 秒的静音，缩短了两个长停顿，从 36 秒缩短到 33 秒”）。
• 画面是否翻转以及原因。
• 现在声音的测量值（“大约 -14，Instagram 和 TikTok 的常用音量级别”）。
• 字幕：字体、颜色、修改过的任何词语。
• 任何你无法解决的问题，以及用户可以如何要求更改。

然后询问用户想要修改什么，并从上面的设置列表中提供一两个建议。

可能出现的错误

• “未检测到语音”：片段无声音或只有音乐。告知用户。
• 字幕位置不对或被裁剪：检查报告中的 inside_safe_zone；降低 size。
• 未找到字体：脚本回退到 Arial Black 并输出提示。提供内置字体之一（docs/STYLE.md），或从 fonts.google.com 下载免费字体（.ttf 文件）放入 ~/.reel-editor/fonts/，并将 captions.font 设置为不带 .ttf 的文件名。
• 缺少配置工具：运行 scripts/setup.sh。如果缺少 Homebrew，请遵循 CLAUDE.md。
• 编辑耗时过长：超过 3 分钟的 4K 片段会占用大量资源。告知用户并让其等待运行完成。

硬性规则

• 永远不要删除或修改用户的原始视频。
• 永远不要在聊天中索要或接受密码或六位验证码。
• 禁止付费服务，禁止将用户视频上传到任何地方。除 iCloud 下载外，所有操作均在此 Mac 上完成。
• 禁止添加滚动提示或“关注我”等覆盖层，除非用户明确要求。
• 不添加用户未说过的内容：字幕仅显示实际说出的内容。