fricat

Small CLI utilities for managing Frigate-style recordings and dated backup directories, with Prometheus textfile metrics output.

• concat: concatenate per-hour/per-camera MP4 segments into a single MKV per hour.
• export-clip: export a clip from hourly archives and recent raw segments.
• check-segments: check recent Frigate segments for missing, sparse, or corrupt audio.
• repair: scan and stream-copy repair hourly archives with malformed duration metadata.
• prune: apply a GFS (daily/weekly/monthly/yearly) retention policy to YYYY-MM-DD directories.
• web: serve a local browser UI for reviewing archived recordings by camera, date, and hour.

• Python 3.13+
• ffmpeg and ffprobe on PATH (for concat, repair, check-segments, and clip export)
• Permissions to write metrics files (defaults under /var/lib/node_exporter/)

From this repo:

uv sync

Or run as a module without installing:

python -m fricat --help

Input layout (example, each segment is ~10 seconds):

/media/frigate/recordings/2025-11-18/14/CAM2/56.31.mp4
                          YYYY-MM-DD/HH/CAM_/MM.SS.mp4

Output layout (example):

/media/frigate/archive/2025-11-18/14_CAM2.mkv

Command:

fricat concat /media/frigate/recordings /media/frigate/archive

Notes:

• Only processes fully-finished hours: if now is 10:00 UTC, it only processes up to 08.
• Skips output files that already exist.
• Writes Prometheus metrics to /var/lib/node_exporter/fricat_concat.prom by default.
• Validates each completed archive and stream-copy remuxes files with malformed durations before publishing them.
• Samples source-segment audio health, warns about corruption, and reports affected hourly archives in metrics without altering their packets.

Export a clip without running the web UI:

fricat export-clip CAM1 \
  '2026-07-26 08:55:00' \
  '2026-07-26 09:05:00' \
  --archive-root /media/frigate/archive \
  --segments-root /media/frigate/recordings

START and END are local ISO timestamps interpreted in America/Vancouver by default. Use --timezone to select another IANA timezone and -o/--output to choose the output path.

The exporter can cross hour and date boundaries. It prefers completed hourly archives and fills newer, uncovered intervals from raw Frigate segments. It fails without creating a partial clip if any part of the requested range is unavailable. Existing output files are never overwritten.

Like clips exported by the web UI, CLI clips stream-copy video and normalize audio timestamps to AAC, filling sparse source-audio intervals with silence.

Check the newest completed Frigate segments for each camera:

fricat check-segments /fastpool/frigate/recordings

The command prints a status for each camera and exits with 0 when healthy, 1 when recordings are corrupt or stale, and 2 when the check itself cannot run reliably.

By default it checks the three newest files that have been settled for at least 15 seconds, requires the newest completed segment to be no more than 60 seconds old, and rejects audio packet durations or PTS gaps over one second. See fricat check-segments --help for overrides.

Prometheus textfile metrics are written to /var/lib/node_exporter/fricat_check_segments.prom by default. Pass every expected camera with repeated --camera options so a camera that produces no directories or segments is reported as unhealthy.

Scan existing hourly archives for malformed container durations. Scanning is the default and does not modify files:

fricat repair /media/frigate/archive

Repair malformed files in place with an atomic stream-copy remux:

fricat repair /media/frigate/archive --apply

The default maximum duration is 3700 seconds and can be changed with --max-duration. Run this command on the machine that stores the archive to avoid transferring media over the network. JSON sidecars are not modified. A repaired file keeps its ownership and mode, while its modification time records when the repair occurred.

Prunes date-named directories inside a base path using a GFS policy.

fricat prune /path/to/backups --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --keep-yearly 2

Dry run:

fricat prune /path/to/backups -d 7 -w 4 -m 6 -y 2 --dry-run

Notes:

• Only directories named YYYY-MM-DD are considered.
• Rules are applied in order: daily, weekly, monthly, yearly.
• Writes Prometheus metrics to /var/lib/node_exporter/fricat_prune.prom by default.

Serve the archive browser at http://127.0.0.1:8000:

fricat web --root /media/frigate/archive

Exported clips stream-copy video and normalize audio timestamps to AAC, filling missing source-audio intervals with silence for consistent playback. Hourly archives remain packet-faithful.

The concat, check-segments, and prune commands write Prometheus textfile metrics via prometheus-client:

• concat: processed bytes/files, repaired files, malformed-audio archives, duration, last run timestamp
• check-segments: per-camera health and latest-segment timestamp, camera status counts, errors, duration, last run timestamp
• prune: input/kept/removed counts, removed bytes, duration, last run timestamp

Override the output path with --metrics-file on each command.