Configuration

Configuration

🌐 English · Deutsch

All settings are managed in the WebUI and stored in the SQLite database (app_settings table). A .env file is no longer required.

Migration: If a legacy ~/.mediaforge/.env still exists, its values are imported into the database once on first start (existing DB values are never overwritten). Afterwards the file can be deleted directly from the UI under Settings → Legacy .env.

On startup the app additionally exports all stored DB settings into the process environment (MEDIAFORGE_*), so both paths behave identically internally. Environment variables remain useful for initial configuration via Docker — values saved from the UI take precedence.

General settings (Settings page, admin only)

Setting	DB key	Env variable	Default	Description
Download path	download_path	MEDIAFORGE_DOWNLOAD_PATH	~/Downloads	Base folder for all downloads
Language separation	lang_separation	MEDIAFORGE_LANG_SEPARATION	0	One subfolder per language (german-dub, english-sub, …)
Disable English Sub	disable_english_sub	MEDIAFORGE_DISABLE_ENGLISH_SUB	0	Hides English Sub (relevant for "All Languages" sync)
FilmPalast subfolder	filmpalast_movie_subfolder	FILMPALAST_MOVIE_SUBFOLDER	0	Put movies into their own subfolder
Default language	download_language	MEDIAFORGE_LANGUAGE	German Dub	Preselection for downloads
Default provider	download_provider	MEDIAFORGE_PROVIDER	VOE	Preselection for downloads
Naming template	naming_template	MEDIAFORGE_NAMING_TEMPLATE	see below	File naming scheme
Web base URL	web_base_url	MEDIAFORGE_WEB_BASE_URL	empty	Public URL behind a reverse proxy (enables secure cookies for https://)
Media statistics	media_stats_enabled	MEDIAFORGE_MEDIA_STATS_ENABLED	0	Adds a Media category to the statistics page (movie/series/episode counts from the library)
Debug mode	debug_mode	MEDIAFORGE_DEBUG_MODE	0	Verbose logging — takes effect live, no restart (on and off). When the app is started with --debug the toggle is locked on and greyed out (with a note).
Web Console	web_console	MEDIAFORGE_WEB_CONSOLE	0	Shows a read-only, SSH-style console of the live application/FFmpeg output directly in the settings page (admin only)

Naming template

Default:

{title} ({year}) [imdbid-{imdbid}]/Season {season}/{title} S{season}E{episode}.mkv

Available placeholders: {title}, {year}, {imdbid}, {season}, {episode}. The scheme is Jellyfin/Plex-compatible (folder per series, Season XX subfolders, SxxExx file names).

AutoSync settings

Setting	DB key	Default	Values
Sync interval	sync_schedule	0 (off)	1min, 30min, 1h, 2h, 4h, 8h, 12h, 16h, 24h
Schedule mode	sync_mode	interval	interval or weekly
Weekdays (weekly)	sync_days	0,1,2,3,4,5,6	Comma list, 0=Mon … 6=Sun
Times (weekly)	sync_times	06:00	Comma list HH:MM, one or more
Sync language	sync_language	German Dub	All languages + All Languages
Sync provider	sync_provider	VOE	Active providers
Path unavailable action	sync_path_unavailable_action	skip	skip or hold
Error retries	sync_error_retries	0	0–10
Retry delay	sync_error_retry_time	5min	0min–5min
Adaptive Auto-Sync	sync_adaptive_enabled	0	0 / 1
↳ Pause after	sync_adaptive_pause_after	4w	2w–8w (weeks without a new episode)
↳ Retry after (value)	sync_adaptive_retry_value	2	2–12
↳ Retry after (unit)	sync_adaptive_retry_unit	days	days, weeks, months

In weekly mode, sync_days + sync_times replace the fixed interval; a job then runs on the selected weekdays at each configured time (caught up if the app was off at that time). How it all works: AutoSync.

Download history

Setting	DB key	Default	Values
Retention	history_retention_days	30	0 (unlimited), 7, 30, 90, 180, 365 (days)

History entries older than the selected period are deleted automatically (cleanup runs roughly hourly in the background). Details: Download History.

Custom paths (additional download targets)

Named extra paths (e.g. a NAS mount) can be created under Settings. Downloads and AutoSync jobs can then pick a custom path per job. Paths in use by queue entries or sync jobs cannot be deleted.

DNS settings

If your ISP's DNS blocks the streaming sites, an alternative resolver can be selected — takes effect immediately, no restart:

Mode	Server
system	Operating system DNS (default)
cloudflare	1.1.1.1 (DoH)
google	8.8.8.8 (DoH)
quad9	9.9.9.9 (DoH)
custom	Your own server IP

The switch works on two levels: the app's HTTP requests use DNS-over-HTTPS (niquests), and socket.getaddrinfo is patched so subprocesses like FFmpeg use the chosen server too. A built-in DNS test checks reachability of aniworld.to, s.to and filmpalast.to.

Syncplay

Configure a Syncplay server for the Watch Together feature in the player (Web UI → Playback & streaming). The server runs a real Syncplay client per viewer, so playback syncs with desktop mpv/VLC users too.

Setting	DB key	Env variable	Default	Description
Server address	syncplay_server	MEDIAFORGE_SYNCPLAY_SERVER	empty	Hostname of the Syncplay server (feature is hidden when empty)
Port	syncplay_port	MEDIAFORGE_SYNCPLAY_PORT	8999	Syncplay server port
Use TLS	syncplay_tls	MEDIAFORGE_SYNCPLAY_TLS	0	Connect over TLS
Server password	syncplay_password	MEDIAFORGE_SYNCPLAY_PASSWORD	empty	Optional server password

Automatic updates (self-update)

Under Settings → Updates the app can update itself and switch release channel. The 24 h update check only shows a notice; this is the actual install side.

Setting	DB key	Default	Description
Auto-update	auto_update_enabled	0	Install an available update automatically
Weekdays	auto_update_days	0,1,2,3,4,5,6	Comma list, 0=Mon … 6=Sun
Time	auto_update_time	03:00	HH:MM — when the scheduled install runs

When enabled, an available update is installed automatically at the selected time on the chosen weekdays; the app restarts itself and any running downloads resume afterwards.

Release channel (stable ↔ dev): you can switch between the stable release and the dev channel (latest commits from the models branch — may be unstable). Switching installs the selected version right away.

Which installs can self-update: pip (release & dev) and pipx installs support self-update and channel switching. Docker, frozen (PyInstaller) and unknown installs cannot self-update — the UI shows a hint instead (update Docker via your image/compose, see Docker).

Watchdog (stuck downloads)

Setting	DB key / env	Default	Description
Hard timeout	watchdog_hang_timeout / MEDIAFORGE_HANG_TIMEOUT	1800 s	Maximum total duration of one episode download
Stall timeout	watchdog_stall_timeout / MEDIAFORGE_STALL_TIMEOUT	3600 s	Abort when no progress for this long

Environment-variable-only options

Some options exist only as environment variables (mostly relevant for Docker):

Variable	Description
MEDIAFORGE_WEB_ADMIN_USER / MEDIAFORGE_WEB_ADMIN_PASS	Auto-create the admin account on first start
MEDIAFORGE_HTTPS	1 = force secure cookies (behind a TLS proxy)
MEDIAFORGE_REDIS_URL	Redis storage for the login rate limit (in-memory otherwise)
MEDIAFORGE_VAPID_PRIVATE_KEY / MEDIAFORGE_VAPID_PUBLIC_KEY / MEDIAFORGE_VAPID_CLAIMS_EMAIL	Custom Web Push keys (auto-generated otherwise)
MEDIAFORGE_INSTALL_FOLDER	Location for auto-downloaded binaries (default ~/.mediaforge)

Other settings areas have dedicated pages: Authentication (SSO/OIDC), Notifications, Integrations (Jellyfin/Plex/Seerr/MediaScan/CineInfo), Encoding and Anime4K Upscaling.