monitor2timelapse

Turn exported camera video clips into a timelapse, with timestamp-based ordering when filenames are unreliable.

中文 | English summary

摄像头导出后通常会得到一批视频片段。monitor2timelapse 会把这些片段完整串联，再压缩成 30 秒、50 秒或任意自定义时长的延时摄影，方便快速整理长时间的摄像头记录。

一个实用亮点是：导出后的文件名有时只是导出或保存时间，并不代表实际录制时间。工具会读取视频首个可用帧上的时间水印，按画面里的真实时间排序，避免文件名不可靠导致片段顺序错乱。

它怎么工作

flowchart LR
  A[摄像头导出的视频目录] --> B[读取首帧左上角]
  B --> C[Tesseract OCR]
  C --> D{合法时间水印?}
  D -- 是 --> E[按水印升序排列]
  D -- 否 --> F[报告失败并停止]
  E --> G[完整串联全部片段]
  G --> H[按目标时长加速]
  H --> I[静音 MP4 延时摄影]

Loading

核心规则很简单：

• 水印是排序依据，文件名和文件保存时间永远不会被静默当作时间轴。
• OCR 失败会阻止编码，并列出失败文件，避免生成“看起来成功但顺序错了”的视频。
• 可以用显式 JSON 覆盖人工核对过的水印时间。
• 编码前会规范化片段、完整串联所有有效片段，再精确压缩到目标时长。
• 默认输出 H.264、30fps、yuv420p、无音频 MP4，适合直接播放和分享。

快速生成延时摄影

1. 安装依赖

需要 Node.js 20+、FFmpeg、FFprobe 和 Tesseract：

node --version
ffmpeg -version
ffprobe -version
tesseract --version

macOS 可使用 Homebrew：

brew install node ffmpeg tesseract
npm install

2. 先预览排序

把 ./clips 换成你的素材目录。建议先执行 --dry-run，核对 OCR 结果和首尾时间：

node bin/monitor2timelapse.js ./clips \
  --duration 30s \
  --dry-run \
  --json-report ./reports/scan.json

示例输出：

Scanning 4 video files for first-frame timestamps...
Parsed 4/4 timestamps.
  1  2026/08/22 10:41:15  camera-clip-001.mp4
  2  2026/08/22 10:41:24  camera-clip-002.mp4
  ...

3. 编码

node bin/monitor2timelapse.js ./clips \
  --duration 30s \
  --output ./output/timelapse-30s.mp4 \
  --json-report ./reports/timelapse-30s.json

支持 30s、50s、1m20s 和 1h2m3s。不传 --output 时，输出到素材目录下的 timelapse-30s.mp4。

4. 人工核对 OCR 失败项

如果某个视频首帧被遮挡、画面刚启动或水印太小，命令会拒绝编码并写入失败报告。人工确认画面中的时间后，复制示例文件并填写覆盖：

mkdir -p ./reports
cat > ./reports/timestamp-overrides.json <<'JSON'
{
  "camera-clip-001.mp4": "2026/08/22 10:41:15"
}
JSON
node bin/monitor2timelapse.js ./clips \
  --duration 50s \
  --timestamp-overrides ./reports/timestamp-overrides.json

覆盖值必须是合法的 YYYY/MM/DD HH:MM:SS。它是显式人工确认，不是文件名或文件保存时间回退。

参数

参数	说明
--duration, -d	必填。目标时长，如 30s、1m20s。
--output, -o	输出 MP4 路径。
--dry-run	只 OCR 和排序，不编码。
--json-report	写入 OCR、排序和失败项 JSON 报告。
--timestamp-overrides	读取人工核对的文件名到水印时间映射。
--watermark-width	左上角水印裁剪宽度比例，默认 0.36。
--watermark-height	左上角水印裁剪高度比例，默认 0.12。
--help, -h	显示帮助。

默认输出是静音视频。监控音频通常包含环境谈话等隐私内容，因此公开版明确不保留音频。

常见问题

OCR 识别不到时间

先用 --dry-run --json-report 查看失败原因。确认水印仍在左上角后，可调大裁剪区域：

node bin/monitor2timelapse.js ./clips -d 30s --dry-run \
  --watermark-width 0.45 \
  --watermark-height 0.18 \
  --json-report ./reports/scan.json

为什么不按文件名排序

因为监控 App 导出或手机保存时，文件名时间可能与画面录制时间不同。项目故意在无法识别水印时失败，而不是悄悄生成错误时间轴。

输入目录里有不同分辨率

这是支持场景。编码阶段会把视频流统一到 3840×2160、30fps、正方形像素，再串联和加速。请确保输入视频本身可被 FFmpeg 解码。

更多排查建议见 docs/TROUBLESHOOTING.md。

隐私与安全

这是一个本地处理工具：视频会交给本机 FFmpeg 和 Tesseract，不会上传到云端。使用前请确认你有权处理素材，并在分享前检查人物、儿童、住址、设备信息、谈话音频和时间水印。

工具不提供通用的人脸识别或隐私脱敏能力。公开发布前，请人工复核导出的每一帧，或选择完全不含个人信息的素材。

开发

npm install
npm test
node bin/monitor2timelapse.js --help

欢迎提交 Issue 和 Pull Request。请先阅读 CONTRIBUTING.md、SECURITY.md 和 CODE_OF_CONDUCT.md。

English summary

monitor2timelapse turns exported camera video clips into a timelapse. It concatenates every valid clip and speeds the complete sequence to a requested duration. When filenames are unreliable, it reads the burned-in timestamp from the upper-left of each clip's first usable frame and uses that timestamp to restore the correct order. Processing is local and the default output is a silent H.264 MP4.

Requires Node.js 20+, FFmpeg, FFprobe, and Tesseract. Start with:

npm install
node bin/monitor2timelapse.js ./clips --duration 30s --dry-run
node bin/monitor2timelapse.js ./clips --duration 30s --output ./output/timelapse-30s.mp4

License

MIT