Estimated reading time: 7 minutes
Today I'd like to introduce you to an open source project that should interest many music fans: Spotizerr. It combines the extensive music search of Spotify with the high audio quality of Deezer - and allows music to be downloaded directly.
Before we get started, a A clear note in advance:
I introduce Spotizerr only. I am not the developer and you uses the tool at his/her own risk. The use can be against the Terms and conditions of Spotify and Deezer violated. If you test Spotizerr, it is best to do so only locally, for learning purposes and with a Test account. No liability!
For detailed instructions and an explanation of all configuration options, I recommend the YouTube video linked below. In this video, every single setting is explained in detail so that you receive comprehensive instructions for the exact setup. You can find any code from the video in this article so that you can use it directly without having to type it in.
This blog post and video is part of a series in which we create and set up our own home server. We start with the basics like an Ubuntu VM installation with Docker and then continue with the configuration of your own domain, security precautions and above all lots of cool and useful self-hosted services. Whether media servers like Plex or Jellyfin or document management like Paperless-NGX. Together we'll build the setup you want to see. We even tackle topics such as single sign-on (SSO) together.
What exactly does Spotizerr do?
Spotizerr is a music downloader that works as follows:
- You are looking for a song - the search runs via the official Spotify API.
- During the download attempt, the tool first checks whether the audio file is in good quality at Deezer is available.
- If so, the file will be downloaded from Deezer.
- If not, Spotizerr uses Spotify as a fallback source.
This gives you potentially high-quality audio files with very little effort. The whole thing is done directly via a GUI interface - it couldn't be easier. The tool is therefore ideal if you want to quickly save certain tracks with the highest possible quality.
🚀 Normal functions (UI features)
As soon as you call up Spotizerr, you can get started straight away. The basic functions:
- 🔍 Search for songs, albums, playlists & artists (via Spotify)
- 📥 Single track download (simply click on the download symbol)
- 🧾 Album & Playlist Download (complete)
- 🎶 Artist-View with top tracks
- 🔁 Fallback to Spotifyif Deezer is not available (optional)
All downloads end up in the specified folder - in the best possible quality (FLAC or MP3 depending on the source).
⚙️ Advanced functions
If you want to go deeper, Spotizerr offers some professional features:
- ✅ Recognize & skip already downloaded songs (you save time & memory)
- 🎵 Automatic filename sanitizer (so that your songs can be played everywhere)
- 🔧 Logging of failed downloads - Ideal for later repetitions
- 🗃️ Fallback mode via Spotify configurable (
fallback_to_spotify: true/false) - 🧠 Offline checkwhether a song already exists in the target directory
These features help you to process large libraries efficiently and manage downloads better.
🔧 Requirements
- Docker installed on your server
- One Spotify Developer Account (for API Key)
- A Deezer account (free is usually enough)
- The Auth component
spotizerr-auth- Python 3.7+ on this device only
- Access to GitHub:
🐳 Install Spotizerr via Docker
The developers of Spotizerr recommend the use via Docker - fast, isolated, system-independent. In addition to spotizerr, we also need Redis as an object cache.
Create a file with the name docker-compose-spotizerr.yml with the following content:
services:
spotizerr:
image: cooldockerizer93/spotizerr
container_name: spotizerr
restart: unless-stopped
networks:
- sascha
environment:
TZ: Europe/Berlin
REDIS_HOST: redis
REDIS_PORT: 6379
REDIS_DB: 0
EXPLICIT_FILTER: false
PUID: "99"
PGID: "100"
UMASK: "0022"
ports:
- 7171:7171
volumes:
- /mnt/cache/appdata/downloader/spotizerr:/app/data:rw
- /mnt/cache/downloads/:/app/downloads:rw
- /mnt/cache/appdata/downloader/spotizerr/logs:/app/logs:rw
healthcheck:
test: ["CMD", "python", "-c", "from urllib.request import urlopen; urlopen('http://localhost:7171')"]
interval: 1m
timeout: 10s
retries: 3
depends_on:
- redis
redis:
image: redis
container_name: redis
restart: unless-stopped
networks:
- sascha
environment:
TZ: Europe/Berlin
ports:
- 6379:6379
volumes:
- /mnt/cache/appdata/redis:/data:rw
command: [
"redis-server",
"--save", "60", "1",
"--loglevel", "warning"
]
healthcheck:
test: ["CMD", "redis-cli", "--raw", "incr", "ping"]
interval: 30s
timeout: 10s
retries: 3
networks:
sascha:
external: trueThis Docker Compose starts two containers:
- spotizerrA tool for Spotify downloads, runs on port 7171 and saves data/downloads/logs locally.
- redis: A cache/database service that spotizerr uses.
Both containers share an external Docker network called sasha.
You can then simply start the services with the following command:
docker compose -f "docker-compose-spotizerr.yml" up -dYou can now open the web interface via http://deine-IP-Adresse:7171 call.
Configuration in detail
After you start the Docker container, you must configure all services.
Here are the most important configuration steps:
🔐 Step 1: Prepare Spotify authentication
1. create Spotify Developer App
- Go to: https://developer.spotify.com/dashboard
- Create new app
- Generate Client ID & Secret and make a note for later
2. connect Spotify with Spotizerr
For Spotizerr to work with your Spotify developer account, you need valid access tokens. To do this, use the tool spotizerr-auth. You can do this on your PC and does not have to be on your server.
📦 This is how it works:
git clone https://github.com/Xoconoch/spotizerr-auth
cd spotizerr-auth
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Execute the script / tool:
python spotizerr-auth.pyNow a local server is running under http://localhost:8888.
Open it in your browser - you will be redirected to the Spotify login page.
The script will guide you through the following steps:
Enter Spotizerr URL:
You will be asked for the base URL of your Spotizerr instance. In your case then http://deine-IP-Adresse:7171.
Configure API access data:
The script checks whether your Spotizerr instance is already connected to a Spotify client_id and client_secret is configured.
- If these are missing, you will be asked if you want to configure them.
- Choose
yand enter your access data when you are prompted to do so. This is only necessary once.
Enter account details:
- Enter a name for the account to identify it in Spotizerr.
- Enter your two-digit Spotify country code (e.g. US, DE, MX).
Authentication via Spotify Connect:
- The tool starts a Spotify Connect device in your network (e.g.
librespot-spotizerr). - Open Spotify on any device (smartphone, desktop), start playback of a song and use the function "Connect with a device"to transfer playback to the new device.
- As soon as you transfer the playback, the script captures the session, creates a file
credentials.jsonand shuts down the Connect server again.
Registration with Spotizerr:
The script automatically sends the recorded access data to your Spotizerr instance and creates or updates the account.
Clean up:
Finally, you will be asked whether you want to save the file credentials.json want to delete. This is recommended for security reasons.
After these steps, your Spotify account is registered in Spotizerr and ready to use. Then you need all the stuff around spotizerr-auth and you can delete all of it.
🔐 Step 2: Prepare Deezer authentication
We will go through the whole thing using Google Chrome as an example. With Firefox, however, it is almost identical. Log in to https://www.deezer.com in the browser. You then have to press F12.
Expand the Cookies section and select "https://www.deezer.com". Find the "arl" cookie and double-click on the text in the "Cookie value" tab.
Copy the value and paste it into the corresponding setting in Spotizerr.
Troubleshooting
If something does not work, check the following:
| Problem | Solution |
|---|---|
| No tracks are found | Make sure that your access_token/refresh_token are valid |
| 403 error with Spotify | The token has probably expired - simply use spotizerr-auth Regenerate |
| Deezer download fails | Check the arl-cookie (is often quickly invalidated) |
| Music is not saved | Folder paths in Docker mounts specified correctly? Write permissions available? |
| No fallback to Spotify | In the config.json must fallback_to_spotify on true be set |
YouTube video implementation
Conclusion
Spotizerr is an extremely useful tool for anyone who wants to work with music locally, set up automated workflows or better understand APIs. Docker makes it easy to use, and thanks to its open structure, you can even extend the tool.
But: You should for private testing purposes only and not with your real Spotify or Deezer account.
0 Comments