How to Configure Recording Retention Based on Detected Objects in Frigate

Set retain.mode to active_objects in your camera's record configuration under detections or alerts to keep only recordings containing detected objects, then specify your retention period with the days parameter.

Frigate is an open-source network video recorder (NVR) with real-time AI object detection that allows you to configure recording retention based on detected objects to optimize storage usage. By leveraging the active_objects retain mode defined in frigate/config/camera/record.py, you ensure the system preserves only video segments containing verified detections rather than continuous footage. This article explains how to implement this retention policy using the configuration schema and processing logic from the Frigate source code.

Understanding Retention Modes

The retention behavior is controlled by the RetainModeEnum defined in frigate/config/camera/record.py (lines 32-36), which supports three distinct modes:

• all: Retains every recorded segment regardless of content
• motion: Retains only segments containing motion activity
• active_objects: Retains only segments containing detected objects (alerts or detections)

When active_objects is selected, Frigate evaluates each segment using ObjectProcessing.should_retain_recording() (lines 64-82 in frigate/track/object_processing.py). This method returns True only when the object is not a false positive and has an assigned severity level, ensuring you retain only meaningful detection events.

Configuration Steps

To configure recording retention based on detected objects:

1. Enable recording by setting record.enabled: true for your camera.
2. Select event types to configure under detections or alerts (or both).
3. Set the retain mode to active_objects within the retain block.
4. Define the retention period using the days parameter to specify how long to keep matching segments.
5. Disable unnecessary recording types (like continuous) by setting their days value to 0.

YAML Configuration Example

Here is a complete example showing how to retain recordings only when objects are detected:

cameras:
  front_yard:
    record:
      enabled: true
      continuous:
        days: 0
      motion:
        days: 2
      detections:
        retain:
          days: 7
          mode: active_objects
      alerts:
        retain:
          days: 30
          mode: active_objects

In this configuration, detections.retain.mode: active_objects ensures that only segments containing detected objects are preserved for seven days, while the alerts retention extends critical events to 30 days. The continuous recording is disabled by setting days: 0, ensuring no footage is retained without object activity.

How the Retention Logic Works Internally

The retention system operates through several key components in the Frigate codebase.

Configuration Schema

The ReviewRetainConfig class (lines 45-49 in frigate/config/camera/record.py) defines the mode parameter, while RecordRetainConfig (lines 23-50) structures the overall retention settings. These classes validate the RetainModeEnum values during startup.

Processing Pipeline

When objects are tracked, ObjectProcessing.should_retain_recording() evaluates whether to mark a segment for retention. According to the source code (lines 64-82 in frigate/track/object_processing.py), this method returns True when:

• The camera has recording enabled
• The object is not a false positive
• The object has moved
• The object has a maximum severity assigned (alert or detection)

Cleanup Execution

The record/maintainer service applies retention policies through should_discard_segment() (lines 61-71 in frigate/record/maintainer.py), while the record/cleanup module (lines 68-72 in frigate/record/cleanup.py) executes the actual deletion of expired recordings based on the configured mode and day limits.

Summary

• Set retain.mode to active_objects in your camera configuration to keep only recordings with detected objects
• Configure days under detections or alerts to control how long object-triggered segments are stored
• Reference RetainModeEnum in frigate/config/camera/record.py for valid retention mode values
• Understand the processing logic in ObjectProcessing.should_retain_recording() to know when segments are marked for retention
• Disable continuous recording by setting continuous.days: 0 to conserve storage space

Frequently Asked Questions

What is the difference between active_objects and motion retention modes?

The motion mode retains any recording segment containing detected motion regardless of whether an object was identified, while active_objects specifically filters for segments containing verified object detections or alerts. According to the implementation in frigate/track/object_processing.py, active_objects requires a valid object with severity that passes the should_retain_recording() check, ensuring you only keep footage with meaningful AI-detected activity.

How do I completely disable continuous recording while keeping detection-based retention?

Set record.continuous.days: 0 in your camera configuration. This disables retention for continuous footage while allowing you to maintain separate retention policies for detections and alerts with mode: active_objects. The days: 0 value signals the cleanup workers in frigate/record/cleanup.py to immediately purge continuous segments while preserving object-triggered recordings.

Where does Frigate store the retention configuration schema?

The configuration schema is defined in frigate/config/camera/record.py, which contains the RecordRetainConfig and ReviewRetainConfig classes (lines 23-50). This file defines the RetainModeEnum with values all, motion, and active_objects (lines 32-36), and validates the days and mode parameters during the configuration loading phase.

Can I set different retention periods for different object types?

No, retention periods in Frigate are configured per event type (detections, alerts, motion, continuous) rather than per object class. However, you can achieve similar filtering by configuring zones and required zones for specific objects, as only objects entering defined camera zones trigger retention events when using active_objects mode. The retention decision occurs at the segment level based on whether any qualifying object was present.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}