dotify-cli 2.0.16

A command-line app for downloading songs, podcasts and videos from Spotify with smart environment management.

🎵 Dotify

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.

Installation • Quick Start • Features • Documentation

---

📦 Installation

Requires Python 3.10+

pip install dotify-cli --upgrade

Set up your environment in one command:

dotify env setup    # creates ~/.dotify/ with all required dirs
dotify env doctor   # verifies dependencies and credentials

New to Dotify? See the full Installation Guide for FFmpeg, Aria2c, and Widevine key setup.

---

🚀 Quick Start

# 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.

---

✨ Features

🎧 Content Support

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

🛠️ Smart Environment Management

• dotify env setup — One-command environment scaffolding
• dotify env doctor — Comprehensive health checks with actionable fixes
• dotify env paths — Inspect all Dotify-related file locations
• dotify env check [component] — Check a specific dependency (ffmpeg, cookies, wvd, ...)

🎨 Advanced Capabilities

• Flexible templates — Customize folder and file names with {artist}, {album}, {year}, {isrc}, and more
• Quality fallback chains — flac-flac-24,flac-flac,aac-high tries each in order automatically
• Multiple download modes — ytdlp (default) or aria2c for 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 .txt file with -r

---

⚙️ Configuration

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

Audio Quality Options

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	❌

Template Variables

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.

---

🔑 Authentication Setup

To access Premium quality content:

1. Get Spotify cookies — Export from open.spotify.com using "Get cookies.txt LOCALLY" (Chrome/Edge) or "Export Cookies" (Firefox). Save to ~/.dotify/cookies.txt.

2. Get a Widevine key — Use KeyDive on an Android device to extract device.wvd. Place it at ~/.dotify/keys/device.wvd.

3. 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 ready

Full walkthrough: Authentication

---

📖 Usage Reference

Basic

dotify "https://open.spotify.com/track/..."
dotify "https://open.spotify.com/album/..."
dotify "https://open.spotify.com/playlist/..."
dotify "https://open.spotify.com/artist/..."

Quality & Output

dotify "URL" --audio-quality flac-flac-24,flac-flac,aac-high
dotify "URL" --output "/path/to/music"
dotify "URL" --synced-lyrics-only

Video Downloads

dotify "URL" --download-music-videos
dotify "URL" --download-podcast-videos
dotify "URL" --video-format webm

Batch & Automation

dotify --read-urls-as-txt urls.txt
dotify "URL1" "URL2" "URL3"
dotify "URL" --wait-interval 10 --log-level DEBUG

Download Modes

dotify "URL" --download-mode ytdlp    # default
dotify "URL" --download-mode aria2c   # faster (requires aria2c)

---

🔧 Troubleshooting

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 paths

Full FAQ: Troubleshooting

---

📚 Documentation

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

---

🌟 Changelog Highlights

v2.0.0 — Environment Management Layer

• dotify env setup — one-command environment scaffolding
• dotify env doctor — comprehensive health checks with actionable errors
• dotify env paths / dotify env check — granular diagnostics
• Centralized config at ~/.dotify/, preflight validation before every run

v1.9.8

• FLAC and 24-bit FLAC audio quality support
• Improved fallback quality chain handling

---

---

🤝 Contributing

Contributions are welcome!

1. Fork the repository
2. Create your feature branch: git checkout -b feature/AmazingFeature
3. Commit your changes: git commit -m 'Add AmazingFeature'
4. Push to the branch: git push origin feature/AmazingFeature
5. Open a Pull Request

---

🙏 Acknowledgments

• Spotify — for the platform
• KeyDive — Widevine key extraction
• yt-dlp — download engine
• FFmpeg — media processing
• All contributors and users of Dotify

---

📝 License

MIT License — see LICENSE for details.

---

📧 [e-mail] · 💬 Discord · 🐛 Issues

⭐ If Dotify saves you time, a star goes a long way! ⭐

Made with ❤️ by @AsHfIEXE