检测功能分析

Frigate 提供了多种工具来排查目标检测与目标追踪相关的问题：在页面中核查已记录的检测结果、使用内置的调试回放功能，以及在高级场景下手动设置虚拟摄像头。

在页面中核查检测结果

在设置回放之前，通常可以直接在 Frigate 页面中核查已有的录像来诊断检测问题。

详细视图（历史记录）

历史记录中的详细视频流视图会显示带有检测叠加层（边界框、路径点和区域高亮）的已录制视频。选择一个核查项目即可查看其追踪目标和全周期事件。点击某个全周期事件会将视频定位到对应时间点，让你准确看到检测器所捕获的内容。

追踪详情（浏览）

在浏览页面中，点击缩略图会打开追踪详情面板，该面板展示单个追踪目标的完整全周期：每次检测、区域进入/退出以及属性变更。视频会叠加边界框回放，让你逐步查看目标的整个全周期过程。

标注偏移

以上两种视图都支持标注偏移设置（即摄像头配置中的 detect.annotation_offset），它可以在时间上将检测叠加层相对于已录制的视频进行偏移。这样可以补偿 detect（检测）和 record（录制）管线之间的时间漂移。

这两条视频流使用完全不同的时钟，具有不同的缓冲和延迟特性，因此检测数据和已录制视频永远不会完全同步。标注偏移通过偏移叠加层的时间，使边界框与录制视频中的目标在视觉上对齐。

为什么不同片段间偏移量会变化

对于给定的摄像头，detect 与 record 之间的基础时间漂移大致是恒定的，因此单个偏移值在平均情况下效果良好。但是，你可能会注意到对齐并非在每个片段中都精确到像素。这是正常现象，由以下几个因素造成：

• 受关键帧约束的定位：当浏览器跳转到某个时间戳时，只能落在最近的关键帧上。每个录制片段的关键帧相对于检测时间戳的位置各不相同，因此相同的偏移值可能在一个片段中略微偏早，在另一个片段中略微偏晚。
• 分段边界裁切：当录制范围从中途开始时，视频会被裁切到请求的起始点。这个裁切点可能与关键帧不对齐，从而偏移了有效的参考点。
• 采集时间抖动：网络缓冲、摄像头缓冲区刷新以及 ffmpeg 自身的缓冲机制，意味着系统时钟时间戳与对应录制帧之间的偏移量并非始终相同。

每个片段的差异通常非常低，主要是关键帧粒度造成的伪影，而非真实漂移的变化。"完美"的对齐需要对每帧进行基于关键帧感知的偏移补偿，这在实际应用中并不现实。请将标注偏移视为适用于该摄像头的"尽力而为"平均值。

调试回放

调试回放允许你针对一段已录制的视频重新运行 Frigate 的检测管线，而无需手动配置虚拟摄像头。它会自动提取录像内容，使用与原始摄像头相同的检测设置创建一个临时摄像头，并将片段循环送入检测管线，让你可以实时观察检测结果。

回放摄像头的行为类似于实时摄像头画面，而非历史记录的视频播放器：它会在 Frigate 分析时持续循环播放片段，并且没有播放控制功能，因此你无法暂停、拖动进度条或逐帧步进。

调试回放并非 Frigate 所有诊断功能的一站式工具，也不是覆盖所有 Frigate 功能的综合调试环境。它只是让你更便捷地启动一个「虚拟摄像头」并在实时进行一些常见调整。对于其他功能的调试，你仍需要使用常规工具（日志、MQTT 客户端等）。

何时使用

• 复现特定时间范围内的检测或追踪问题
• 使用已知片段测试配置修改效果（模型设置、区域、过滤规则、画面变动检测）
• 为问题反馈收集日志和调试叠加层

NOTE

同一时间只能有一个回放会话处于活动状态。如果已有会话正在运行，系统会提示你导航到该会话或先将其停止。

启动调试回放

调试回放可以从页面的多个位置启动。不同的启动入口决定了回放的时间范围。

• 历史记录：操作菜单。 导航到历史记录 > {摄像头}页面，打开工具栏中的操作菜单，选择调试回放。在这里你可以选择预设选项（最后 1 分钟、最后 5 分钟）、在时间线上直接选择范围（从时间线），或输入精确的起止时间（自定义）。这是最灵活的方式，也是想要在检测前后添加填充时间时的最佳选择。在移动端，相同的选项会出现在操作抽屉中。
• 历史记录：详细视频流事件菜单。 在详细视频流中查看核查项目时，打开追踪目标事件卡片上的菜单，选择调试回放。回放范围会自动设置为该目标的起止时间。
• 浏览：搜索结果菜单。 在浏览页面中，打开卡片上的"更多"菜单，选择调试回放。范围取自该追踪目标的全周期。
• 浏览：追踪详情操作菜单。 打开追踪目标的追踪详情对话框，然后从操作菜单中选择调试回放。时间范围与搜索结果菜单相同，为自动计算。
• 导出：导出卡片菜单。 在导出页面中，打开一个导出项目的菜单，选择调试回放，即可将已导出的片段循环送入该导出来源摄像头的检测管线。

详细视频流、浏览和导出这些入口使用的是底层录像或导出文件的时间边界，并附带少量填充时间。这对于快速检查很方便，但如果检测时间很短，或你希望为画面变动检测和检测器留出额外的「稳定」时间，建议从历史记录的操作菜单启动回放，并手动扩大时间范围。

需要考虑的变量

• 回放的结果不会总是与原始运行的结果完全相同。回放时可能会选取不同的视频帧，这可能会改变检测结果和追踪行为。
• 画面变动检测取决于所使用的确切帧；微小的帧偏移可能会改变画面变动区域，进而影响传递给检测器的内容。
• 目标检测并非完全确定性的：模型和后处理过程在每次运行时可能产生略微不同的结果。
• 如果检测时间很短，回放可能只有少量帧，建议在检测前后手动添加一些填充时间，让画面变动检测器和目标检测器有时间适应场景。与其从浏览中启动调试回放，不如导航到摄像头的历史记录，从操作菜单中选择调试回放，并点击"从时间线"或"自定义"选项。
• 回放摄像头会继承源摄像头的区域。任何基于这些区域名称触发的自动化也会为回放摄像头触发。这在调试区域行为时可能有用，但也可能出乎意料。如果想在自动化中排除回放触发的自动化，可以在自动化中添加源摄像头名称的条件。

请将回放视为「高度还原的近似场景」，而非精准复刻。建议多次循环回放，并检查调试叠加层和日志，以理解实际行为。

手动虚拟摄像头

对于高级场景（例如使用来自不同来源的片段进行测试、调试 ffmpeg 行为，或使用完全自定义的配置来运行片段），你可以手动设置虚拟摄像头。

配置示例

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