SpotiFLAC Python Module

Integrate SpotiFLAC directly into your Python projects. Perfect for building custom Telegram bots, automation tools, bulk downloaders, downloading music for Jellyfin or web interfaces.

Looking for a standalone app?

SpotiFLAC (Desktop)

Download music in true lossless FLAC from different providers for Windows, macOS & Linux

SpotiFLAC (Mobile)

SpotiFLAC for Android & iOS — maintained by @zarzet

---

Installation

pip install SpotiFLAC

---

Quick Start

SpotiFLAC can be used in multiple ways. Choose the mode that fits your needs:

GUI Mode (Recommended for most users)

Launch the graphical user interface with the --gui flag:

spotiflac --gui

(Or python launcher.py --gui if running from source)

Interactive Mode (Step-by-step wizard)

SpotiFLAC features a smart Interactive Wizard that guides you step-by-step. To launch the wizard, use the --interactive flag:

spotiflac --interactive

(Or python launcher.py --interactive if running from source)

On launch it automatically runs a service health check before asking any questions, so you always know which providers are reachable.

What the wizard does at startup:

1. Service Health Check — probes provider endpoints and shows provider availability inline (✅ / ❌) before asking anything
2. URL History — shows your last 8 downloads so you can re-run one with a single keypress
3. Folder Memory — remembers your last output directory and offers it as the default
4. Profile Load — optionally restores a full saved configuration

Smart URL Detection: If you input an Artist URL, it will ask if you want to download "Featuring" tracks. It skips this question for albums or playlists.

Smart File Paths: If you input a Single Track URL, it will ask if you want to set a specific .flac output path. If you do, it intelligently skips all questions about filename formatting and subfolder organization.

Unified Quality Profiles: Automatically translates your desired quality tier across different services (like Tidal and Qobuz).

CLI Generator: At the end of the configuration, it generates and prints the exact CLI command for your specific setup, so you can copy and reuse it in your automated scripts.

Profile Save: After confirming the download, you can save the entire configuration as a named profile to reuse later.

---

Docker Usage

A CLI-focused Docker image is available for running SpotiFLAC without the desktop GUI.

Build the image:

docker build -t spotiflac .

Run a download with a mounted local output directory:

docker run --rm -v "$(pwd)/downloads:/app/downloads" spotiflac \
  https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT \
  ./downloads -s tidal -q LOSSLESS

The Docker image is intended for CLI mode only; it does not launch the webview GUI.

For interactive terminal mode, run with -it:

docker run --rm -it -v "$(pwd)/downloads:/app/downloads" spotiflac \
  --interactive

Published image (GHCR)

Official images are published to GitHub Container Registry (GHCR) via GitHub Actions. You can pull them with:

docker pull ghcr.io/ShuShuzinhuu/SpotiFLAC-Module-Version:latest

Run a pulled image:

docker run --rm -v "$(pwd)/downloads:/app/downloads" ghcr.io/ShuShuzinhuu/SpotiFLAC-Module-Version:latest \
    https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT ./downloads -s tidal -q LOSSLESS

---

from SpotiFLAC import SpotiFLAC

# Simple Download
SpotiFLAC(
    url="https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT",
    output_dir="./downloads"
)

CLI usage:

spotiflac url ./out --service tidal

---

Supported URL Types

SpotiFLAC supports the following URL formats for Spotify, Tidal, Apple Music, SoundCloud, YouTube and Pandora:

Type	Spotify	Tidal	Apple Music	SoundCloud	YouTube / YT Music	Pandora
Track	open.spotify.com/track/...	listen.tidal.com/track/...	music.apple.com/.../song/...	soundcloud.com/artist/track-slug	youtube.com/watch?v=... · youtu.be/...	pandora.com/artist/.../song/TR:... · pandora.app.link/...
Album / Set	open.spotify.com/album/...	listen.tidal.com/album/...	music.apple.com/.../album/...	soundcloud.com/artist/sets/set-slug	music.youtube.com/playlist?list=OLAK5uy_...	—
Playlist	open.spotify.com/playlist/...	listen.tidal.com/playlist/...	music.apple.com/.../playlist/...	—	youtube.com/playlist?list=PL...	—
Discography (via artist URL)	open.spotify.com/artist/...	listen.tidal.com/artist/.../discography/albums	music.apple.com/.../artist/...	—	—	—

Note: SoundCloud and YouTube tracks are downloaded as MP3 (neither platform distributes lossless audio). Apple Music downloads as M4A/ALAC (lossless) or AAC depending on the selected quality. Pandora downloads as MP3 (mp3_192 by default) or M4A (aac_64 / aac_32). All other services deliver FLAC.

Joox, NetEase, Migu and Kuwo are download-only services — they cannot be used as input URL sources. Use a Spotify or Tidal link and set one of these as the service. These providers are primarily available in select Asian markets and may require a VPN outside those regions.

SoundCloud short links (on.soundcloud.com/...) and mobile links (m.soundcloud.com/...) are automatically resolved. Tracking parameters (e.g. ?utm_source=...) are stripped before processing.

Apple Music track links with an ?i= song parameter (e.g. music.apple.com/us/album/album-name/id?i=trackid) are also supported.

Pandora app links (pandora.app.link/...) are automatically resolved to their canonical web URL. Pandora pretty URLs (e.g. pandora.com/artist/artist-name/album-name/song-name/TR:...) are fully supported.

---

Advanced Configuration

You can customize the download behavior, prioritize specific streaming services, and organize your files automatically into folders.

from SpotiFLAC import SpotiFLAC

SpotiFLAC(
    url="https://open.spotify.com/album/41MnTivkwTO3UUJ8DrqEJJ",
    output_dir="./MusicLibrary",
    services=["qobuz", "amazon", "tidal"],
    filename_format="{year} - {album}/{track}. {title}",
    use_artist_subfolders=True,
    use_album_subfolders=True,
    loop=60,                     # retry duration in minutes
    track_max_retries=2,         # extra per-track retries on failure
    post_download_action="notify"
)

---

Service Health Check

SpotiFLAC can probe all provider endpoints before downloading to verify which ones are currently reachable.

In Interactive Mode this runs automatically at startup. In code or scripts you can call it directly:

from SpotiFLAC.core.health_check import (
    run_health_check,
    print_health_report,
    get_working_providers,
)

results = run_health_check(["tidal", "qobuz", "deezer", "soundcloud", "pandora"])
print_health_report(results)

working = get_working_providers(results)
print("Available providers:", working)

# CLI: check all services then download
spotiflac https://open.spotify.com/track/... ./out --service tidal qobuz

The health check runs in parallel with a configurable timeout (default: 5 s per endpoint) and never blocks your download if a check fails. In the GUI, the check reports provider-level availability and endpoint counts, without exposing individual raw endpoint URLs.

---

Configuration Profiles

Save and reuse complete download configurations without re-typing them every time.

Save a profile

# Save current flags as "hires-tidal"
spotiflac https://... ./out \
  --service tidal \
  --quality HI_RES_LOSSLESS \
  --use-album-subfolders \
  --filename-format "{year} - {album}/{track}. {title}" \
  --save-profile hires-tidal

Load a profile

# Load "hires-tidal" — flags override profile values when both are present
spotiflac https://... ./out --profile hires-tidal

In Python

import asyncio
from SpotiFLAC.core.profiles import (
    save_profile_async,
    get_profile_async,
    list_profiles_async,
)

async def main():
    await save_profile_async("hires-tidal", {
        "services":             ["tidal"],
        "quality":              "HI_RES_LOSSLESS",
        "use_album_subfolders": True,
        "filename_format":      "{year} - {album}/{track}. {title}",
    })

    cfg = await get_profile_async("hires-tidal")
    print(await list_profiles_async())  # ['hires-tidal']

asyncio.run(main())

Profiles are stored at ~/.cache/spotiflac/profiles.json. In the Interactive Wizard, you are prompted to load a profile at startup and optionally save one at the end.

---

Batch Downloads

Pass a list of URLs to download them all in sequence. Failed tracks per URL are collected and can be retried with loop.

from SpotiFLAC import SpotiFLAC

SpotiFLAC(
    url=[
        "https://open.spotify.com/album/41MnTivkwTO3UUJ8DrqEJJ",
        "https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M",
        "https://listen.tidal.com/album/364272512",
    ],
    output_dir="./MusicLibrary",
    services=["tidal", "qobuz"],
    use_album_subfolders=True,
)

---

Auto-Retry on Failure

Set track_max_retries (Python) or --retries (CLI) to automatically retry failed tracks. Each retry cycles through all configured providers from the beginning, waiting exponentially longer between attempts (2 s → 4 s → 8 s …, capped at 30 s).

from SpotiFLAC import SpotiFLAC

SpotiFLAC(
    url="https://open.spotify.com/album/...",
    output_dir="./downloads",
    services=["tidal", "qobuz", "deezer"],
    track_max_retries=3,   # up to 3 extra attempts per track
)

spotiflac https://open.spotify.com/album/... ./out \
  --service tidal qobuz deezer \
  --retries 3

Tip: Combine --retries with --loop for maximum resilience — --retries handles transient errors on individual tracks, while --loop re-queues permanently failed tracks after N minutes.

---

Per-Track Timeout

Set timeout_s (Python) or --timeout (CLI) to cap the time SpotiFLAC will spend downloading a single track. If the download does not complete within the specified number of seconds, the process is terminated and the track is marked as failed — allowing the next provider or retry to take over.

# CLI — skip any track that takes more than 3 minutes
spotiflac https://open.spotify.com/album/... ./out --service tidal --timeout 180

# Python API
from SpotiFLAC import SpotiFLAC
SpotiFLAC(
    url="https://open.spotify.com/album/...",
    output_dir="./downloads",
    services=["tidal", "qobuz"],
    timeout_s=120,
)

Tip: Pair --timeout with --retries so that a stalled track is automatically re-attempted against the next provider instead of blocking the entire queue indefinitely.

---

Post-Download Actions

Action	Description
none	Do nothing (default)
open_folder	Open the output folder in the system file manager
notify	Send an OS desktop notification with a summary
command	Run a custom shell command — placeholders: {folder}, {succeeded}, {failed}

SpotiFLAC(url="...", output_dir="./downloads", post_download_action="open_folder")

SpotiFLAC(url="...", output_dir="./downloads",
          post_download_action="command",
          post_download_command="rsync -av {folder}/ user@nas:/music/")

spotiflac https://... ./out --post-action notify
spotiflac https://... ./out --post-action command --post-command "rsync -av {folder}/ user@nas:/music/"

---

Discography Download

Download the complete discography of an artist. Duplicate tracks (same ISRC across different releases) are automatically skipped.

```python from SpotiFLAC import SpotiFLAC

Spotify — albums + singles

SpotiFLAC(url="https://open.spot