Skip to content

Configuration Reference ​

YTMDL's backend is configured from environment variables (and, optionally, a YAML file). In the standard container deployment every value comes from .env, which Compose passes to the ytmdl-backend container. A template with safe example values ships as .env.example.

How configuration is resolved ​

The backend builds its configuration in this order, where each later step wins:

  1. Built-in defaults (documented in the tables below).
  2. YAML file — only if a config.yaml exists at the working directory, or a path is passed explicitly. The official container images do not mount one, so this is rarely used.
  3. Environment variables — always override the YAML file and the defaults.

Variable name prefixes ​

PrefixMeaning
MUSICDL_*The canonical, supported container contract. Prefer these.
YTDM_*Legacy aliases kept for backwards compatibility.

When the same setting is provided under both prefixes, MUSICDL_* wins. For the core settings (MUSICDL_LISTEN_ADDR, MUSICDL_LIBRARY, MUSICDL_CONCURRENT_DOWNLOADS, MUSICDL_YTDLP, MUSICDL_FFMPEG, MUSICDL_FFPROBE, MUSICDL_DATABASE_URL) a present canonical value also suppresses parsing of the legacy alias, so a stale YTDM_* value cannot make a valid MUSICDL_* configuration fail to start.

WARNING

The removed SQLite variables MUSICDL_DATABASE and YTDM_DATABASE_PATH are rejected with a clear startup error. Use MUSICDL_DATABASE_URL (PostgreSQL).

Dynamic settings (no restart) ​

A subset of settings — worker concurrency, lyrics toggles, minimum match score, the Genius fallback — can also be changed at runtime by an administrator in Settings (PUT /api/v1/settings). Runtime changes are stored in the database and take precedence over the environment for those specific fields.


Core Service ​

VariableDefaultDescription
MUSICDL_LISTEN_ADDR0.0.0.0:8080Address and port for the Go HTTP API.
MUSICDL_DATABASE_URL(required)PostgreSQL connection string, e.g. postgres://ytmdl:pass@db:5432/ytmdl?sslmode=disable.
MUSICDL_LIBRARY/music (container)Target directory for the organised music library.
MUSICDL_TRUSTED_PROXIES127.0.0.1/32,::1/128Comma-separated CIDRs/IPs trusted for X-Forwarded-For. The bundled compose files pass 127.0.0.1/32,::1/128,172.31.250.0/28 so the frontend proxy is trusted out of the box.
MUSICDL_COOKIE_SECUREfalseForce the Secure flag on session cookies (enable when serving over HTTPS).

Outbound proxy ​

Set HTTP_PROXY and HTTPS_PROXY in the deployment .env when providers must be reached through a proxy. Both Compose files pass that file to the backend. Set the lowercase http_proxy and https_proxy aliases to the same values for command-line tools, and use NO_PROXY / no_proxy for local services such as localhost,127.0.0.1,::1,backend,frontend,db. Recreate the backend after changing its environment; a container restart alone does not reload .env.

The proxy endpoint must be reachable from the container. A proxy on a private network is supported when explicitly configured, while private origin addresses and redirects remain blocked by the HTTP client. Origin DNS answers are checked locally; the trusted proxy must also enforce its own destination policy. The frontend and database do not need provider proxy settings.

Database pool ​

VariableDefaultDescription
MUSICDL_DB_MAX_CONNS10Maximum pooled server connections. Raise only together with worker count.
MUSICDL_DB_MIN_CONNS2Minimum idle connections kept open.
MUSICDL_DB_MAX_CONN_LIFETIME30mMaximum lifetime of a pooled connection.
MUSICDL_DB_MAX_CONN_IDLE_TIME5mIdle timeout before a connection is closed.
MUSICDL_DB_CONNECT_TIMEOUT10sTimeout for a single connection attempt.
MUSICDL_DB_STARTUP_TIMEOUT90sTotal budget spent waiting for PostgreSQL during startup.
MUSICDL_DB_STARTUP_BACKOFF1sFirst retry delay while waiting for PostgreSQL (doubles, capped at 5s).

Storage & Reliability ​

VariableDefaultDescription
MUSICDL_STAGING_DIR(empty → internal default)Persistent scratch directory for in-progress downloads. In the container this lives under /data.
MUSICDL_STORAGE_GUARD_ID(empty)Expected content of .ytmdl-storage-id at the library root. Empty disables the Storage Identity Guard. See Storage.
MUSICDL_LIBRARY_MIN_FREE_BYTES0 (disabled)Minimum free bytes on the library filesystem before downloads pause. 0 disables the check.
MUSICDL_STAGING_MIN_FREE_BYTES0 (disabled)Minimum free bytes in the staging directory. 0 disables the check.
MUSICDL_STAGING_MAX_BYTES0 (unbounded)Soft cap on total staging usage.
MUSICDL_ALLOW_OFFLINE_STAGINGfalseAllow yt-dlp to keep staging locally while the library mount is offline.

NOTE

The 5 GiB / 2 GiB free-space reserves mentioned in earlier documentation were not backend defaults — they are only active if you set the variables above. Choosing an explicit reserve (for example 5368709120 = 5 GiB) is recommended for network storage.


Downloads & Matching ​

VariableDefaultDescription
MUSICDL_CONCURRENT_DOWNLOADS2Maximum simultaneous yt-dlp download processes (valid range 1–16). Dynamic.
MUSICDL_MAX_ATTEMPTS5Maximum attempts for a job item across protected and unprotected retries.
YTDM_MAX_RETRIES2Ordinary retry budget for transient errors (range 0–10).
YTDM_RETRY_BACKOFF15sBase backoff between ordinary retries.
YTDM_TRACK_TIMEOUT30mHard timeout for a single track's acquisition, including time spent waiting for a media session. A track that reaches it is retried as TRACK_TIMEOUT within MUSICDL_MAX_ATTEMPTS; it never pauses a provider.
YTDM_MATCH_MIN_SCORE70Minimum match confidence (0–100) for a candidate to be accepted. Dynamic.
YTDM_MATCH_CANDIDATE_LIMIT10Maximum candidates evaluated per track (1–50).
YTDM_MATCH_DURATION_TOLERANCE_MS4000Allowed duration difference between metadata and audio candidate.

Combined-stream audio fallback (v0.27.3+) ​

Off by default, for every existing and every new installation. It is meant to be switched on deliberately for a controlled comparison first — see Audio format classification.

VariableDefaultDescription
YTDM_COMBINED_AUDIO_FALLBACKfalseAllow acquiring a track from a combined audio/video stream when the item offers no audio-only stream. The audio is copied out without re-encoding; the video never reaches the library. Requires a restart.
YTDM_COMBINED_FALLBACK_MAX_BYTES134217728 (128 MiB)Hard limit on what one combined transfer may move. An announced size above it is refused before the transfer, a running transfer is stopped once its progress passes it, and the arrived file is measured afterwards. A stop ends the item as TRANSFER_BUDGET_EXCEEDED without a retry.
YTDM_COMBINED_FALLBACK_TIMEOUT10mHard limit on how long one combined transfer may run, because it occupies the media session for its whole duration. It starts once the session's execution slot is granted; waiting for a busy session does not count. A stop ends the item as TRANSFER_BUDGET_EXCEEDED without a retry.

What the switch does not change: an audio-only stream always wins when one exists; matching, verification and duration tolerance are untouched; nothing is re-encoded; preview, DRM-protected and insufficiently described formats stay rejected; the absence of an audio-only stream never puts a provider family on hold; and with the switch off, an item without an audio-only stream ends exactly as before (TRACK_NOT_FOUND, no retry). A budget stop never pauses a provider family either.


Library output ​

VariableDefaultDescription
MUSICDL_LIBRARY_WRITE_COVER_FILEtrueWrite an external cover.jpg next to each release.
MUSICDL_LIBRARY_EMBED_COVERtrueEmbed album artwork into the audio file.
MUSICDL_LIBRARY_LYRICS_ENABLEDtrueResolve lyrics during download. Dynamic.
MUSICDL_LIBRARY_LYRICS_WRITE_SIDECARtrueWrite .lrc / .txt sidecar files. Dynamic.
MUSICDL_LIBRARY_AUTO_RENAMEtrueAfter an update that changes the file naming scheme, move existing files to their new names automatically, in the background. Set false to keep the old names until you choose the moment (media servers such as Plex track files by path); set it back and restart to run the move. Read at startup.
MUSICDL_LIBRARY_IDENTITY_MIGRATIONtrueAfter an update that changes how the backend recognises a track it already owns (its identity key), carry the keys of stored tracks over to the new form in the background, about 15 seconds after start. Only the key and its scheme number change; no file and no other data is touched. Set false to keep the stored keys; tracks are still found by their older keys. State at GET /api/v1/library/identity-migration. Read at startup.

Tools ​

VariableDefaultDescription
MUSICDL_YTDLPyt-dlpPath to the yt-dlp binary.
MUSICDL_FFMPEGffmpegPath to the ffmpeg binary.
MUSICDL_FFPROBEffprobePath to the ffprobe binary.
MUSICDL_COOKIE_FILE / YTDM_COOKIEFILE(empty)Optional Netscape cookies.txt for legacy external YouTube auth (e.g. /data/cookies.txt). Managed Media Sessions are the preferred mechanism — see Providers.
MUSICDL_YTDLP_PLAYER_CLIENTS(yt-dlp default)Comma-separated yt-dlp player-client list.
YTDM_TOOL_TIMEOUT5mTimeout for a single tool invocation.

Metadata & Media Providers ​

VariableDefaultDescription
YTDM_DEFAULT_METADATA_PROVIDERdeezerPreferred metadata provider.
YTDM_DEFAULT_MEDIA_PROVIDERytmusicPreferred media acquisition provider.
YTDM_SPOTIFY_CLIENT_ID(empty)Spotify Developer Client ID. Spotify auto-disables itself if either credential is missing.
YTDM_SPOTIFY_CLIENT_SECRET(empty)Spotify Developer Client Secret.
YTDM_SPOTIFY_MARKETDESpotify catalogue market.
MUSICDL_DEEZER_REQUESTS_PER_SECOND8Deezer sustained request ceiling (Deezer's own limit is ~10/s).
MUSICDL_DEEZER_BURST5Deezer token-bucket burst.
MUSICDL_DEEZER_MAX_RETRIES3Deezer retry attempts.
MUSICDL_DEEZER_RETRY_BACKOFF500msDeezer initial retry backoff.
MUSICDL_DEEZER_MAX_RETRY_BACKOFF8sDeezer maximum retry backoff.
MUSICDL_YTMUSIC_REQUESTS_PER_SECOND1.0YouTube Music metadata request ceiling.
MUSICDL_YTMUSIC_BURST1YouTube Music burst.
MUSICDL_YOUTUBE_REQUESTS_PER_SECOND(provider default)YouTube family request ceiling.
MUSICDL_YOUTUBE_BURST(provider default)YouTube family burst.
MUSICDL_SOUNDCLOUD_ENABLEDtrueEnable SoundCloud as an independent media provider.
MUSICDL_SOUNDCLOUD_REQUESTS_PER_SECOND1.0SoundCloud request ceiling.
MUSICDL_SOUNDCLOUD_BURST3SoundCloud burst.

Lyrics — Genius fallback ​

VariableDefaultDescription
MUSICDL_GENIUS_ENABLEDfalseEnable the optional Genius plain-text lyrics fallback. Dynamic (Settings).
MUSICDL_GENIUS_ACCESS_TOKEN(empty)Genius API client token. If set, the authenticated Genius Search API is used; otherwise a best-effort public search is attempted.

NOTE

The canonical names are MUSICDL_GENIUS_ENABLED / MUSICDL_GENIUS_ACCESS_TOKEN (plus YTDM_* aliases and a bare GENIUS_ACCESS_TOKEN). Older notes that used MUSICDL_PROVIDERS_GENIUS_* were incorrect and are ignored by the parser.


Managed Media Sessions ​

VariableDefaultDescription
MUSICDL_COOKIE_DIR / YTDM_COOKIE_DIR/data/cookies (container)Directory where uploaded session cookie files are stored (writable by UID 10001; defaults to ./data/cookies for non-container runs).
MUSICDL_SESSION_MAX_LEASES1Concurrent yt-dlp processes allowed per managed session.
MUSICDL_SESSION_REQUESTS_PER_SECOND0.5Per-session process-start rate.
MUSICDL_SESSION_BURST1Per-session burst.
MUSICDL_GLOBAL_REQUESTS_PER_SECOND2.0Family-wide process-start ceiling.
MUSICDL_GLOBAL_BURST4Family-wide burst.

Subscriptions ​

VariableDefaultDescription
MUSICDL_SUBSCRIPTIONS_ENABLEDtrueMaster switch for periodic subscription sync (endpoints and manual "check now" stay available when false).
MUSICDL_SUBSCRIPTION_SYNC_INTERVAL24hTarget interval between discography checks per artist.
MUSICDL_SUBSCRIPTION_CHECK_INTERVAL15mHow finely the scheduler observes the sync interval.
MUSICDL_SUBSCRIPTION_RETRY_INTERVAL1hDelay before retrying a failed sync.
MUSICDL_SUBSCRIPTION_SYNC_TIMEOUT30mExecution budget for one artist's catalogue walk.
MUSICDL_SUBSCRIPTION_BATCH_SIZE25Releases evaluated per batch.

Update Checks (v0.15+) ​

VariableDefaultDescription
MUSICDL_UPDATE_CHECKS_ENABLEDtrueEnable periodic background checks for new stable GitHub releases.
MUSICDL_UPDATE_REPOSITORYDer-Felix/ytmdlowner/repo queried for release metadata.
MUSICDL_UPDATE_CHECK_INTERVAL1hCache TTL / minimum interval between checks (floored at 5m).

NOTE

MUSICDL_UPDATE_CHECKS_ENABLED=false disables all outbound HTTP requests to the GitHub Releases API. No telemetry is sent in either case.


Logging ​

VariableDefaultDescription
YTDM_LOG_LEVELinfodebug, info, warn, or error.
YTDM_LOG_FORMATjsonjson (structured, default) or text (human-readable).

The backend never logs credentials or the database password; the connection URL is always redacted before it reaches a log line.

Released under the Apache 2.0 License.