Frequently Asked Questions
General
What is YTMDL, and how is it different from a yt-dlp web wrapper?
A typical yt-dlp web UI takes a URL and hands you a file. YTMDL is a library manager: it resolves a complete artist discography from structured metadata providers (Deezer, Spotify, YouTube Music), matches each track to an audio candidate with conservative scoring, downloads native Opus without re-encoding, writes standardised tags and cover art, resolves synchronised lyrics, files everything into a Jellyfin/Plex/Navidrome/Emby-compatible folder tree, tracks everything in PostgreSQL, and keeps it up to date through artist subscriptions. It also includes a multi-user web player. The download step is one part of a pipeline, not the product.
Is YTMDL affiliated with YouTube, Spotify, or Deezer?
No. It is an independent open-source project (Apache-2.0). Provider names and trademarks belong to their owners. See Legal.
Does YTMDL send telemetry?
No. The only outbound "phone home" is the optional GitHub release check, which is an anonymous GET to the public Releases API and can be disabled entirely with MUSICDL_UPDATE_CHECKS_ENABLED=false.
Installation & Platforms
Which platforms are supported?
Application containers (ghcr.io/der-felix/ytmdl-backend / -frontend) are published for linux/amd64 and linux/arm64. The ytmdlctl host CLI is additionally built for darwin/amd64 and darwin/arm64. Windows is not supported. On macOS, ytmdlctl drives a Podman Machine or Docker daemon.
Do I need to build from source?
No — for stable releases use the official images with compose.ghcr.yaml. You only build from source to run the unreleased dev branch: git clone -b dev, then docker compose -f compose.yaml up -d --build. See Development.
Podman or Docker?
Both work. With Podman, use a Compose v2 provider (Docker Compose plugin or podman-compose-subcommand). The legacy Python podman-compose (1.3.x and older) does not support the Compose v2 volume flags and keep-id user-namespace mapping YTMDL relies on; ytmdlctl detects it in preflight and refuses to proceed.
Configuration & Storage
Where do settings live?
In environment variables, supplied through .env. See the Configuration Reference. A handful of settings (worker concurrency, lyrics toggles, minimum match score, Genius) can also be changed at runtime in Settings without a restart.
MUSICDL_* or YTDM_*?
Prefer MUSICDL_* — it is the supported contract. YTDM_* names still work as aliases; if both are set, MUSICDL_* wins.
Can I store my library on a NAS?
Yes, by mounting the SMB/CIFS or NFS share on the host and bind-mounting the host path into the container as /music. YTMDL never mounts network filesystems itself. Protect against a disconnected share with the Storage Identity Guard. See Storage, SMB, NFS.
What is the Storage Identity Guard?
A marker file (.ytmdl-storage-id) at the library root whose expected value you put in MUSICDL_STORAGE_GUARD_ID. If the marker is missing or wrong (share unmounted, wrong volume), YTMDL pauses the queue and rejects writes instead of silently filling the host disk.
Downloads & Library
Why is a download "Wartet auf Provider"?
The media provider or an authenticated session is in a temporary cooldown (rate limit or verification challenge). This is not a failure: the item waits without spending its retry budget and resumes automatically when the provider recovers. See Providers.
Why did a track fail to match?
Conservative matching rejects candidates outside the duration tolerance (4000 ms default) or below the minimum score (70), and filters out live versions, covers, and remixes. Lower YTDM_MATCH_MIN_SCORE or raise YTDM_MATCH_DURATION_TOLERANCE_MS cautiously if legitimate tracks are missed.
Manual downloads run before my subscription sync — why?
Manual requests default to High priority; subscription sync jobs are Low. You can change any job's priority on the Downloads page. See Download Automation.
Does YTMDL re-encode audio?
No. It prefers a native Opus stream and remuxes stream-copy. Other native formats (AAC/M4A, etc.) are stored as-is. YTDM_ALLOW_TRANSCODE is false by default.
How are files named?
Artist/YYYY - Album/NN - Title.opus, with 1-01 -, 2-01 - numbering for multi-disc releases, embedded Vorbis comments, cover.jpg, and .lrc/.txt lyric sidecars. Characters a filesystem refuses become fullwidth look-alikes (AC/DC is stored as AC/DC). See File names.
Updates, Backup & Rollback
How do I update?
Raise YTMDL_VERSION in .env and run ytmdlctl update (preview first with ytmdlctl update --dry-run). It takes a verified database backup, checks image digests against the release manifest, and can roll back. See Updates.
What does a backup contain — and not contain?
ytmdlctl backup (or pg_dump -Fc) captures the PostgreSQL catalogue only: users, artists, albums, tracks, jobs, playlists, favorites, audit history. It does not contain your audio files (./music) or ./data (cookie files). Back those up separately.
Can I always roll back?
Only when the target release is schema_neutral and the schema has not drifted. Across a schema migration, automatic rollback is intentionally blocked; you restore the verified pre-migration backup with ytmdlctl recover restore. The pre-update backup always remains in backups/.
Is there a database migration in the current stable release?
Stable v0.27.0 keeps schema 12; no migration. The last migration was schema 11 → 12 in v0.23.0 (playlists/favorites).
Player
The player won't play a file in Safari.
Codec support is the browser's. Opus-in-Ogg is not universally supported in Safari. Try the same track in Chromium/Firefox to confirm. YTMDL does not transcode on the fly. See Player → Known Browser Limitations.
Is there a mobile app or a TV app?
No. There is no installable PWA, service worker, or native app of any kind. The browser UI is the only client.
Security
How are passwords stored?
Argon2id. Sessions are random server-side tokens in PostgreSQL; mutating endpoints require a CSRF token (double-submit cookie). Two roles exist: Administrator and User. See Security.
How do I report a vulnerability?
Privately, via GitHub Private Vulnerability Reporting — not a public issue. See SECURITY.md.
