Downtify

Install • Documentation • Android App

Features • Changelog • Sponsor • Contributing

Self-hosted music downloader. Paste a Spotify link,
get a perfectly tagged audio file no API keys, no account, no hassle

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)

1. 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.
2. Audio match. ytmusicapi finds the best YouTube Music result by comparing durations. When there is no good match, standard YouTube is searched automatically (details).
3. Download and tag. yt-dlp fetches the audio, ffmpeg converts it to the format you chose, and mutagen embeds title, artist, album, year and cover art.

All of it runs inside a single Docker container. See How it works for the full pipeline.

Features

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.

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

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. Deezer 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:

1. Copy frontend/src/i18n/locales/en.js to a new file named after an IETF language tag (de.js, it.js, pt-PT.js).
2. Translate the values. Keep the keys and placeholder tokens ({count}, {name}, {file}) unchanged, and set language.name to the language's native name.
3. 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.

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:

• Use it! Write about it! Star it! If you love Downtify, drop me a line and tell me what you love.
• Blog about Downtify to spread the word. If you're good at writing, send PRs to improve the documentation at downtify.henriquesebastiao.com.
• Sponsor my work at https://www.buymeacoffee.com/henriquesebastiao

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.