企业官网建设流程全解析

Frigate History 视图完全指南：全分辨率录像回放、时间轴同步、追踪细节检视与导出分享

【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate

History 是 Frigate 的全分辨率录像查看器，与 Live、Review、Explore 不同，它没有独立的菜单入口，而是从其他视图跳转进入，用于回放历史录像、拖动时间轴、切换摄像头、检视被追踪对象（Tracked Object）的完整生命周期，并导出或分享任意时刻的录像片段。本文将以 Frigate 仓库中的 History 使用文档 为主体，结合 前端实现源码 深度展开，帮助你完整掌握 History 视图的打开方式、时间轴交互、Detail 检视器、Actions 菜单与 AI 摘要等全部能力。

本文介绍的是 History 视图的使用方法；关于录像的配置（保留策略、pre/post 捕获等），请参阅 Recording 配置文档。

什么是 History 视图

History 是 Frigate 提供的全分辨率录像查看器。与 Review（事件摘要视图）、Explore（对象检索视图）不同，History 直接面向原始录像本身：

• Review将时间上重叠、相邻的活动聚合为"审查条目"（review items），用于快速扫描发生了什么；
• Explore用于事后检索某个具体的被追踪对象（按标签、时间、区域、描述）；
• History则让你以全分辨率、逐帧地回放某台摄像机的录像，适合仔细查看事件前后细节、跟踪对象移动过程、截取精确片段用于导出。

从实现上看，History 视图对应前端仓库中的 RecordingView.tsx 组件（其核心播放器为DynamicVideoPlayer），它在桌面上以"主播放器 + 侧边面板 + 次要预览行"的布局呈现，在移动端则以抽屉（Drawer）形式组织。

打开 History 视图

History 没有主菜单入口，必须从其他视图进入，主要有三种方式：

进入 History 后，顶栏提供两个导航按钮：

• Back（返回）：返回进入 History 之前的视图。实现上，如果是从分享链接直达（无历史可回退），则跳转到首页（见 RecordingView.tsx 中handleBack对recording?.navigationSource === "shared-link"的处理）；
• Live（直播）：跳转到当前摄像头（主摄像头）的实时画面，对应代码中的navigate(/#${mainCamera})。

:::tip 提示：遇到 "No recordings found for this time"（该时间没有录像） 最常见的原因有三种：该事件发生时对应摄像头未启用录像；录像保留期已过，相应分段已被清除；或存储空间不足，Frigate 提前删除了这些分段以释放空间。请检查 Recording 配置 中的保留策略设置。 :::

时间轴、事件与 Detail：侧边面板的三种模式

History 主播放器旁有一个可切换的侧边面板（移动端为抽屉），通过切换开关可在三种模式间切换。在 RecordingView.tsx 中对应timelineType状态（"timeline" | "events" | "detail"，类型定义见 types/timeline.ts 的TimelineType）：

Timeline（时间轴）模式

• 展示所选摄像机的可拖动垂直时间轴；
• 时间轴中央的水平线表示运动（motion），线条越长代表该时刻运动越多；
• 审查条目以着色区域标出：红色表示警报（alert），橙色表示检测（detection）；
• 无着色背景的空白段表示该时段没有录像（代码中通过recordings/unavailable接口拉取无录像区间noRecordingRanges并渲染为间隔）。

在实现中，时间轴由 MotionReviewTimeline.tsx 组件渲染，运动数据来自review/activity/motion接口（按segmentDuration缩放比例请求），审查条目数据来自mainCameraReviewItems。

Events（事件）模式

• 以可滚动列表展示所选时间范围内该摄像机的审查条目；
• 点击某个条目会将播放器定位到该条目（代码中点击后执行manuallySetCurrentTime(review.start_time - REVIEW_PADDING, true)，即在条目开始时间前加一段REVIEW_PADDING缓冲再开始播放）；
• 该模式下会过滤掉纯运动（significant_motion）条目。

Detail（检视）模式

• 将侧边面板变为追踪细节检视器，详见下文 Detail 视图。

:::note 当你在选择导出范围时，侧边面板会临时切换回 Timeline 模式（代码中：exportRange != undefined && debugReplayRange != undefined ? timelineType : "timeline"），以便用时间轴手柄选择导出区间。 :::

拖动时间轴与预览

时间轴拖动与缩放

拖动时间轴上的手柄（handlebar）即可在时间中移动；主播放器与所有次要摄像头预览会同步拖动，保证一切保持同步。这在实现上表现为scrubbing状态下同时调用mainControllerRef.current?.scrubToTimestamp(currentTime)以及遍历previewRefs逐个调用controller.scrubToTimestamp(currentTime)（见 RecordingView.tsx）。

时间轴提供缩放按钮，可在三档缩放级别间切换（从粗粒度到细粒度分段）：

无录像的时段在时间轴上显示为间隔（gaps）。

次要预览（桌面端）

在桌面上，当有多个摄像头可用时，主播放器下方/侧方会出现一行次要预览，展示同一时刻其他摄像头的画面：

• 点击某个预览，该摄像头即成为主摄像头并定位到当前时间戳，从而可以跨摄像头追踪活动而不丢失进度（实现上为onSelectCamera将mainCamera切换为新摄像头并保持currentTime）；
• 次要预览使用IntersectionObserver懒加载（只加载可见的预览），并通过PreviewPlayer渲染；
• 移动端则使用摄像头抽屉（MobileCameraDrawer）来切换摄像头。

过滤与日历

History 支持按摄像头和日期过滤，过滤控件与 Review 中的行为一致（ReviewFilterGroup，参数filters={["cameras", "date", "general"]}）：

• 日期下划线：某天日期下有下划线，表示当天存在录像（来自recordings/summary接口的RecordingsSummary）；
• 彩色圆点：红色圆点表示当天有未审阅的警报，橙色圆点表示有未审阅的检测。

Detail 视图：追踪细节检视器

Detail模式将侧边面板转变为追踪细节检视器，对应前端组件 DetailStream.tsx：

审查条目卡片

每个审查条目对应一张卡片，展示：

• 严重程度（severity，通过圆点颜色区分：红色 alert / 橙色 detection，见ReviewGroup中的review.severity判断）；
• 开始时间；
• 涉及的对象标签（最多显示 5 个图标，iconLabels.slice(0, 5)）；
• 被追踪对象的数量（trackedObject计数，来自review.data.detections?.length或review.data?.objects?.length）；
• 时长（getDurationFromTimestamps(review.start_time, review.end_time)）。

当前播放位置对应的活动卡片会高亮（isActive时为shadow-selected outline-selected），点击卡片会定位到该条目。

展开查看对象生命周期

展开一张卡片，可以看到每个被追踪对象的生命周期（lifecycle）——每一行代表一个关键时刻（检测到、进入区域、变为活动、变为静止、离开等）。这些时刻来自TrackingDetailsSequence类型（见 types/timeline.ts），并带有随播放位置前进的进度线。

• 悬停某一行：显示该时刻的 score（置信度）、ratio（宽高比）与 area（面积，含像素数与百分比），见LifecycleItem中 Tooltip 的实现；
• 点击某一行：将视频定位到该精确时间戳（onSeek(item.timestamp + annotationOffset / 1000, false)，即检测时间加上注释偏移量换算为录像时间）。

Detail View 设置

面板底部是Detail View Settings（Detail 视图设置），包含两个选项：

1. 始终自动展开活动条目（Always Expand Active）：开关控制当前活动条目中的对象是否自动展开（useUserPersistence("detailStreamActiveExpanded", true)，默认开启）；
2. 注释偏移量（Annotation Offset）：一个用于微调的时间校正值，用于在摄像头快照与录像时间戳发生漂移时，让边界框（bounding-box）叠加层与录像画面精确对齐。对应组件为 AnnotationOffsetSlider.tsx。

:::tip 注释偏移量的取值范围 从前端常量 const.ts 可以看到：

• 最小值ANNOTATION_OFFSET_MIN = -10000（-10 秒）；
• 最大值ANNOTATION_OFFSET_MAX = 10000（+10 秒）；
• 步长ANNOTATION_OFFSET_STEP = 50（50 毫秒）。

偏移量的符号含义：检测时间戳与录像时间戳之间相差的毫秒数，正数表示录像时间晚于检测时间。拖动滑块（80ms 节流）会即时生效，reset可归零。管理员可以点击Save将偏移量保存到摄像头配置：底层通过PUT config/set?cameras.${camera}.detect.annotation_offset=${annotationOffset}（requires_restart: 0）写入配置，无需重启。该配置项在 config-form 的 detect 配置段 中标记为signed（允许负值）且属于高级字段。 :::

Actions 菜单（操作菜单）

在桌面上，Actions 菜单（胶片图标，对应 ActionsDropdown）集中了针对当前录像片段的操作：

此外，你还可以：

• 捕捉当前帧的即时快照（instant snapshot）；
• 将某一帧提交给 Frigate+（仅管理员）：用于改进模型，对应 FrigatePlusDialog。

AI 审查摘要

当配置了 生成式 AI 审查（Generative AI review） 时，Frigate 可以为审查条目生成标题、描述与威胁分类，并在你拖动 History 时间轴时呈现出来。带有 AI 摘要的审查条目会在以下位置显示摘要信息：

• 视频上方：当该条目出现在画面中时，播放器上方弹出摘要（对应GenAISummaryChip，桌面端在播放器区域渲染，移动端在时间轴顶部渲染）；
• Events 侧边面板：带摘要的条目在缩略图下方显示标题；
• Detail 侧边面板：条目卡片在追踪细节旁显示标题（见 DetailStream.tsx 中review.data.metadata?.title的渲染，带MdAutoAwesome图标）。

点击以上任意位置的摘要，会打开AI Analysis（AI 分析）对话框，展示生成的详细信息与该条目被标记的任何关注点（GenAISummaryDialog）。

从实现上看，只有当config?.cameras?.[mainCamera].review.genai?.enabled_in_config为真时，activeReviewItem（当前时间点处于其时间范围内的审查条目，判断带REVIEW_PADDING缓冲）才会被计算并显示摘要（见 RecordingView.tsx）。

小结与最佳实践

• History 用于"看录像"：当需要以全分辨率回放、逐帧核对事件细节、跨摄像头追踪同一时刻活动时使用 History；快速浏览"发生了什么"优先使用 Review，事后检索具体对象则使用 Explore。
• 时间轴是核心交互：拖动手柄实现主播放器与预览同步，三档缩放配合运动线条、审查条目色块与无录像间隔，可以快速定位目标时刻。
• Detail 检视器是深度工具：展开条目查看对象生命周期（score / ratio / area），配合注释偏移量校准边界框对齐；管理员可将校准值保存到摄像头配置detect.annotation_offset。
• 导出与分享：用 Export 保护重要片段免遭保留策略删除；用 Share Timestamp 生成内部时间戳链接；管理员还可使用 Debug Replay 验证检测流水线处理结果。

如需深入了解底层原理，可继续阅读：History 视图主组件 RecordingView.tsx、追踪细节检视器 DetailStream.tsx、运动时间轴 MotionReviewTimeline.tsx，以及录像保留配置 record.md。

【免费下载链接】frigateNVR with realtime local object detection for IP cameras项目地址: https://gitcode.com/GitHub_Trending/fr/frigate