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.

GitHub stars Latest release PyPI version Python versions GitHub downloads PyPI downloads Telegram community

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:

  1. Ensuring your use of this software, and any extension or registry you choose to install, complies with your local laws.
  2. Reading and adhering to the Terms of Service of any platform or provider you access, directly or through an extension.
  3. 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?

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)
  • Interactive CLI Wizard
  • Docker support
  • Configuration Profiles
  • MusicBrainz metadata enrichment
  • Synchronized lyrics — embedded in the tag and, optionally, written out as .lrc files; word-by-word where the source has it, or line-synced if you prefer
  • 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 --web mode (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, interactive wizard, Python — and the URL types it accepts
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, 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.

Ko-fi

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.

Project links

Data verified by PyPI on Sep 3, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (4.1.0)

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for bartolomeorusso9 from gravatar.com bartolomeorusso9 Avatar for ShuKurenais from gravatar.com ShuKurenais

Credits

Author: BartolomeoRusso9, ShuKurenais

GitHub Statistics

Data verified by PyPI on Sep 3, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT

Requires

Python >=3.10

Provides Extra

dev web hires dedup

Tags

spotify flac downloader music lossless lossless-music tidal qobuz amazon-music audio SpotiFLAC spotify-downloader no-account hi-res

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

spotiflac-3.9.0.tar.gz (1.3 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

spotiflac-3.9.0-py3-none-any.whl (1.2 MB view details)

Uploaded Python 3

File details

Details for the file spotiflac-3.9.0.tar.gz.

File metadata

  • Download URL: spotiflac-3.9.0.tar.gz
  • Upload date:
  • Size: 1.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for spotiflac-3.9.0.tar.gz
Algorithm Hash digest
SHA256 d339035d7dc35a4e1edcb9b2b4fb330c99448087402e554324422d52cee97e87
MD5 be56fb022a5a17bf922085eeccdfc24b
BLAKE2b-256 c14302da32bd90dab8aadc91c1fac00b1af65f68112ffa8c9dbaece59eecdd66

See more details on using hashes here.

Provenance

The following attestation bundles were made for spotiflac-3.9.0.tar.gz:

Publisher: publish.yml on BartolomeoRusso9/SpotiFLAC-Module-Version

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file spotiflac-3.9.0-py3-none-any.whl.

File metadata

  • Download URL: spotiflac-3.9.0-py3-none-any.whl
  • Upload date:
  • Size: 1.2 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for spotiflac-3.9.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ef5d779fc3bfbe0877e3174c4f7b9c6bf12c38667f7e3a5c75ce74719cffa17c
MD5 07fbe48f3d79ca6031707bced76e71c7
BLAKE2b-256 f96cb4cb76629fe480bc83a20f9d8524b298410f23ed4d774ec56acf3095f3f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for spotiflac-3.9.0-py3-none-any.whl:

Publisher: publish.yml on BartolomeoRusso9/SpotiFLAC-Module-Version

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

4.1.0

2 files

4.0.3

2 files

4.0.2

2 files

4.0.1

2 files

4.0.0

2 files

This release

3.9.0 This release

2 files

3.8.0

2 files

3.7.0

2 files

3.6.0

2 files

3.5.0

2 files

3.1.0

2 files

3.0.9

2 files

3.0.8

2 files

3.0.7

2 files

3.0.6

2 files

3.0.5

2 files

3.0.4

2 files

3.0.3

2 files

3.0.2

2 files

3.0.1

2 files

3.0.0

2 files

1.8.1

2 files

1.8.0

2 files

1.7.9

2 files

1.7.8

2 files

1.7.7

2 files

1.7.6

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.9

2 files

1.6.8

2 files

1.6.7

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.9

2 files

1.5.8

2 files

1.5.7

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.9

2 files

1.3.8

2 files

1.3.7

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.9

2 files

1.1.8

2 files

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.9

2 files

0.8.7

2 files

0.8.6

2 files

0.8.5

2 files

0.8.4

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.9

2 files

0.6.8

2 files

0.6.7

2 files

0.6.6

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.9

2 files

0.5.8

2 files

Pre-release

0.5.7b0

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.9

2 files

0.4.8

2 files

0.4.7

2 files

0.4.6

2 files

0.4.5

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.9

2 files

0.3.8

2 files

0.3.7

2 files

0.3.6

2 files

0.3.5

2 files

0.3.3

2 files

0.3.2

2 files

0.2.13

2 files

0.2.8

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

0.1.9

2 files

0.1.8

2 files

0.1.7

2 files

0.1.6

2 files

0.1.5

2 files

0.1.4

2 files

0.1.3

2 files

0.1.2

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page