Overview
Downtify is a self-hosted web app that turns Spotify and YouTube Music links into a tagged audio library. It never touches the Spotify API, and it needs no account and no Premium subscription. It also plays that library back, so what you download is one tab away from listening.
Spotify embed page → YouTube Music search → yt-dlp + ffmpeg + mutagen
(metadata) (audio match) (download & tag)
- Metadata. Track, album and playlist links are resolved from the public
open.spotify.com/embed pages, so no Spotify credentials of any kind are needed.
- Audio match.
ytmusicapi finds the best YouTube Music result by comparing durations. When there is no good match, standard YouTube is searched automatically (details).
- Download and tag.
yt-dlp fetches the audio, ffmpeg converts it to the format you chose, and mutagen embeds title, every credited artist, album, album artist, year and cover art; a song with several artists is filed under its album artist (see File organization).
All of it runs inside a single Docker container. See How it works for the full pipeline.
Features
| |
|---|
| Download | Spotify tracks, albums, playlists and artists (their releases and top songs); YouTube Music songs, albums, playlists and artists; SoundCloud tracks; free-text search; CSV imports from Soundiiz, TuneMyMusic and Exportify. MP3, FLAC, M4A, OGG or OPUS at the bitrate you pick. SoundCloud can also be turned on as an audio source for songs missing elsewhere (SoundCloud). See Download settings and Library import. |
| Pause the queue | Pause downloads before changing settings, troubleshooting or updating: downloads already running finish, nothing new starts, and the waiting songs (and the pause itself) survive a restart. Resume when ready. See Download Queue. |
| Charts | Browse Deezer's global "what's trending" chart — tracks (streaming in full, downloadable straight from the list), plus albums, artists and playlists to explore. See Charts. |
| Similar | Name an artist and a track to get similar tracks from YouTube Music's radio mix — every row plays in full in the player, downloaded or streamed, no key needed. See Similar. |
| Finder | Discover's search box: search Deezer, then explore an artist in Finder-style columns: their profile and bio, their whole discography, and any album's tracks playing in full, ready to download. See Finder. |
| Tags and lyrics | Title, artist, album, year and cover art embedded in every file, plus an explicit marker (the "E" you know from Spotify) on songs with explicit lyrics, shown in search, the Library and the player. Plain and time-synced lyrics from LRCLIB and NetEase, tried in the order you choose. See and . |
Read-only music folders stay protected during Upgrade library: their tracks are skipped before remote lookups, without changing files or marking unchecked categories as complete. See Upgrade library.
Existing Library .m3u playlists can use UTF-8 or the Windows-1252 legacy fallback. Unreadable playlists are skipped with a warning; reading keeps existing files intact. See M3U compatibility.
Quick start
You only need Docker.
docker run -d -p 8000:8000 --name downtify \
-v /path/to/downloads:/downloads \
-v downtify_data:/data \
ghcr.io/henriquesebastiao/downtify
Open http://localhost:8000, sign in as admin / downtify, change that password in Settings → General (or turn accounts off with DOWNTIFY_DISABLE_AUTH=true on a server only you can reach), then paste a link and start the download. Replace /path/to/downloads with the folder where you want your music.
/downloads holds your audio files and /data holds Downtify's database and settings. Keep both persistent, or settings, likes and playlist tracking are lost when the container is recreated.
Docker Compose
services:
downtify:
container_name: downtify
image: ghcr.io/henriquesebastiao/downtify:latest
ports:
- '8000:8000'
volumes:
- ./downloads:/downloads
- downtify_data:/data
restart: unless-stopped
volumes:
downtify_data:
To serve it on another port, set DOWNTIFY_PORT and map the same port (or choose it in Settings → Server → Port and change the mapping to match):
ports:
- '30321:30321'
environment:
- DOWNTIFY_PORT=30321
The remaining deployment options (timezone, monitor sync time, cookies file, IPv4) are listed under Environment variables. Everything else is configured from Settings in the web interface.
Home server platforms
What you can paste in
| Input | Example |
|---|
| Spotify track, album, playlist or artist | open.spotify.com/track/… |
| YouTube Music playlist | music.youtube.com/playlist?list=… |
| YouTube Music artist | music.youtube.com/channel/UC… or music.youtube.com/@artist |
| YouTube or YouTube Music video | youtube.com/watch?v=… |
| Deezer track, album, playlist or artist | deezer.com/track/… |
| SoundCloud track | soundcloud.com/artist/track |
| Free-text search | The Night Owls Do I Still Recall |
| Library export (CSV) | Soundiiz, TuneMyMusic, Exportify |
An artist link opens the artist's page, with their releases and a Top Songs button to pick from their most popular songs and download them, optionally as a playlist (details). Artists in your Library also get a Top songs tab with their first five Spotify top songs, kept in a per-artist file for a week, each streaming in full until you download it; an artist's bio, genre and links are also filled in, in your language, in the background as their first track finishes downloading (details). Artists can also be watched for new releases with the Playlist Monitor — just albums, singles or EPs if you like, and optionally only what comes out from now on, skipping the back catalogue. Public Deezer playlists can be watched too; Deezer artist links can be downloaded but not watched.
Downtify for Android
An Android app is being built: it signs in to your server with your username and password (or pairs by scanning a QR code from Settings → Apps), then browses your library, plays it in the original quality or a smaller one for mobile data, keeps songs on the phone for offline listening and casts to a Chromecast.
[!WARNING]
The app is still in development and no version has been published yet — there is nothing to install for now, and how it works may still change. The server side of it already ships with Downtify, which is why Settings → Apps is marked experimental.
Repository: henriquesebastiao/downtify-android
Anything that talks to the server can be built against the same API — see the mobile client contract.
Troubleshooting
Most download problems share one cause: YouTube wants a signed-in session. Upload a cookies.txt in Settings → YouTube cookies and they usually go away. If YouTube still rate-limits you, raise Delay between downloads, lower Parallel downloads, then try DOWNTIFY_FORCE_IPV4=1.
See Troubleshooting for the full list of symptoms and fixes, and YouTube cookies for how to export the file.
Translations
The interface is available in English, Spanish, Brazilian Portuguese, French, Turkish, Hungarian, Greek, Bulgarian, German and Korean, and so is the documentation: it opens in your browser's language when it is translated into it (English otherwise), and the globe button in the top bar switches language. Switch the app's language in Settings → Language; the choice is saved in the browser and applies without a reload.
Contributing translations
You can translate the app, the documentation, or both — they are independent, and partial work is welcome. For the app, adding a language is a small change and needs no tooling beyond the existing Vite setup:
- Copy
frontend/src/i18n/locales/en.js to a new file named after an IETF language tag (de.js, it.js, pt-PT.js).
- Translate the values. Keep the keys and placeholder tokens (
{count}, {name}, {file}) unchanged, and set language.name to the language's native name.
- Register the locale in
frontend/src/i18n/index.js.
Missing keys fall back to English, so a partial translation is welcome. For the documentation, each language is a folder in docs/ with the same pages as English; npm run i18n -- status <code> (from docs/) shows what is left to translate. The full walkthrough for both, with the registration snippet and tips, is in Internationalization.
Documentation
[!WARNING]
Users are responsible for their actions and any legal consequences. Downtify does not support unauthorized downloading of copyrighted material and takes no responsibility for user actions.
slskd polling
Idle Soulseek transfers are checked every 60 seconds instead of repeatedly walking the music folders. DOWNTIFY_POLL_INTERVAL (5), DOWNTIFY_POLL_IDLE_INTERVAL (60), DOWNTIFY_TRANSFERS_TTL (3) and DOWNTIFY_POLL_DEEP_SCAN_EVERY (12) tune this behavior; see slskd polling for limits and latency. The Compose example includes the defaults.
Contributing
Contributions, issues and feature requests are welcome. Check the issues page or open a pull request.
Before sending a pull request, read CONTRIBUTING.md. It covers local setup, the coding and formatting standards (Ruff for Python, Prettier for the frontend), testing requirements, commit conventions and the pull request checklist.
If Downtify has been useful to you, a star on GitHub helps other people find it.
Contributors
Thanks for your contribution to the project!
Support
There are many ways to support Downtify:
License
Licensed under the AGPL-3.0 License.
Icons by Font Awesome (Free, CC BY 4.0), loaded via Iconify.
Library-only mode
Settings → General can restrict every browser and Android client to music already in the server library, including search and tag-based similar tracks. External streams and downloads are disabled without deleting music or watched playlists. See Library-only mode.
Administrators can configure download exclusions and cumulative attempt budgets.
