wjs-reframing-video

通过从源视频中裁剪一个窄条区域来改变视频朝向，而非物理旋转画面。裁剪窗口始终跟随正在说话的人（active speaker）——即嘴部正在运动的面部，而非仅依据面积最大或置信度最高的面部。配套生成的 .crop.json 辅助文件记录了完整的裁剪方案、各片段的发言人判定结果，以及所用参数。原始输入文件**永远不会被修改**。

适用场景

• 将 16:9 的播客 / 访谈 / 演讲视频重新适配为竖屏短视频平台（微信视频号、抖音、小红书、YouTube Shorts、TikTok、Reels）。
• 将 9:16 的手机竖屏录制内容重新适配为横屏播放器（YouTube 长视频、博客嵌入等）。
• 将 4:3 的存档素材适配为 3:4 移动端比例，或反之。

输出画幅为源画幅的宽高互换 —— 即 16:9 → 9:16，而非“在 9:16 画框内添加黑边的 16:9”。

不适用场景

• 多人问答类内容（Multi-person Q&A）：当每个发言人都需独立裁剪时，本技能仅支持为整段视频选择一条裁剪轨迹。如需按发言人分别渲染，请改用 wjs-editing-multicam。
• 无面部的动画内容 / B-roll：将退化为居中裁剪，通常不符合创作意图。
• 源视频存在剧烈镜头运动（手持平移/变焦）：人脸追踪器会放大抖动。请先进行画面稳定处理。
• 源视频已符合目标画幅：无需处理。

该技能的定位 —— “是”与“不是”

当无人讲话（静音、纯音乐段落）时，自动回退至“面积最大面部”策略。

依赖项

pip install mediapipe opencv-python numpy

（MediaPipe 不包含在标准 Python 发行版中；ffmpeg 和 ffprobe 必须位于系统 PATH 中。）

首次运行模型下载：MediaPipe 0.10+ 使用 Tasks API，需加载 face_landmarker.task 模型文件（约 4 MB）。首次调用时，crop.py 将自动下载至 ~/.claude/skills/wjs-reframing-video/models/ 并缓存，供后续运行复用。首次离线运行将失败。

检测距离限制：内置 landmark 检测器针对距摄像头约 2 米范围（自拍 / 播客 / 访谈距离）优化。广角活动场景中若人脸过小可能无法检出 —— 建议先抽帧验证检测效果。

裁剪数学原理

源画幅 = W / H，目标画幅 = H / W（倒置）。裁剪窗口计算如下：

例如 1920×1080 → 竖屏： W_crop = 608，H_crop = 1080；最终缩放至 1080×1920（约 1.78× 上采样）。 1080×1920 → 横屏： W_crop = 1080，H_crop = 608；最终缩放至 1920×1080。

若希望输出为原生裁剪尺寸而非上采样，可通过 --output-size 1080x1920 手动指定最终尺寸。

处理流程

1. 探测：通过 ffprobe 获取输入分辨率、帧率、时长。
2. 判断朝向：根据画幅自动推断（可通过 --target portrait|landscape 手动覆盖）。
3. 帧采样：以 --sample-fps（默认 5 fps）采样帧 —— 足够捕捉嘴部运动（语音奈奎斯特频率约 10 Hz，至少需 4–5 fps）。
4. 人脸关键点检测：对每帧采样使用 MediaPipe Tasks FaceLandmarker（478 点）检测人脸关键点。对每个检测到的人脸记录：中心坐标、尺寸代理值、MAR（嘴部宽高比 = 内唇垂直距离 / 嘴角水平距离）。
5. 人脸追踪：基于中心距离匹配实现跨帧追踪 → 每个人脸获得稳定的 face_id。
6. 逐采样点主动发言人判定：对每个人脸轨迹，在滑动时间窗（--mar-var-window-sec，默认 1 秒）内计算 MAR 方差。方差最高者视为“正在说话”。若低于 --mar-var-threshold，则判定为无声 → 回退至面积最大者。
7. 迟滞机制：候选发言人切换仅在新发言人持续稳定达 --min-segment-sec（默认 1.5 秒）后才生效；更短的抖动将被抑制 —— 避免因单帧误检导致裁剪窗口来回跳变。
8. 发言人对齐分段：对每一段，取该发言人在此段内所有帧的面部中心坐标的均值作为裁剪中心，并在整段内保持固定。
9. 构建 ffmpeg 分段函数表达式（--motion cut，默认）：使每段裁剪位置恒定，并在段边界处瞬时跳变 —— 视觉效果等效于真实摄像机角度切换。（--motion smooth 切换为分段线性平移，但对访谈类内容通常不适用，因镜头会在句中漂移。）
10. 渲染：单次 ffmpeg 渲染 —— crop=W:H:x='expr':y='expr', scale=OUT_W:OUT_H。crop 滤镜原生支持逐帧计算 x 与 y；音频流拷贝。

scripts/crop.py 为具体实现。输出副作用包括：

• .crop.json —— 记录裁剪方案的辅助文件
• _cropped.mp4 —— 最终裁剪并缩放后的视频

辅助文件结构（.crop.json）

{
  "_about": "wjs-reframing-video crop plan for cam_a.MOV. Active-speaker detected via MAR variance.",
  "_help": {
    "source_size":     "[width, height] in pixels.",
    "target_size":     "[width, height] of the final rendered output.",
    "crop_window":     "[width, height] of the moving crop in source coords.",
    "chunks":          "Speaker-aligned segments: {t0, t1, cx, cy, speaker_id}.",
    "face_pick_mode":  "speaker = MAR-variance active-speaker; largest = old behavior.",
    "speaker_id":      "Stable face track id. null means no face / silence fallback."
  },
  "schema_version": 2,
  "source": "cam_a.MOV",
  "source_size": [1920, 1080],
  "target": "portrait",
  "target_size": [1080, 1920],
  "crop_window": [608, 1080],
  "face_pick_mode": "speaker",
  "sample_fps": 5.0,
  "mar_var_window_sec": 1.0,
  "mar_var_threshold": 1.5e-4,
  "min_segment_sec": 1.5,
  "chunks": [
    {"t0":  0.0, "t1":  4.2, "cx": 808, "cy": 540, "speaker_id": 0},
    {"t0":  4.2, "t1": 11.6, "cx": 1182, "cy": 540, "speaker_id": 1},
    {"t0": 11.6, "t1": 14.0, "cx": 808, "cy": 540, "speaker_id": 0}
  ],
  "face_sample_count": 1234,
  "track_count": 2
}

性能表现

• 检测阶段 是瓶颈。Apple Silicon 设备以 2 fps 采样时，预计耗时为实时长度的 ~10–20 倍（30 分钟源视频约需 1–2 分钟完成检测）。提高 --sample-fps 会使检测变慢，但追踪响应更灵敏。
• 渲染阶段 很快 —— 单次 ffmpeg 硬件编码（macOS 上为 hevc_videotoolbox）。1080p 源视频常低于 1× 实时速度。
• 对于超长源视频（>200 个分段），ffmpeg 表达式可能过于复杂；脚本会自动对分段中点降采样，将控制点数量控制在约 200 以内。

常见问题

• 嘴部动作 ≠ 说话：打哈欠、大笑、进食、吸气等动作同样会提升 MAR 方差。检测器可能短暂误判为说话。对于高要求内容，建议检查 sidecar 中的发言人时间线（脚本会打印 face#N: Xs on screen (Y%) 汇总），必要时调整 --mar-var-threshold 后重试。
• 侧脸或低头姿态：当面部相对摄像头旋转超过 60° 时，MediaPipe 可能无法稳定检测嘴部关键点，导致 MAR 方差趋平。此时将自动回退至“面积最大面部”。若长期存在大量侧脸镜头，可考虑启用 --face-pick largest。
• 两人重叠发言（打断 / 抢话）：双方 MAR 方差均升高，但仅一人胜出。落败者被标记为听众。如需在串扰场景下实现准确的逐发言人追踪，请使用 wjs-editing-multicam 并配备独立摄像头。
• 长时间静音段（B-roll、纯音乐）：将回退至面积最大面部。若该面部非目标发言人（例如听众静止而发言人麦克风拾取背景音乐），将出现裁剪漂移。建议预先对纯音乐段落进行分段处理。
• 源视频含烧录字幕 / 下栏（lower-thirds）：横转竖时，底部区域会被裁掉；竖转横时，下栏虽保留但会被拉伸。运行前请先剥离烧录内容。
• 广角 / 鱼眼镜头：关键点检测易在画面边缘失效。请先用 ffmpeg lenscorrection 校正畸变。
• 上采样伪影：如 608×1080 → 1080×1920 需 1.78× 上采样，锐利文字可能出现可见失真。若需保持叠加图层清晰度，可输出原生裁剪尺寸（--output-size 608x1080），交由平台自行上采样。
• 输出码率超出平台限制：默认为 --bitrate 12M。微信视频号上限为 10 Mbps；针对该平台请指定 --bitrate 8M。