Recordings & retention

Fregata can record continuously, only when something happens (motion, an object detection, an “alert” event), or some mix of the two. The behavior is configured in the web UI’s Settings or in config.yml, for every camera at once or per camera, and the data lands under ~/Fregata/media/ by default.

Two kinds of recording

Fregata keeps one kind of video file: the segmented MP4s under recordings/. What differs is why a segment is kept, and for how long.

• Continuous and motion footage is kept because it covers the timeline (record.continuous) or because something moved in the frame (record.motion). Disk-hungry but invaluable when something happens between triggers.
• Alert and detection footage is kept because it overlaps an event (a person walked through the front-porch zone, a car pulled into the driveway), for record.alerts.retain.days and record.detections.retain.days. Those windows can be much longer than the other two, so it’s cheap to keep for a long time.

There is no separate “clip” file. When something asks for an event’s clip, such as a request to /api/events/<event-id>/clip.mp4, Frigate cuts it on demand: it stitches the matching segments from recordings/ together without re-encoding and streams the result back. Nothing is written to clips/ for it. The flip side is that a clip can only be produced while the segments behind it still exist.

The web UI’s Review tab lists alerts and detections and plays each one back from the recorded segments, so a camera must have recording enabled to produce review items.

Configuring recording and retention

Recording is set under the record: and snapshots: blocks, with the same schema as upstream Frigate and no macOS-specific keys. Put a value at the top level to apply it to every camera, or under cameras.<name>: to override it for one.

Settings UI

1. In the web UI, go to Settings → Global configuration → Recording. To change one camera only, use Settings → Camera configuration → Recording and pick the camera in the selector at the top.
2. Turn on Enable recording.
3. Under Continuous retention, set Retention days to 1: how long to keep footage regardless of what happened in it. 0 turns the continuous tier off.
4. Under Motion retention, set Retention days to 14: how long to keep the segments that contain motion.
5. Under Alert retention and Detection retention, set Retention days inside Event retention to 30: how long to keep the footage around alerts and detections.
6. Click Save.
7. For snapshots, go to Settings → Global configuration → Snapshots, turn on Enable snapshots, and set Default retention under Snapshot retention to 30. Click Save.

To skip the continuous tier for one camera (the driveway example in the YAML tab), use Settings → Camera configuration → Recording, pick the camera, and set Continuous retention → Retention days to 0.

YAML

record:
  enabled: true
  continuous:
    days: 1        # everything, all day
  motion:
    days: 14       # only segments with motion
  alerts:
    retain:
      days: 30     # footage around alerts
  detections:
    retain:
      days: 30     # footage around detections

snapshots:
  enabled: true
  retain:
    default: 30

# Override one camera (here: no continuous tier for the driveway)
cameras:
  driveway:
    record:
      continuous:
        days: 0

The full reference (continuous vs. motion-only retention, alert and detection retention, snapshot quality, copy-vs-re-encode) lives in Frigate’s recording docs. We don’t mirror it here; the upstream docs stay current with every Frigate release.

Disk budgeting

A rough rule of thumb for an H.264 1080p main-stream camera at 15 fps and a sane bitrate:

Mode	≈ per camera per day	14-day retention
Continuous, all segments	25–40 GB	350–560 GB
Motion segments only (typical street)	4–10 GB	60–140 GB
Motion segments only (low-traffic)	1–3 GB	15–40 GB
Alerts and detections only	0.1–0.5 GB	1–7 GB

HEVC (H.265) cuts roughly 30–40 % off these numbers if your camera encodes it. On Apple Silicon, encoding recordings with hevc_videotoolbox is essentially free. See Performance.

Tip

When you’re sizing a new install, the safest approach is start with motion-only recording and short retention, watch the actual disk growth for a week, then dial up.

Settings UI

1. Go to Settings → Global configuration → Recording.
2. Under Continuous retention, set Retention days to 0.
3. Under Motion retention, set Retention days to 7.
4. Click Save.

YAML

record:
  enabled: true
  continuous:
    days: 0    # no 24/7 tier
  motion:
    days: 7    # short motion-only tier to start with

Where recordings land

~/Fregata/media/
├── recordings/<YYYY-MM-DD>/<HH>/<camera>/<MM.SS>.mp4
├── clips/
│   ├── <camera>-<event-id>-clean.webp   # event snapshots
│   ├── thumbs/<camera>/                 # event thumbnails (webp)
│   ├── previews/<camera>/               # hourly preview videos, not event clips
│   ├── review/                          # review item thumbnails (webp)
│   ├── triggers/<camera>/               # semantic search trigger thumbnails (webp)
│   └── ...                              # faces, export thumbnails, other working data
└── exports/                             # user-initiated exports (MP4)

The path layout is the same as upstream Frigate. The date and hour folders under recordings/ are in UTC, so they won’t line up with your wall clock. If you’ve been running Frigate in Docker before, the layout will be familiar.

Changing the media location

Tray menu — Settings → Folders → Change Media Location… Pick a new folder. Fregata will move the existing files on next launch, or let you move them yourself.

The destination should be on large enough disk to store all the recordings you wish to keep. External USB drives or NAS network shares are common.

Pruning by hand

Fregata prunes expired recordings on its own, every 60 minutes by default (Record cleanup interval under Advanced Settings on the Recording page, record.expire_interval in config.yml). To reclaim space immediately:

# Drop everything older than 7 days right now.
find ~/Fregata/media/recordings -type f -mtime +7 -delete

That frees the disk. Then run a media sync so the database forgets the files you just removed, and the web UI doesn’t show ghost segments. In the web UI, go to Settings → Maintenance → Media sync, set Media Types to Recordings, turn Dry Run off, and click Start Sync. If the result says it aborted because the deletion would exceed the safety threshold, turn on Force and start it again.

The same sync from a terminal goes through Fregata’s loopback API port (5000: plain HTTP and unauthenticated, loopback-only; the main port 8971 is HTTPS with a login). Use 127.0.0.1, not localhost, because if AirPlay Receiver is on, localhost:5000 can hit it instead of Fregata:

curl -X POST http://127.0.0.1:5000/api/media/sync \
  -H 'Content-Type: application/json' \
  -d '{"dry_run": false, "media_types": ["recordings"]}'

Exports

The Export button in the web UI’s playback view (open an alert or detection in the Review tab) opens a dialog. Choose a time range (Last Hour or another recent window, Select from Timeline, or Custom), name the export, and pick Single Camera or Multi-Camera. Fregata writes an MP4 to ~/Fregata/media/exports/, and finished exports are listed on the Export tab.

Exports copy the recorded segments without re-encoding, so quality is unchanged. There is no speed-up control in the dialog.