Skip to content

Configuration Reference ​

The configuration file lives at sakuramedia-data/config/config.toml. Every path in the configuration refers to a path inside the container. /data holds backend runtime data.

Configuration overview ​

  • Root level: enable_docs
  • [database]
  • [auth]
  • [media]
  • [metadata]
  • [plugins]
  • [scheduler]
  • [downloads]
  • [logging]
  • [image_search]
  • [qdrant]

enable_docs ​

toml
enable_docs = false

Controls whether the Swagger / ReDoc documentation pages are enabled. Keep it false for normal use and switch it to true only when you need to read the API documentation.

[database] ​

toml
[database]
engine = "postgres"
url = "postgresql://sakuramedia:sakuramedia@postgres:5432/sakuramedia"
FieldDefaultPurpose
enginepostgresDatabase type. PostgreSQL is used at present.
urlpostgresql://sakuramedia:sakuramedia@postgres:5432/sakuramediaPostgreSQL connection string.

No changes are needed if you copy the compose file from Quick Start; with an external PostgreSQL, enter a reachable connection string and prepare the database before starting.

[auth] ​

toml
[auth]
username = "account"
password = "account"
secret_key = ""
algorithm = "HS256"
access_token_expire_minutes = 43200
refresh_token_expire_minutes = 10080
file_signature_secret = ""
FieldPurpose
username / passwordCredentials for the first login. They can be changed in System Settings after signing in.
secret_keyJWT signing key. When left empty, it is generated automatically on first start and written to the configuration.
algorithmJWT signing algorithm, HS256 by default.
access_token_expire_minutesAccess token lifetime (minutes).
refresh_token_expire_minutesRefresh token lifetime (minutes).
file_signature_secretSigning key for media, image and subtitle files. Generated automatically on first start when left empty.

[media] ​

toml
[media]
allowed_min_video_file_size = 268435456
import_image_root_path = "/data/cache/assets"
media_clip_root_path = "/data/media-clips"
media_clip_max_duration_seconds = 900
media_clip_ffmpeg_timeout_seconds = 120
FieldPurpose
allowed_min_video_file_sizeMinimum video size for media import (bytes), 256 MB by default.
import_image_root_pathDirectory where images are cached during import.
media_clip_root_pathDirectory where clip files are stored.
media_clip_max_duration_secondsMaximum allowed duration of a single clip, 900 seconds by default.
media_clip_ffmpeg_timeout_secondsTimeout for one ffmpeg clip operation, 120 seconds by default.

Collection detection for movies is handled by an installed plugin. Go to "System Settings → Plugins" to install, enable and configure the corresponding plugin.

[metadata] ​

toml
[metadata]
gfriends_filetree_url = "https://cdn.jsdelivr.net/gh/xinxin8816/gfriends/Filetree.json"
gfriends_cdn_base_url = "https://cdn.jsdelivr.net/gh/xinxin8816/gfriends"
gfriends_filetree_cache_path = "/data/cache/gfriends/gfriends-filetree.json"
gfriends_filetree_cache_ttl_hours = 168
import_metadata_max_workers = 3
FieldPurpose
gfriends_filetree_urlURL of the GFriends file-tree index.
gfriends_cdn_base_urlBase URL of the GFriends CDN.
gfriends_filetree_cache_pathLocal cache path for the file tree.
gfriends_filetree_cache_ttl_hoursFile-tree cache lifetime (hours).
import_metadata_max_workersNumber of concurrent threads used to fetch metadata during movie import.

Requests to external sites uniformly use the container environment variables HTTP_PROXY, HTTPS_PROXY and NO_PROXY. Connections to indexers, download providers and media providers are managed by each plugin's own configuration.

Metadata plugins ​

The official image bundles and enables two metadata sources, JavBus and AVMOO; install DMM / FANZA, FC2, FC2CMADB and others from the plugin market when needed. Movie search, import by movie number, and manual matching use only enabled metadata plugins, in the order configured under Settings → Metadata Sources; restart the API and APS after saving the order. This release requires every plugin to declare Host API 18, and older plugins must be released again before they can load. Actor search uses the backend's bundled GFriends index and needs no account configuration. See the FAQ for the domains metadata plugins need and proxy configuration.

[plugins] ​

toml
[plugins]
root_dir = "/data/plugins"
enabled = []
job_crons = {}
settings = {}
# stats_source = "stats_plugin"
# review_source = "review_plugin"
FieldPurpose
root_dirRoot directory where plugins are installed.
enabledList of enabled plugin IDs.
job_cronsCron overrides for plugin background tasks, grouped by plugin ID.
settingsPrivate plugin settings, grouped by plugin ID.
stats_sourcePlugin ID used for movie interaction stats and heat. Leave empty to keep existing data without syncing; the frontend hides interaction stats and heat.
review_sourcePlugin ID used for movie reviews. When empty, no review plugin is called and the frontend hides the review entry.

The entry point for installing, enabling and configuring plugins is "System Settings → Plugins"; you can also use the plugins commands in Common Commands.

Interaction stats and review sources are configured under "System Settings → Metadata Sources"; restart the API and APS after saving. Only one plugin can provide interaction stats at a time.

[scheduler] ​

This group controls host scheduled tasks. Every value is a cron expression; the defaults are as follows:

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 * * *"
activity_cleanup_cron = "30 5 * * *"
gfriends_filetree_refresh_cron = "0 4 * * 1"
activity_task_run_retention_per_key = 200
activity_notification_read_retention_days = 3
FieldPurpose
enabledWhether background scheduled tasks are enabled.
log_dirLog directory for background tasks.
actor_subscription_sync_cronSync of movie lists for subscribed actors.
subscribed_movie_auto_download_cronAuto-download of missing subscribed movies.
download_task_sync_cronSync of provider download task status.
download_task_auto_import_cronHands completed provider tasks to the import flow.
movie_stats_sync_cronRefreshes interaction stats and heat through the bound plugin.
media_file_hash_backfill_cronFills in hashes for media files that lack them.
media_thumbnail_cronMedia thumbnail generation.
image_search_index_cronVector indexing of media thumbnails and scene images.
movie_similarity_recompute_cronMovie similarity recalculation.
moment_recommendation_generate_cronRecommended moment generation.
daily_recommendation_generate_cronDaily recommendation snapshot generation.
activity_cleanup_cronCleanup of Activity Center records.
gfriends_filetree_refresh_cronRefresh of the GFriends file-tree cache.
activity_task_run_retention_per_keyNumber of run records kept per task key.
activity_notification_read_retention_daysDays to keep read notifications.

See Background Tasks for task details and how to trigger them manually.

[downloads] ​

toml
[downloads]
subscription_search_fresh_days = 90
subscription_search_stale_attempt_limit = 3
torznab_timeout_seconds = 60.0
FieldPurpose
subscription_search_fresh_daysNumber of days by which a movie counts as new based on its release date; when a search for a new movie finds no resources, it does not consume the stale attempt count.
subscription_search_stale_attempt_limitMaximum number of rounds in which no usable resource is found for an older movie; once reached, it is marked as "given up" and the search must be reset manually.
torznab_timeout_secondsTimeout for a single indexer search request (seconds), 60 by default.

Which indexer and download client are used is decided by the indexer bindings; the provider's own connection parameters are entered in the media library or download client configuration.

[logging] ​

toml
[logging]
level = "INFO"

Supported values are DEBUG, INFO, WARNING, ERROR and CRITICAL. Use INFO normally and switch to DEBUG temporarily when troubleshooting.

toml
[image_search]
enabled = false
inference_base_url = "http://siglip2-embed:8080"
inference_timeout_seconds = 120.0
inference_connect_timeout_seconds = 3.0
inference_api_key = ""
inference_batch_size = 16
session_ttl_seconds = 600
default_page_size = 20
max_page_size = 100
search_scan_batch_size = 100
index_upsert_batch_size = 100

enabled controls image/text frame search, image vector indexing and visual recommendations, and it requires [qdrant].enabled to be on as well. On desktop you can edit both switches, the connection address and the API key in "System Settings → Advanced Settings → Image Search / Similarity"; restart the backend container (API and APS) after saving for the change to take effect.

Both switches are off by default on new deployments; when upgrading an older deployment, only missing switches are filled in as enabled, so values you have already saved are never overwritten. Mobile does not provide a settings form, but adjusts its entry points based on server capabilities.

These fields control the SigLIP2 embedding service connection, search sessions and Qdrant index batching. The default address matches the siglip2-embed service name in the Quick start; you only need to change the connection fields when the embedding service runs on another host, uses a different service name, or has authentication enabled.

Text-to-frame search also requires the SigLIP2 container to load the text tower (loaded by default); if the container sets TEXT_TOWER_ENABLED=false, only image vectors are provided, text-to-frame search is unavailable, and image search is unaffected. See Optional vector services and SigLIP2 hardware options for details.

index_upsert_batch_size controls how many pending thumbnails and scene images the indexing task reads per round. The task keeps processing until both pending queues are empty; the parameter only limits the amount read per round and does not cap the total work of a single run.

[qdrant] ​

toml
[qdrant]
enabled = false
url = "http://qdrant:6333"
api_key = ""

url is the Qdrant HTTP API address; with the compose deployment, use the in-container service name qdrant. Fill in api_key when Qdrant authentication is enabled.

enabled controls similar movies and the vector service. When it is off, Qdrant is not contacted and recommendations skip the movie similarity signal; disabling image search does not affect similar movies, which depend on Qdrant alone. When disabling Qdrant you should disable image search as well; desktop prompts you and saves both together. The switch does not stop or remove Docker containers — to free resources, stop the containers on the deployment side.

Released under the GNU GPL v3 License.