Continuous rollover storage retention policy (NVR-style recording)

[iamrans0m00]

Problem

Currently Frigate requires users to set explicit retention days (continuous.days, motion.days) for recordings. This works well when you know your storage capacity and camera bandwidth, but many users coming from traditional NVR systems expect a simpler model: record until the disk is full, then overwrite the oldest footage.

This has been requested in #9275 and attempted in #21494, but the previous approach ran into several design issues that were raised by maintainers.

Proposed Solution

A new global config option retain_policy with two modes:

record:
  enabled: true
  retain_policy: continuous_rollover  # default: "time" (existing behavior)

time (default): Existing behavior — recordings expire after configured days. No changes.

continuous_rollover: Recordings fill available disk space. When space runs low, StorageMaintainer reclaims space using prioritized deletion.

How This Addresses Previous Concerns (#21494)

The maintainer feedback on #21494 raised three specific issues. Here's how this proposal handles each:

1. Per-camera vs global confusion

#21494 added max_size per-camera, making global behavior unintuitive. This proposal makes retain_policy strictly global-only — it's a system-wide mode switch, not a per-camera setting. It's hidden from per-camera config in the UI.

2. No deletion priority between segment types

#21494 had no logic for deciding which recordings to delete first. This proposal implements three-tier prioritized deletion in StorageMaintainer when in rollover mode:

1. Overwritable first — continuous recordings with no event or review segment overlap (oldest first)
2. Event retention second — recordings tied to active review segments, only if overwritable wasn't enough
3. Protected last — recordings tied to retain_indefinitely events, emergency only

Classification uses the same sorted two-pointer overlap algorithm already used in RecordingCleanup, with camera-scoped review segment checking.

3. Mixing days + size retention

#21494 layered max_size on top of the existing days system, requiring users to configure both. This proposal makes it an either/or mode switch — in rollover mode, continuous.days and motion.days are explicitly ignored (with a config warning). Only alert/detection retention days still apply for event clip aging. Users don't need to think about both systems.

Implementation Details

• New RetainPolicyEnum (time | continuous_rollover) on RecordConfig
• RecordingCleanup skips time-based expiry in rollover mode (review segment expiry still runs)
• StorageMaintainer gets a new _reduce_storage_rollover() method with the three-tier deletion logic
• New /api/recordings/storage/breakdown endpoint categorizes storage into overwritable/event-retention/protected
• Frontend shows the breakdown in the storage metrics page when rollover mode is active
• Existing time policy code path is completely untouched

I have a working implementation with tests in #22204. Happy to adjust the approach based on feedback.

Config Example

record:
  enabled: true
  retain_policy: continuous_rollover
  alerts:
    retain:
      days: 30        # alert clips still age out after 30 days
  detections:
    retain:
      days: 14        # detection clips age out after 14 days
  # continuous.days and motion.days are ignored in rollover mode

[hawkeye217]

It is worth noting that this can already be accomplished by setting a ridiculously high retain days number. When less than an hour of space is remaining, Frigate purges the oldest recordings. This has been in place since Frigate 0.13.

[NickM-27]

yeah, as described this feature doesn't really add anything. We need to make the addition be a way to set retention based on % of free storage. The problem is how that interacts between global config and camera specific config.

[iamrans0m00]

Sometimes the answer is just too easy. Thanks!