用 Claude Code 剪口播视频：完整工具包

我要在这台 Mac（Apple 芯片）上搭建一套“AI 口播视频剪辑”的工作环境。请帮我逐项安装并检查下面这些工具。每一项都先检查是否已经装好；没装才安装。遇到下载超过 100MB 的东西，先告诉我文件名、来源和大小，等我同意再下载。

1. Homebrew（如果没有，按 https://brew.sh 的官方命令安装）
2. Xcode Command Line Tools：xcode-select --install（需要 git 和 swift）
3. FFmpeg：brew install ffmpeg
4. Node.js：brew install node
5. uv：brew install uv
6. Python 套件：pip3 install pillow mlx-whisper faster-whisper
7. 在 ~/video-studio/_build 建一个项目文件夹，执行 npm init -y、npm i playwright、npx playwright install chromium
8. 确认 swift 可以调用 Apple Vision：写一个最小的 swift 脚本，对一张测试图片执行 VNRecognizeTextRequest，确认能输出文字

全部完成后，给我一张检查表：工具名称、版本号、是否正常。有任何一项失败，说明原因和解决方法，不要跳过。

环境装好了，现在帮我准备剪辑要用的免费素材。下载前先告诉我来源、授权和大小，等我同意再下载。

1. 音效（都是 CC0，可以商用、不用署名）：
   - 在 ~/ai-tools/sfx 里 git clone https://github.com/Calinou/kenney-interface-sounds.git
   - 在 ~/ai-tools/sfx/elements 里，用 curl 从 https://tryelements.dev/sfx/<名称>.mp3 下载这 17 个：boom click drone error glitch keyboard magic-reveal notification pop reverse-whoosh riser shutter success swoosh whoosh whoosh-alt1 whoosh-alt2。下载后用 ffprobe 确认每个都能读取。
2. 背景音乐生成器 ACE-Step 1.5（MIT 授权，可以商用）：
   - git clone https://github.com/ACE-Step/ACE-Step-1.5.git 到 ~/ai-tools，然后 uv sync
   - 用 macOS 的 API 启动脚本（start_api_server_macos.sh，端口 8001）把服务开起来。第一次启动会下载 10–17GB 的模型，先跟我确认。
   - 照官方 API 文档（docs/en/API.md）生成一段 30 秒的测试配乐：科技感电子乐、纯音乐、适合口播当背景。音频复制到 ~/ai-tools/test-bgm.wav，再告诉我它的响度（LUFS）。
3. 转写模型：用 mlx-whisper 加载 mlx-community/whisper-large-v3-turbo，对任意一段中文音频跑一次，让模型下载并缓存好。

最后列出：每样素材放在哪个文件夹、授权是什么、占多少空间。

我要剪一支口播视频，素材在：【填你的视频文件夹路径】
我的官网是：【填你的网址】，请参考它的配色和科技感。
动画灵感请到 https://prompt-motion.com/ 找适合这支内容的作品。

如果项目文件夹里有 剪辑SOP.md，先读它，照里面的规则做。
请按这个流程来，每一步都等我确认再往下：
1. 先看懂内容：用环境里装好的转写工具（Mac 用 mlx-whisper，Windows 用 faster-whisper，模型都选 large-v3-turbo）转写，读完整篇讲稿；用 ffprobe 看清素材规格，每隔几秒抽一帧拼成一张图看画面结构。
2. 再去 prompt-motion.com 和 GitHub 找这支视频可以用的新工具、新动画手法，提出 1–3 个具体的“本期突破点”。
3. 写出剪辑方案：怎么剪（去停顿、删重复句）、每一句配什么动画（落在具体的词上）、字幕样式、成片比例（默认 1080×1920）、配乐和音效。视频里提到的产品或平台，请先跟我要官方 Logo。
4. 我确认后，先做 10 秒左右的样片：
   - 用 HTML 写动画，用 Playwright 逐帧截成透明 PNG，再用 FFmpeg 叠到视频上
   - 背景音乐用 ACE-Step 生成 A/B 两版；音效用 ~/ai-tools/sfx 里的 CC0 音效
   - 背景音乐要比人声低约 15 LU：听得到，但不抢人声
5. 样片确认后再出完整版，最后做封面。
6. 每一步交付前，你自己先拼截图检查画面、测量响度，再告诉我你检查了什么。
7. 进入渲染、合成这类机械性步骤前，先停下来提醒我把模型切换到 Sonnet，可以省额度；需要做设计判断时，再提醒我切回 Opus。

画面上不要放公司 Logo 和水印（小红书会限流）。所有剪辑点和每段长度都要对齐到整数帧，避免动画和画面错位。

我要在这台 Windows 电脑上搭建一套“AI 口播视频剪辑”的工作环境。请用 PowerShell 和 winget 帮我逐项安装并检查。每一项都先检查是否已经装好；没装才安装。遇到下载超过 100MB 的东西，先告诉我文件名、来源和大小，等我同意再下载。

0. 先检查这台电脑有没有 NVIDIA 显卡，有的话显存多大（nvidia-smi），告诉我结果，后面的安装会根据这个调整。
1. Git for Windows：winget install Git.Git
2. FFmpeg：winget install Gyan.FFmpeg
3. Node.js：winget install OpenJS.NodeJS.LTS
4. Python 3.12：winget install Python.Python.3.12
5. uv：winget install astral-sh.uv
6. Python 套件：pip install pillow faster-whisper rapidocr onnxruntime mediapipe
   - 有 NVIDIA 显卡：照 faster-whisper 官方 README 的 Windows 说明，放好 CUDA 12 的 cuBLAS 和 cuDNN 9 库，确认 faster-whisper 能用 device="cuda"
7. 在 C:\video-studio\_build 建一个项目文件夹，执行 npm init -y、npm i playwright、npx playwright install chromium
8. 分别做一次最小测试：
   - RapidOCR：识别一张有中英文字的截图，输出文字和位置
   - MediaPipe：对一张人像照片做人像分割，输出黑白遮罩图
   - faster-whisper：用 turbo 模型转写一小段中文音频，输出每个字的时间点

装好新软件后，如果命令找不到，提醒我重开 PowerShell 再继续。
全部完成后，给我一张检查表：工具名称、版本号、是否正常、用的是 GPU 还是 CPU。有任何一项失败，说明原因和解决方法，不要跳过。

环境装好了，现在帮我准备剪辑要用的免费素材。下载前先告诉我来源、授权和大小，等我同意再下载。

1. 音效（都是 CC0，可以商用、不用署名）：
   - 在 C:\ai-tools\sfx 里 git clone https://github.com/Calinou/kenney-interface-sounds.git
   - 在 C:\ai-tools\sfx\elements 里，从 https://tryelements.dev/sfx/<名称>.mp3 下载这 17 个：boom click drone error glitch keyboard magic-reveal notification pop reverse-whoosh riser shutter success swoosh whoosh whoosh-alt1 whoosh-alt2。下载后用 ffprobe 确认每个都能读取。
2. 背景音乐：
   - 如果有 NVIDIA 显卡（6GB 显存以上）：git clone https://github.com/ACE-Step/ACE-Step-1.5.git 到 C:\ai-tools，按官方 README 的 Windows 说明安装（或用官方便携包），执行 start_api_server.bat 启动 API。第一次会下载 10GB 以上的模型，先跟我确认。然后照 docs/en/API.md 生成一段 30 秒的测试配乐：科技感电子乐、纯音乐、适合口播当背景。
   - 如果没有 NVIDIA 显卡：先不要装 ACE-Step。帮我找 2–3 个可以商用的免版税或 CC0 音乐来源，列出每个来源的授权条款重点，等我决定。
3. 转写模型：用 faster-whisper 加载 turbo 模型，对任意一段中文音频跑一次，让模型下载并缓存好。

最后列出：每样素材放在哪个文件夹、授权是什么、占多少空间。

# 口播视频剪辑 SOP（学员版）

> 使用方法：把这份文件存成 `剪辑SOP.md`，放进你的项目文件夹。每次开工时告诉 Claude Code：「先读 剪辑SOP.md，照着做」。
> 这份 SOP 整理自 WINS AI CLASS EP.29–31 的实际剪辑过程（v1.6），Mac 和 Windows 都适用。
> 每做完一支视频，请 Claude Code 在文末「迭代记录」补一行，并把新学到的做法改进正文。

---

## 0. 总原则

> **最高原则：每一支都要进步一点、突破一点。**
> 这份 SOP 是底线，不是天花板。每支视频开工前都要先看懂内容，再去网上找新工具、新风格、新动画手法，想清楚「这一支比上一支强在哪里」。

1. **先出方案，确认后才动手。** 顺序固定：剪辑方案 → 样片（约 10 秒）→ 完整版 → 封面。每一步都等我确认再往下。
2. **缺资源不要停下。** 缺音乐、音效、素材或工具时，先去网上和 GitHub 找免费或开源的方案，列出具体文件、授权和大小让我挑。
3. **下载要先征得同意。** 列清楚文件名、来源、大小和授权，我同意后才下载。
4. **不碰任何密钥和密码。** 不读取、不打印任何 API Key 或密码。
5. **省用量：每支视频开一个新对话。** 不要把多支视频接在同一个对话里做。对话越长，每一步要重新读取的内容越多，额度消耗会大好几倍。
6. **省用量：进入机械性步骤前，先停下来提醒我切换到 Sonnet**（见第 4 节）。
7. **交付前自己先检查。** 用截图拼图检查画面，用响度测量检查音频。没检查过的不能说「完成」。音乐好不好听要我本人判断，要明说。

---

## 1. 开工前先确认（第一次回复就问清楚）

| 项目 | 说明 |
|---|---|
| 成片比例 | 竖屏默认 1080×1920 |
| 发布平台 | 小红书等平台：封面和视频都**不放公司 Logo 和水印**（会被限流） |
| 背景音乐 | 本机生成原创配乐，一次出 A/B 两版让我选 |
| 片尾 | 要不要片尾、要不要“下一支”提示 |
| 重复或口误的句子 | 列出来，建议删掉，由我确认 |
| 视频里提到的产品或平台 | **先跟我要官方 Logo**，不要用自己画的占位图标 |
| 系列标签 | 我的系列名称和期数（例如「XXX · EP.01」），开场和封面都用 |
| 封面文案 | 主标题加一句副标题，由你提议、我确认 |

---

## 2. 品牌视觉规范

- 先读取我的官网：【填你的网址】，提取配色、字体和整体风格，写成一组颜色和字体变量，之后所有动画、字幕、封面都从这组变量来。
- 字幕：放在画面中不挡脸的位置，深色半透明底，逐字弹出，重点词用主色高亮。
- 中文字体：Mac 用苹方；Windows 没有苹方，要明确指定 Noto Sans SC（Google Fonts）。
- 禁止：公司 Logo 和水印。

---

## 3. 环境与工具

| 用途 | Mac | Windows |
|---|---|---|
| 剪辑、合成、混音、测响度 | FFmpeg | FFmpeg |
| 动画渲染（HTML 逐帧截成透明 PNG） | Node.js + Playwright | Node.js + Playwright |
| 中文转写（含每个字的时间点） | mlx-whisper + large-v3-turbo | faster-whisper + turbo |
| 屏幕文字识别（标注跟着画面走） | Apple Vision（swift 调用） | RapidOCR |
| 人像抠图（文字出现在人物身后） | Apple Vision（swift 调用） | MediaPipe 或 rembg |
| 背景音乐 | ACE-Step 1.5 | ACE-Step 1.5（建议 NVIDIA 显卡） |
| 音效 | Kenney Interface Sounds、Elements（CC0） | 同左 |
| 动画灵感 | prompt-motion.com | 同左 |

把各个功能写成**可以重复使用的小脚本**，放在项目的 `_build/` 文件夹，例如：转写、找停顿、字幕初稿、逐帧渲染、合成、静帧检查、封面截图。下一支视频直接复制 `_build/` 当起点。

---

## 4. 流程

### Step 0 — 先看懂内容，再找突破点（必做）
1. **看懂内容**：转写后读完整篇讲稿，弄清核心观点、哪几句最值得用画面强调、观众看完要记住什么。
2. **全网找新东西**（每支都要重新找）：
   - prompt-motion.com：按动态文字、示意图、图表、粒子、产品界面等分类，找适合这支内容的动画手法，记下作品链接。
   - GitHub：找新的开源工具（动画、字幕、配乐、音效、抠像、追踪、3D 等），确认授权可以商用。
3. **定出 1–3 个「本期突破点」**，写在方案最前面。要具体、做得出来、服务内容，并说明比上一支好在哪里。新工具先做小测试，不行就退回原做法，不能影响交付。

### Step 1 — 分析素材
- 用 ffprobe 看分辨率、帧率、时长。**手机素材常是可变帧率**，合成时一定要统一成 30fps。
- 每 3–5 秒抽一帧拼成一张图，看清画面结构（例如上半是屏幕、下半是人）。分界线用程序算出来，不要凭眼睛估。

### Step 2 — 转写
- 用最准的模型（large-v3-turbo），在提示词里加上这支视频的专有名词（产品名、英文术语）。
- **同音字要按上下文判断**（例如「简介」其实是「剪辑」）。两个模型都听错的地方，交付时请我确认。
- 每句最后一个字的时长常被拉长，剪辑出点要按实际停顿判断。

### Step 3 — 剪辑方案（交给我确认）
- 开头先写「本期突破点」，附上参考链接。
- 删掉句间停顿（保留 0.05–0.1 秒），停顿小于约 0.45 秒的就保留，避免跳剪太多。
- 找出意思重复的句子，建议删掉。
- 列一张动画表：时间 / 原话 / 动画。**每个动画都要落在具体的词上。**
- 列出需要我决定的事（见第 1 节）。

### Step 4 — 剪辑时间轴
- ⚠️ **每段的入点和长度都要对齐到整数帧**（30fps 就是 1/30 秒的倍数），合成时强制每段的精确帧数。否则很多段累积下来，画面和动画会错位。
- 每段剪辑在「正常」和「推近约 10%」之间轮流切换，用来掩盖跳剪。
- 字幕和动画时间都按**素材原始时间**记录，由程序自动换算成成片时间。改了剪辑点，动画会自动对齐。

### Step 5 — 写动画
- 动画用 HTML 写，每一帧由 `seek(t)` 画出；同一个时间点永远画出同一帧，随机数要用固定种子。
- 每个场景先判断时间范围，范围外直接隐藏；所有「某个时刻才出现」的元素，CSS 默认 `opacity: 0`。
- 每个场景的 CSS 类名要有专属前缀，避免互相覆盖。
- **任何文字都不能宽于画面减去两侧留白**（1080 宽的画面，文字不超过约 1000px）；入场放大的最大倍数不超过 1.35。
- **分层合成**，从下到上：原视频 → 背景层（放在人物身后的大字和背景）→ 抠出的人像 → 画中画 → 前景层（字幕、标注）。
- 想让文字出现在人物身后，人物头顶要有空间：头顶贴着画面边缘时，把人缩小成半身像（边缘自动淡出），背景层铺一块不透明的品牌背景。
- 画中画（真实的视频、截图）要从第 0 秒开始补透明帧，否则会跟其他层对不上。
- 画面上重现的对话、报告，**每一句都要用原话，不编造**。
- 超过 1 分钟的长视频：加顶部进度条和章节卡片（每 30–40 秒一章）；每 5–8 秒至少要有一个新的视觉变化。

### Step 6 — 先做静帧检查（最省时间的一步）
- 先挑 7–14 个关键时刻，各渲染一帧，叠到视频上拼成一张图检查，再决定要不要整片渲染。
- 重点看：文字有没有超出画面、有没有折行、有没有元素没出现或一直挡着画面、颜色和字体对不对。

### 🔁 模型切换提醒（每支必做）
设计和判断用 **Opus**；跑命令、等渲染这类机械性工作用 **Sonnet**（消耗的额度大约是 Opus 的五分之一）。

| 阶段 | 模型 |
|---|---|
| Step 0–6：看内容、找工具、写方案、写动画、静帧检查 | Opus |
| **Step 7–8：渲染、合成、测响度、抽帧检查** | **Sonnet** |
| 检查后要大改设计 | 换回 Opus |
| Step 9：封面（挑帧、排版） | Opus |

静帧检查确认、准备开始渲染时，先**停下来**单独提醒我：
> 「接下来是渲染和合成这类机械性步骤，建议在模型选单切换到 Sonnet 再继续，可以省大约 4/5 的额度。切换好后跟我说一声。」

我切换后再继续；需要做设计判断时，也提醒我切回 Opus。

### Step 7 — 样片（约 10 秒）
- 只渲染前几段。有两首备选配乐时出 A/B 两版，画面相同，只换音乐。

### Step 8 — 完整版
- 交付前把全片每隔几秒抽一帧拼成一张图检查，并核对：底片总帧数 = 时间轴总帧数。
- 整体响度约 **-15 LUFS**，峰值不超过 -1 dBFS。
- 中间文件（逐帧图片、底片）存在项目的 `_build/cache/`，不要放系统临时文件夹（会被清掉）。确认成片不再修改后，再删除 cache 释放空间。
- 只交付完整版。我需要压缩版时会说。

### Step 9 — 封面（1080×1920）
- 固定元素：系列标签、大字主标题、一句副标题、带发光边框的照片框、视频里提到的产品 Logo（斜着压在照片框边上）、底部一句金句（最好取自我在视频里说的话）。不放公司 Logo。
- 照片：先拼一张候选帧图，挑**眼睛睁开、表情对题**的一帧。
- 抠像做法：把人抠出来，照片框里从下到上依次是品牌背景 → 网格 → 巨大的描边关键词（2–4 个字）→ 人像。人像的头要压住关键词的下半部分，形成景深。人离镜头远就把人像放大（最多原尺寸 1:1）。
- **画面只缩小、不放大**，放大会糊。
- 检查：标题不超出画面、Logo 不盖住脸、标签不超出画面；交付前打开成品看一眼。

---

## 5. 音效规则

- 每个动画配一个音效，触发点按素材原始时间记录。
- 常用对应：开场用 glitch；标题定格用 boom；转场用 whoosh 系列；卡片飞入用 whoosh-alt；揭晓用 magic-reveal 加 confirmation；终端打字用 keyboard；完成用 success；节点出现用 drop；进度和等级用 tick。
- 音量参考：转场 0.35–0.55、界面音效 0.4–0.5、打字约 0.15–0.18、环境底噪约 0.15–0.2。

---

## 6. 背景音乐（ACE-Step）

1. 启动 ACE-Step 的 API 服务（Mac：`start_api_server_macos.sh`；Windows：`start_api_server.bat`），第一次会下载 10GB 以上的模型。
2. 用文字描述风格，例如：科技感电子乐、纯音乐、给口播留空间；一次生成 A/B 两版。
3. 生成的文件要复制到项目的 `_build/music/`，不然会被清掉。
4. 曲子开头常有一段安静的铺垫：用起点偏移让鼓点刚好落在开场结束的那一刻。
5. 长视频可以用段落标记（Intro / Build / Drop / Breakdown / Outro）一次生成分段配乐，再把高潮对准最重要的那一章。
6. **混音标准**：说话时音乐自动压低（压低比例约 3）。交付前单独测量：音乐要比人声低**约 15 LU**。低超过 18 LU 就会几乎听不到，每首曲子都要实测后调整音量。

---

## 7. 常见的坑

| 坑 | 解决方法 |
|---|---|
| 找不到音乐就停下 | 主动找开源和 CC0 资源，或用 ACE-Step 生成 |
| 专有名词被听错（Claude → Cloud） | 转写提示词加入专有名词，并人工校对 |
| 字幕放在白墙上看不清 | 加深色半透明底 |
| 文字、卡片超出画面或折行 | 文字宽度设上限，加 `nowrap` |
| 用了占位图标 | 开工前先要官方 Logo |
| 封面放大后发糊、选到眨眼帧 | 挑候选帧，只缩小不放大 |
| 放了公司 Logo、水印 | 一律不放 |
| CSS 类名撞名，元素尺寸被覆盖 | 每个场景的类名加专属前缀 |
| 闪光之类的元素默认全亮，整片发白 | 默认 `opacity: 0` |
| 很多段累积帧数误差，接缝处画面错位 | 入点和长度对齐整数帧，并核对总帧数 |
| 画中画从中途才开始，时间被打乱 | 从第 0 秒补透明帧 |
| 场景交接时露出原始画面 | 背景层持续铺底 |
| 背景音乐压得太狠，听不到 | 比人声低约 15 LU，每首实测 |
| 中间文件放在临时文件夹被清掉 | 存在项目的 `_build/cache/` |
| 多支视频接在同一个对话里做，额度消耗很快 | 每支视频开新对话 |

---

## 8. 交付清单

- [ ] 完整版视频：1080×1920，30fps，H.264，约 -15 LUFS
- [ ] 封面：1080×1920，没有公司 Logo
- [ ] `_build/` 工程留着，方便之后修改
- [ ] 渲染、合成前，已提醒切换到 Sonnet
- [ ] 回报里写清楚：本期突破点有没有做到、检查了什么、哪些要我亲自确认（例如音乐听感）

---

## 迭代记录

每支做完都补一行，并把新学到的做法改进正文、删掉过时的做法。

| 日期 | 视频 | 本期突破 | 变更 / 教训 |
|---|---|---|---|
| | | | |