视频剪辑巧匠
把真人出镜的口播视频，剪成一条能直接发的竖屏短视频（抖音 / 视频号 / 小红书）。
一、这个技能是干嘛的
一句话：你负责说，我负责剪。
你把「对着镜头说话的视频」和「要展示的素材」放进一个文件夹，这个技能帮你把它们拼成一条成品视频——包括切气口、提速、降噪、提音量、加字幕、排版、脱敏、导出，全程不用你懂剪辑。
它不做的事：写脚本、写文案、写口播稿（那是另一个技能的活）。这个技能假设你已经拍好了、录好了。
二、⚠️ 第一次用，先看这里（两条都要看）
2.1 需要装什么（一次性，约 2 分钟）
| 环境 | 步骤 |
|---|---|
| 都要装 | Python 3.8 以上，然后执行 pip install imageio-ffmpeg（自动带一个免安装的 ffmpeg） |
| Mac 用户 | 无需额外操作（系统自带 avconvert，处理特殊素材时用到） |
| Windows 用户 | 无需额外操作；若遇到个别手机拍的视频读不出来，用「剪映」重新导出一次即可（见技术手册） |
> 装完就不用再管了，后面全靠这个技能自己跑。
2.2 需要准备什么素材（放进一个文件夹）
新建一个项目文件夹，按下面结构放素材：
你的项目文件夹/
├── 01_口播视频/ ← 你对着镜头说话的视频（最重要，必须有一条）
├── 02_屏幕素材/ ← 你要展示的东西：录屏、截图（知识库、工具界面、文档）
├── 03_AI生成素材/ ← 空着也行，缺画面时我会生成
├── 04_字卡与后期/ ← 空着也行，字卡我会出
└── 05_成片/ ← 剪好的成品放这里（我自动建）
最少要有：01_口播视频/ 里的一条口播视频（手机竖屏 9:16 拍的就行）。
详细准备清单和拍摄建议 → 看 references/素材准备引导.md。
2.3 缺素材了会怎样
我不会卡住，也不会瞎编。缺什么我会主动告诉你，并给你替代方案：
| 缺什么 | 我会怎么说 |
|---|---|
| 缺口播视频 | 「需要一段你真人出镜、对着镜头说话的视频（手机竖屏拍就行）。实在没有，先把要讲的内容写下来发我，我帮你把结构理出来再拍。」 |
| 缺屏幕素材 | 「这一步要展示你的知识库/工具界面，麻烦录一段屏幕（5-8 秒）：打开它，鼠标上下滚一下就行。」 |
| 缺某个画面 | 「这一步的画面你没有提供，我可以用①上一段画面延长盖过去，②生成一张替代图，你选哪个？」 |
| 缺字卡 | 不需要你提供，我自动生成。 |
原则：缺什么先问，不硬凑、不瞎猜。
三、核心红线（不可违抗）
- 声画同步是最高铁律：说的内容必须和画面一致，说什么画面放什么，一个字都不许错位。
- 四模式版式：每个镜位先定模式再剪，不是一种版式用到底（见第四节）。
- 语速 5-6 字/秒：不是固定倍数，实测母带语速后反推。
- 字幕以实际口播为准：逐字稿可能和嘴巴说的对不上，错字、口误在预案阶段标出来让用户改。
- 口癖词必须掐：嗯、啊、呃、就是、然后 这类口头禅，和气口一起处理。
- 脱敏是红线：画面里的人名、手机号、客户名必须打码。
- 先预案、后剪辑：素材和字幕没确认之前不动剪刀。
- 不加花式转场：全片硬切，节奏靠内容变化撑，不靠特效。
四、四模式版式体系（核心）
每个镜位先判定模式，再套对应版式。同一片子里模式可以切换。
| 模式 | 触发条件 | 画面 |
|---|---|---|
| 全屏·人 | 纯口播，没有内容要衬托 | 人满屏 |
| 全屏·内容 | 展示知识库/智能体/流程图/字卡，不需要人出镜 | 内容满屏 |
| 对半 | 人和内容都要，内容需要展示面积 | 上内容 / 下 人 |
| 横版 | 内容为主，但要保留人的存在感 | 内容满屏 + 人右上角小窗 |
横版小窗：放右上角，面积占全屏的 1/6 ~ 1/9（典型 1/8），比「画中画」稍大，要有存在感。
判断口诀：这段需不需要人脸？不需要 → 全屏·内容；需要 → 内容占不占地方？占 → 对半/横版，不占 → 全屏·人。
典型映射：钩子/反转/立场/提问/收尾 → 全屏·人；展示知识库/智能体/图谱/流程图/字卡 → 全屏·内容（或横版）；边讲边展示文档 → 对半（或横版）。
五、工作流（六步）
第 1 步：素材盘点
扫项目目录，摸清有什么，生成素材清单，标出缺口。
- 重命名规范：镜号_用途_内容_规格.后缀
- 缺的素材：按「2.3 缺素材引导」主动问，或跳过（延长前一段），不硬凑。
第 2 步：分析口播母带
- 抽帧看画面（人脸位置、构图）
- 检测气口、实测语速 → 反推倍速到 5-6 字/秒
⚠️ 语速的分母是「有效说话时长」（总时长 − 静音），不是总时长。 拿总时长当分母会
把静音算进去，低估 15~20%，误判成"语速偏低需要提速"。（实例：68.05s 母带含 12.76s 静音，
按总时长算是 4.36 字/秒，按有效说话 55.30s 算是 5.37 字/秒——后者才是真的，本来就达标。） - 语音识别出逐字稿（词级时间码），和稿件逐句比对：错字、口误、漏句全部标出，
明显同音错按稿件改，两可的标「待确认」交用户拍板 - 记录每个时点的头顶位置 → 定下半区裁切窗口起点
⚠️ 裁切窗口要按全片头顶位置最高的那一帧来定，不能按平均值。否则那个瞬间会切到头发。
定完抽 1~2 张极端帧（人离镜头最近/最远的那一帧）验证一遍。
第 3 步：出可视化剪辑预案（HTML）
可交互的 HTML（见第六节），能看、能批注、能选、能填。
第 4 步：交互确认
用户在 HTML 里改字幕、勾人名、切模式、选语速、写批注，回流给我，逐项确认后再动手。
第 5 步：⭐ 先跑样片，再批量剪
别一次把全部镜位跑完——取段/对齐/音量三处最容易出错，全跑完再发现问题就是 ×N 返工。
- 先只跑 第 1 镜 + 一段带素材的镜位（共 3~5 秒）
- 抽帧 +
volumedetect双检：版式、字幕位置、素材取段、人脸完整、峰值不削波 - 全对 → 再批量跑全部镜位
第 6 步：剪辑成片
按确认后的预案，用 ffmpeg 实际剪出来，交付 05_成片/。中间产物留 05_成片/_work/，方便改参数重跑。
> 两条硬性工程要求（不做必踩）：
> - 镜位边界量化到帧（round(t*fps)），否则逐段整帧取整会累积漂移
> - 字幕在最终合成阶段按绝对时间统一烧，不要逐段烧
> 详见 references/剪辑技术手册.md 第十三节。
六、可视化剪辑预案 HTML 规范
6.1 展示层
- 手机框 9:16 实时预览（拖动 / 播放看每个镜位）
- 时间轴（波形 + 镜位色带 + 气口标记 + 播放头）
- 逐镜卡片（时间码、模式、画面、字幕、剪法、注意点）
6.2 交互层（必须做）
| 交互元素 | 用途 |
|---|---|
| 字幕可编辑 | 用户点字幕直接改错字 |
| 人名/敏感词标注 + 勾选 | 确认「要打码」的位置 |
| 镜位模式下拉 | 每个镜位切「全屏·人 / 全屏·内容 / 对半 / 横版」 |
| 语速选择 | 预设档（5 / 5.5 / 6 字/秒） |
| 批注横线 | 每镜位一条「批注：___」 |
6.3 回流机制（HTML 无法直接写本地文件）
底部放「生成批注」按钮，把用户的修改/选择/批注整理成一段 Markdown，用户复制发我。
前期轻沟通（不需要看画面）直接走 MD，留批注横线 【批注：___】。
6.4 版式铁律
- 预览画面里只出现成片真实会有的元素
- 辅助标记（安全区/分界线/占位提示）默认隐藏、可开关、标注「不是成片内容」
- 禁止在画面里放「接缝」「无字幕」这类占位文字
6.5 三个必踩的坑（都实测过）
- 素材路径必须纯 ASCII。 本地打开（file:// 协议）时，路径里的中文和空格会让图片/视频静默加载失败——页面不报错，只是那一格全白。
→ 在 HTML 同目录建assets/，把素材复制成p01_cover.png这类英文名再引用。 - 字卡容器如果是 flex，文字会被拆成并排的 flex item。 文本节点 + 内层
<span>会各占一列，文字挤成两栏。
→ 字卡容器显式加flex-direction:column。 - 初始化时别调
scrollIntoView。 页面一打开就滚动，用户会失去方向；用无头浏览器截图核对时还会导致整页空白。
→ 把滚动做成可选参数，只在用户点击卡片 / 按上下镜时触发。
6.6 自己验证预案 HTML 的最快方式
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
--headless=new --disable-gpu --no-sandbox --allow-file-access-from-files \
--hide-scrollbars --screenshot=out.png --window-size=1400,900 \
--virtual-time-budget=3500 "file:///绝对路径/预案.html?shot=3"
比加载完整浏览器自动化轻得多，逐镜截图核对够用。
配合在 HTML 里加一行 ?shot=N 参数支持（初始化时读取 location.search），可以直接跳到任意镜位截图。
七、跨平台说明
| 能力 | Mac | Windows |
|---|---|---|
| 核心剪辑（ffmpeg） | ✅ | ✅ |
| 抽帧 / 气口检测 / 语速 | ✅（ffmpeg） | ✅（ffmpeg） |
| 中文字幕 | ✅ | ✅（字体路径不同，自动检测） |
| 手机素材色彩规整 | ✅（avconvert） | ⚠️ 用「剪映」重新导出（未实测） |
> 主链路 100% 走 ffmpeg，两边都能跑。个别极端素材（安卓拍的怪异色彩空间）在 Windows 上没实测过，遇到会引导你用剪映导一次。
八、技术细节
- 现成脚本直接用，别每次临时写 →
scripts/analyze.py（母带分析：气口 / 语速 / 建议倍速 / 保留片段表），用法见scripts/README.md - 完整 ffmpeg 命令、参数、踩坑 →
references/剪辑技术手册.md - 素材怎么拍、怎么录、怎么准备 →
references/素材准备引导.md
8.1 ⚠️ 两个必踩的硬坑
① trim 会压坏时间戳，不要用它来控制时长。
[0:v]trim=end_frame=N,setpts=PTS-STARTPTS[a] 接 vstack 之后，帧数是对的，但输出时长会腰斩
（实测 1754 帧只剩 31.46 秒），成片直接报废。
→ 正确做法：在生成素材片段的阶段就用 -frames:v N 把帧数控死，合成时直接 vstack，不做 trim。
② 掐气口要给每处留 0.12 秒垫片。
全掐干净会只剩 55 秒左右，语音之间没有呼吸、听起来很赶。
→ 中间的气口每处保留前 0.12s（cuts = (a+0.12, b)），只掐开头和结尾的静音不留垫片。
8.2 中文字写字体从哪来
macOS 常规字体目录没有手写中文字体，但按需资源里有：
/System/Library/AssetsV2/com_apple_MobileAsset_Font8/*/AssetData/
可用的：Hanzipen.ttc（翩翩体，首选）、Hannotate.ttc（手札体）、WawaSC（娃娃体）、
YuppySC（雅痞手写体）、Xingkai.ttc（行楷）、WeibeiSC（魏碑）、Kaiti.ttc。
- 翩翩体的字重：ttc 里
index=0是 SC Regular，index=2是 SC Bold（字幕用 Bold，笔画够粗） - ⚠️ 行楷（Xingkai）不含英文字母和数字——字幕里出现 "AI剪辑""10分钟" 会渲染成乱码，别用
8.3 手写体字幕完整链路
- 字体文件复制到项目
fonts/ - 生成 ASS，
Style行 Fontname 写字体族名（翩翩体是HanziPen SC） - 烧字幕时带 fontsdir，libass 直接读项目字体，不用把字体装进系统：
-vf "ass=subs.ass:fontsdir=fonts" - 字幕时间必须从原始时间映射到掐气口后的时间轴，否则全片错位
- 字幕位置
Alignment=2（底部居中）+MarginV=230：这个值是按"下半格人脸下巴在 y≈1530"
反推的，正好压在人脸下方、不挡嘴也不进手机底部 UI 区 - 字幕断行 ≤16 字（56px 字号在 1080 宽内刚好放得下）
⚠️ 同一句拆出的多行不要做相邻合并，合并会把前一行吞掉只剩最后一行
8.4 推荐的音频链（人声降噪 + 提亮）
afftdn=nf=-25, highpass=f=90, equalizer=f=2600:t=q:w=1.2:g=3,
acompressor=threshold=-20dB:ratio=3:attack=5:release=200, volume=8.5dB, alimiter=limit=0.9
从原始母带提到 -13~-14 LUFS（抖音/视频号的舒适区）。alimiter 收尾防削波。
⚠️ 别用单遍 loudnorm——它带 3 秒前视延迟，会造成音画不同步。
第 2 步「分析口播母带」直接跑现成脚本：
python scripts/analyze.py <口播视频> --words <总字数> --framedir <抽帧目录> --out analysis.json
它输出的 retain 字段就是掐气口要用的「保留片段表」，直接喂给第 5 步。
九、下游传递摘要
skill_name: 视频剪辑巧匠
core_mode: 四模式版式（全屏·人 / 全屏·内容 / 对半 / 横版）
speed_std: 5-6 字/秒
subtitle_rule: 以实际口播为准，错字预案期改
filler_rule: 口癖词掐掉
html: 展示 + 交互批注 + 生成批注回流
frame_align: 镜位边界必须量化到帧，否则逐段整帧取整会累积漂移
subtitle_burn: 字幕在最终合成阶段按绝对时间统一烧，不逐段烧
sample_first: 先跑 3~5 秒样片验证全链路，再批量剪
cross_platform: ffmpeg 主链路，Mac/Windows 通用
scripts: analyze.py（母带分析，通用）
