Command Line Interface version of SpotiFLAC.

Usage

Basic usage:

python3 SpotiFLAC.py [options] <spotify-url> <output_dir>

Options

• --service: tidal (default) or deezer.
• --filename-format: title_artist (default), artist_title, title_only.
• --use-track-numbers: Prepend track numbers for albums/playlists.
• --use-artist-subfolders: Create artist subfolders for playlists.
• --use-album-subfolders: Create album subfolders for playlists.
• --quality: lossless (FLAC) or high (320kbps MP3/M4A).
• --loop <minutes>: Re-run downloads in a loop.

New / Useful options added in this fork

• --tidal-api <url>: Use a specific Tidal proxy API instance (e.g. https://vogel.qqdl.site).
• --auto-fallback: When enabled, the downloader will try other known API instances automatically if the selected API returns HTTP 429 or fails.
• --verbose: Enable more detailed output for debugging (colored logs are used).

Example

Download a single track (lossless) to a folder:

python3 SpotiFLAC.py --service tidal --quality lossless "https://open.spotify.com/track/..." /path/to/out

Download a playlist with a preferred Tidal API and auto-fallback enabled, minimal output:

python3 SpotiFLAC.py --service tidal --quality high --tidal-api https://vogel.qqdl.site --auto-fallback "https://open.spotify.com/playlist/..." /path/to/out

Verbose output (colors + info/debug):

python3 SpotiFLAC.py --verbose --service tidal --quality high "https://open.spotify.com/track/..." /path/to/out

Looping through a file list safely

When running multiple SpotiFLAC.py invocations from a shell loop reading from a file, avoid piping cat list | while read ... — a child process may consume stdin and cause the loop to stop after one iteration. Use this safe form instead:

xargs -d '\n' -I {} python3 SpotiFLAC.py \
    --service tidal --quality high "{}" \
    '/destination/' \
    --filename-format title_only --auto-fallback < /dev/null \
    < list.txt

Notes about rate-limits (HTTP 429)

• Many public Tidal proxy APIs have strict rate limits. Use --tidal-api to point at a less-used instance, or enable --auto-fallback to try multiple instances automatically.
• Adding a short delay between downloads (e.g. sleep 1) helps reduce hitting rate limits.

Cross-filesystem moves / renames

• This fork fixes an issue where renaming/moving downloaded files across different filesystems (e.g., WSL -> Windows paths) would leave the original file behind. The tool now tries an atomic os.replace() and falls back to shutil.move() to ensure the original is removed.

Colors and verbosity

• Output is colorized for Success/Warning/Error messages. Use --verbose to enable info/debug messages which are otherwise suppressed.
• If your terminal does not support ANSI colors, you can disable colors by setting the environment variable NO_COLOR=1 when running the script.

Dependencies

• Python 3.8+
• requests
• mutagen
• pyotp (for Spotify metadata access)
• ffmpeg (only required if converting M4A -> MP3)

Installation

Install dependencies (example using pip):

pip install -r requirements.txt --break-system-packages
# or
pip install requests mutagen pyotp --break-system-packages

Troubleshooting

• If you see a lot of HTTP 429 responses, try --auto-fallback or provide a different --tidal-api URL.
• If renaming fails across filesystems, ensure ffmpeg or required tools are installed and you have write permissions to both source and target paths.