Retention and protection

Retention, cutoffs and deletion protection

Applies to 2026.10.19. The clearer warnings and configurable retention schedule shipped in this release. Per-video deletion protection already existed.

Use this guide when a downloaded video disappears earlier than expected, or when you want to keep a particular video regardless of automatic cleanup.

Understand the two cleanup rules

Open a source and choose Edit to review Download Cutoff Date and Retention Period (days). Switch to Advanced editing mode if a setting is hidden.

Rule	Compared fields	When automatic cleanup can remove files
Download cutoff	Video publication date and source Download Cutoff Date	The publication date is earlier than the configured cutoff date. Videos published on the cutoff day are included.
Age-based retention	Video download time, source retention days and current time	The download time plus the configured number of days has passed. Deletion happens when scheduled cleanup next runs.
Per-video protection	Prevent Automatic Deletion	When enabled, both automatic cleanup rules skip that video. Manual deletion is still allowed.

The download cutoff affects both automatic download eligibility and cleanup of existing downloads. A manual download does not automatically protect a video from later cleanup. Blank or zero retention means No age-based deletion; cutoff cleanup can still apply. Pausing downloads does not disable these cleanup rules.

Indexing Cutoff Date is a different field: it limits which publication dates are indexed. When both cutoffs are set, the indexing cutoff must be on or before the download cutoff. Moving the download cutoff earlier cannot recover videos that were never indexed; review indexing settings as well.

Worked example

Suppose a video was published on October 15, 2026, downloaded manually on October 18, 2026, and its source has:

• Download Cutoff Date: October 17, 2026.
• Retention Period: 10 days.

The publication date of October 15 falls before the configured cutoff of October 17. Cutoff cleanup can therefore remove the files at the next scheduled run, even though the download time plus ten days has not passed. A video published on October 17 would not meet this cutoff-deletion condition, but could later expire through age-based retention.

Protect a video

1. Open the video's detail page.
2. For an unprotected video published before its source cutoff, choose Protect this video. Otherwise, use Actions > Edit.
3. Enable Prevent Automatic Deletion and save.
4. Return to the detail page and confirm that protection is shown.

Protection applies to both cutoff and retention cleanup. It does not restore deleted files, create a backup, or prevent manual deletion. If files were already removed, save protection first, then download the video again. Download/retry confirmations also show cutoff guidance where it applies.

Configure the cleanup schedule

Add the schedule to your existing application service in Compose:

environment:
  RETENTION_CRON: '0 */4 * * *'
  RETENTION_TIMEZONE: Europe/Berlin

This example runs cleanup every four hours in Berlin time. Recreate the application container after changing its environment. The defaults are daily at 01:00 UTC. TZ / TIMEZONE do not change this schedule. Invalid or empty retention schedule values prevent startup; inspect container logs if startup fails.

See Environment variables for the reference. Other scheduled jobs retain their own schedules.

Automatic quality upgrades skip media already eligible for retention cleanup, including media that expires while its upgrade waits in the queue. Protected media remains eligible for upgrades; forced downloads retain their override.

A permitted successful replacement updates the recorded download time, which is used for subsequent age-based retention. It does not change the publication date used by cutoff cleanup.

Change many source cutoffs

Use bulk source management to preview affected downloads before confirming. Confirmation changes the source dates; scheduled cleanup acts later. Clearing a cutoff does not restore files already deleted.

For unexpected deletion, record the publication date, download time, source cutoff, retention days, protection state and cleanup log. Those values distinguish the two rules. See download recovery and backups and restore.

All feature guides