frigate/CONFIG_SCHEMA_SUMMARY.md

Frigate Configuration Schema - Complete Analysis

This document provides a comprehensive overview of the entire Frigate configuration schema, extracted from all config model files.

Configuration Structure Overview

The Frigate configuration is hierarchical, with the root FrigateConfig object containing both global settings and per-camera configurations.

Top-Level Configuration Sections

1. System Configuration

   • version - Config version tracking
   • safe_mode - Safe mode flag
   • environment_vars - Environment variable definitions
   • logger - Logging configuration
   • database - Database path configuration

2. Authentication & Security

   • auth - Authentication settings (AuthConfig)
   • proxy - Proxy authentication settings (ProxyConfig)
   • tls - TLS configuration (TlsConfig)

3. Communication

   • mqtt - MQTT broker configuration (MqttConfig)
   • networking - Network settings including IPv6 (NetworkingConfig)
   • notifications - Global notification settings (NotificationConfig)

4. User Interface

   • ui - UI preferences (UIConfig)
   • camera_groups - Camera grouping for UI (Dict[str, CameraGroupConfig])

5. Detection & AI

   • detectors - Hardware detector configuration (Dict[str, BaseDetectorConfig])
   • model - Detection model settings (ModelConfig)
   • genai - Generative AI provider configuration (GenAIConfig)
   • classification - Object classification settings (ClassificationConfig)
   • semantic_search - Semantic search configuration (SemanticSearchConfig)
   • face_recognition - Face recognition settings (FaceRecognitionConfig)
   • lpr - License plate recognition settings (LicensePlateRecognitionConfig)

6. Global Camera Defaults

   • audio - Global audio detection settings (AudioConfig)
   • audio_transcription - Audio transcription settings (AudioTranscriptionConfig)
   • birdseye - Birdseye view configuration (BirdseyeConfig)
   • detect - Global detection settings (DetectConfig)
   • ffmpeg - Global FFmpeg settings (FfmpegConfig)
   • live - Live view settings (CameraLiveConfig)
   • motion - Global motion detection (MotionConfig)
   • objects - Global object tracking (ObjectConfig)
   • record - Global recording settings (RecordConfig)
   • review - Review settings (ReviewConfig)
   • snapshots - Global snapshot settings (SnapshotsConfig)
   • timestamp_style - Timestamp styling (TimestampStyleConfig)

7. Cameras

   • cameras - Per-camera configuration (Dict[str, CameraConfig])
   • go2rtc - Restream configuration (RestreamConfig with extra='allow')

8. Telemetry

   • telemetry - System statistics and monitoring (TelemetryConfig)

Camera Configuration (CameraConfig)

Each camera has extensive configuration options:

Camera Identity

• name - Camera identifier
• friendly_name - UI display name
• enabled - Enable/disable camera
• type - Camera type (generic, lpr)

Camera Features (all inherit from global defaults)

• audio - Audio detection (AudioConfig)
• audio_transcription - Audio transcription (AudioTranscriptionConfig)
• birdseye - Birdseye participation (BirdseyeCameraConfig)
• detect - Object detection (DetectConfig)
• face_recognition - Face recognition (CameraFaceRecognitionConfig)
• ffmpeg - FFmpeg settings (CameraFfmpegConfig) REQUIRED
• live - Live view streams (CameraLiveConfig)
• lpr - License plate recognition (CameraLicensePlateRecognitionConfig)
• motion - Motion detection (MotionConfig)
• objects - Object tracking and filtering (ObjectConfig)
• record - Recording settings (RecordConfig)
• review - Review configuration (ReviewConfig)
• semantic_search - Semantic triggers (CameraSemanticSearchConfig)
• snapshots - Snapshot settings (SnapshotsConfig)
• timestamp_style - Timestamp styling (TimestampStyleConfig)

Camera-Specific Settings

• best_image_timeout - Timeout for best image capture
• mqtt - MQTT image publishing (CameraMqttConfig)
• notifications - Notification settings (NotificationConfig)
• onvif - ONVIF/PTZ configuration (OnvifConfig)
• ui - UI display settings (CameraUiConfig)
• webui_url - Direct camera URL
• zones - Zone definitions (Dict[str, ZoneConfig])

Key Nested Configurations

FFmpeg Configuration (CameraFfmpegConfig)

The most critical camera setting with required inputs:

• inputs - List of camera input streams (List[CameraInput])
  • Each input has: path, roles (detect, record, audio), global_args, hwaccel_args, input_args
• path - FFmpeg binary path
• global_args - Global FFmpeg arguments
• hwaccel_args - Hardware acceleration (defaults to "auto")
• input_args - Input arguments (defaults to "preset-rtsp-generic")
• output_args - Output arguments per role (FfmpegOutputArgsConfig)
  • detect - Detect stream output args
  • record - Record stream output args
• retry_interval - Reconnection interval
• apple_compatibility - HEVC tag for Apple devices

Detection Configuration (DetectConfig)

• enabled - Enable detection
• width, height - Detection resolution
• fps - Detection frame rate (default: 5)
• min_initialized - Frames to initialize object
• max_disappeared - Frames before object expires
• stationary - Stationary object handling (StationaryConfig)
  • interval - Check interval
  • threshold - Frames to consider stationary
  • max_frames - Max tracking frames (StationaryMaxFramesConfig)
  • classifier - Use visual classifier
• annotation_offset - Timestamp offset

Object Tracking (ObjectConfig)

• track - List of objects to track (default: ["person"])
• filters - Per-object filters (Dict[str, FilterConfig])
  • min_area, max_area - Size filters (pixels or percentage)
  • min_ratio, max_ratio - Aspect ratio filters
  • threshold - Average confidence threshold
  • min_score - Minimum confidence
  • mask - Detection mask polygon
• mask - Global object mask
• genai - GenAI object analysis (GenAIObjectConfig)
  • enabled, use_snapshot, prompt, object_prompts
  • objects, required_zones, debug_save_thumbnails
  • send_triggers (GenAIObjectTriggerConfig)

Recording Configuration (RecordConfig)

• enabled - Enable recording
• sync_recordings - Sync on startup
• expire_interval - Cleanup interval
• continuous - Continuous recording retention (RecordRetainConfig)
• motion - Motion recording retention (RecordRetainConfig)
• detections - Detection event settings (EventsConfig)
  • pre_capture, post_capture - Buffer times
  • retain - Retention settings (ReviewRetainConfig)
• alerts - Alert event settings (EventsConfig)
• export - Export settings (RecordExportConfig)
• preview - Preview quality (RecordPreviewConfig)

Snapshot Configuration (SnapshotsConfig)

• enabled - Enable snapshots
• clean_copy - Clean image without overlays
• timestamp - Add timestamp overlay
• bounding_box - Add bounding box
• crop - Crop to object
• required_zones - Zone requirements
• height - Snapshot height
• retain - Retention settings (RetainConfig)
  • default - Default retention days
  • mode - Retain mode (all, motion, active_objects)
  • objects - Per-object retention
• quality - JPEG quality (0-100)

Zone Configuration (ZoneConfig)

• coordinates - Polygon coordinates (required)
• filters - Per-object zone filters (Dict[str, FilterConfig])
• distances - Real-world distances (4 values for quadrilateral)
• inertia - Frames to confirm object in zone
• loitering_time - Seconds to trigger loitering
• speed_threshold - Minimum speed
• objects - Objects that trigger zone

ONVIF/PTZ Configuration (OnvifConfig)

• host, port, user, password - ONVIF connection
• tls_insecure - Skip TLS verification
• ignore_time_mismatch - Ignore time sync issues
• autotracking - PTZ autotracking (PtzAutotrackConfig)
  • enabled - Enable autotracking
  • calibrate_on_startup - Calibrate on start
  • zooming - Zoom mode (disabled, absolute, relative)
  • zoom_factor - Zoom amount (0.1-0.75)
  • track - Objects to track
  • required_zones - Zones to trigger tracking
  • return_preset - Home preset
  • timeout - Return timeout
  • movement_weights - Calibration weights (6 floats)

Review Configuration (ReviewConfig)

• alerts - Alert review settings (AlertsConfig)
  • enabled, labels, required_zones, cutoff_time
• detections - Detection review settings (DetectionsConfig)
  • enabled, labels, required_zones, cutoff_time
• genai - GenAI descriptions (GenAIReviewConfig)
  • enabled, alerts, detections
  • additional_concerns, debug_save_thumbnails
  • preferred_language

Motion Detection (MotionConfig)

• enabled - Enable motion detection
• threshold - Detection threshold (1-255)
• lightning_threshold - Lightning detection (0.3-1.0)
• improve_contrast - Contrast enhancement
• contour_area - Contour area threshold
• delta_alpha - Delta blending
• frame_alpha - Frame blending
• frame_height - Processing height
• mask - Motion mask polygon
• mqtt_off_delay - MQTT update delay

Audio Configuration (AudioConfig)

• enabled - Enable audio detection
• max_not_heard - Timeout for audio events
• min_volume - Minimum volume threshold
• listen - Audio types to detect (default: bark, fire_alarm, scream, speech, yell)
• filters - Per-audio-type filters (Dict[str, AudioFilterConfig])
  • threshold - Confidence threshold
• num_threads - Detection threads

Advanced Features

Face Recognition (FaceRecognitionConfig)

Global settings:

• enabled, model_size, device
• unknown_score, detection_threshold, recognition_threshold
• min_area, min_faces, save_attempts
• blur_confidence_filter

Per-camera (CameraFaceRecognitionConfig):

• enabled, min_area

License Plate Recognition (LicensePlateRecognitionConfig)

Global settings:

• enabled, model_size, device
• detection_threshold, recognition_threshold
• min_area, min_plate_length
• format - Regex pattern
• match_distance - Fuzzy matching
• known_plates - Known plate list
• enhancement - Image enhancement (0-10)
• debug_save_plates
• replace_rules - Normalization rules (List[ReplaceRule])

Per-camera (CameraLicensePlateRecognitionConfig):

• enabled, expire_time, min_area, enhancement

Semantic Search (SemanticSearchConfig)

• enabled, reindex
• model - CLIP model (jinav1, jinav2)
• model_size, device

Per-camera triggers (CameraSemanticSearchConfig):

• triggers - Dict of trigger configs (Dict[str, TriggerConfig])
  • enabled, type (thumbnail, description)
  • data - Text phrase or image ID
  • threshold - Confidence threshold
  • actions - Actions to perform (notification)

Classification (ClassificationConfig)

• bird - Bird classification (BirdClassificationConfig)
  • enabled, threshold
• custom - Custom models (Dict[str, CustomClassificationConfig])
  • enabled, name, threshold
  • object_config - Object-based classification
    • objects, classification_type (sub_label, attribute)
  • state_config - State-based classification
    • cameras - Per-camera crops
    • motion - Motion-triggered
    • interval - Time-based interval

Generative AI (GenAIConfig)

• api_key, base_url
• model - Model name (default: gpt-4o)
• provider - Provider (openai, azure_openai, gemini, ollama)
• provider_options - Extra options

Detector Configuration

Supported Detector Types

• cpu (not recommended)
• cpu_tfl
• deepstack
• degirum
• edgetpu_tfl
• hailo8l
• memryx
• onnx
• openvino
• rknn
• synaptics
• teflon_tfl
• tensorrt
• zmq_ipc

Base Detector Fields (BaseDetectorConfig)

• type - Detector type (required)
• model - Model configuration (ModelConfig)
• model_path - Custom model path

Model Configuration (ModelConfig)

• path - Model file path (or plus:// for Frigate+ models)
• labelmap_path - Custom label map
• width, height - Model input size (default: 320x320)
• labelmap - Label map overrides
• attributes_map - Object attribute mappings
• input_tensor - Tensor shape (nchw, nhwc, hwnc, hwcn)
• input_pixel_format - Pixel format (rgb, bgr, yuv)
• input_dtype - Data type (float, float_denorm, int)
• model_type - Model architecture (dfine, rfdetr, ssd, yolox, yolonas, yolo-generic)

MQTT Configuration (MqttConfig)

• enabled - Enable MQTT
• host, port - Broker connection
• topic_prefix, client_id - MQTT topics
• stats_interval - Stats publishing interval
• user, password - Authentication (supports EnvString)
• tls_ca_certs, tls_client_cert, tls_client_key - TLS settings
• tls_insecure - Skip TLS verification
• qos - MQTT QoS level

Authentication (AuthConfig)

• enabled - Enable authentication
• reset_admin_password - Reset admin password
• cookie_name - JWT cookie name
• cookie_secure - Secure cookie flag
• session_length - Session duration (seconds)
• refresh_time - Refresh threshold (seconds)
• failed_login_rate_limit - Rate limiting
• trusted_proxies - Trusted proxy IPs
• hash_iterations - Password hashing iterations (default: 600000)
• roles - Custom role definitions (Dict[str, List[str]])
  • Keys: role name
  • Values: list of camera names (empty = all cameras)
  • Reserved roles: 'admin', 'viewer'

UI Configuration (UIConfig)

• timezone - Override system timezone
• time_format - Time format (browser, 12hour, 24hour)
• date_style - Date style (full, long, medium, short)
• time_style - Time style (full, long, medium, short)
• strftime_fmt - Custom strftime format
• unit_system - Measurement units (imperial, metric)

Timestamp Styling (TimestampStyleConfig)

• position - Position (tl, tr, bl, br)
• format - strftime format (default: "%m/%d/%Y %H:%M:%S")
• color - RGB color (ColorConfig)
  • red, green, blue (0-255)
• thickness - Line thickness
• effect - Effect type (solid, shadow)

Telemetry (TelemetryConfig)

• network_interfaces - Interfaces to monitor
• stats - Stats configuration (StatsConfig)
  • amd_gpu_stats - AMD GPU monitoring
  • intel_gpu_stats - Intel GPU monitoring
  • network_bandwidth - Network bandwidth monitoring
  • intel_gpu_device - SR-IOV device
• version_check - Check for updates

Live View (CameraLiveConfig)

• streams - Stream mappings (Dict[str, str])
  • Key: friendly name
  • Value: go2rtc stream name
• height - View height (default: 720)
• quality - Encoding quality (1-31, default: 8)

Camera Groups (CameraGroupConfig)

• cameras - Camera list (string or list)
• icon - Group icon (default: "generic")
• order - Sort order (default: 0)

Birdseye Configuration

Global (BirdseyeConfig)

• enabled - Enable birdseye
• mode - Mode (objects, motion, continuous)
• restream - RTSP restream
• width, height - Output resolution
• quality - Encoding quality (1-31)
• inactivity_threshold - Inactivity timeout
• layout - Layout settings (BirdseyeLayoutConfig)
  • scaling_factor - Scale factor (1.0-5.0)
  • max_cameras - Camera limit

Per-Camera (BirdseyeCameraConfig)

• enabled - Include camera
• mode - Camera mode
• order - Display order

Important Notes

1. Global vs Camera Settings: Most settings can be defined globally and overridden per-camera. The system performs a deep merge of global and camera-specific configs.

2. Required Fields:

   • mqtt (at root level)
   • cameras (at root level)
   • ffmpeg.inputs (per camera)
   • path (per input)
   • roles (per input, must include "detect")
   • coordinates (per zone)

3. EnvString: Many sensitive fields (passwords, API keys) support environment variable interpolation using {FRIGATE_VARNAME} syntax.

4. Preset Support: FFmpeg args support preset strings (e.g., "preset-rtsp-generic", "preset-record-generic-audio-aac") which are expanded automatically.

5. Hardware Acceleration: hwaccel_args: "auto" will automatically detect and configure hardware acceleration.

6. Percentage vs Pixels: Filter min_area and max_area accept integers (pixels) or floats 0.000001-0.99 (percentage of frame).

7. Coordinate Format: Masks and zones use relative coordinates (0.0-1.0) or absolute pixels. Format: "x1,y1,x2,y2,..." or list of "x,y" strings.

8. State Tracking: Many configs have enabled_in_config fields to track original config state vs runtime changes.

9. Validators: Many fields have complex validation rules enforced by Pydantic validators (see source code for details).

10. Extra Fields: The go2rtc config accepts any extra fields (extra='allow') and passes them through to go2rtc.

Configuration File Format

Frigate accepts both YAML and JSON configuration files. The system auto-detects the format based on:

1. File extension (.yaml, .yml, .json)
2. Content sniffing (looks for JSON structure)

Default config location: /config/config.yml

Schema Validation

The configuration uses Pydantic models with:

• Type validation
• Range validation (ge, le, gt, lt)
• Pattern matching (regex)
• Custom validators
• Field descriptions and titles
• Default values

All config models inherit from FrigateBaseModel which sets:

• extra="forbid" - No unknown fields allowed
• protected_namespaces=() - Allow "model_" field names

Complete Field Count

This schema documents over 500 individual configuration fields across:

• 70+ configuration classes
• 30+ enum types
• Multiple levels of nesting
• Global and per-camera settings
• Feature-specific configurations

Every field includes:

• Type information
• Default values
• Validation rules
• Description/title
• Required/optional status
• Nested object references