Skip to content

Tasks

v0.8.0

The Tasks page shows all background jobs that keep Trailarr running smoothly. You can view scheduled jobs, see their status, and run them manually if needed.

Task Actions

Scheduled tasks will show the following action buttons:

Run Now

This runs the task immediately without waiting until the next scheduled run.

Once a task is run immediately, it will continue its schedule to run at specified intervals from that time until next app restart.

Pause

Active Tasks can be paused so that they won't run anymore.

Resume

Paused Tasks can be resumed to continue with their schedule.

Edit

Tasks can be edited to change their name, interval and delay.

  • Interval: The time between 2 scheduled runs of the task.
  • Delay: The time delay before the task is run for the first time on app startup. This can be used to set the task cadence. For example, Arr Data Refresh task has default delay of 30 seconds and Download Missing Trailers task has default delay of 15 minutes -> so Arr Data Refresh always runs before Download Missing Trailers.

If you want to change the cadence of task runs by editing delays, restart Trailarr once you set the proper delays.

Scheduled Tasks

Arr Data Refresh

  • Runs every 60 minutes (first run starts 30 seconds after app launch). Use the task's edit dialog on this page to change the interval.
  • Connects to all Radarr and Sonarr connections to sync media items and their status in Trailarr.
  • Applies Monitor and Status values, and scans for trailers for new items.
  • Runs as a background job; first run starts 30 seconds after app launch.
  • If the task is already running, a new instance will not start until the previous one finishes.

Docker Update Check

  • Runs once a day (first run starts 4 minutes after app launch).
  • Checks if a new Docker image is available for Trailarr and notifies in the UI/logs.
  • Does not auto-update; you must update the container manually.

Scan All Media Folders

v0.9.9

  • Runs every 60 minutes (same as Arr Data Refresh; first run starts 8 minutes after app launch).
  • Scans your media folders for all files and folders, detects trailers, and reconciles what it finds on disk with what Trailarr has recorded in its database.
  • This task refreshes the files and folders for all media items in Trailarr.
  • Useful if you add, rename, or delete trailers manually or outside of Trailarr.

For each media item, the scan compares the trailer file(s) it finds on disk to what's already recorded, and handles four kinds of changes:

What changed on disk What Trailarr does
A new trailer file appears Recorded as a new download.
An existing trailer is renamed or moved Recognized by comparing file content, not just the name/path — the existing download record is updated in place, keeping its history. Logged as a Trailer Renamed event.
An existing trailer's content changes but keeps the same name (e.g. re-encoded outside the app) Detected via a content-hash mismatch — the file's metadata (size, resolution, codecs, duration) is refreshed automatically. Logged as a Trailer Modified event.
An existing trailer is renamed or moved, and its content changes too (e.g. new audio tracks) v0.14.2 Recognized by its file name or by the YouTube id in its metadata — see Matching a file to a download. The existing download record takes the new path, and its metadata is refreshed. Logged as a Trailer Renamed event.
A trailer that was marked as deleted is on disk again v0.14.2 The deleted download record is active again, also when the file has a new name or new content — see Matching a file to a download. Logged as a Trailer Detected event.
An existing trailer is deleted The download record is marked as missing. Logged as a Trailer Deleted event.

How trailers are detected

v0.9.6 A video file counts as a trailer if either of the following is true:

  • It is inside a recognized trailer folder — Trailers/, Trailer/, or any custom Folder Name set in a profile. Folder placement is authoritative: any video file in such a folder is a trailer, with no size or name requirements.
  • It sits next to the media file ("inline") with trailer in its file name and no SxxEyy episode pattern. Files under 200 MB are accepted directly; larger files are verified with ffprobe and only count if their duration is 10 minutes or less — so a full movie with "trailer" in its name is not mistaken for one.

Minimal Files Scan from v0.9.0

The task now checks folder modification times before doing a full recursive scan. If neither the media folder nor any of its immediate subdirectories (e.g., Trailers/) have changed since the last scan, the folder is skipped entirely. User-initiated scans always run in full. This significantly reduces scan time for large libraries where most folders are unchanged between runs.

Rename & content-change detection from v0.9.9

v0.9.9 Renaming or editing a trailer file used to look identical to "the old one was deleted and a new one appeared", which lost the file's history. The scan now recognizes these cases (see table above) and updates the existing record in place instead.

Matching a file to a download

v0.14.2

A trailer file can change outside Trailarr: you can rename it, move it to another folder, or change its tracks with another tool. Trailarr matches a file to an existing download by one of these rules, in this order:

  1. The file is at the path of the download.
  2. The file has the file name of the download, in another folder.
  3. The file has the YouTube id of the download in its metadata. A trailer that Trailarr downloaded with Embed Metadata on has one.

If the file and the download both have a YouTube id, and the ids are not the same, the file is another video, and rules 1 and 2 do not apply. When the path or the size of the file changed, Trailarr analyzes the file again and updates the resolution, codecs, size and duration of the download. The YouTube id, the profile and the history of the download stay. A file that Trailarr cannot analyze, for example a file that is not complete, does not take a download back.

Network drive protection from v0.9.9

v0.9.9 If your media is stored on a network drive (SMB/NFS) that temporarily disconnects, the scan can no longer tell "the drive is offline" apart from "someone deleted all the trailers" — until now. Before marking any trailers as missing, the scan checks that the underlying storage is actually reachable. If it looks unreachable, that media item is skipped for this run (with an error logged) and retried on the next scheduled run, instead of incorrectly marking its trailers as missing.

Download Missing Trailers

v0.10.0

  • Runs every 60 minutes (same as Arr Data Refresh; first run starts 15 minutes after app launch).
  • For every monitored media item, finds the Profiles whose filters match, and downloads a video for each matching profile that does not already own one.
  • Downloads are tracked per profile: a profile that already has its downloaded video never downloads again, so monitored media is not re-downloaded — you can keep media monitored forever. Existing trailers on disk that Trailarr is not yet tracking are claimed by the highest-priority matching profile instead of being downloaded again.
  • Downloading no longer turns monitoring off — the monitor toggle stays exactly as you set it.
  • If a trailer file is deleted from disk, the next files scan notices it and the owning profile becomes unsatisfied — the trailer is downloaded again on the following run.
  • v0.14.2 Just before it downloads for a media item, Trailarr looks for a deleted download of that item whose file is on disk again. It examines the path of the download, and it searches the folder of the media item for the file with a new name — see Matching a file to a download. If it finds the file, it marks the download as active again, and the profile does not download the same video again. This helps when a network drive comes back while Trailarr runs.
  • v0.10.1 If the storage backing a media folder is unreachable (e.g. a disconnected network drive), the item is skipped with a Storage unreachable reason — it is not counted as a failed download attempt, and is simply retried on the next run once the storage is back.
  • v0.11.5 The task scans the library in sweeps, so media and profiles that become eligible during a long run can still be downloaded in that run; profile changes apply to media items whose download has not started, while trailers already downloaded keep the profile settings used to download them.
  • Uses yt-dlp and ffmpeg for downloading and conversion.

Failed downloads back off

v0.10.0 When a download attempt genuinely fails (e.g. no matching video can be found), that media + profile combination is not retried on every run. The retry delay doubles after each failure — 1 day, then 2 days, then 4 days — capped at one attempt per week. A successful download resets the backoff, and a manual download from Media Details always bypasses it. Skips (missing media folder, waiting for the media file) do not count as failed attempts. v0.13.1 After two failed runs, the library pages show the item in a banner with a Failing Downloads quick filter, so you can find it and fix the cause — see Filtering.

Preview mode

v0.10.2 When Downloads Enabled is turned off in Settings → General, this task computes and publishes its full work list but downloads nothing — the media pages show a Preview mode banner listing every (media, profile) pair it would download. Scans, syncs and attribution keep running so the preview stays accurate, and manual downloads still work.

  • There is a delay between consecutive trailer downloads. The delays are as follows:

    Download No Delay
    1 - 9 2 mins
    10 - 49 4 mins
    50 - 99 6 mins
    100 - 199 7 mins
    200 - 499 9 mins
    1000+ 10 mins

    All delays also includes an extra random time between 0 - 60 seconds.

Refresh Video Lists

v0.13.0

  • Runs every 12 hours (first run starts 10 minutes after app launch).
  • Asks TMDB which videos belong to the media items that are waiting for a trailer, so the Known videos list is ready before a download needs it.
  • v0.13.1 Also asks TMDB about the media items whose trailer can go to a TMDB trailer, for profiles with Upgrade To TMDB on. These items have a trailer, so no download waits for them, and without this task Trailarr would not learn that TMDB has a trailer for them.
  • Does nothing when no TMDB API key is set.
  • Asks about at most 200 media items in one run, and leaves an item alone when its videos were read in the last 7 days. A large library fills in over a few runs instead of sending thousands of requests at once.

Refresh Plex Trailer Flags

v0.9.3

  • Runs once a week (first run starts 10 minutes after app launch, only if a Plex connection exists).
  • For each media item linked to a Plex connection, calls the Plex API to check whether Plex already has a remote (internet-sourced) trailer and stores the result in the database.
  • The Download Missing Trailers task reads this cached flag instead of calling Plex on every run, which significantly reduces API calls for large libraries.
  • Automatically triggered within 3 minutes whenever a new Plex connection is added, so newly linked media is scanned promptly.
  • Only appears in the Tasks page if at least one Plex connection has been added.

Only remote trailers are counted

Locally stored trailer files (e.g. ones Trailarr itself downloaded) are not counted as Plex trailers. Only internet-sourced trailers provided by Plex are considered.

Cached flag behaviour

Once a media item has been scanned, the cached True/False value is used by the download task until the next refresh run. New media items added between runs have no cached value yet and will trigger a live Plex API check on their first download attempt.

Image Refresh

  • Runs every 6 hours (first run starts 12 minutes after app launch).
  • Updates artwork and images for your media library.
  • Ensures posters, and backgrounds are up to date.

Trailer Cleanup

v0.14.2

  • Runs once a day (first run starts 4 hours after app launch).
  • Cleans up broken, incomplete, or audio-less trailers from your library.
  • If a media item is marked as trailer existing but has no downloaded trailers, it will be marked as not having trailers. Does not change monitoring status.
  • If a media item has downloaded trailers but file does not exist, the download record will be marked as file deleted. Does not change monitoring status. Trailarr does this only when the folder that holds the trailer still has files. For a trailer in the media folder or in its subfolder, that folder is the media folder. For a trailer in a custom folder, it is the folder of the trailer.
  • If a download record is marked as file deleted, and its file is on disk again at the same path, Trailarr marks the record as active again. If the file changed, for example its tracks, Trailarr analyzes it again — see Matching a file to a download. A new download of the same video is then not necessary. Trailarr also does this at each start, and just before a download for the media item.
  • Updates the statistics that the database uses to find data quickly, after the library grows or shrinks.
  • Helps keep your storage clean and avoids playback issues.

Storage that is not mounted

v0.14.2 A network drive that is not mounted can show as an empty folder. A Docker bind whose source folder did not exist when the container started also shows as an empty folder. If the folder of a trailer is empty or missing, Trailarr does not mark the trailer as deleted, and it logs a warning at the end of the task. Make sure that your network drives are mounted before the Trailarr container starts.

Queued Tasks - Jobs

A scheduled run of a task is called Job. You can see queued/running jobs and their progress in real time in the Queued Jobs section.

Tip

A task does not start a new run while a run of the same task is still active. The scheduler skips the new run and waits for the next schedule.

Stop Job

v0.14.0

A running task/job shows a Stop button. Click it to stop the job. Trailarr stops at predefined points in the task flow, so a stop does not lose data.

When a Trailer Download job runs yt-dlp or ffmpeg, a stop ends that process at once, together with the ffmpeg that yt-dlp starts to merge the streams. Trailarr removes the partial file, and the job ends as Cancelled. The trailers that the job put in place before the stop stay.

Job Logs

Jobs will show a log button that can be used to view the logs of that task run.

Internally, Trailarr uses the Job's id (UUID4) to trace the logs related to that job - so when you click on the logs button it will open logs page and set that job id as filter.