A highly configurable Spotify CLI downloader for tracks, albums, playlists, podcasts, and music videos.
Build permanent offline music libraries with lossless FLAC, full metadata, cover art, and synced lyrics.
Designed for music enthusiasts, Python developers, and automated media library workflows.
Requires Python 3.10+
pip install dotify-cli --upgradeSet up your environment in one command:
dotify env setup # creates ~/.dotify/ with all required dirs
dotify env doctor # verifies dependencies and credentialsNew to Dotify? See the full Installation Guide for FFmpeg, Aria2c, and Widevine key setup.
# Download a track
dotify "https://open.spotify.com/track/18gqCQzqYb0zvurQPlRkpo"
# Download an album
dotify "https://open.spotify.com/album/0r8D5N674HbTXlR3zNxeU1"
# Download a playlist
dotify "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M"
# Download an artist's full discography
dotify "https://open.spotify.com/artist/..."
# Download in lossless FLAC (Premium required)
dotify --audio-quality flac-flac,aac-high "https://open.spotify.com/track/..."For Premium quality (FLAC / AAC 256kbps), you'll need Spotify cookies and a Widevine key.
See Authentication for the full setup walkthrough.
| Type | Formats | Quality | Notes |
|---|---|---|---|
| Songs | Vorbis | 96–320kbps | No extra tools required |
| Songs | AAC | 128–256kbps | Requires .wvd + Premium |
| Songs | FLAC / 24-bit FLAC | Lossless | L1-certified .wvd + Premium |
| Podcasts | Vorbis / AAC | 96–320kbps | Free + Premium |
| Music Videos | MP4 (H.264), WebM | Up to 1080p | Requires .wvd + FFmpeg + Premium |
| Podcast Videos | MP4, WebM | Up to 1080p | Requires FFmpeg / MP4Box |
| Lyrics | LRC (synced) | — | Downloaded automatically |
dotify env setup— One-command environment scaffoldingdotify env doctor— Comprehensive health checks with actionable fixesdotify env paths— Inspect all Dotify-related file locationsdotify env check [component]— Check a specific dependency (ffmpeg,cookies,wvd, ...)
- Flexible templates — Customize folder and file names with
{artist},{album},{year},{isrc}, and more - Quality fallback chains —
flac-flac-24,flac-flac,aac-hightries each in order automatically - Multiple download modes —
ytdlp(default) oraria2cfor parallel multi-connection downloads - Multiple remux modes — FFmpeg, MP4Box, or mp4decrypt
- Preflight validation — Checks credentials and dependencies before every download
- Batch downloads — Pass multiple URLs or a
.txtfile with-r
Config file is auto-created at ~/.dotify/config.ini (Linux/macOS) or %USERPROFILE%\.dotify\config.ini (Windows).
| Key | Description | Default |
|---|---|---|
cookies_path |
Path to Spotify cookies file | ~/.dotify/cookies.txt |
wvd_path |
Path to Widevine .wvd key |
~/.dotify/keys/device.wvd |
output_path |
Root output directory | Spotify |
audio_quality |
Quality priority list | aac-medium |
wait_interval |
Seconds between downloads | 5 |
log_level |
Logging verbosity | INFO |
| String | Format | Bitrate / Depth | Requires Premium |
|---|---|---|---|
flac-flac-24 |
FLAC | 24-bit lossless | ✅ |
flac-flac |
FLAC | 16-bit lossless | ✅ |
aac-high |
AAC | 256kbps | ✅ |
vorbis-high |
Vorbis | 320kbps | ✅ |
aac-medium |
AAC | 128kbps | ❌ |
vorbis-medium |
Vorbis | 160kbps | ❌ |
vorbis-low |
Vorbis | 96kbps | ❌ |
| Scope | Variables |
|---|---|
| Album | {album}, {album_artist}, {year}, {label} |
| Track | {title}, {track}, {disc}, {artist} |
| Metadata | {isrc}, {composer}, {copyright}, {genre} |
| Playlist | {playlist_title}, {playlist_artist}, {playlist_track} |
# Example: organized library structure
dotify "URL" \
--album-folder-template "{album_artist}/{album} [{year}]" \
--single-disc-file-template "{track:02d} - {title}"See the full Configuration Reference for all options.
To access Premium quality content:
-
Get Spotify cookies — Export from open.spotify.com using "Get cookies.txt LOCALLY" (Chrome/Edge) or "Export Cookies" (Firefox). Save to
~/.dotify/cookies.txt. -
Get a Widevine key — Use KeyDive on an Android device to extract
device.wvd. Place it at~/.dotify/keys/device.wvd. -
Verify — Run
dotify env doctor.
dotify env setup --create-placeholders # scaffolds empty files so you know what to fill in
dotify env doctor # confirms everything is readyFull walkthrough: Authentication
dotify "https://open.spotify.com/track/..."
dotify "https://open.spotify.com/album/..."
dotify "https://open.spotify.com/playlist/..."
dotify "https://open.spotify.com/artist/..."dotify "URL" --audio-quality flac-flac-24,flac-flac,aac-high
dotify "URL" --output "/path/to/music"
dotify "URL" --synced-lyrics-onlydotify "URL" --download-music-videos
dotify "URL" --download-podcast-videos
dotify "URL" --video-format webmdotify --read-urls-as-txt urls.txt
dotify "URL1" "URL2" "URL3"
dotify "URL" --wait-interval 10 --log-level DEBUGdotify "URL" --download-mode ytdlp # default
dotify "URL" --download-mode aria2c # faster (requires aria2c)| Error | Cause | Fix |
|---|---|---|
403 Forbidden / Unauthorized |
Cookies expired | Re-export from incognito, replace ~/.dotify/cookies.txt |
Getting 128kbps despite aac-high |
Free account or missing .wvd |
Check dotify env doctor |
ffmpeg not found |
Not in PATH | Install FFmpeg or set ffmpeg_path in config |
dotify not found after install |
Scripts dir not in PATH | Run python -m dotify "URL" or reinstall with --user |
| Video download fails | mp4decrypt/MP4Box missing |
Install Bento4 + GPAC, verify with mp4decrypt --version |
| Slow downloads | Aria2c not installed | Install aria2c, use --download-mode aria2c |
dotify env doctor --verbose # full diagnostic
dotify env doctor --json # machine-readable output
dotify env check ffmpeg # check a specific component
dotify env paths # inspect all file pathsFull FAQ: Troubleshooting
Full documentation is available in the Wiki:
| Page | Description |
|---|---|
| Installation | pip install, FFmpeg, Aria2c, Bento4 setup |
| Environment Setup | env setup, env doctor, v1→v2 migration |
| Authentication | Cookies, KeyDive, Widevine .wvd |
| Basic Usage | Tracks, albums, playlists, artists |
| Advanced Usage | Templates, video, lyrics-only, batch |
| Audio Quality Reference | All format strings and priority examples |
| Configuration | Full config.ini key reference |
| Dependencies Explained | FFmpeg, Aria2c, mp4decrypt, MP4Box, WVD |
| Troubleshooting | Error index and fixes |
dotify env setup— one-command environment scaffoldingdotify env doctor— comprehensive health checks with actionable errorsdotify env paths/dotify env check— granular diagnostics- Centralized config at
~/.dotify/, preflight validation before every run
- FLAC and 24-bit FLAC audio quality support
- Improved fallback quality chain handling
Contributions are welcome!
- Fork the repository
- Create your feature branch:
git checkout -b feature/AmazingFeature - Commit your changes:
git commit -m 'Add AmazingFeature' - Push to the branch:
git push origin feature/AmazingFeature - Open a Pull Request
- Spotify — for the platform
- KeyDive — Widevine key extraction
- yt-dlp — download engine
- FFmpeg — media processing
- All contributors and users of Dotify
MIT License — see LICENSE for details.
📧 salahin0ashfi@gmail.com · 💬 Discord · 🐛 Issues
⭐ If Dotify saves you time, a star goes a long way! ⭐
Made with ❤️ by @AsHfIEXE