检测功能故障排查

排查目标检测或目标追踪相关问题时，可将导出的视频文件作为临时的「虚拟摄像头」进行回放，这种方式能在本地复现问题、反复调试各项配置（检测、区域、识别增强相关配置），同时捕获日志与视频片段用于分析。

适用场景

• 回放导出的视频片段，复现识别结果异常的问题
• 基于已知的视频片段，测试各类配置修改效果（模型参数、追踪器、过滤规则）
• 收集可复现的日志与录像文件，用于问题调试或提交问题反馈

配置示例

将需要回放的视频片段放到 Frigate 可访问的目录下（例如 /media/frigate/，开发环境下可放入项目的 debug/ 文件夹）。随后在你的 config/config.yml 配置文件中，新增如下临时摄像头配置：

cameras:
  test:
    ffmpeg:
      inputs:
        - path: /media/frigate/car-stopping.mp4
          input_args: -re -stream_loop -1 -fflags +genpts
          roles:
            - detect
    detect:
      enabled: true
    record:
      enabled: false
    snapshots:
      enabled: false

• -re -stream_loop -1 用于指定 ffmpeg 以实时速率播放视频文件，并无限循环播放，该参数非常适合长时间的调试场景。
• -fflags +genpts 作用是在视频文件缺失显示时间戳时，自动生成对应的时间戳，保证播放正常。

操作步骤

1. 将需要回放的视频片段导出或复制到 Frigate 所在主机的指定目录（如 /media/frigate/ 或 debug/clips/）。根据你需要调试的具体问题，导出视频片段时，额外延长导出的视频时长（即使这段时间目标还未出现在画面中）通常会很有帮助。
2. 在 config/config.yml 中添加上述临时摄像头配置。建议使用 test、replay_camera 这类辨识度高的名称，方便后续删除。
   • 若你正在调试某一台特定摄像头的问题，可将该摄像头的各项配置（帧率、模型/识别增强参数、区域规则等）完整复制到这个临时摄像头中，让回放环境与原环境尽可能一致。除非你需要专门调试录像或快照功能，否则建议保持 record 和 snapshots 为关闭状态。
3. 重启 Frigate 使配置生效。
4. 视频回放期间，在 Frigate 可视化界面查看调试视图并核对日志信息。重点关注检测结果、区域触发情况或待调试的相关功能，同时记录日志中出现的错误信息，完成问题复现。
5. 反复调整摄像头或识别增强的相关配置（模型、帧率、区域、过滤规则），并重新回放验证，直至问题解决。
6. 调试完成后，务必从配置文件中移除该临时摄像头，避免产生无效的监控数据或录像文件。

目标追踪的相关注意事项

• 回放的视频画面，不一定能与该视频原始接入 Frigate 时的运行状态完全一致（甚至每次循环回放的画面也会存在差异）。回放过程中调用的视频帧可能不同，进而导致检测结果与追踪行为发生变化。
• 移动侦测的结果取决于实际调用的视频帧，微小的帧偏移都可能改变移动侦测的区域范围，最终影响传入检测器的画面内容。
• 目标检测本身不具备确定性：模型推理与后期数据处理环节，在每次运行时都可能产生不同结果，因此每次回放得到的检测结果、目标追踪 ID 都可能不一致。

调试时，请将视频回放视为「高度还原的近似场景」，而非字节级的精准复刻。建议多次回放测试，如有需要可开启录像功能，同时仔细分析日志与保存的事件片段，以此判断结果的差异性。

常见问题排查

• 无视频画面：检查视频文件路径配置正确，且 Frigate 进程/容器拥有该路径的访问权限。
• 出现 FFmpeg 相关报错：查看日志中输出的 FFmpeg 专属错误信息，根据你的视频文件/封装格式，对应调整 input_args 参数。必要时，可为该虚拟摄像头关闭硬件加速（配置 hwaccel_args: ""）。
• 无目标检测结果：确认摄像头的 roles 配置项中包含 detect，且模型/检测器相关配置已开启。