Watch downloaded videos

Watch downloaded videos for changes

Available in 2026.11.0: PR #173, merged as 76c8ccf, adds opt-in watch windows and saved originals. These controls require 2026.11.0 or later.

Use a watch window to check a newly downloaded video's remote duration and visibility for a fixed period. A suspected change blocks replacement; a confirmed change appears in history and queues an Apprise notification. This feature does not compare the remote video's actual content byte by byte.

Enable a watch window

1. Open Media Profiles > Edit and set Watch window (days). 0 disables new watches; 1 to 365 enables that many days of monitoring.
2. Open Sources > Edit to override it for a source. Blank inherits the profile, 0 disables monitoring for that source, and a positive value overrides the profile.
3. Download a new video. Open its detail page and expand Watch details to check the window, remote and local durations, visibility, check results and protection state.

Existing downloads are not enrolled retroactively. The window starts at the first completed local download, after configured postprocessing, and retains that start and end time through retries and replacements. Changing the configured number of days does not resize existing windows.

For example, a video published on October 25, 2026, whose first local download completes on November 1, 2026 at 12:00 UTC, starts a 14-day watch at that download time. Its watch ends on November 15 at 12:00 UTC. A replacement downloaded on November 3 does not move the end date. Publication date is separate from the download time used by the watch.

Disabling monitoring pauses checks without deleting a saved original or clearing an incident hold. Re-enabling it before the stored end time resumes the remaining window.

Understand checks and notifications

The dispatcher looks for due watches every 15 minutes. Successful observations are normally about six hours apart, with jitter; checks are not immediate. The app uses the configured YouTube Data API key, or yt-dlp metadata when no key is configured.

A remote duration difference greater than two seconds or a supported visibility change creates a suspicion. Matching observations at least 15 minutes apart confirm the transition. Confirmed transitions record history and queue notifications. A later distinct transition can create another event.

Missing duration, an absent API result, authentication errors and failed extractor calls are inconclusive. They are retried with backoff from about 15 minutes to six hours; they do not establish that the creator deleted the video or made it private. Livestreams and premieres need a stable completed baseline. Title-only edits and equal-duration content edits are not detected.

Configure a destination under Settings > Notifications, use Send Test, and check the destination itself. Watch alerts include the video title, observed change and local media-page link. Set External Base URL to an address recipients can reach. See Notifications for delivery setup.

Failed deliveries retry independently of media downloads. Delivery is at-least-once: a crash after a provider accepts a message but before its acknowledgement is saved can produce a duplicate. A successful job or fixture-backed test is not proof that Matrix or another external provider received it.

Find affected videos

Open Source > Videos and view downloaded items. The watch filter supports Changed or suspected, Unlisted now, Private or unavailable, and Inconclusive remote check, as well as the combined changed/unavailable view. It works with search and list/grid views.

On the video page, expand Watch details and Watch history. Compare the baseline and current remote durations with the local playback duration; local SponsorBlock processing can change the local duration without proving an upstream edit.

Keep and access the original

Before replacing an eligible watched download, Pinchflat-ngx preserves and verifies its first completed local artifact and present associated files. A separate saved original lives under <media_directory>/.pinchflat-originals/<watch-id>/ with a manifest. Exclude this directory from media-server scans if your server would otherwise list it.

The saved-original section appears once an archive exists. Use Play saved original, Download original, and Associated files when available. These routes require the application's management authentication; public podcast/stream access does not expose the archive.

Allow space for the original, staged replacement and temporary recovery copies. Suspected changes, inconclusive/stale observations, an unverified archive or pending recovery can block replacement. Do not delete archive, intent or pending staging files to bypass a hold. Check Watch details and Download recovery.

The open window and incident holds protect active media from automatic cleanup. Expiry stops polling, keeps saved originals and retains incident holds. Without an incident hold, the current download can become eligible for normal cutoff/retention cleanup after the window ends. Manual protection settings remain independent. See Retention and protection.

End watch protection

1. Download any saved original and associated files you want to keep.
2. Open the video and choose End watch protection.
3. Read the confirmation. If an archive exists, continuing permanently deletes that saved original and its archived sidecars.
4. Cancel to leave protection in place, or confirm on the current page to end it.

The current download and manual protection settings remain unchanged. Normal download and retention rules apply afterward. A later download does not enroll the same item again.

Confirmation expires after ten minutes and is bound to the current watch and archive. If state changes, request a fresh confirmation. Interrupted archive cleanup blocks replacement and file deletion until recovery completes. Deleting watched media, source or profile records is refused until watch protection has been explicitly ended.

Backups, transfer and recovery

Back up the database, media volume including .pinchflat-originals, and the application's configuration/extras together. A database-only backup does not contain saved-original bytes. Keep a consistent recovery point and preserve archive paths and mounts when restoring or transferring between SQLite and PostgreSQL. See Backups and restore and SQLite-to-PostgreSQL migration.

Startup and later mutation attempts reconcile interrupted replacement intents. Uncertain ownership or missing/unverified files retain a recovery hold rather than authorizing deletion. Correct storage, mounts and permissions before retrying; keep the original and recovery files while investigating. Database and filesystem changes are recoverable steps, not one atomic transaction or protection against storage failure.

API and verification limits

Media profile and source inputs accept watch_window_days from 0 to 365; source null inherits the profile. The media API includes a read-only watch object for enrolled items. Existing management API authentication still applies.

Automated integration and packaged AMD64 checks covered synthetic watch state and preservation flows. Real YouTube edits/private/deletion changes, external Matrix delivery and ARM64 runtime behavior were not verified for the original PR build. Report your release/image version, database, architecture, action, observed durations/visibility and relevant redacted logs if a released version fails.

All feature guides