spdrm

A lightweight Spotify track downloader and mp3 converter.

Research / disclaimer: For educational and research use only, with content and accounts you are authorized to access. The author is not liable for misuse, account issues, data loss, or any other damages.

What it does

Takes a Spotify track URL and downloads the audio (OGG / MP3) using your Premium sp_dc cookie.

Requirements

• Python 3.10+
• Spotify Premium + sp_dc cookie
• FFmpeg (only for MP3 conversion)

Setup

A — raw / local (repo root)

pip install -r requirements.txt
cp .env.example .env

Run from the repo root so import spdrm works (PYTHONPATH=. if needed).

B — optional installable package

pip install -e . # or use pip install spdrm
cp .env.example .env

Same deps as requirements.txt; also installs the spdrm CLI (spdrm → HTTP service).

Edit .env:

SP_DC=
QUALITY=normal
PORT=7331
AUTH_MODE=none

• Quality: low | normal | high | very-high (default normal)
• Port: PORT (default 7331) for python api.py / spdrm.api.start()
• Auth: default examples assume AUTH_MODE=none. For api-key / bearer, set API_KEY and send X-API-Key or Authorization: Bearer …

Usage

Library

import spdrm

url = "https://open.spotify.com/track/3fvY2U1AzW0diYF0hnBbKt?si=747f057de61745d8"

result = spdrm.download(url)
print(result["path"], result.get("time"))

path = spdrm.download_path(url, format="mp3", quality="normal")
ogg = spdrm.download(url, format="ogg")

spdrm.clean()  # clear internal download cache
spdrm.close()

Or use the class:

with Spdrm() as client:
    client.download(url)
    client.clean()

Also available:

search("query")
get_track("3fvY2U1AzW0diYF0hnBbKt")
capabilities()
clean()

API server

Repo root:

python api.py

Or after install:

import spdrm
spdrm.api.start()

Download (sync wait:true includes base64 file by default):

curl -X POST http://localhost:7331/download \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"https://open.spotify.com/track/016z46SJwcRosW9Xb8JKmF\",\"format\":\"mp3\",\"wait\":true}"

Example response:

{
  "trackId": "016z46SJwcRosW9Xb8JKmF",
  "path": "…",
  "file": "<base64 audio bytes>",
  "format": "mp3",
  "bytes": 2400000,
  "cached": false,
  "transcoded": true,
  "lossless": false,
  "time": 1.23,
  "sourceFormat": 1
}

Docker

With .env configured (see Setup):

docker compose up

API on http://localhost:7331 (host port from PORT, default 7331).

TypeScript (save locally)

import { mkdir, writeFile } from "node:fs/promises";
import { join } from "node:path";

const res = await fetch("http://localhost:7331/download", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    input: "https://open.spotify.com/track/016z46SJwcRosW9Xb8JKmF",
    format: "mp3",
    wait: true,
  }),
});

const data = await res.json();
console.log({
  trackId: data.trackId,
  format: data.format,
  bytes: data.bytes,
  time: data.time,
});

await mkdir("./downloads", { recursive: true });
const out = join("./downloads", `${data.trackId}.${data.format}`);
await writeFile(out, Buffer.from(data.file, "base64"));
console.log("saved", out);

Stream / save the binary (no base64):

curl -OJ http://localhost:7331/file/016z46SJwcRosW9Xb8JKmF

Send to a Discord webhook (simplest — save then upload):

# 1) download track (mp3 lands in cwd via -OJ)
curl -OJ http://localhost:7331/file/016z46SJwcRosW9Xb8JKmF

# 2) attach to webhook
curl -F "[email protected]" "$DISCORD_WEBHOOK_URL"

Or decode the JSON file field first:

curl -X POST http://localhost:7331/download \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"https://open.spotify.com/track/016z46SJwcRosW9Xb8JKmF\",\"format\":\"mp3\",\"wait\":true}" \
  -o result.json

python -c "import json,base64; r=json.load(open('result.json')); open(f\"{r['trackId']}.{r['format']}\",'wb').write(base64.b64decode(r['file']))"

curl -F "[email protected]" "$DISCORD_WEBHOOK_URL"

MP3 + metadata:

curl -X POST http://localhost:7331/download \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"https://open.spotify.com/track/016z46SJwcRosW9Xb8JKmF\",\"format\":\"mp3\",\"quality\":\"normal\",\"metadata\":\"basic\",\"artwork\":\"thumbnail\",\"wait\":true}"

Raw OGG (includeFile:false if you only need the path / /file/...):

curl -X POST http://localhost:7331/download \
  -H "Content-Type: application/json" \
  -d "{\"input\":\"https://open.spotify.com/track/3fvY2U1AzW0diYF0hnBbKt\",\"format\":\"ogg\",\"includeFile\":false,\"wait\":true}"

Body options

Field	Values	Default
input	track URL / URI / id	required
format	mp3 | ogg	mp3
quality	low | normal | high | very-high	normal
metadata	none | basic | full	none
artwork	disabled | thumbnail | full	disabled
includeFile	true | false	true when wait:true
wait	true | false	true

file is base64 audio (capped at 25 MiB by default; use GET /file/{trackId} for larger files or streaming). Prefer saving file to your own folder (see TypeScript example).

Support

Development is currently paused. I’m not planning to provide ongoing support, maintenance, bug fixes, or new updates unless the project receives enough interest and support.

If the repository reaches a sufficient number of stars, I may return to the project and add stuff or release further improvements. Until then, the project should be considered unmaintained.

You can support the project on Ko-fi: