--- name: frigate-configurator description: Configure Frigate NVR with optimized YAML, object detection, recording, zones, and hardware acceleration. Use when setting up Frigate cameras, troubleshooting detection issues, configuring Coral TPU/OpenVINO, or integrating with Home Assistant. --- # Frigate NVR Configuration Expert > Comprehensive Frigate NVR configuration assistance with optimized YAML generation, detector setup, and troubleshooting. ## BEFORE YOU START **This skill prevents 12+ common errors and saves ~60% tokens on Frigate configuration.** | Metric | Without Skill | With Skill | |--------|--------------|------------| | Setup Time | 2-4 hours | 30-45 min | | Common Errors | 12+ | 0 | | Token Usage | ~15,000 | ~6,000 | ### Known Issues This Skill Prevents 1. Bus errors from insufficient shared memory allocation 2. Green/distorted video from incorrect resolution configuration 3. Database locked errors when using network storage for SQLite 4. Missing audio in recordings due to default audio stripping 5. MQTT connection failures from using localhost in Docker 6. Coral TPU not detected due to missing device passthrough 7. High CPU usage from missing hardware acceleration 8. False positives from missing motion masks on timestamps 9. No alerts triggered due to misconfigured required_zones 10. Recording corruption from h265 streams without transcoding 11. go2rtc WebRTC failures from missing STUN configuration 12. Object detection misses from wrong detect stream resolution ## Quick Start ### Step 1: Create Minimal Configuration ```yaml mqtt: enabled: false cameras: front_door: ffmpeg: inputs: - path: rtsp://user:pass@192.168.1.100:554/stream1 roles: - detect detect: width: 1280 height: 720 fps: 5 ``` **Why this matters:** Start with the absolute minimum to verify camera connectivity before adding complexity. Frigate requires explicit detect stream role assignment. ### Step 2: Add Hardware-Accelerated Detector ```yaml detectors: coral: type: edgetpu device: usb # OR for Intel with OpenVINO: detectors: ov: type: openvino device: GPU ``` **Why this matters:** CPU detection is not recommended for production. Even a single USB Coral TPU dramatically reduces CPU usage and improves detection latency. ### Step 3: Enable Recording with Retention ```yaml record: enabled: true retain: days: 1 mode: motion alerts: retain: days: 14 detections: retain: days: 7 cameras: front_door: ffmpeg: inputs: - path: rtsp://user:pass@192.168.1.100:554/stream1 roles: - detect - path: rtsp://user:pass@192.168.1.100:554/stream2 roles: - record ``` **Why this matters:** Use separate streams for detect (low-res) and record (high-res) to optimize performance. Retention modes prevent storage from filling up. ## Critical Rules ### Always Do - Use `width` and `height` that match your camera's ACTUAL resolution (verify with VLC) - Set `detect` fps between 5-10 (higher wastes resources, lower misses events) - Use separate streams for `detect` (sub-stream) and `record` (main stream) - Allocate adequate `shm-size` in Docker (64MB minimum per camera) - Create motion masks for timestamp overlays and areas with constant motion - Use environment variables for credentials: `{FRIGATE_RTSP_PASSWORD}` - Test RTSP URLs in VLC first before adding to Frigate config ### Never Do - Never use `localhost` or `127.0.0.1` for MQTT inside Docker containers - Never set detect resolution higher than 1280x720 (wastes detector capacity) - Never enable recording without specifying retention policy - Never mount `/media/frigate` on network storage without relocating database - Never mix multiple detector types for object detection (e.g., Coral + OpenVINO) - Never use UDP RTSP transport without explicit configuration (TCP is default) ### Common Mistakes **Wrong:** ```yaml cameras: cam1: ffmpeg: inputs: - path: rtsp://192.168.1.100/stream roles: - detect - record detect: width: 1920 height: 1080 fps: 30 ``` **Correct:** ```yaml 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 ``` **Why:** Using 1080p@30fps for detection wastes resources. Detection works best at 720p or lower at 5fps. Always use the camera's sub-stream for detection and main stream for recording. ## Known Issues Prevention | Issue | Root Cause | Solution | |-------|-----------|----------| | Bus Error | Insufficient shared memory | Set `shm-size: 256mb` in docker-compose | | Database Locked | SQLite on network storage | Use `database.path: /config/frigate.db` | | Green/Distorted Video | Wrong resolution in config | Match camera's actual output resolution | | No Audio in Recordings | Default audio removal | Use `preset-record-generic-audio-aac` | | MQTT Connection Failed | localhost in Docker | Use host IP address instead | | Coral Not Detected | Missing device passthrough | Add `/dev/bus/usb` to Docker devices | | High CPU Usage | Missing hwaccel | Add appropriate preset (vaapi/qsv/nvidia) | | Missing Alerts | No required_zones | Configure zones with review.alerts.required_zones | | UDP Stream Failures | TCP is default in Frigate | Add `preset-rtsp-udp` to input args | ## Configuration Reference ### config.yml Structure ```yaml # 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 ``` **Key settings:** - `detect.fps`: 5 is optimal for most cameras (reduces detector load) - `detect.width/height`: Must match actual camera sub-stream resolution - `record.retain.mode`: Use `motion` or `active_objects` to save storage - `motion.mask`: Define polygons as comma-separated coordinates - `zones.coordinates`: Bottom-center of bounding box determines zone presence ## Hardware Acceleration Presets ### Intel (6th Gen+) ```yaml # 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 ```yaml ffmpeg: hwaccel_args: preset-nvidia ``` Requires NVIDIA Container Toolkit: ```yaml # docker-compose.yml services: frigate: runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICES=all ``` ### AMD GPU ```yaml ffmpeg: hwaccel_args: preset-vaapi # docker-compose.yml environment: - LIBVA_DRIVER_NAME=radeonsi ``` ### Raspberry Pi ```yaml # Raspberry Pi 4/5 ffmpeg: hwaccel_args: preset-rpi-64-h264 # or preset-rpi-64-h265 ``` Requires: `gpu_mem=128` in `/boot/config.txt` and device mapping in Docker. ## Object Detector Types ### USB Coral TPU ```yaml detectors: coral: type: edgetpu device: usb # Single USB Coral # device: usb:0 # First of multiple USB Corals ``` Docker device mapping: ```yaml devices: - /dev/bus/usb:/dev/bus/usb ``` ### M.2/PCIe Coral TPU ```yaml detectors: coral: type: edgetpu device: pci # device: pci:0 # First of multiple PCIe Corals ``` ### OpenVINO (Intel) ```yaml detectors: ov: type: openvino device: GPU # or CPU model: path: /openvino-model/ssdlite_mobilenet_v2.xml width: 300 height: 300 ``` ### ONNX (Multi-GPU) ```yaml detectors: onnx: type: onnx # Automatically uses: ROCm (AMD), OpenVINO (Intel), TensorRT (NVIDIA) ``` ## Advanced Features ### Zone-Based Speed Estimation ```yaml 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 Detection ```yaml audio: enabled: true listen: - bark - fire_alarm - scream - speech cameras: front_door: ffmpeg: inputs: - path: rtsp://camera/stream roles: - audio ``` ### GenAI Event Descriptions ```yaml genai: enabled: true provider: ollama base_url: http://192.168.1.100:11434 model: llava ``` ### Face Recognition (Frigate+) ```yaml face_recognition: enabled: true threshold: 0.6 cameras: front_door: detect: width: 1280 # Higher res improves face detection ``` ### License Plate Recognition ```yaml lpr: enabled: true cameras: driveway: lpr: enabled: true ``` ## go2rtc Integration ```yaml go2rtc: streams: front_door: - rtsp://user:pass@192.168.1.100:554/stream1 - "ffmpeg:front_door#video=copy#audio=opus" webrtc: candidates: - 192.168.1.50:8555 - stun:8555 ``` ## Docker Compose Template ```yaml 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} ``` ## Bundled Resources ### Templates Located in `templates/`: - [`docker-compose.yml`](templates/docker-compose.yml) - Production-ready compose file - [`config-minimal.yml`](templates/config-minimal.yml) - Minimal starter config - [`config-full.yml`](templates/config-full.yml) - Full-featured config template ### References Located in `references/`: - [`detector-comparison.md`](references/detector-comparison.md) - Detector performance comparison - [`ffmpeg-presets.md`](references/ffmpeg-presets.md) - All available FFmpeg presets - [`mqtt-topics.md`](references/mqtt-topics.md) - MQTT topic reference ### Scripts Located in `scripts/`: - `validate-config.sh` - Validate config syntax before applying ## Dependencies ### Required | Package | Version | Purpose | |---------|---------|---------| | Docker | 20.10+ | Container runtime | | docker-compose | 2.0+ | Service orchestration | ### Optional | Package | Version | Purpose | |---------|---------|---------| | NVIDIA Container Toolkit | Latest | NVIDIA GPU support | | Coral Edge TPU runtime | Latest | Coral TPU support | ## Official Documentation - [Frigate Documentation](https://docs.frigate.video/) - [Configuration Reference](https://docs.frigate.video/configuration/reference) - [Getting Started Guide](https://docs.frigate.video/guides/getting_started) - [Troubleshooting FAQs](https://docs.frigate.video/troubleshooting/faqs) ## Troubleshooting ### Camera Shows Offline **Symptoms:** Camera fps shows 0, web UI shows offline status **Solution:** ```bash # 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" ``` ### High CPU Usage **Symptoms:** CPU consistently above 80%, system becomes unresponsive **Solution:** 1. Enable hardware acceleration (see presets above) 2. Reduce detect fps from 10 to 5 3. Lower detect resolution to 720p or below 4. Add Coral TPU for object detection ### No Objects Detected **Symptoms:** Motion detected but no object events created **Solution:** 1. Verify detector is configured and running: check `/api/stats` 2. Check object filters aren't too restrictive (min_area, threshold) 3. Ensure detect stream resolution is correct 4. Verify objects list includes desired types ### Recording Not Working **Symptoms:** Events show but no recordings available **Solution:** ```yaml # 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 ``` ## Setup Checklist Before deploying Frigate, verify: - [ ] Docker and docker-compose installed - [ ] RTSP URLs tested in VLC (note actual resolution) - [ ] Camera credentials ready for environment variables - [ ] Storage volume has adequate space (100GB+ recommended) - [ ] Shared memory size configured (64MB per camera minimum) - [ ] Hardware acceleration device mapped (if applicable) - [ ] Coral TPU device mapped (if using) - [ ] MQTT broker accessible (if integrating with Home Assistant) - [ ] Port 8971 available for web UI - [ ] Firewall allows required ports (8554, 8555 for streaming)