运动视频编辑技能

把一堆运动素材（多段视频 + 照片）变成一条能直接发布的成片，或先给用户一份可执行的剪辑方案。本技能由「需求咨询」与「剪成单条成片」两条链路合并而成：咨询决定参数，执行按同一套标准落地。

两种使用模式

咨询模式 —— 用户只问「该怎么剪」「用什么参数」、不要求出片时：给判断 + 参数表 + 可执行命令，不动素材、不渲染。回答必须落到具体数值（分辨率、转场时长、LUFS、BGM 音量），不给模糊建议。

执行模式 —— 用户给了素材路径并要求成片时：走完下面「标准工作流」6 步，交付 mp4 + 说明（叙事顺序依据、剔除理由、音频实测值）。

环境前提

必装二进制：ffmpeg / ffprobe ≥ 6.0，需 full build（含 libx264、xfade、zoompan、loudnorm、afftdn、alphamerge）。脚本优先走 PATH，找不到会再自动扫 winget 安装目录（%LOCALAPPDATA%\Microsoft\WinGet\Packages）。
- Windows winget install --id Gyan.FFmpeg -e｜macOS brew install ffmpeg｜Linux apt install ffmpeg。

Python 依赖：同目录有 requirements.txt，装法 pip install -r requirements.txt。
- 硬依赖：numpy（体检、参考实现、特效）、Pillow（照片快闪、分屏、智能铺满）；
- 强推荐：opencv-python-headless<5（人脸检测、人物居中、智能取景；别装 5.x，5.0 移除了 CascadeClassifier/HOGDescriptor）。未装时相关能力自动退化为居中裁切，不报错；
- 可选：rembg（仅 apply_fx cutout 抠像用）。

中文字体：脚本自动探测系统字体（Windows 微软雅黑/黑体 → macOS PingFang → Linux Noto Sans CJK）。也可用环境变量 WB_CJK_FONT 指定 .ttf/.ttc，或把字体放进 scripts/assets/font/。

编码：只用 CPU 软编 libx264 —— 老显卡（如 MX250 + 441.12 驱动）NVENC 会初始化失败并产出 0 字节文件。

目录约定：素材目录视为只读；中间产物写 <工作目录>/work/<日期>/，成片写 <工作目录>/out/。

装完先自检：cd scripts && python selftest.py —— 检查依赖、造测试素材、跑一遍最小出片流水线并校验产物。换机器/换环境务必先跑（--quick 只查依赖，秒级）。

依赖谁来装（AI 必读）

技能安装只是复制文件，平台不会跑任何安装脚本。所以脚本自带、依赖要装，分三类处理：

缺依赖时的标准动作（不要跳过、不要静默安装）：

1. 先跑 python selftest.py --quick 拿到确切缺项（别凭猜测）；
2. 把缺什么、装什么、体积多大一次讲清，给出对应该平台的命令；
3. 等用户同意再执行；用户不同意就走降级路径（见下）；
4. 用运行脚本的那个解释器安装，即 "{sys.executable}" -m pip install ...，不要用裸 pip —— 用户机器上常有多个 Python（venv / conda / 系统），裸 pip 装完可能 import 不到，表现为"装了还是报错"；
5. 装完重跑 --quick 复核，通过了再开工。

降级路径（用户不想装 / 装不上时也能出片）：

• 缺 opencv → 人脸检测、人物居中、智能取景退化为居中裁切，其余功能不受影响，不必阻塞；
• 缺 rembg → 只是 apply_fx cutout 抠像不可用；
• 缺 numpy / Pillow → 硬依赖，没有替代，必须装；
• 缺 FFmpeg → 完全无法工作，必须装。

标准工作流（0 + 6 步，不要跳步）

第 0 步（强制前置）：定画幅 —— 素材横竖混杂，开工前必须先向用户确认这条片子是横屏还是竖屏，不得由 AI 自行假设、不得先斩后奏。

• 画幅按显示画幅判定（已处理手机竖拍的 rotation / display-matrix 元数据，横存竖显的素材不会误判）；方形素材两边都算合规。
• 用户没明确回答前，不要开始体检排序、不要试渲染。
• 允许「缩放 + 智能裁剪」混用；禁止「裸旋转 + pad」混用（2026-10-09 用户修正，替代原"只吃同画幅"与"绝不旋转"的表述）：
• ❗禁止裸旋转 90°——竖屏 720x1280 旋转后尺寸虽变 1280x720，但画面内容侧躺（人物横躺、文字横倒），那是内容错乱不是"方向一致"；
• ✅ 正解是不旋转、只缩放+智能裁剪：竖→横 = scale 到 1280x2276 再沿高度裁 720 的窗口；横→竖 = scale 到 2276x1280 再沿宽度裁 720 的窗口，窗口位置由人脸/主体决定（smart_crop_video.py 已实现，等价于 ffmpeg crop+scale）；
• 流程：异画幅素材先 smart_crop_video.py --input x.mp4 --out reframed/ --width W --height H 归一化 → 归一化片段再进 edit_vertical.py 拼接（此时全是同画幅，不再需要 --allow-mixed）；
• 裁切取景遵循用户四原则：人脸锚上 1/3 + 头顶留白 / 无人脸回退（top/center/saliency）/ 人与动物优先于景物 / 不可靠片段写 _需要人工确认.md 等用户处理后重跑。

1. 体检 — analyze_clips.py --src <素材目录>：拿到每段的 creation_time、抖动（双窗 RMS）、黑帧、冻结、响度、色彩六类指标，同时生成 1fps 全片缩略图条与首尾 3s 的 3fps 边界条。
2. 定叙事顺序 — 用缩略图接触表看内容排序，不靠文件名或时间戳；据此判定每段可用区间。
3. 写剪辑单 — 每段的 start:end 与剔除理由落到 CUTLIST（edit_narrative.py 是参考实现），理由必须能对上第 1 步的数据。
4. 决策成片参数 — 画幅、转场、调色、音频、BGM、是否插照片段，按「推荐参数表」取值并显式传参；用户明确指定则覆盖。
5. 渲染 — 通用出片用 edit_vertical.py（参数化，一条命令出片）；需要逐段精修或多素材类型混排时，以 edit_narrative.py / edit_final.py 为参考实现改写。
6. 验收 — 抽帧看画面（含转场处）+ 量响度（分段与全片），确认无废镜头、无削波、无断层，再交付。

工具速查

> 所有出片脚本默认拒绝覆盖已存在的输出文件（防冲掉旧成片），确要覆盖请显式加 --force。

常用命令：

PY="python"   # 换成你本机 Python 解释器的实际路径（需已 pip install -r requirements.txt）
cd <skill>/scripts
# 0) 定画幅（强制第 0 步）：先看素材画幅构成，再决定这条片子是横屏还是竖屏
"$PY" edit_vertical.py --input "G:/素材/0621晨跑" --probe-only
#     报告会列出每段画幅（横/竖 + 旋转角）与「主画幅原样用 / 异画幅先归一化」
# 1) 体检
"$PY" analyze_clips.py --src "G:/素材/0621晨跑" --work "G:/素材/0621晨跑/work"
# 2) 出片（--input 顺序即叙事顺序，--trim 与之一一对应）
"$PY" edit_vertical.py \
  --input "A.mp4,B.mp4,flashA.mp4,C.mp4,D.mp4" \
  --trim "0:12,0:6.8,0:,2.2:,1.9:" \
  --out "G:/素材/0621晨跑/out/成片_竖屏1080x1920.mp4" \
  --transition fade --transition-duration 0.8 \
  --grade soft --audio-norm loudnorm --bgm bgm.wav --bgm-volume 0.45
# 2b) 横屏成片（只吃横屏素材）
"$PY" edit_vertical.py --input "L1.mp4,L2.mp4" --width 1920 --height 1080 \
  --out "G:/素材/0621晨跑/out/成片_横屏1920x1080.mp4" --grade soft --transition dissolve
#     混画幅属例外：默认报错退出，由用户明确同意后才可加 --allow-mixed
# 3) 分屏画中画段（无边框无间隔，满幅铺满）-> 作为片头或结尾插进 --input 链
"$PY" make_pip.py \
  --clips "A.mp4,B.mp4,C.mp4,D.mp4" --starts "1.5,0.8,0.6,2.0" \
  --dur 5.0 --layout rows4 --enter zoom --lead 0.12 --stagger 0.22 --out pip.mp4
#    布局可选：quad4 四等分2x2 / main3 一大三小 / rows4 四行(竖屏画布) /
#              cols4 四列(横屏画布) / grid9 九宫格 /
#              diamond4 菱形对角4三角【仅横屏】 / para4 斜向平行四边形【仅横屏】
#    ⚠ 斜切类（diamond4 / para4）只在横屏画布使用；竖屏画布传这两个布局脚本会直接报错。
#      竖屏要满幅等分就用 rows4 / quad4 / main3 / grid9。
#    横屏素材配竖屏画布时 rows4 裁切最轻；quad4/grid9 格子窄，人物居中才适用
#    等分取中原则：默认 --smart-center auto，有人物人物居中、纯景物景物居中
#    素材塞不进格子时用 --cell-fill blur（画面完整 + 自身模糊填充，仍无间隙）
#    纯 BGM 版成片：edit_vertical.py 加 --no-source-audio --audio-norm none --bgm-volume 0.7 --loudnorm
# 4) 单段效果（24 项技巧，全部见 references/techniques.md）
"$PY" apply_fx.py slowmo  -i A.mp4 -o A_slow.mp4 --factor 0.5        # 0.5x 慢放+声音降调
"$PY" apply_fx.py speedup -i A.mp4 -o A_fast.mp4 --factor 1.8 --denoise
"$PY" apply_fx.py freeze  -i A.mp4 -o A_freeze.mp4 --at 2.5 --dur 1.0
"$PY" apply_fx.py zoom    -i A.mp4 -o A_zoom.mp4 --mode in --dur 3 --amount 0.25
"$PY" apply_fx.py text    -i A.mp4 -o A_txt.mp4 --text "周末晨跑" --anim pop --start 1
"$PY" apply_fx.py keying  -i green.mp4 -o overlay.mov --color 0x00FF00   # 抠像->透明素材
#    转场技巧：edit_vertical.py --transition fadewhite 0.2(闪白) / fade 0.4(叠化) /
#              wipeleft(线性蒙版) / circleopen(圆形放大)

推荐参数表（用户未指定就用这套；必须显式传给脚本）

> ⚠️ 本表是推荐值，不是脚本的 argparse 默认值 —— 两者刻意不同。举例：
> --grade 脚本默认 none（不传就不调色）、--bgm-volume 脚本默认 0.5、
> --transition-duration 脚本默认 0.6。AI 按本表决策时要把参数显式写进命令行，
> 否则实际出片会与本节承诺不符。

硬规则

• 智能取中依赖 OpenCV：make_pip.py --smart-center 需要 pip install "opencv-python-headless<5"（别装 5.x，5.0 移除了 CascadeClassifier/HOGDescriptor）；没装则自动退化为居中裁切，不报错。
• 顺序靠看，不靠元数据：文件系统 mtime 拷贝即重置；creation_time 常常只是导出/落盘顺序（同批素材可能只差几秒）。必须用 1fps 接触表看内容定叙事序。接触表编号与文件名的对应关系要先核对画幅（横/竖、分辨率）再判断内容 —— 认反过一次就会把废镜头剪进片子。
• 抖动判定用短窗：analyze_clips.py 的双窗残差里，0.5s 窗 = 摇镜 + 抖动总量，0.17s 窗（hf）才是纯抖动。能不能用看 hf：hf 持续 > 8px 的时段剔除；拿长窗数据判断会把跟拍摇镜误判成抖动。
• 音频增益有上限：按峰值约束给静态增益（上限约 +20~22dB）。近无声素材（RMS -46dB）硬抬会炸噪底，正解是加轻 BGM 托底，不是无限抬。
• 调色不硬拉基准：按「向中位数靠拢 60% + 上限 1.20」温和收敛；直接归一到基准会把白墙红跑道这类画面饱和度推爆。
• filtergraph 里不写 Windows 绝对路径：盘符冒号是参数分隔符，fontfile=C\:/... 各种转义都会崩（实测 ffmpeg 9 直接报 No option name）。把字体复制进项目 assets/font/，用相对路径 + cwd=scripts/ 跑。
• drawtext 文本用 textfile= + expansion=none：filtergraph 有两层转义，标题里同时出现 ' 和 : 时无论怎么转义都会拼坏（实测必炸）；只出现 % 也会被当成 drawtext 扩展语法而报 Stray %。正解是把文本写进项目内临时文件、用相对路径 textfile= 引用并加 expansion=none（edit_vertical.py / apply_fx.py 已这么做，跑完自动清理临时文件）。
• 画幅：允许缩放+智能裁剪混用，禁止裸旋转+pad 混用（用户 2026-10-08 定、2026-10-09 修正）：开工前先与用户确认画幅（工作流第 0 步）。主画幅素材原样用；异画幅素材用 smart_crop_video.py 归一化（不旋转 90°——旋转让内容侧躺；正解是缩放+智能裁剪）；判定用显示画幅（含 rotation 元数据修正）；方形素材两边通用。edit_vertical.py / make_pip.py 仍硬拦截异画幅（退出码 1），所以归一化必须发生在拼接之前。
• 视频跟踪裁切的画质账：16:9 源裁 9:16 只保留 32% 宽度。1080p 源要放大 1.78x（明显损画质，慎用）；4K 源仅 1.27x（可接受）。竖屏成片优先用原生竖拍素材，横屏素材裁切是"有就比没有强"的补充。
• 斜切分屏只在横屏用（用户 2026-10-08 定）：diamond4（菱形对角）与 para4（斜向平行四边形）只在横屏画布使用，竖屏成片一律用 rows4 / quad4 / main3 / grid9。竖屏比例下斜切会切掉单格大半可用面积、人物易被斜线切脸；make_pip.py 已对该组合直接 SystemExit 报错，不要绕过。
• 不擅自删用户素材；不擅自加 BGM（用户说「保留原声」就是不加）；成片另存新文件，不覆盖旧版。
• 渲染前先给方案表（段序、区间、剔除理由、参数）。单条成片渲染约 3~5 分钟；用户要改只重渲一次，别来回试。

参考文档

• references/workflow.md — 分步操作细则、CUTLIST/TIMELINE 写法、多素材类型混排策略。
• references/specs-and-qc.md — 成片规格、响度验收表、抽帧验收命令、交付命名规范。
• references/pitfalls.md — 环境与踩坑清单（ffmpeg 安装、anullsrc 参数名、tile 拼图早 flush、中文路径清理等），卡住先查这里。

技巧选用原则（用户 2026-10-08 定，执行任何效果前先过一遍）

1. 服务内容优先：特效、运镜只用来强化叙事，不堆砌；画面信息多时少用旋转/大幅移动。
2. 同片风格统一：控制运镜、转场种类，不同时叠加推镜+旋转+蒙版扫动+闪白。
3. 关键帧克制：优先慢速小幅动画（推镜 ≤8%、时长 ≥3s）。
4. 转场宁缺毋滥：纪实/访谈用叠化 dissolve /硬切；快剪短视频才用闪白 fadewhite。
5. 音画同步：慢放开 --pitch 声音降调；卡点对齐 BPM 网格。
6. 不同时叠加多个强动态：旋转+推镜+蒙版扫动必乱。
7. 分屏先主后辅：先出主视频，再单独生成画中画分屏段插进 --input 链。
8. 抠像顺序：绿幕 keying > 智能 cutout；背景杂乱有毛边需手动修。
9. 文字动画只用一种：渐显（--title-fade）或逐字弹出（apply_fx text --anim pop），不混用。
10. 音频收尾三件套：--audio-denoise 降噪 → --audio-norm 平衡 → --audio-fade "in:out" 防爆音。
11. 视觉稳定：快速旋转/大幅摇晃慎用（apply_fx rotate 建议 ≤5°）。
12. 先统一调色再加特效：--grade soft 先行，避免色调割裂。
13. 氛围效果轻微：--vignette 5~8（越大越轻）、blurbg 模糊适中，不遮主体。
14. 斜切分屏只在横屏用（用户 2026-10-08 定）：斜切类布局 diamond4（菱形对角）/ para4（斜向平行四边形）只在横屏画布使用；竖屏成片用满幅等分布局 rows4 / quad4 / main3 / grid9。make_pip.py 对竖屏 + 斜切组合直接报错，别绕过。
15. 画幅：允许缩放+智能裁剪混用，禁止裸旋转+pad 混用（用户 2026-10-08 定、2026-10-09 修正）：开工先问定横屏/竖屏；主画幅素材原样用，异画幅素材走 smart_crop_video.py 缩放+智能裁剪融入（不旋转），人脸锚上 1/3、无人脸回退、人与动物优先于景物、不可靠片段人工兜底；放大 >2.5x 用 --overflow blur 模糊垫底。照片快闪段不受此限（满幅 crop）。

精剪收尾参数（2026-10-08 实战验证）

• edit_vertical.py：--vignette <n>（全片统一暗角，加在全片链）、--audio-denoise（各段 afftdn 降噪保人声）、--audio-fade "in:out"（全片首尾 afade 防爆音）、--title-fade <s>（标题渐显渐隐）。
• make_flash.py：--trans dissolve|fade|fadewhite（图片间转场可选，纪实片用 dissolve 去白闪）。
• apply_fx.py freeze：定格拉长画面时原声自动 apad 补等长静音，音画总长一致。
• 参考配置（纪实晨跑精剪 48.7s 实测 -13.9 LUFS / 峰值 -0.7dBFS）：
  --transition dissolve --transition-duration 0.4 --grade soft --vignette 6 --audio-denoise --audio-fade "1:1.5" --bgm-volume 0.42 --audio-norm loudnorm --loudnorm
• 注意：crf 20 + 暗角渐变会把码率推到 ~15 Mbps（90MB/48s），在意体积用 crf 23（约减半）。