Skip to content

Background Tasks ​

The SakuraMedia host includes built-in scheduled tasks, and plugins can register their own. The Task Center shows run status, progress, results and error messages.

Built-in task overview ​

TaskPurposeDefault schedule
Subscribed actor movie syncSyncs movie lists for subscribed actors and imports missing movie recordsDaily at 02:00
Auto-download missing subscribed moviesSearches for and submits matching resourcesDaily at 02:30
Movie stats and heat syncRefreshes interaction stats and heat through the bound pluginDaily at 05:00
Download task status syncSyncs task status from each provider's download clientEvery minute
Auto-import completed downloadsHands completed tasks to the import flow using completed_source_refEvery minute
Media file hash backfillComputes hashes for media files that lack themDaily at 03:00
Media thumbnail generationGenerates thumbnails for playable mediaEvery 30 minutes
Image search indexingGenerates vectors for media thumbnails and scene imagesEvery 5 minutes
Movie similarity recalculationComputes similar movie resultsDaily at 03:30
Recommended moment generationGenerates candidate recommended momentsDaily at 04:00
Daily recommendation generationGenerates daily recommendation snapshotsDaily at 05:00
GFriends avatar cache refreshRefreshes the GFriends file-tree cacheMondays at 04:00
Activity record cleanupCleans up task run records and read notificationsDaily at 05:30

Tasks registered by plugins appear in the same Task Center and use the plugin's own settings and cron.

When "Image & Text Search" is off, the image search indexing task is not scheduled; when "Similar Movies & Vector Service" is off, similarity recalculation and the index build at startup do not run. The Task Center shows them as "Not enabled" and they cannot be run manually; related tasks already queued before the restart are skipped. Thumbnail generation and recommendation tasks remain, and recommendations skip the disabled signal.

Subscription sync tasks ​

Subscribed actor movie sync ​

The system walks through subscribed actors, calls every enabled metadata plugin that declares the actor movie list capability, merges and deduplicates movie numbers, imports missing movies into the local library, and links them to the actor. The first sync scans the full list, and later runs check incrementally; the task is skipped when no capable plugin is enabled. The bundled JavBus and AVMOO plugins support this capability.

Subscribing to an actor only syncs release data. It does not subscribe to her movies or download them automatically.

Download pipeline tasks ​

Auto-download missing subscribed movies ​

The system queries indexers for movies that are subscribed but do not have playable media yet. Candidates are selected by the backend's filtering rules and then handed to the first download client bound to that indexer; the download client is provided by a provider, and its exact capabilities are decided by the plugin.

Download task status sync ​

Status is synced through the task interface of the download client provider. Task records keep the state the host needs and the source reference returned by the provider.

Auto-import completed downloads ​

Once a download client returns completed with a completed_source_ref, the task enters the import queue. The import request passes source_ref unchanged to the provider of the target media library, which scans the source and writes it into the media library.

Media and discovery tasks ​

  • Media thumbnail generation: prepares the thumbnails needed for moment previews and image search on playable media.
  • Media file hash backfill: computes hashes for media files that lack them.
  • Image search indexing: hands pending media thumbnails and scene images to the SigLIP2 embedding service, then writes them into Qdrant.
  • Movie similarity recalculation: computes the similar movies shown on detail pages offline.
  • Recommended moment generation / daily recommendation generation: prepares data for the discover and recommendation pages.
  • Movie stats and heat sync: refreshes interaction_stats and the plugin-computed heat for movies. It does nothing when no stats plugin is bound; existing values remain available.
  • GFriends avatar cache refresh: downloads the file-tree index and writes it to the local cache.

Default cron configuration ​

toml
[scheduler]
enabled = true
log_dir = "/data/logs"

actor_subscription_sync_cron = "0 2 * * *"
subscribed_movie_auto_download_cron = "30 2 * * *"
download_task_sync_cron = "* * * * *"
download_task_auto_import_cron = "* * * * *"
movie_stats_sync_cron = "0 5 * * *"
media_file_hash_backfill_cron = "0 3 * * *"
media_thumbnail_cron = "*/30 * * * *"
image_search_index_cron = "*/5 * * * *"
movie_similarity_recompute_cron = "30 3 * * *"
moment_recommendation_generate_cron = "0 4 * * *"
daily_recommendation_generate_cron = "0 5 * * *"
gfriends_filetree_refresh_cron = "0 4 * * 1"
activity_cleanup_cron = "30 5 * * *"

activity_task_run_retention_per_key = 200
activity_notification_read_retention_days = 3

Task execution rules ​

  • Tasks triggered by aps <job> or from the Task Center appear in the Task Center.
  • Manual and scheduled runs of the same task are mutually exclusive; a running task is not queued again.
  • A service restart reclaims the state of interrupted tasks.
  • Download tasks can be deleted from the download task center; when deleting, you can let the provider delete the remote task and its files as well, depending on what the provider supports.
  • Deleting a task record only affects the local list; it is not a substitute for storage management in the media library or the provider.

See the Configuration Reference for task cron expressions and retention periods; plugin tasks follow the plugin settings.

Released under the GNU GPL v3 License.