← Back to the README

API Reference

API Reference

SpotiFLAC() Parameters

Parameter	Type	Default	Description
url	str / list[str]	Required	A single URL or a list of URLs (batch mode).
output_dir	str	Required	The destination directory path where the audio files will be saved.
output_path	str	None	Exact destination file path for single track downloads. Overrides output_dir + filename_format. Automatically ignored for albums, playlists and artist discographies.
services	list	["ext:tidal-web"]	Extensions to use and their priority order, as ext:<id> (or a legacy alias — see Extensions). Each id must correspond to an extension you have already installed; nothing is bundled or installed automatically.
registries	list	None	One or more extension-registry JSON URLs to add before the run, as an alternative to SPOTIFLAC_REGISTRIES or a .env file. Must be https://. Persisted to ~/.spotiflac/registry_settings.json on first use, so subsequent runs (CLI, GUI, or Python) pick it up automatically without passing it again — see Extensions.
filename_format	str	"{title} - {artist}"	Format for naming downloaded files. See placeholders below.
use_track_numbers	bool	False	Prefixes the filename with the track number.
use_album_track_numbers	bool	False	Uses the track's original album number instead of the download queue position.
use_artist_subfolders	bool	False	Automatically organizes downloaded files into subfolders by artist.
use_album_subfolders	bool	False	Automatically organizes downloaded files into subfolders by album.
create_playlist_subfolders	bool	False	Creates a subfolder per playlist/album when downloading a collection, in addition to any artist/album subfolders.
first_artist_only	bool	False	Uses only the first artist in tags and filename.
artist_separator	str	None	Custom separator (e.g. ", " or " / ") to join multiple artists into a single string in tags, instead of using standard multi-value fields. Useful for players like Rekordbox.
include_featuring	bool	False	When downloading an artist discography, also includes tracks where the artist appears as a featured artist.
max_concurrent_downloads	int	2	How many tracks to download in parallel.
tidal_custom_api	str	None	Optional setting forwarded to the installed tidal-web-family extension, if it supports it. Has no effect on its own — see Passing Settings to an Extension.
timeout_s	int	None	Per-track download timeout in seconds. If a single track download does not complete within this time, the process is terminated and the track is marked as failed. SpotiFLAC then moves on to the next extension or retry. Set to None (default) to disable the timeout.
loop	int	None	Duration in minutes to keep retrying permanently failed tracks after a full session completes.
track_max_retries	int	0	Extra download attempts per track when all extensions fail on the first try. Each retry cycles through all configured extensions again with exponential backoff (2 s → 4 s → 8 s …, capped at 30 s).
quality	str	"LOSSLESS"	Requested profile: LOSSLESS or HI_RES_LOSSLESS. DOLBY_ATMOS is also accepted but is Tidal-exclusive — any other provider falls back to HI_RES_LOSSLESS instead. Legacy provider-specific values are accepted and normalized.
allow_fallback	bool	True	For HI_RES_LOSSLESS, allows fallback to LOSSLESS when the higher-resolution tier is unavailable. It never downgrades lossless requests to compressed audio.
log_level	int	logging.WARNING	Python logging level.
embed_lyrics	bool	True	Whether to fetch and embed synchronized lyrics (LRC) into the audio file.
lyrics_providers	list	["spotify", "apple", "musixmatch", "lrclib", "amazon"]	Priority order of lyrics providers. All are queried at once; the answers are read back in this order, so the first entry that has lyrics wins. Put apple first for word-by-word timing.
apple_lyrics_word_by_word	bool	True	Keep Apple's lyrics in their native word-by-word (per-syllable) form. Set False to get plain line-synced LRC from Apple instead. Only affects the apple provider.
save_lrc	bool	False	Also write the lyrics as <audio file's name>.lrc, next to the track.
lrc_library_dir	str	None	Also collect every lyric into this folder as Artist - Title.lrc, the layout overlay players (LyricsX and similar) look lyrics up by.
save_canvas	bool	False	Also save the track's Spotify Canvas (the short looping visual) next to the track, under the audio file's own name. The extension follows the media Spotify actually serves — usually .mp4, .jpg for the canvases that are a still image. Never embedded — see Spotify Canvas.
canvas_library_dir	str	None	Also collect every canvas into this folder as Artist - Title, with the same extension save_canvas would give it.
canvas_providers	list	["spotify", "paxsenix"]	Where a canvas is looked up, in order: spotify asks Spotify's own canvaz-cache endpoint, paxsenix goes through the public JSON wrapper.
enrich_metadata	bool	True	Enables multi-provider metadata enrichment (HD covers, BPM, labels, etc.).
enrich_providers	list	["deezer", "apple", "qobuz", "tidal"]	Priority order of metadata providers to attempt. soundcloud is also accepted but isn't on by default.
qobuz_token	str	None	Optional setting forwarded to the installed Qobuz extension, if it supports it. Has no built-in behavior of its own.
qobuz_local_api_url	str	None	Optional setting forwarded to the installed qobuz-web-family extension, if it supports it. Has no effect on its own — see Passing Settings to an Extension.
use_extensions_fallback	bool	True	Whether to automatically fall back to another installed extension for the same alias if one fails. Set to False to use only the extensions explicitly listed in services.
transcode_to	str	None	Converts every finished track to this format: "flac", "alac" (.m4a), "wav", "aiff", "wavpack" (.wv), "tta" or "mp3" (see Transcoding). The lossless targets keep the sample rate and bit depth of the source. None keeps the extension's original format. Requires ffmpeg.
transcode_bitrate	str	"320k"	Bitrate used by the lossy transcode_to targets, e.g. "320k", "256k", "192k". Ignored by the lossless ones.
transcode_keep_original	bool	False	Keeps the original downloaded file next to the converted one. By default the source is deleted once the conversion succeeds.
verify_hires	bool	False	Runs a spectral-analysis QA check after each successful lossless download, flagging files that declare a high sample rate but lack real content above standard-definition frequencies (possible upsampling), and files whose declared bit depth is padding (24-bit carrying a 16-bit master). Nothing extra to install. Never fails or delays a download — see Hi-Res Verification.
redownload_fake_hires	bool	False	Acts on a verify_hires finding instead of only logging it: the flagged file is set aside, the track is downloaded again at LOSSLESS, and the flagged file is deleted only once the replacement is on disk (if every extension fails, the original is restored). Implies verify_hires=True, and only applies when a Hi-Res quality was requested — see Hi-Res Verification.
post_download_action	str	"none"	Action after all downloads finish: "none", "open_folder", "notify", "command".
post_download_command	str	""	Shell command to run when post_download_action="command". Supports {folder}, {succeeded}, {skipped}, {failed} placeholders; quote {folder} in your template (e.g. '{folder}') since the substituted path may contain spaces.

Filename Format Placeholders & Custom Formatting

String Template with Placeholders

When customizing the filename_format string, you can use the following dynamic tags:

• {title} — Track title
• {artist} — Track artist(s)
• {album} — Album name
• {album_artist} — The artist(s) of the entire album
• {disc} — The disc number
• {track} — The track's original number in the album
• {position} — Download queue / playlist position (zero-padded, e.g. 01)
• {date} — Full release date (e.g., YYYY-MM-DD)
• {year} — Release year (e.g., YYYY)
• {isrc} — Track ISRC code
• {platform} — Source platform (e.g., "tidal", "soundcloud", "youtube") — the extension/service that provided the download
• {id} — Platform-specific track ID (e.g., Tidal track ID, SoundCloud user ID, YouTube video ID) — useful for tracing a file back to its origin

Examples:

SpotiFLAC(
    url="https://open.spotify.com/track/...",
    output_dir="./downloads",
    services=["ext:tidal-web"],
    # Standard string template
    filename_format="{year} - {album}/{track}. {title}",
)

# Using platform and ID in the filename (flat):
SpotiFLAC(
    url="https://open.spotify.com/playlist/...",
    output_dir="./downloads",
    filename_format="{platform}_{album}_{title}",
)

Custom Function (Lambda) for Advanced Logic

For complex naming rules, pass a callable (function or lambda) instead of a string. The function receives:

• metadata — the TrackMetadata object
• platform — the source platform string (e.g., "tidal")
• native_id — the platform-specific ID, or None if not available
• **kwargs — additional context

The function must return a filename (without directory or extension — those are added automatically).

Example — use ISRC if available, fall back to platform_id:

from SpotiFLAC import SpotiFLAC

def my_filename_logic(metadata, platform, native_id, **kwargs):
    """
    Prioritize ISRC, then fall back to platform_id for traceability,
    then just use the title.
    """
    if metadata.isrc:
        return metadata.isrc
    
    if native_id:
        return f"{platform}_{native_id}"
    
    return metadata.title

SpotiFLAC(
    url="https://open.spotify.com/album/...",
    output_dir="./downloads",
    services=["ext:tidal-web", "ext:soundcloud-web"],
    filename_format=my_filename_logic,  # Pass the function directly
)

Example — include platform and year in filename (flat):

SpotiFLAC(
    url="https://open.spotify.com/playlist/...",
    output_dir="./downloads",
    filename_format=lambda metadata, platform, native_id, **kw: (
        f"{platform}_{metadata.year or 'unknown'}_{metadata.title}"
    ),
)

CLI Flag Reference

Flag	Short	Default	Description
--service	-s	ext:tidal-web	One or more extensions in priority order, as ext:<id> (or a legacy alias resolved to an installed extension — see Extensions).
--registries		None	An extension-registry JSON URL to add before running; repeat the flag for each one. Alternative to SPOTIFLAC_REGISTRIES or a .env file. Must be https://. Persisted to ~/.spotiflac/registry_settings.json, so you only need to pass it once — see Extensions.
--filename-format	-f	{title} - {artist}	Filename template with placeholders.
--output-path	-o	None	Exact output file path for single track downloads. Ignored for albums, playlists and discographies.
--quality	-q	LOSSLESS	Requested profile: LOSSLESS or HI_RES_LOSSLESS. DOLBY_ATMOS is also accepted but is Tidal-exclusive — any other provider falls back to HI_RES_LOSSLESS instead. Legacy provider-specific values are accepted and normalized.
--fallback		True	Let a provider serve a lower tier when the requested --quality is unavailable for a track. Enabled by default; the flag exists to override a profile that disabled it.
--no-fallback			Fail a track outright when the requested --quality is not available, instead of accepting a lower tier.
--use-track-numbers		False	Prefix filenames with track numbers.
--use-album-track-numbers		False	Use the track's original album number instead of queue position.
--use-artist-subfolders		False	Organize files into per-artist subfolders.
--use-album-subfolders		False	Organize files into per-album subfolders.
--playlist-subfolders		True	Create a subfolder for playlist downloads (enabled by default).
--no-playlist-subfolders			Keep playlist downloads directly in the output directory instead of a subfolder.
--first-artist-only		False	Use only the first artist in tags and filename.
--artist-separator		None	Custom separator for joining multiple artists in tags (e.g. ", " or " / "). Useful for Rekordbox.
--include-featuring		False	Include tracks where the artist appears as a featured artist. Only applies to artist/discography URLs.
--qobuz-local-api		None	Optional setting forwarded to the installed Qobuz extension, if it supports it.
--tidal-api		None	Optional setting forwarded to the installed Tidal extension, if it supports it.
--timeout		180	Maximum seconds allowed for each provider attempt. If a track download stalls or takes longer than this limit, it is forcibly terminated and marked as failed, then SpotiFLAC moves to the next extension or retry.
--loop	-l	None	Keep retrying permanently failed tracks every N minutes.
--watch		None	Re-run this exact command every N minutes, forever, instead of exiting after one pass. See Watch Mode.
--retries		0	Extra per-track download attempts on failure. Cycles through all configured extensions with exponential backoff.
--max-concurrent		2	How many tracks to download at once. Each track still tries its providers in order/fallback on its own — this only controls how many tracks run simultaneously. Use 1 for fully sequential downloads with no interleaved console output.
--playlist	-p	None	Playlist URL to sync; repeat once per playlist. All tracks go to a single destination folder, shared tracks are downloaded once, and each playlist gets its own M3U file (see Multiple Playlists in One Folder).
--m3u		m3u8	Playlist file written for each --playlist: m3u8, m3u or none. Rewritten only when its content changed.
--transcode		none	Convert every downloaded track to this format: none, flac, alac, wav, aiff, wavpack, tta or mp3. Requires ffmpeg.
--mp3			Shorthand for --transcode mp3.
--alac			Shorthand for --transcode alac — lossless .m4a, read natively by macOS.
--transcode-bitrate		320k	Bitrate used by the lossy --transcode targets, e.g. 320k, 256k, 192k. Ignored by the lossless ones.
--keep-original		False	Keep the original downloaded file alongside the transcoded one.
--verify-hires		False	Runs a spectral-analysis QA check after each successful lossless download, flagging files that declare a high sample rate but lack real content above standard-definition frequencies (possible upsampling), and files whose declared bit depth is padding (24-bit carrying a 16-bit master). Nothing extra to install. Never fails or delays a download — see Hi-Res Verification.
--redownload-fake-hires		False	Acts on a certain or likely --verify-hires finding instead of only logging it (a suspect, which may be a genuine filtered master, is only reported): the flagged file is set aside, the track is downloaded again at LOSSLESS, and the flagged file is deleted only once the replacement is on disk (if every extension fails, the original is restored). Implies --verify-hires, and only applies when a Hi-Res quality was requested — see Hi-Res Verification.
--verbose	-v	False	Enable debug logging.
--log-level		INFO	Console log level: DEBUG, INFO, WARNING, ERROR, CRITICAL (aliases like WARN and numeric values are accepted). The default reports the milestones of a run — provider tried, ticket, audio fetch, transcode. Third-party libraries (httpx, httpcore, hpack, urllib3) are held at WARNING unless the level is DEBUG, so INFO stays readable. Overrides --verbose, which is a shorthand for DEBUG. A level stored in a profile ranks below --verbose.
--no-lyrics		False	Disable lyrics embedding (lyrics are embedded by default).
--lyrics-providers		apple lrclib	Lyrics provider priority order (CLI default; the Python API default is spotify apple musixmatch lrclib amazon when lyrics_providers is left unset).
--apple-lyrics-line-synced		off	Get plain line-synced LRC from the Apple lyrics provider instead of word-by-word (per-syllable) enhanced LRC.
--save-lrc		off	Also write the lyrics as an .lrc file next to the track, under the audio file's own name.
--lrc-dir	DIR	—	Also collect every lyric into DIR as Artist - Title.lrc.
--save-canvas		off	Also save the track's Spotify Canvas next to it, under the audio file's own name, with the extension of the media Spotify serves (usually .mp4, .jpg for a still).
--canvas-dir	DIR	—	Also collect every canvas into DIR as Artist - Title, with the extension of the media Spotify serves (usually .mp4, .jpg for a still).
--canvas-providers		spotify paxsenix	Where a canvas is looked up, in order.
--no-enrich		False	Disable multi-provider metadata enrichment (enrichment is enabled by default).
--enrich-providers		deezer apple qobuz tidal	Metadata enrichment provider priority order. soundcloud is also accepted but isn't on by default.
--post-action		none	Action after all downloads finish: none, open_folder, notify, command.
--post-command		""	Shell command for --post-action=command. Placeholders: {folder}, {succeeded}, {skipped}, {failed}; quote {folder} in your template (e.g. '{folder}') since the substituted path may contain spaces.
--profile		None	Load a saved profile. CLI flags override profile values.
--save-profile		None	Save current CLI configuration as a named profile after the run.
--gui		False	Launch the GUI as a native window (pywebview). See GUI Mode.
--web		False	Launch the same GUI as a local web server instead of a native window. See Web Mode.
--host		127.0.0.1	Host to bind --web to. Only change this deliberately — see the security note under Web Mode.
--port		8000	Port to bind --web to.
--web-token		None	Shared secret required on every --web request. Falls back to SPOTIFLAC_WEB_TOKEN. See Authentication.
--web-multiuser		False	Require per-account login for --web instead of/alongside --web-token. See Multi-user mode.
--web-user-add			Create a --web-multiuser account: --web-user-add USERNAME PASSWORD.
--web-user-remove			Delete a --web-multiuser account by username.
--web-user-list			List configured --web-multiuser usernames.
--tui		False	Launch the terminal UI, the guided mode. See Terminal UI.
--interactive		False	Deprecated — an alias for --tui, with a warning. The step-by-step wizard it used to open has been removed.
--registry-directories		None	A directory JSON URL to add before running (lists registries, not extensions — repeat once per URL). Alternative to SPOTIFLAC_REGISTRY_DIRECTORIES. See Extension Discovery.
--trust-key-add			Trust a registry-signing public key: --trust-key-add NAME PUBLIC_KEY_B64. See Registry Trust.
--trust-key-remove			Remove a trusted key by name.
--trust-key-list			List trusted key names/public keys.
--ext-scaffold			Generate a new extension skeleton: --ext-scaffold NAME [--runtime python|javascript] [--output-dir DIR]. See Developing Extensions.
--ext-dry-run			Validate an extension (directory or packaged ZIP) without installing it or contacting any registry: --ext-dry-run PATH.

---