多台 Insta360 / 拇指相机想做多目同步采集，但没有硬件触发线？

我做了个开源工具：用一组动态二维码，把各相机录制的视频离线对齐到同一条 UTC 毫秒时间轴，达到多目相机同步效果。面向具身智能数据采集。

Python 3.11 + uv，开箱即用。

🔗 https://t.co/KNAcBbH6Go

XiaomingX/multicam-timestamp-align

Source: https://github.com/XiaomingX/multicam-timestamp-align

Multi-Camera Timestamp Alignment (multicam-align)

用一组动态播放的二维码，把多台相机（Insta360、拇指相机等）各自录制的视频，离线对齐到同一条 UTC 毫秒时间轴，达到多目相机同步的效果。面向具身智能多视角数据采集。

原理

单靠“各相机各自录、事后对齐“无法得到毫秒级精度。本工具的做法：

1. 在屏幕上以固定频率 freq（如 10 Hz）循环播放一组二维码。

2. 每个二维码编码：

   NTP1|<T0_ms>|<frame_index>|<seq_len>
   

   • T0_ms：序列第 0 帧对应的 UTC 毫秒时间戳（整组相同）。
   • frame_index：0,1,2… 递增计数器（定宽 4 位）。

3. 所有相机开始录制，把屏幕拍进画面。

4. 录完后离线处理：逐帧用 pyzbar 识别 frame_index，把每一帧映射到绝对时间：

   t_abs_ms = T0_ms + frame_index / freq * 1000
   

   因为 frame_index 在相邻屏幕刷新之间递增，相机捕捉到的任意一帧都能内插到亚帧级绝对时刻，补偿了屏幕刷新延迟和相机快门延迟。

5. 对每路视频做线性回归 t_abs = a·vf + b（vf = 视频帧时间秒），斜率吸收真实帧率（含 29.97 这类非整数），截距即该相机视频帧 0 的绝对时间。

6. 以“序列出现最早“的相机为基准，算出每台相机的 offset，得到统一时间轴。

误差来源与缓解

关键约束：序列播放频率必须是相机帧率的约数。例如相机 30 fps，序列用 10 Hz（每 3 视频帧一个二维码），确保没有视频帧同时拍到两个相邻二维码而产生歧义。

安装

需要 Python 3.11+ 和 uv。macOS 还需系统库 zbar 与 ffmpeg：

# macOS
brew install zbar ffmpeg
# 或从源码 / 包管理器安装 ffmpeg（Linux: apt install zbar ffmpeg）

# 安装 Python 依赖
uv sync

如果 import pyzbar 报 Symbol not found，说明系统缺少 zbar 库，先 brew install zbar（macOS）或 apt install libzbar0（Linux）。

使用流程

1. 生成二维码序列 + 播放页

uv run multicam-align gen --freq 10 --seq-len 20 --out qr_seq/

• 生成 qr_seq/qr_0000.png … qr_seq/qr_0019.png 与全屏播放页 qr_seq/play.html。
• T0 默认取“当前时间 + 3 秒“，留足你打开播放页、启动所有相机的时间。也可用 --t0 <UTC_ms> 显式指定。

2. 录制

1. 全屏打开 play.html（建议关掉系统节能/息屏，浏览器标签保持前台）。
2. 所有相机开始录制，确保画面能清晰拍到屏幕上的二维码序列（画面里出现几秒循环即可，不必全程拍）。
3. 开始你的采集动作。
4. 停止录制，把视频文件拷到本机。

3. 对齐

uv run multicam-align align \
  --videos cam1.mp4 cam2.mp4 cam3.mp4 \
  --names cam1 cam2 cam3 \
  --out aligned/

• 逐帧识别二维码、拟合时间轴，输出 aligned/result.json 与各相机 offset / 覆盖率 / RMS。
• 可选 --reference <name> 指定基准相机；默认用序列出现最早者。
• --step N 可只解码每 N 帧以加速（覆盖率统计会变粗）。

4. 重封装视频（起点对齐）

uv run multicam-align remux --result aligned/result.json --out synced/

按各相机 offset 用 ffmpeg -ss 裁剪，使所有输出视频从同一 UTC 时刻开始（synced/<name>_aligned.mp4）。

5. 生成对齐报告

uv run multicam-align report --result aligned/result.json --out report.html

HTML 报告含：各相机 offset / 覆盖率 / RMS / 大段漏识别告警，以及“绝对时间线拟合图“和“残差散点图“，用于判断对齐质量。

6. 提取某一时刻的同步帧

uv run multicam-align extract --result aligned/result.json --at 1703123457000 --out frames/

从每台相机提取最接近目标 UTC 毫秒的那一帧（frames/<name>_<utc>.png），用于拼同步多视角快照。

模块结构

src/multicam_align/
├── cli.py          # 统一 CLI（gen/align/remux/report/extract）
├── qr_generator.py # 生成动态二维码序列 + play.html + payload 解析
├── decoder.py      # 逐帧识别 frame_index + 线性拟合时间轴
├── align.py        # 多相机 offset + 全局时间轴 + result.json
├── remux.py        # ffmpeg 按 offset 重封装对齐
├── report.py       # matplotlib + HTML 报告
└── extract.py      # 给定 UTC 时间提取最近帧

测试

uv run pytest

tests/test_roundtrip.py 验证：生成的每个二维码都能被识别并还原出 (t0, frame_index, seq_len)，即对齐方案的核心不变量。

注意事项 / 排错

• 频率约数约束：序列频率务必为相机帧率的约数，否则会出现一帧跨两码的歧义。
• 漏识别告警：若某相机覆盖率过低或存在长段漏识别，报告会标 ⚠，需检查该相机画面中二维码是否清晰、有无运动模糊。
• 超长录制：相机时钟漂移随录制时长累积，长时间采集建议中途再拍一次二维码序列做分段重锚（后续版本可支持多锚点）。
• ffmpeg 精度：-ss 输入级 seek 已足够好；需要逐帧精确重封装时把 remux.py 改为重新编码（更慢）。