Frigate 快照Snapshots完全指南最佳帧选取、按需渲染与保留策略【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate快照Snapshot是 Frigate 为每一个被追踪目标保存的一张最佳瞬间静态图片它捕获的是目标穿越画面时最清晰的一帧。本文以官方配置文档docs/docs/configuration/snapshots.md为主线结合 Frigate 源码快照配置模型、目标跟踪与写入流程、最佳帧评分算法、事件快照 API系统讲解快照的启用方式、全部配置项、帧选择机制、磁盘存储与请求时渲染模型帮助你在部署中正确配置快照并理解其底层工作方式。快照是什么快照与录像recordings不同录像是连续视频而快照是每个被追踪目标在追踪结束后保存的一张代表性图片。简单说Frigate 在跟踪某个目标的全过程中持续评估每一帧选出最清晰的一帧等目标离开画面追踪结束后再写入磁盘。启用快照后Frigate 会为每个被追踪对象在/media/frigate/clips目录保存一张名为camera-id-clean.webp的图片。其中-clean的含义是始终不带任何注释没有时间戳、没有边框、没有裁剪保证你拥有一份原始帧的未修改副本而边框、时间戳等注释是在通过 HTTP API 请求快照时按需叠加的见下文 渲染模型。需要记住的几点快照按被追踪对象保存因此即使录像开启只要摄像头没有检测到任何对象也不会产生快照快照与录像在配置与保留策略上是相互独立的启用其中一项不会自动启用另一项快照可以在 UI 的 Explore 面板中查看并支持一键提交到 Frigate 服务进行模型优化训练如果只想保存进入特定区域的对象的快照请参考区域Zones文档中restricting snapshots to specific zones限制快照到特定区域一节通过 MQTT 发送的快照是独立的需要到camera 的 MQTT 设置下单独配置不属于本节snapshots配置的范畴。启用快照快照默认是关闭的源码中enabled的默认值为False。可以全局启用也可以针对单个摄像头覆盖默认设置。全局启用作用于所有摄像头UI 方式进入Settings Global configuration Snapshots将Enable snapshots打开YAML 方式snapshots: enabled: True为指定摄像头覆盖UI 方式进入Settings Camera configuration Snapshots选择对应摄像头打开Enable snapshotsYAML 方式cameras: front_door: snapshots: enabled: True在源码层无论全局还是相机级最终都落到同一个配置模型上。相机级的SnapshotsConfig会覆盖全局配置Frigate 读取实际生效配置时始终以self.config.cameras[camera].snapshots为准见 object_processing.py这一机制同样支撑了配置 profile 对快照开关的动态切换例如 runtime_state.py 中snapshots状态与 MQTT 的ON/OFF联动参见 mqtt.py。快照选项详解下列设置控制快照的渲染方式与存储方式同时构成通过 API 请求快照时的默认渲染参数。UI 方式进入Settings Global configuration Snapshots可配置字段如下字段说明Enable snapshots启用或禁用为被追踪对象保存快照Timestamp overlay通过 API 获取快照时叠加时间戳Bounding box overlay通过 API 获取快照时为被追踪对象绘制检测边框Crop snapshot通过 API 获取快照时按检测框裁剪到对象区域Snapshot height快照缩放的目标高度像素留空表示保留原始尺寸Snapshot quality保存快照的编码质量0-100Required zones对象必须进入的区域列表否则不保存快照YAML 完整示例snapshots: enabled: True timestamp: False bounding_box: True crop: False height: 175 required_zones: [] quality: 60各选项在源码中的默认值与约束以上 YAML 项与配置模型SnapshotsConfig一一对应定义在 frigate/config/camera/snapshots.py配置项类型默认值说明取自源码描述enabledboolFalse为所有摄像头启用/禁用保存快照可在单个摄像头覆盖timestampboolFalse通过 API 返回的快照叠加时间戳bounding_boxboolTrue通过 API 返回的快照绘制检测边框cropboolFalse通过 API 返回的快照裁剪到检测框required_zoneslist[str][]对象必须进入的区域满足条件才保存快照heightint | NoneNoneAPI 快照缩放高度像素None表示保留原尺寸qualityint60保存快照的编码质量0-100源码约束ge0, le100retainRetainConfig见下节快照保留策略注意bounding_box默认是True而timestamp、crop默认都是False且这些参数只影响从 API 请求渲染的结果——磁盘上的-clean.webp永远不带注释。快照保留策略快照在磁盘上的保留时长独立于录像。可以设置统一的默认保留天数也可以为特定对象类型单独设置更长的保留天数。UI 方式进入Settings Global configuration Snapshots字段说明Snapshot retention Default retention快照保留天数默认10Snapshot retention Object retention Person按对象类型覆盖保留天数例如让person快照保留 15 天YAML 示例snapshots: enabled: True retain: default: 10 objects: person: 15源码中RetainConfig定义于 frigate/config/camera/snapshots.pydefault是浮点型天数默认 10objects是dict[str, float]即对象标签 → 覆盖保留天数的映射。磁盘上快照与事件缩略图都遵循各自目录的保留策略Frigate 的清理任务会按这些天数定期淘汰过期文件相关清理逻辑可见 frigate/events/cleanup.py 与 frigate/util/camera_cleanup.py两者均参与-clean.webp快照文件的生命周期管理。帧选择Frigate 如何选出最佳帧Frigate不会保存每一帧而是为每个被追踪对象挑选一张最佳帧判定依据包括检测置信度detection confidence分数越高越好对象尺寸object size面积越大越好关键属性是否存在例如人脸、车牌等对识别有价值的属性会显著加分是否触碰画面边缘目标贴在画面边缘的帧会被降低优先级deprioritized。当追踪结束时这个最佳帧才被写入磁盘。也就是说整个追踪过程是对帧的持续评审最终只落盘一次。评分算法的源码级实现帧的优劣由 frigate/util/image.py 中的is_better_thumbnail()函数决定具体规则如下属性优先遍历该对象类型配置的非 logo 属性如人脸、车牌等来自模型attributes_map见 tracked_object.py若新帧出现了当前最佳帧没有的关键属性直接判定为更优若当前帧已具备某属性而新帧没有则不更新除非新帧在该属性上得分更高边缘惩罚如果新帧的目标框在画面边缘、而当前最佳帧不在边缘则不更新分数显著提升新帧得分比当前最佳帧高出 5% 以上new_obj[score] current_thumb[score] 0.05则更新面积显著变大新帧的目标面积比当前最佳帧大 10% 以上new_obj[area] current_thumb[area] * 1.1则更新。每一帧在 tracked_object.py 的update()流程中调用该函数胜出的帧连同box、area、score、attributes、recognized_license_plate等信息被存入thumbnail_data作为后续渲染快照的素材。快照何时写入磁盘当对象追踪结束时跟踪流程object_processing.py会依次执行重新计算has_snapshot调用should_save_snapshot若需要快照或录像先写事件缩略图write_thumbnail_to_disk若需要快照再调用write_snapshot_to_disk()将 clean 图写入磁盘。其中should_save_snapshot()object_processing.py的判定条件非常关键目标是误检false_positive→ 不保存摄像头快照未启用 → 不保存目标从未改变过位置position_changes 0→ 不保存静止/误检目标不会产生快照配置了required_zones且目标从未进入这些区域 → 不保存全部通过 → 保存。实际写盘动作write_snapshot_to_disk()位于 tracked_object.py它调用get_clean_webp()以timestampFalse, bounding_boxFalse, cropFalse, heightNone且quality取自camera_config.snapshots.quality的参数渲染 WebP 图片然后写入/media/frigate/clips/camera-id-clean.webp。事件缩略图用于 UI 列表则单独写入缩略图目录THUMB_DIR/camera/id.webp其固定按 175px 高度裁剪渲染见 tracked_object.py 的get_thumbnail()与磁盘上的 clean 快照用途不同。渲染模型请求时叠加注释Frigate 在磁盘上只保存一张不带注释的 clean 快照所有注释时间戳、边框、裁剪都在请求发生时即时渲染。这保证了同一份原始素材可以被不同用途重复使用而互不影响。API / 用途结果磁盘存储文件camera-id-clean.webp始终无注释/api/events/id/snapshot.jpg以摄像头的snapshots默认配置为起点在请求时叠加查询参数覆盖后渲染输出/api/events/id/snapshot-clean.webp返回磁盘上同一张快照不带任何注释Frigate 提交即 Frigate 首个模型使用同一张磁盘上的 clean 快照渲染流程在get_img_bytes()tracked_object.py中实现先从帧缓存取出thumbnail_data[frame_time]对应的 YUV 帧并转换为 BGR随后将timestamp、bounding_box、crop、height、quality、对象标签、检测框、得分、属性、时间戳样式等参数一并交给get_snapshot_bytes()完成注释绘制与编码。因此snapshot.jpg端点天然支持时间戳、边框、裁剪、高度、质量等渲染参数的按请求覆盖。这几个事件快照端点/events/{event_id}/snapshot.jpg与/events/{event_id}/snapshot-clean.webp在 frigate/api/media.py 与 frigate/api/media.py 中定义媒体访问遵循 Frigate 的认证与授权体系可参考 API 集成文档 了解认证方式。此外还有一个按对象实时请求的端点/{camera_name}/{label}/snapshot.jpgmedia.py通常与 MQTT 探测配合使用。完整渲染链路速览检测帧 → update() 中用 is_better_thumbnail() 评选最佳帧 → thumbnail_data 记录该帧元数据 │ ├─ 追踪结束 → should_save_snapshot() 判定 → write_snapshot_to_disk() │ └─ get_clean_webp() 以无注释参数编码 → /media/frigate/clips/camera-id-clean.webp │ └─ API 请求 /api/events/id/snapshot.jpg └─ get_img_bytes() 按请求参数叠加时间戳/边框/裁剪/高度/质量MQTT 快照与事件快照的差异MQTT 快照是独立于本节snapshots配置体系的另一套机制需要特别区分MQTT 快照发布更频繁每次在追踪过程中发现更好的缩略图帧或当前最佳图片早于best_image_timeout默认 60 秒时就会向{camera}/{label}/snapshot主题推送一张新的 JPEG 快照见 object_processing.py 的snapshot()回调MQTT 开关同样受required_zones约束参见同文件should_mqtt_snapshot()MQTT 快照使用摄像头 MQTT 设置下的独立注释与渲染参数timestamp、bounding_box、crop、height、quality与全局snapshots设置无关事件快照是追踪结束时在磁盘落盘一张 clean WebP与 MQTT 按帧发布的 JPEG 是两套产物互不影响。换言之snapshots配置只决定磁盘上会不会有一张 clean 快照以及 API 请求时默认怎么渲染而 MQTT 通知里的抓拍请到摄像头的 MQTT 配置项中调整。快照与区域Zones的联动required_zones与 MQTT 的required_zones在源码中是两套独立判定object_processing.py 与 object_processing.py逻辑一致只要配置了必入区域目标就必须进入过其中至少一个区域set(obj.entered_zones) set(required_zones)非空才会保存/推送快照。区域定义本身及更精细的对象过滤见区域Zones文档。常见误区小结快照 ≠ 视频快照按对象存单张图录像按时间存片段两者独立启用、独立保留磁盘文件始终是 clean 图界面上看到的带框/带时间戳快照是 API 渲染产物不是磁盘原样没有检测到移动对象就没有快照从未移动的目标position_changes 0不会保存快照MQTT 快照走 camera 的 MQTT 配置改全局snapshots不会影响 MQTT 通知抓拍。通过合理组合required_zones、retain.objects、按对象的区域过滤以及 API 请求时的渲染参数可以在几乎不占用额外计算与存储的前提下把 Frigate 快照用于门禁记录、区域入侵取证、人脸/车牌样本收集与 Frigate 模型优化等场景。相关源码文件索引配置模型与默认值frigate/config/camera/snapshots.py快照保存判定与写盘时序frigate/track/object_processing.py、object_processing.py最佳帧评选算法frigate/util/image.py帧记录、渲染与写盘实现frigate/track/tracked_object.py、tracked_object.py快照/clean 图 API 端点frigate/api/media.py、media.py清理任务参与快照生命周期frigate/events/cleanup.py、frigate/util/camera_cleanup.py【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考