Why does this exist? Spotify AI DJ sucks. What kinda DJ doesn't take requests??
While working, I was having trouble picking out the right music. I thought, "Man, it would be great if I could request a song from an AI that would truly understand what I want." I tried the official Spotify AI DJ, but it really does suck. So I decided to make my own.
It started as a super small project, but I liked it so much that I made it into a full app to share.
Anyways, this one doesn't suck. Tell it what you wanna hear and it will play it.
- Smart Requests: Just type "Play lofi music" or "something fast for coding."
- Playlist support: Link a playlist and it can intelligently queue up similar music.
- Model support: Use a Local LLM or Google Gemini via API.
- Toggle Control: Switch between Local LLM or Cloud easily.
- Playback Control: Basic media controls (play, pause, like songs).
- Preferenece engine Learns your preferences in music over time from likes and skips (inside of the app).
- Spotify Premium (Required for playback control via API).
- Gemini API Key from Google AI Studio.
- Note: It takes a few seconds to make and is free!! (a good thing).
- Or: Ollama running locally no API key needed, fully private, works offline.
- Download and unzip the project folder
- Double-click
install.bat - If Python is not installed, your browser will open the download page.
Install Python — make sure to tick "Add Python to PATH" — then
double-click
install.batagain - Launch via the Spotify AI DJ shortcut on your Desktop
git clone https://github.com/schultz-dev0/SpotifyDJ ~/SpotifyDJ./SpotifyDJ/install.shAfter install, launch via your application menu or run bash launch.sh
from the project folder.
git clone https://github.com/schultz-dev0/SpotifyDJ /Users/YourUserName/Downloads/SpotifyDJbash /Users/YourUserName/Downloads/SpotifyDJ/install_mac.shCreates Spotify AI DJ.app in ~/Applications
which you can drag into the Dock.
To open graphical window, launch from application launcher or:
dj
python main.pyType your request and press Play or Enter.
Pass your request as an argument to a global dj command:
dj "dark techno"
dj "relaxing lo-fi for studying"
dj "90s hip hop"
dj "aggressive drum and bass"
dj "something cinematic and intense"On Windows, use Python directly since the dj command is not installed:
python main.py "dark techno"If you want to use a local model instead of Gemini you can:
- Install Ollama and pull a model
ollama pull llama3.2- Open the settings panel in the app and fill in:
- Base URL:
http://localhost:11434 - API Key: leave blank
- Model:
llama3.2:latest
- Base URL:
dj --help- Learning music preferences
- Expand the example library for better prompt recognition
- (For me) watch user suggestions for improvements
- Uninstall script
"No Spotify device found" Open Spotify on your computer then try again. The app can only control a device that already has Spotify running.
Playback starts but nothing plays / skips immediately Spotify Premium is required for remote playback control via the API. Free accounts can search but cannot be controlled programmatically.
Gemini quota errors The app automatically tries several models in sequence. If all fail it falls back to basic keyword search so you always get results. If you use the app too much you will run out of request quota and you will need to wait, I suggest a local LLM if you know you will send a lot of requests
Linux — GTK4 not found error
Run bash install.sh again. If you installed manually, make sure
python3-gi and gir1.2-gtk-4.0 are installed at the system level
(not via pip).
macOS — app does not open after double-clicking
Open Terminal, navigate to the project folder, and run bash launch.sh.
If that works, the issue is macOS Gatekeeper blocking unsigned apps.
Go to System Settings > Privacy & Security and allow the app to run.
Reset the app
Delete ~/.spotify-ai-dj/ to wipe your saved key and Spotify token.
The setup screen will appear on next launch.
SpotifyDJ/
├── main.py Entry point — routes to GUI or CLI based on arguments
├── app.py Backend router — detects Wayland vs X11/Windows/macOS
├── app_gtk.py GTK4 backend (Linux Wayland)
├── app_ctk.py customtkinter backend (Windows, macOS, Linux X11)
├── cli.py Headless CLI mode — play without opening a window
├── brain.py Gemini AI — converts requests to Spotify search queries
├── spotify_client.py Spotify OAuth and playback control
├── config.py User config storage (~/.spotify-ai-dj/config.json)
├── requirements.txt Python dependencies
├── install.bat Windows installer (double-click)
├── install.sh Linux installer (all distros, Wayland + X11)
└── install_mac.sh macOS installer (Big Sur+)
app.py checks $WAYLAND_DISPLAY at startup:
Linux + WAYLAND_DISPLAY set -> app_gtk.py (native Wayland window)
everything else -> app_ctk.py (customtkinter window)
To force a specific backend for testing, edit the run() function in
app.py and hard-code which backend to load.
All colours, fonts, and spacing are defined in the APP_CSS constant
near the top of app_gtk.py. It uses standard CSS. Edit it freely.
Edit the constants at the top of app_ctk.py:
ctk.set_appearance_mode("dark") # "dark" | "light" | "system"
ctk.set_default_color_theme("blue") # "blue" | "dark-blue" | "green"Font and colour constants (FONT_*, COLOR_*) are also at the top of
the same file.
If you fork and redistribute this project, create your own Spotify app
at https://developer.spotify.com/dashboard and set the Redirect URI to
http://127.0.0.1:8888/callback. Then update the constants at the top
of spotify_client.py:
SPOTIFY_CLIENT_ID = "your_client_id"
SPOTIFY_CLIENT_SECRET = "your_client_secret"Edit CANDIDATE_MODELS in brain.py. Models are tried in order — put
the fastest or most quota-generous ones first.
Gemini is NOT required to run it but if you intend to use a free AI agent, it is the best provider to use
The GTK4 backend registers the app with the ID com.spotifyaidj.app.
You can target it in hyprland.conf:
windowrule = float, class:com.spotifyaidj.app
windowrule = size 540 620, class:com.spotifyaidj.app
windowrule = blur, class:com.spotifyaidj.app
| Platform | Path |
|---|---|
| Windows | C:\Users\<you>\.spotify-ai-dj\ |
| macOS | /Users/<you>/.spotify-ai-dj/ |
| Linux | /home/<you>/.spotify-ai-dj/ |
Contents:
config.json Gemini API key
.spotify_cache Spotify OAuth token (auto-refreshed)
pip install pyinstaller
pyinstaller --onefile --windowed --name "SpotifyAIDJ" main.pyOutput is placed in the dist/ folder. Note that the GTK4 backend
cannot be bundled this way — the PyInstaller build will always use
the customtkinter backend regardless of platform.
Planned to make this available for phones but spotify actually made their own request DJ thing for phones so not doing that anymore