Skip to content

Passive Music Downloader

A background service that monitors Spotify and YouTube Music playlists and automatically downloads newly added tracks as local audio files, with metadata and album artwork embedded in each file's tags.

How it works

The service runs continuously and performs a sync cycle on a configurable interval. Each cycle:

  1. For every configured Spotify and YouTube Music playlist, fetches the current list of tracks from the provider's API.
  2. Skips tracks that are already recorded in the local SQLite database, so only new tracks are downloaded.
  3. Resolves each new track to a YouTube video and downloads its audio with yt-dlp, converting to the configured output format (MP3, M4A, OGG, FLAC, or Opus).
  4. Looks up the track on MusicBrainz to find its canonical recording ID, fetches album art from the provider or the Cover Art Archive, and embeds everything (title, artist, album, album art, and provider/MusicBrainz IDs) into the file's tags.
  5. Records the downloaded file in the database so it is not downloaded again.

A full scan runs at startup, reconciling the database against the files on disk. Files that appear without a database entry are added by reading their embedded IDs; files that have been deleted are removed from the database.

See Architecture for the details of each stage and the Configuration reference for a full list of options.

Key concepts

  • Track identity: every downloaded file stores its Spotify, YouTube Music, and MusicBrainz IDs in standard tag frames (UFID). The database and the filesystem can therefore be reconciled without guessing.
  • Filesystem as source of truth: the download directory is the canonical record of what exists; the database is derived from it on every startup.
  • Serialised downloads: tracks are downloaded one at a time, in a worker thread, to avoid hammering YouTube and to allow clean cancellation on shutdown.

Design history

Decisions that explain why the software behaves the way it does are recorded as architecture decision records, linked from the relevant sections of the product docs.