wjs-syncing-multicam

针对同一事件的多源录制素材，利用音频互相关（audio cross-correlation）计算每个素材相对于参考时间线的单一时间偏移量，并在各原始文件旁生成对应的 .sync.json 侧车文件（sidecar）。原始文件绝不会被修改、复制或重新编码。 下游工具通过 -itsoffset 参数在消费（consume）阶段动态应用该偏移量。

设计原则 —— 侧车文件优于重编码

该能力早期版本通过裁剪 + 重编码生成 *_synced.MOV 文件，将偏移“烘焙”进文件中。我们已移除该行为：

• 磁盘空间 —— 3 台摄像机拍摄的 75 分钟 4K 素材约 60+ GB；重编码生成的同步副本将体积翻倍，却未带来任何信息增益。
• 画质 —— 每次重编码均有损。原始文件是唯一真实来源（source of truth）；侧车文件仅是可逆的元数据。
• 速度 —— 在 Apple Silicon 上，单个 _synced.MOV 文件生成耗时超 10 分钟；而生成侧车文件仅需数秒。
• 可组合性 —— 任意下游工具（如 autoedit.py、NLE 导入、ffmpeg 单行命令）均可读取侧车文件并自行应用偏移量。无工具专属格式锁定风险。

不适用场景

• 单机位素材 —— 无可同步对象。若需将单路素材切分为多个片段，请使用 video-segmentation。
• 已在 NLE 时间线上对齐的素材 —— 勿与剪辑师对抗。
• 自动剪辑 / 切点 / 画中画（PiP）渲染等同步之后的步骤，请使用 wjs-editing-multicam（该能力消费本能力生成的侧车文件）。

为何采用包络法而非原始波形

原始 PCM 波形互相关在两支麦克风增益/房间响应差异较大时（即副机位几乎总是如此），会产生弱峰值与错误匹配。对数能量包络（log-energy envelope）能有效捕捉对话与音乐的动态特征，这些特征无论频率响应如何，两支麦克风均能共同捕获。切勿跳过包络提取步骤 —— 这正是本能力在低信噪比（low SNR）下保持鲁棒性的根本原因。

算法流程

1. 从各输入中提取单声道 PCM 音频：采样率 8 kHz，位深 16-bit。
2. 计算对数能量包络：帧率为 100 Hz（帧移 10 ms，窗长 50 ms）。使用二阶 Butterworth 高通滤波器（截止频率 0.05 Hz），并以 filtfilt 方式零相位滤波 —— 用于消除缓慢漂移与增益偏置。
3. 对包络进行全段 FFT 互相关 → 得到粗略偏移量（精度约 ±10 ms）。
4. 在样本级精修偏移量：以粗对齐位置为中心，在参考素材 A 中截取长度为 60 秒的探测片段 B，搜索窗口为 ±2 秒，采用抛物线插值法定位峰值。
5. 多段探测漂移校验：每约 3 分钟重复步骤 4。对偏移量随时间变化关系 delta(t) = slope·t + intercept 进行线性拟合，可识别真实时钟漂移（典型值为 5–50 ppm）。最终采用中点规范偏移量（slope · midpoint + intercept），使残差围绕零对称分布。
6. 计算参考时间线中的重叠窗口：overlap = [max(0, delta), min(ref_dur, delta + src_dur)]。
7. 生成 .sync.json 侧车文件：置于每个非参考输入文件旁。无任何文件被复制、裁剪或重编码。参考输入也生成侧车文件（其中 delta_seconds: 0），以便下游代码统一处理所有输入。

scripts/sync.py 是本能力的具体实现。注意：当前脚本仍会同时输出 _synced.MOV 文件，但该路径已被弃用；侧车文件是唯一权威输出。

侧车文件 Schema（.sync.json）

每个原始输入对应一个侧车文件，与其同目录存放。纯 JSON 格式，文件内不含注释 —— 下方字段说明即为权威定义。

{
  "_about": "Sync metadata for cam_b.MOV. Apply via ffmpeg -itsoffset. See wjs-syncing-multicam SKILL.md for full schema.",
  "schema_version": 1,
  "source": "cam_b.MOV",
  "reference": "cam_a.MOV",
  "delta_seconds": 12.345,
  "drift_slope": 1.8e-5,
  "overlap_in_reference": [12.345, 4512.180],
  "overlap_in_source":    [0.000,   4499.835],
  "verification": {
    "median_residual_ms": 4.2,
    "residual_spread_ms": 11.8,
    "probe_count": 24
  }
}

字段说明

下游工具如何消费侧车文件

-itsoffset 是 ffmpeg 的 per-input 参数，且必须置于 -i 之前。务必始终从侧车文件中读取 delta_seconds：

# 将 cam_b 对齐至 cam_a 的时间线播放
ffmpeg -itsoffset $(jq -r .delta_seconds cam_b.MOV.sync.json) -i cam_b.MOV 
       -i cam_a.MOV 
       -filter_complex "[0:v][1:v]hstack" out.mp4

# 裁剪至双方共同覆盖的时间窗口（参数来自 cam_b.MOV.sync.json）
ffmpeg -ss  -i cam_b.MOV -t  ...

对于 wjs-editing-multicam，其 autoedit.py 中的 EDL 构建器会自动加载所有 .sync.json 文件；你无需手动拼接这些命令行参数。

部分覆盖片段（Partial-coverage clips）

常见情况：主摄像机覆盖 75 分钟，而 Riverside / 手机 / 领夹麦录音设备仅覆盖中间 30 分钟。scripts/sync_partial.py REF.MOV NEW.mp4 执行以下操作：

1. 将新输入与参考素材进行互相关。
2. 定位新片段的 t=0 在参考时间线中的位置（delta_seconds 可能很大，例如 1842.5）。
3. 仅写入侧车文件 —— 不添加黑场填充、不添加音频填充、不重编码。 overlap_in_reference 明确告知消费者该输入的有效覆盖时段；超出此窗口的部分，回退至主摄像机素材。

--audio-only 标志仅用于向下游提示该源无视频流 —— 当前已无编码环节可跳过。

何时跳过漂移校正

对于镜头剪辑（camera-cut editing，最常见情形），一小时内 ±25 ms 的残差低于人眼可感知阈值 —— 此时可设 drift_slope: 0.0，仅使用中点 delta_seconds。

对于需音画同步 / 长时唇形同步（>30 分钟且 verification.residual_spread_ms > 40）的情形，下游需对源素材应用 atempo = 1 + drift_slope。源文件本身仍不作修改 —— atempo 滤镜仅在消费时运行。

验证（务必执行）

scripts/verify.py REF.MOV SRC.MOV SRC.sync.json 会依据侧车文件中记录的 delta_seconds，对两个原始文件（对源素材应用 -itsoffset）重新提取音频，并再次执行多段探测互相关。结果将写回侧车文件的 verification 字段中。

通过标准：median_residual_ms < 15 且 residual_spread_ms < 交付帧率（delivery fps）下单帧时长。失败则需启用漂移校正后重试。

常见陷阱

• 原始波形互相关在低信噪比下易产生虚假峰值。 务必先提取包络 —— 此非可调选项，而是整个能力成立的前提。
• -itsoffset 在音频与视频上的语义不同 —— 为确保同步正确性，它必须是该输入的第一个参数。ffmpeg -i src -itsoffset X 错误；ffmpeg -itsoffset X -i src 正确。
• 侧车文件中 source / reference 的路径必须相对于侧车文件所在目录，而非下游进程的工作目录。请以 Path(sidecar).parent 为基准解析 source 与 reference。
• 切勿将 drift_slope “烘焙”进侧车文件的 delta_seconds 字段中。 二者分属独立字段自有其意义 —— 简单消费者可忽略漂移，音画同步消费者可主动应用；混合二者将丢失关键信息。