sdm-pycli 2.0.1

A fast, zero-config CLI tool to download and sync playlists from Spotify, Apple Music, Tidal, YouTube, and SoundCloud.

SDM - SDM Downloads Music

sdm is a fast, lightweight, and zero-config CLI tool to download and sync Playlists, Albums, and Tracks from Spotify, Apple Music, Tidal, YouTube, and SoundCloud.

Why sdm?

Recently, Spotify restricted their Web API, requiring developers to have a Premium subscription, which broke popular open-source tools with 403 Forbidden errors.

sdm was built to completely bypass these restrictions. It uses native web scraping to extract flawless metadata directly from streaming services, pairs it with yt-dlp to fetch the highest-quality audio, and embeds the tags natively. No API keys required.

Features

• Universal Support: Spotify, Apple Music, Tidal, YouTube, and SoundCloud.
• Smart Syncing: Two-way mirroring. Run sdm sync to fetch new tracks and clean up removed ones.
• Multi-Format: Download in M4A (default), MP3, FLAC, or OPUS with native tags.
• Perfect Metadata: Embeds Track, Artist, Album, Cover Art, Track/Disc Numbers, Genre, Release Year, and automatically generates .m3u8 playlists.
• Advanced Processing: Synced lyrics via LRCLIB, custom 2-pass EBU R128 (-14 LUFS) audio normalization algorithm for perfectly balanced studio-grade levels without dynamic range compression artifacts, and SponsorBlock trimming.

Installation

You must have Python 3.8+ installed on your system. (Windows users: Make sure to check the "Add Python to PATH" box during installation!)

Install directly from PyPI:

pip install sdm-pycli

Usage

Open a terminal in the folder where you want your music saved, then run the commands below.

Playlist

To download a playlist, run

sdm download [playlistUrl]

Example:

sdm download https://open.spotify.com/playlist/37i9dQZF1E8NjgPSXnmGkI?si=O0kgUaFcQnatcvlZzS9yJw

Album

To download an album, run

sdm download [albumUrl]

Example:

sdm download https://open.spotify.com/album/6eUW0wxWtzkFdaEFsTJto6?si=nYD6g_tZQvuFsMzyKG2sRA

Track

To download a single track, run

sdm download [trackUrl]

Example:

sdm download https://open.spotify.com/track/4PTG3Z6ehGkBFwjybzWkR8?si=1d83934b63464e9e

Apple Music

Apple Music albums, playlists, and songs are also supported.

sdm download https://music.apple.com/us/album/starboy/1440871397

Sync

sdm remembers the source URL for each folder. To update a previously downloaded folder with any changes from the remote playlist, run

sdm sync [directory]

Example:

sdm sync "C:\Users\You\Music\My Playlist"

Inject

To import a local audio file into your playlist with official metadata and protect it from future sync deletions, run

sdm inject [filePath] [trackUrl (Optional)]

If the trackUrl is omitted, sdm will launch an interactive search menu to help you find and apply metadata (including Last.fm enrichment and high-resolution cover art).

Example:

sdm inject "C:\Users\You\Downloads\song.mp3"

Config

You can set persistent default options (like format, workers, or API keys) so you never have to type them again:

sdm config --format flac --workers 5 --lastfm-key "YOUR_API_KEY"

Tag

To recursively scan an existing local directory and enrich the audio files with extensive Last.fm metadata (Genres, Track Bios, and MusicBrainz IDs) without redownloading them, run:

sdm tag [directory]

Example:

sdm tag "C:\Users\You\Music\My Playlist"

Search

To search and download a single track directly from YouTube Music, run

sdm search [query]

Example:

sdm search "Never Gonna Give You Up - Rick Astley"

Stats

To show comprehensive statistics for your local library (such as track count, total size, format distribution, Top Genres, Top Artists, and Decades), run

sdm stats [directory]

This command also runs a Health Check, warning you if any files are missing cover art or have a bitrate below 128kbps. Add the -v or --verbose flag to print a detailed list of problematic files.

Example:

sdm stats "C:\Users\You\Music" -v

Migrate

To bulk convert a downloaded library to a different audio format (multithreaded for significantly faster processing), run

sdm migrate --dir [directory] [target_format] -w [workers]

Example:

sdm migrate --dir "C:\Users\You\Music\FLAC Library" opus -w 5

Options & Flags

Flag	Description
-o, --output	Save to a specific directory
-f, --format	Audio format: m4a, mp3, flac, opus (default: m4a)
-w, --workers	Number of concurrent downloads or migrations (default: 3)
-v, --verbose	Show detailed list of tracks with warnings during stats
--cleanup	Run sync cleanup logic on a standard download to remove orphaned files
--index	Manually override the track index number when injecting a file
--dir	Target directory for the migrate and stats commands
--lyrics	Fetch and embed synced lyrics from LRCLIB
--resize-covers	Resize high-res cover art to 600x600px to save storage space
--normalize	Apply custom 2-pass EBU R128 (-14 LUFS) volume normalization
--sponsor-block	Trim non-music sections from YouTube sources
--dry-run	Simulate a sync/download without making changes
--no-delete	Download new tracks but never delete local files
--refresh-metadata	Re-tag existing files with the latest metadata (alias: --refresh)
--cookies	Pass browser cookies for age-restricted content
--lastfm-key	Enable extensive track-level genres and wiki summaries via Last.fm API
--version	Show the version and exit

Example with flags:

sdm download https://open.spotify.com/playlist/37i9dQZF1E8UXBoz02kGID -f flac --lyrics --normalize

Music Sourcing & Audio Quality

sdm fetches flawless metadata (tags, cover art, tracklists) directly from Spotify, Apple Music, and Tidal, but sources the actual audio streams from YouTube.

Unlike other tools that require your Premium credentials and risk permanent account bans by ripping directly from encrypted servers, sdm acts as a safe, unauthenticated metadata matcher. It reliably delivers DRM-free audio (up to 256kbps AAC or Opus) perfectly packaged to match the original release.

Legal Disclaimer

Users are responsible for their actions. We do not support unauthorized downloading of copyrighted material. sdm is open-source (MIT License) for educational and personal use only.

---

Important Notes:

• Spotify Playlists must be set to Public. Private playlists and personalized mixes will not work.
• Explicit Content: If YouTube blocks downloads, pass browser cookies with --cookies firefox. Firefox is recommended.