frigate-configurator

Frigate NVR 設定エキスパート

Frigate NVR の設定を包括的に支援し、最適化された YAML の生成、検出器のセットアップ、トラブルシューティングを行います。

始める前に

このスキルを使うと、よくあるエラーを 12 件以上防ぎ、Frigate の設定にかかるトークンを約 60% 節約できます。

指標	スキルなし	スキルあり
セットアップ時間	2～4 時間	30～45 分
よくあるエラー	12 件以上	0 件
トークン使用量	約 15,000	約 6,000

このスキルで防止できる既知の問題

1. 共有メモリの割り当て不足によるバスエラー
2. 解像度の設定ミスによる、緑色または歪んだ映像
3. SQLite でネットワークストレージを使用した場合のデータベースロックエラー
4. 音声のデフォルト除去による録画音声の欠落
5. Docker 内で localhost を使用した場合の MQTT 接続失敗
6. デバイスのパススルー設定不足による Coral TPU の未検出
7. ハードウェアアクセラレーションの設定不足による CPU 使用率の上昇
8. タイムスタンプ上のモーションマスク不足による誤検知
9. required_zones の設定ミスによるアラートの未発報
10. トランスコードなしで h265 ストリームを使用した場合の録画破損
11. STUN 設定不足による go2rtc の WebRTC 接続失敗
12. detect ストリームの解像度間違いによる物体検出漏れ

クイックスタート

ステップ 1：最小限の設定を作成する

mqtt:
  enabled: false

cameras:
  front_door:
    ffmpeg:
      inputs:
        - path: rtsp://user:[email protected]:554/stream1
          roles:
            - detect
    detect:
      width: 1280
      height: 720
      fps: 5

重要な理由： 複雑な設定を追加する前に、最小限の設定でカメラの接続を確認します。Frigate では detect ストリームの役割を明示的に割り当てる必要があります。

ステップ 2：ハードウェアアクセラレーション対応の検出器を追加する

detectors:
  coral:
    type: edgetpu
    device: usb

# OR for Intel with OpenVINO:
detectors:
  ov:
    type: openvino
    device: GPU

重要な理由： 本番環境での CPU 検出は推奨されません。USB Coral TPU を 1 台追加するだけでも、CPU 使用率が大幅に下がり、検出の遅延が改善されます。

ステップ 3：保持期間を設定して録画を有効にする

record:
  enabled: true
  retain:
    days: 1
    mode: motion
  alerts:
    retain:
      days: 14
  detections:
    retain:
      days: 7

cameras:
  front_door:
    ffmpeg:
      inputs:
        - path: rtsp://user:[email protected]:554/stream1
          roles:
            - detect
        - path: rtsp://user:[email protected]:554/stream2
          roles:
            - record

重要な理由： パフォーマンスを最適化するには、detect（低解像度）と record（高解像度）で別々のストリームを使用します。保持モードを設定すると、ストレージがいっぱいになるのを防げます。

重要なルール

必ず行うこと

• width と height には、カメラの実際の解像度（VLC で確認）を設定します
• detect の FPS は 5～10 に設定します（高すぎるとリソースを浪費し、低すぎるとイベントを見逃します）
• detect（サブストリーム）と record（メインストリーム）には別々のストリームを使用します
• Docker で十分な shm-size を割り当てます（カメラ 1 台あたり最低 64MB）
• タイムスタンプのオーバーレイや常に動きのある領域には、モーションマスクを作成します
• 認証情報には環境変数を使用します：{FRIGATE_RTSP_PASSWORD}
• Frigate の設定に追加する前に、VLC で RTSP URL をテストします

絶対に行わないこと

• Docker コンテナ内の MQTT に localhost や 127.0.0.1 を使用しないでください
• detect の解像度を 1280x720 より高く設定しないでください（検出器の能力を浪費します）
• 保持ポリシーを指定せずに録画を有効にしないでください
• データベースの保存場所を移さずに、ネットワークストレージを /media/frigate にマウントしないでください
• 物体検出で複数の検出器タイプを併用しないでください（例：Coral + OpenVINO）
• 明示的に設定せずに UDP RTSP トランスポートを使用しないでください（デフォルトは TCP です）

よくある間違い

誤り：

cameras:
  cam1:
    ffmpeg:
      inputs:
        - path: rtsp://192.168.1.100/stream
          roles:
            - detect
            - record
    detect:
      width: 1920
      height: 1080
      fps: 30

正しい例：

cameras:
  cam1:
    ffmpeg:
      inputs:
        - path: rtsp://192.168.1.100/substream
          roles:
            - detect
        - path: rtsp://192.168.1.100/mainstream
          roles:
            - record
    detect:
      width: 1280
      height: 720
      fps: 5

理由： 検出に 1080p@30fps を使用すると、リソースを浪費します。検出は 720p 以下、5fps で最も効果的に機能します。検出には必ずカメラのサブストリームを、録画にはメインストリームを使用してください。

既知の問題の予防

問題	根本原因	解決策
バスエラー	共有メモリ不足	docker-compose に shm-size: 256mb を設定します
データベースのロック	ネットワークストレージ上の SQLite	database.path: /config/frigate.db を使用します
映像が緑色になる／乱れる	設定の解像度が正しくない	カメラの実際の出力解像度に合わせます
録画に音声がない	デフォルトで音声が削除される	preset-record-generic-audio-aac を使用します
MQTT 接続に失敗する	Docker 内の localhost	代わりにホストの IP アドレスを使用します
Coral が検出されない	デバイスのパススルーが設定されていない	Docker のデバイスに /dev/bus/usb を追加します
CPU 使用率が高い	hwaccel が設定されていない	適切なプリセット（vaapi/qsv/nvidia）を追加します
アラートが表示されない	required_zones が設定されていない	review.alerts.required_zones でゾーンを設定します
UDP ストリームに失敗する	Frigate では TCP がデフォルト	入力引数に preset-rtsp-udp を追加します

設定リファレンス

config.yml の構造

# MQTT Configuration (optional but recommended)
mqtt:
  enabled: true
  host: 192.168.1.50
  port: 1883
  user: "{FRIGATE_MQTT_USER}"
  password: "{FRIGATE_MQTT_PASSWORD}"

# Detector Configuration
detectors:
  coral:
    type: edgetpu
    device: usb  # or pci for M.2/PCIe

# Global Object Settings
objects:
  track:
    - person
    - car
    - dog
    - cat
  filters:
    person:
      min_area: 5000
      max_area: 100000
      threshold: 0.7

# Recording Settings
record:
  enabled: true
  retain:
    days: 1
    mode: motion
  alerts:
    retain:
      days: 14
  detections:
    retain:
      days: 7

# Snapshot Settings
snapshots:
  enabled: true
  retain:
    default: 7

# Camera Configuration
cameras:
  front_door:
    enabled: true
    ffmpeg:
      inputs:
        - path: "rtsp://{FRIGATE_RTSP_USER}:{FRIGATE_RTSP_PASSWORD}@192.168.1.100:554/stream1"
          input_args: preset-rtsp-restream
          roles:
            - detect
        - path: "rtsp://{FRIGATE_RTSP_USER}:{FRIGATE_RTSP_PASSWORD}@192.168.1.100:554/stream0"
          input_args: preset-rtsp-restream
          roles:
            - record
      output_args:
        record: preset-record-generic-audio-aac
    detect:
      width: 1280
      height: 720
      fps: 5
    motion:
      mask:
        - 0,0,200,0,200,100,0,100  # Timestamp area
    zones:
      front_yard:
        coordinates: 100,500,400,500,400,720,100,720
        objects:
          - person
          - car
    review:
      alerts:
        required_zones:
          - front_yard

主な設定：

• detect.fps：ほとんどのカメラで 5 が最適です（検出器の負荷を軽減します）
• detect.width/height：カメラの実際のサブストリーム解像度に合わせる必要があります
• record.retain.mode：ストレージを節約するには motion または active_objects を使用します
• motion.mask：ポリゴンをカンマ区切りの座標で定義します
• zones.coordinates：バウンディングボックスの下部中央で、ゾーン内に存在するかどうかを判定します

ハードウェアアクセラレーションのプリセット

Intel（第 6 世代以降）

# For Intel gen8+ (prefer QSV)
ffmpeg:
  hwaccel_args: preset-intel-qsv-h264  # or preset-intel-qsv-h265

# For Intel gen1-gen7 (use VAAPI)
ffmpeg:
  hwaccel_args: preset-vaapi

NVIDIA GPU

ffmpeg:
  hwaccel_args: preset-nvidia

NVIDIA Container Toolkit が必要です：

# docker-compose.yml
services:
  frigate:
    runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all

AMD GPU

ffmpeg:
  hwaccel_args: preset-vaapi

# docker-compose.yml
environment:
  - LIBVA_DRIVER_NAME=radeonsi

Raspberry Pi

# Raspberry Pi 4/5
ffmpeg:
  hwaccel_args: preset-rpi-64-h264  # or preset-rpi-64-h265

必要な設定：/boot/config.txt の gpu_mem=128 と、Docker でのデバイスマッピング。

オブジェクト検出器の種類

USB Coral TPU

detectors:
  coral:
    type: edgetpu
    device: usb  # Single USB Coral
    # device: usb:0  # First of multiple USB Corals

Docker のデバイスマッピング：

devices:
  - /dev/bus/usb:/dev/bus/usb

M.2/PCIe Coral TPU

detectors:
  coral:
    type: edgetpu
    device: pci
    # device: pci:0  # First of multiple PCIe Corals

OpenVINO（Intel）

detectors:
  ov:
    type: openvino
    device: GPU  # or CPU

model:
  path: /openvino-model/ssdlite_mobilenet_v2.xml
  width: 300
  height: 300

ONNX（マルチ GPU）

detectors:
  onnx:
    type: onnx
    # Automatically uses: ROCm (AMD), OpenVINO (Intel), TensorRT (NVIDIA)

高度な機能

ゾーンベースの速度推定

zones:
  driveway:
    coordinates: 100,500,400,500,400,720,100,720
    distances:
      - "100,500|400,500|20ft"  # 20 feet between points
    speed:
      threshold: 15  # Minimum mph to register

音声検出

audio:
  enabled: true
  listen:
    - bark
    - fire_alarm
    - scream
    - speech

cameras:
  front_door:
    ffmpeg:
      inputs:
        - path: rtsp://camera/stream
          roles:
            - audio

GenAI イベントの説明

genai:
  enabled: true
  provider: ollama
  base_url: http://192.168.1.100:11434
  model: llava

顔認識（Frigate+）

face_recognition:
  enabled: true
  threshold: 0.6

cameras:
  front_door:
    detect:
      width: 1280  # Higher res improves face detection

ナンバープレート認識

lpr:
  enabled: true

cameras:
  driveway:
    lpr:
      enabled: true

go2rtc との統合

go2rtc:
  streams:
    front_door:
      - rtsp://user:[email protected]:554/stream1
      - "ffmpeg:front_door#video=copy#audio=opus"
  webrtc:
    candidates:
      - 192.168.1.50:8555
      - stun:8555

Docker Compose テンプレート

services:
  frigate:
    container_name: frigate
    image: ghcr.io/blakeblackshear/frigate:stable
    restart: unless-stopped
    shm_size: "256mb"
    devices:
      - /dev/bus/usb:/dev/bus/usb  # USB Coral
      - /dev/dri/renderD128:/dev/dri/renderD128  # Intel GPU
    volumes:
      - ./config:/config
      - ./storage:/media/frigate
      - type: tmpfs
        target: /tmp/cache
        tmpfs:
          size: 1000000000
    ports:
      - "8971:8971"  # Web UI
      - "8554:8554"  # RTSP feeds
      - "8555:8555/tcp"  # WebRTC
      - "8555:8555/udp"  # WebRTC
    environment:
      FRIGATE_RTSP_USER: admin
      FRIGATE_RTSP_PASSWORD: ${RTSP_PASSWORD}
      FRIGATE_MQTT_USER: frigate
      FRIGATE_MQTT_PASSWORD: ${MQTT_PASSWORD}

同梱リソース

テンプレート

templates/ にあります：

• docker-compose.yml - 本番環境向けの compose ファイル
• config-minimal.yml - 最小構成のスターター設定
• config-full.yml - 全機能を備えた設定テンプレート

リファレンス

references/ にあります：

• detector-comparison.md - 検出器のパフォーマンス比較
• ffmpeg-presets.md - 使用可能なすべての FFmpeg プリセット
• mqtt-topics.md - MQTT トピックのリファレンス

スクリプト

scripts/ にあります：

• validate-config.sh - 適用前に設定の構文を検証します

依存関係

必須

パッケージ	バージョン	用途
Docker	20.10+	コンテナランタイム
docker-compose	2.0+	サービスのオーケストレーション

オプション

パッケージ	バージョン	用途
NVIDIA Container Toolkit	最新	NVIDIA GPU のサポート
Coral Edge TPU runtime	最新	Coral TPU のサポート

公式ドキュメント

• Frigate のドキュメント
• 設定リファレンス
• はじめに
• トラブルシューティング FAQ

トラブルシューティング

カメラがオフラインと表示される

症状： カメラの fps が 0 と表示され、Web UI にオフライン状態が表示される

解決策：

# Test RTSP URL directly
ffprobe -rtsp_transport tcp "rtsp://user:pass@ip:554/stream"

# Check Docker logs
docker logs frigate 2>&1 | grep -i "camera_name"

CPU 使用率が高い

症状： CPU 使用率が常に 80% を超え、システムの応答が遅くなる

解決策：

1. ハードウェアアクセラレーションを有効にします（上記のプリセットを参照）
2. detect fps を 10 から 5 に下げます
3. detect の解像度を 720p 以下に下げます
4. オブジェクト検出用に Coral TPU を追加します

オブジェクトが検出されない

症状： 動きは検出されますが、オブジェクトイベントが作成されません

解決方法：

1. 検出器が設定され、実行中であることを確認します。/api/stats を確認してください
2. オブジェクトフィルターの条件が厳しすぎないか確認します（min_area、threshold）
3. 検出ストリームの解像度が正しいことを確認します
4. オブジェクトのリストに目的の種類が含まれていることを確認します

録画が機能しない

症状： イベントは表示されますが、録画を利用できません

解決方法：

# Ensure record role is assigned
cameras:
  cam1:
    ffmpeg:
      inputs:
        - path: rtsp://camera/stream
          roles:
            - record  # Must be explicitly set
    record:
      enabled: true  # Must be true

セットアップのチェックリスト

Frigate をデプロイする前に、次の項目を確認してください。

• Docker と docker-compose がインストールされている
• RTSP URL を VLC でテスト済み（実際の解像度をメモしてください）
• 環境変数用のカメラ認証情報を用意済み
• ストレージボリュームに十分な空き容量がある（100GB 以上を推奨）
• 共有メモリーサイズが設定されている（カメラ 1 台あたり最低 64MB）
• ハードウェアアクセラレーションデバイスがマッピングされている（該当する場合）
• Coral TPU デバイスがマッピングされている（使用する場合）
• MQTT ブローカーにアクセスできる（Home Assistant と連携する場合）
• Web UI 用のポート 8971 が使用可能
• ファイアウォールで必要なポート（ストリーミング用の 8554、8555）が許可されている