SpotiFLAC Python Module
Fetch Spotify track metadata and retrieve matching lossless audio through Tidal, Qobuz, Amazon Music and other provider backends — supplied entirely via extensions you choose and configure yourself. Integrate directly into your Python projects, build custom Telegram bots, automation tools, or bulk downloaders.
Disclaimer
This project is intended for educational and personal use only. The developer does not condone or encourage copyright infringement. The software is licensed under the MIT License.
SpotiFLAC-Module-Version is an independent, third-party tool and is not affiliated with, endorsed by, or connected to Spotify, Tidal, Qobuz, Amazon Music, Deezer, or any other streaming service. It is also not affiliated with, and has no control over or responsibility for, any other project sharing a similar name on other platforms.
No copyrighted content is hosted, stored, mirrored, or distributed by this repository. The core application does not bundle, ship, or default to any third-party extension, registry, or provider. Extensions are installed only if a user explicitly configures and requests them from a source of their own choosing; the maintainer has no control over, does not review, and assumes no responsibility for the content or behavior of third-party extensions or registries a user may choose to install.
You are solely responsible for:
- Ensuring your use of this software, and any extension or registry you choose to install, complies with your local laws.
- Reading and adhering to the Terms of Service of any platform or provider you access, directly or through an extension.
- Any legal consequences resulting from the use or misuse of this tool.
This software is provided free of charge by the maintainer. If you paid a third party for access to it, you may have been misled or scammed.
The software is provided "as is", without warranty of any kind, express or implied. The author assumes no liability for any bans, damages, or legal issues arising from its use or misuse. Users assume all risk associated with its use.
If you are a copyright holder or an authorized representative and believe this repository infringes upon your rights, please contact the maintainer with sufficient detail (including relevant URLs and proof of ownership); the matter will be promptly investigated.
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
Why the module (instead of the standalone apps)
The Desktop and Mobile apps are built for direct, immediate use: open it, paste a link, download. The Python module exists for a different case — integrating this logic into something else.
It makes sense to start here if:
- You're building a bot (Telegram, Discord) or a service that needs to handle requests from many users automatically, not a single manual download.
- You need the async API (
AsyncSpotiFLAC) inside an existing FastAPI/Quart/Sanic app, with shared connection pooling. - You want to orchestrate bulk downloads via scripts — multiple playlists, full discographies, local library retagging — with custom logic (filenames via a Python function, post-download actions, saved profiles).
- You need to run headless, on a server, a NAS, or inside Docker, possibly as part of a larger pipeline.
- You want full control over which extensions get loaded and from which registry, instead of relying on a fixed set baked into an app.
If you just want a GUI for personal use, with no code involved, the Desktop or Mobile apps remain the simpler choice — this module is the building block those (and similar projects) can be built on top of.
Features
- Native synchronous and asynchronous Python APIs
- Modular JavaScript and Python Extension system (bring-your-own registry — nothing bundled)
- Automatic fallback among the extensions you have installed
- Built-in GUI, as a native window or served locally in a browser (
--gui/--web) - Guided terminal UI (
--tui), with the download queue live on screen - Docker support
- Configuration Profiles
- MusicBrainz metadata enrichment
- Synchronized lyrics — embedded in the tag and, optionally, written out as
.lrcfiles; word-by-word where the source has it, or line-synced if you prefer - Optional Spotify Canvas sidecars — the short looping visual a track carries, saved next to it as a video file (off by default; no media server reads these on its own)
- Optional MP3 320 kbps transcoding
- Watch mode: re-sync a playlist/album/artist/URL on an interval, indefinitely
- Optional shared-secret or per-account authentication for
--web, plus a queued, per-user download history in multi-user mode - Extension discovery directories, and optional Ed25519 signature verification on top of registry checksums
- Local-library duplicate detection by acoustic fingerprint, independent of tags/ISRC
- Extension scaffolding + dry-run validation for developing your own
- Installable as a PWA in
--webmode (Add to Home Screen / standalone window) - Follow artists — check for new releases and fetch only what came out since
- Library upgrade — find files below a target quality (including fake Hi-Res) and re-fetch them
- Outbound notifications — webhook, Discord, Telegram or ntfy, per track or one summary per run
- Versioned REST API at
/api/v1, with an OpenAPI document at/docs - CSV input — hand it a playlist export (Exportify, Soundiiz, a bare list of links) and it downloads what the file lists, matching rows that carry no link and reporting the ones it cannot
- Dashboard — what you have actually downloaded, as numbers: top artists, genres, decades, providers, listening time, activity by weekday and streaks (
--stats, or the Stats screen) - Durable queue and download log (SQLite): a restart no longer loses queued work
- Per-account quotas and an admin role in
--web-multiuser - Extension health panel — success rate, latency and last error per provider
- Wrong-recording guard — a provider that answers with a karaoke take, a clean edit of an explicit track, or another artist's cover is rejected and the download falls through to the next one, instead of producing a file that carries the right tags and the wrong audio
Installation
pip install SpotiFLAC
Important: out of the box, SpotiFLAC does nothing but resolve Spotify metadata — it ships with no built-in provider and no default extension source. Before you can download anything, you need to point it at an extension registry of your own choosing and install at least one extension. See Extensions below.
Documentation
The full guide lives in docs/guide/ — the README had grown
to 76 KB and 87 headings, which is past the point where GitHub or PyPI
renders it usefully. Every page below is the same text that used to be here.
| Page | What's in it |
|---|---|
| Quick Start | Every way to run it — GUI, web, CLI, terminal UI, Python — and the URL types it accepts |
| Terminal UI | --tui, the guided mode: every setting on one screen, and the download queue live |
| Extensions | Registries, installing providers, signature verification and trust tiers |
| Downloading from a CSV | Feeding it a file of tracks instead of a link: supported exports, how rows without a link are matched, and the unmatched-row report |
| Your library in numbers | The dashboard built from what you have actually downloaded — top artists, genres, decades, activity |
| Configuration | Every option: naming, quality, lyrics, enrichment, transcoding, watch mode, profiles |
| API Reference | SpotiFLAC and AsyncSpotiFLAC, and the objects they return |
| Local Tagging | Retagging an existing library, MusicBrainz enrichment, download validation |
| Automation & Operations | JSON output, post-download hooks, notifications, M3U, library rescan, cache maintenance, running the web server |
| Following Artists | Subscriptions, new-release checks, scheduled playlist monitoring, and the library-upgrade pass |
| REST API | The versioned /api/v1 surface, quotas and the admin endpoints |
| Docker | Headless and NAS setups |
| CLI | The standalone executables |
Security policy and the reporting process: SECURITY.md.
Want to support the project?
If this software is useful and brings you value, consider supporting the project by buying us a coffee. Your support helps keep development going.
API Credits
Song.link · MusicBrainz · LRCLIB · Musixmatch · iTunes Search API
Provider-specific credits (Tidal, Qobuz, Amazon Music, Deezer, SoundCloud, Apple Music, Pandora, and any third-party API used to reach them) now belong to whichever extension you install — see that extension's own documentation for its credits and terms.
[!TIP] Star the repo to show support, and click Watch → Custom → Releases on GitHub if you want to be notified as soon as a new release goes out.
2 maintainers
Release files for SpotiFLAC 4.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| spotiflac-4.2.2.tar.gz | 1.6 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| spotiflac-4.2.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.9 MB
Release files / spotiflac-4.2.2.tar.gz
| Download URL | spotiflac-4.2.2.tar.gz |
|---|---|
| Size | 1.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
191773543595a999d075b581a288628a1506015b46a0cc4e9c0ffec6a031e0cb
|
|
BLAKE2b-256 checksum How to use checksums |
5404b8522f8dfdc8823409e694677e41dd99740b0d8edce6d9d230667e723f9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency logRelease files / spotiflac-4.2.2-py3-none-any.whl
| Download URL | spotiflac-4.2.2-py3-none-any.whl |
|---|---|
| Size | 1.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
15aa808d8e8022bec769069eb301b4b4079460a7c684ca2ee6b76f5221fb5930
|
|
BLAKE2b-256 checksum How to use checksums |
91e44d1da69dab153a97ac963d4e993725509c4eee8d4eebdfc778e7948656b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency log
