Frigate中文文档

主题

2025-12-16
2456
8.7m

音频检测器 ​

Frigate 自带音频检测功能，该功能直接在 CPU 上运行。相比图像物体/目标检测，音频检测的计算量要小得多，因此完全可以在 CPU 上高效运行。

配置 ​

音频事件通过检测特定类型的音频并创建事件来工作，当该类型音频在配置的时间内未被检测到时，则结束该事件。音频事件会在事件开始时保存快照，并在整个事件过程中保存录音。录音使用配置的录制保留设置进行保留。

启用音频事件 ​

可以为所有摄像头或仅特定摄像头启用音频事件。

yaml
audio: # <- 为所有摄像头启用音频事件
  enabled: True

cameras:
  front_camera:
    ffmpeg:
    ...
    audio:
      enabled: True # <- 可单独为front_camera启用音频事件

如果使用多个流，则必须在用于音频检测的流上设置audio功能，这可以是任何流，但该流必须包含音频。

NOTE

用于捕获音频的 ffmpeg 进程将与分配给摄像头的其他功能一起建立到摄像头的单独连接，因此建议使用 go2rtc 转流传输来实现此目的。更多信息请参阅转流传输文档。

yaml
cameras:
  front_camera:
    ffmpeg:
      inputs:
        - path: rtsp://.../main_stream
          roles:
            - record
        - path: rtsp://.../sub_stream # <- 此流必须启用音频
          roles:
            - audio
            - detect

配置最小音量 ​

音频检测器使用音量级别的方式与摄像头画面中的运动用于物体/目标检测的方式相同。这意味着除非音频音量高于配置的水平，否则 Frigate 不会运行音频检测以减少资源使用。不同摄像头型号的音量水平可能有很大差异，因此进行测试以了解音量水平非常重要。在 Frigate 网页的调试页面中，对于开启了audio功能的摄像头，会显示一个音频选项卡，其中会以图表形式展示当前音量水平。min_volume 参数应设置为运行音频检测所需的最低 RMS​ 音量。

提示

音频被视为画面变动录制（motion），这意味着当record -> retain -> mode设置为motion时，任何声音音量小于最小音量（min_volume）的时候，该摄像头的录制片段都将被保留。

配置音频事件 ​

内置音频模型可以检测500 多种不同类型的音频，其中许多并不实用。默认情况下会开启bark(狗叫)、fire_alarm(火警)、scream(尖叫)、speech(说话)和yell(喊叫)这几种音频事件，当然你也可以根据自己的需求进行调整。

yaml
audio:
  enabled: True
  listen:
    - bark
    - fire_alarm
    - scream
    - speech
    - yell

音频转录 ​

Frigate 支持完全本地化的音频转录，可使用 sherpa-onnx 或通过 faster-whisper 调用 OpenAI 的开源 Whisper 模型。该功能的目标是支持对谈话的音频事件进行语义搜索。
Frigate 并非设计成为持续、全自动的语音转录功能，因为自动转录所有语音（或将大量音频事件排入队列等待转录）会消耗大量 CPU（或 GPU）资源，在大多数系统上并不现实。因此，事件的转录需由用户在页面或 API 中手动触发，而非在后台持续运行。

转录的准确性在很大程度上取决于摄像头麦克风的质量与录音环境。许多摄像头使用廉价麦克风，而且说话者距离、音频比特率过低或背景噪声都会显著降低转录质量。如果需要更高的准确率、更稳健的长队列支持或大规模自动转录，建议使用 HTTP API 配合自动化平台以及云端转录服务。

配置 ​

要启用转录功能，需在配置中开启。注意：必须同时按上述说明启用音频检测，才能使用音频转录功能。

yaml
audio_transcription: 
  enabled: True
  device: ...
  model_size: ...

可在摄像头级别禁用选定摄像头的音频转录：

yaml
cameras:
  back_yard: # <- 此处为摄像头名称
    ... # 此处为省略的其他配置项内容
    audio_transcription: 
      enabled: False

NOTE

必须使用并配置音频检测（如上所述），才能使用音频转录功能。

可在全局级别设置的可选配置参数包括：

  • enabled：启用或禁用音频转录功能。

    • 默认值：False
    • 建议仅在全局级别配置功能，在具体摄像头级别启用。

  • device：运行转录与翻译模型所用的设备。

    • 默认值：CPU
    • 可选 CPU 或 GPU。sherpa-onnx 模型较为轻量，只能在 CPU 上运行；而whisper模型可在 GPU 上运行，但仅支持 CUDA硬件。

  • model_size：用于实时转录的模型规模。

    • 默认值：small
    • 可选 small 或 large。small 使用 sherpa-onnx 模型，速度快、轻量、始终在 CPU 上运行，但准确度不如 whisper 模型。
    • 此配置仅适用于实时转录。已录制的谈话事件始终使用不同的 whisper 模型（如可用 device: GPU，可在 CUDA 硬件上加速）。

  • language：定义 whisper 用于翻译谈话音频事件的语言（仅在使用 large 模型时对实时音频有效）。

摄像头级别唯一有效的字段是 enabled。

实时转录 ​

Frigate 网页的单摄像头实时预览页面支持对定义了 audio 功能的视频流进行实时音频转录。使用 启用/禁用实时音频转录 按钮或开关来切换转录处理。当检测到语音时，网页会在摄像头画面上覆盖一个黑色文本框并显示文字。
MQTT 主题 frigate/<camera_name>/audio/transcription 也会实时更新转录文本。

结果可能因以下因素出现误差：

  • 摄像头麦克风质量差
  • 声源距离麦克风较远
  • 摄像头音频比特率设置过低
  • 背景噪声
  • 使用 small 模型 —— 虽然快，但对低质量音频的准确度有限

如果声源离摄像头较近且背景噪声很小，可使用 small 模型。
若有 CUDA 硬件，可尝试在 GPU 上运行 large 的 whisper 模型。虽然性能不及 sherpa-onnx 的 small 模型快，但实时转录准确度要高得多。在 CPU 上运行 large 模型可能会太慢，无法满足实时需求。

谈话音频事件的转录与翻译 ​

在浏览中的任何谈话事件，可通过目标追踪详情面板的转录 按钮进行转录或翻译。

要对历史事件使用转录与翻译功能，必须启用音频检测，并在配置中将谈话定义为要监听的音频类型。要将谈话事件翻译成所选语言，请在配置中设置 language 参数并使用正确的 https://github.com/openai/whisper/blob/main/whisper/tokenizer.py#L10。

转录/翻译后的语音会出现在跟踪对象详情面板的描述框中。如果启用了语义搜索，将为转录文本生成嵌入向量，并可通过描述搜索类型完全检索。

NOTE

一次只能转录一个谈话事件。Frigate 不会自动转录谈话事件，也未实现长时转录模型推理的队列。

已录制的谈话事件始终使用 whisper 模型，不受 model_size 配置影响。在没有支持的 Nvidia GPU 的情况下，生成长谈话事件的转录可能需要较长时间，请耐心等待。

常见问题 ​

  1. 为什么 Frigate 不自动转录所有谈话事件？
    Frigate 并未实现语音转录的队列机制，且添加该功能并不简单。一个合适的队列需要实现背压、优先级、内存/磁盘缓冲、重试逻辑、崩溃恢复，以及防止事件处理速度跟不上时无限增长的防护措施。这对大多数实际环境来说会带来巨大复杂性，而收益却很低，因为大部分事件只是低价值的噪声。

    由于转录是串行执行（一次一个事件），而语音事件的产生速度可能远快于处理速度，开启自动转录会迅速形成不断增长的积压，并拖慢核心功能。考虑到涉及的工程量与风险，这对多数部署（通常在低功耗边缘硬件上）实用价值非常有限。

    如果你听到重要且值得保存/索引的语音，只需在浏览中对该谈话事件按下转录按钮。这样既明确、可靠，又完全在你的控制之下。

    未来版本正考虑支持外部 whisper Docker 容器的转录选项，这样单一转录服务可被 Frigate 与其他应用（如 Home Assistant Voice）共享，并在有更强机器时运行。

  2. 为什么不保存实时转录文本并用于谈话事件？ 无法保证谈话事件是由正好经过转录模型的音频生成的。实时转录与谈话事件生成是两个独立的异步过程。即使两者都正确配置，试图将语音事件的精确起止时间与模型当时处理的音频对齐也是不可靠的。

    自动保存这些数据往往会导致错位、残缺或不相关的转录，同时仍需承担转录带来的 CPU、存储与隐私成本。因此 Frigate 将转录视为由用户主动触发的操作，而非每个谈话事件的自动进行。

最近更新