Téléchargeur Spotify

Le streaming est idéal pour découvrir et organiser la musique, mais il ne vous donne pas de fichiers audio ordinaires que vous pouvez gérer vous-même. spotDL relie ces deux flux de travail.

Un lien Spotify fournit des détails structurés - titre de la chanson, artiste, album, date de sortie, numéro de piste et pochette. spotDL recherche une correspondance adéquate auprès d’un fournisseur pris en charge, télécharge l’audio, le convertit si nécessaire et intègre les métadonnées. Le résultat est une collection musicale portable, et non un dossier rempli de téléchargements non identifiés.

Installer avec Python

L’installation via Python est recommandée pour un usage régulier, les mises à jour, l’automatisation et l’ensemble complet des fonctionnalités en ligne de commande. Prérequis : Python 3.10-3.14, FFmpeg 4.2+, Deno recommandé, et le Visual C++ Redistributable sous Windows.

pip install spotdl

# mettre à jour une installation existante
pip install --upgrade spotdl

Docker

Une image maintenue convient aux serveurs, systèmes NAS et environnements reproductibles. Le répertoire de musique monté doit être accessible en écriture par l’utilisateur du conteneur.

docker pull spotdl/spotify-downloader

docker run --rm -v $(pwd):/music \
  spotdl/spotify-downloader download [Spotify URL]

Termux, Arch et compilation depuis les sources

spotDL s’installe également sous Android via Termux, depuis l’Arch User Repository, ou en compilant l’exécutable depuis les sources avec uv.

# Termux (Android)
curl -L https://raw.githubusercontent.com/spotDL/spotify-downloader/master/scripts/termux.sh | sh

# Compiler depuis les sources
git clone https://github.com/spotDL/spotify-downloader
cd spotify-downloader
pip install uv
uv sync
uv run scripts/build.py

FFmpeg

FFmpeg est requis pour traiter, convertir et taguer l’audio. Installez-le directement dans le dossier spotDL, ou à l’échelle du système via votre gestionnaire de paquets.

spotdl --download-ffmpeg

# ou à l’échelle du système
brew install ffmpeg            # macOS
sudo apt install ffmpeg        # Debian / Ubuntu

Deno

Deno est fortement recommandé : les téléchargements YouTube actuels via yt-dlp peuvent nécessiter un environnement d’exécution JavaScript. Sans lui, certaines pistes peuvent échouer, y compris certaines vidéos marquées comme destinées aux enfants.

spotdl --download-deno

Authentification Spotify

Les liens publics fonctionnent pour les flux de travail standard de titres, albums, playlists, artistes et recherches. L’accès aux données de compte privées - titres aimés, playlists personnelles, artistes suivis, albums enregistrés - nécessite une authentification Spotify, et certains raccourcis requièrent aussi l’option API officielle de Spotify avec des identifiants valides.

Choisir une correspondance YouTube précise

La correspondance automatique vise l’enregistrement recherché, mais vous pouvez associer une source YouTube précise aux métadonnées Spotify lorsque vous souhaitez un contrôle exact sur l’audio utilisé.

spotdl download "https://www.youtube.com/watch?v=XXYlFuWEuKI|https://open.spotify.com/track/0VjIjW4GlUZAMYd2vXMi3b"

Télécharger une bibliothèque Spotify personnelle

Les raccourcis authentifiés peuvent traiter les titres aimés, toutes vos playlists, les playlists enregistrées, les artistes suivis et les albums enregistrés. Ils nécessitent une authentification Spotify ; le flux de travail actuel avec l’API officielle est destiné aux comptes Spotify Premium.

spotdl download saved --user-auth --use-official-api
spotdl download all-user-playlists --user-auth --use-official-api
spotdl download all-saved-playlists --user-auth --use-official-api
spotdl download all-user-followed-artists --user-auth --use-official-api
spotdl download all-user-saved-albums --user-auth --use-official-api

Les options d’authentification incluent --user-auth, --use-official-api, --client-id, --client-secret, --auth-token, --cache-path, --no-cache, --headless et --max-retries. Traitez les identifiants et les jetons comme privés - ne les validez jamais dans un dépôt public.

spotDL construit une recherche à partir des détails Spotify - titre, artistes, album, durée, type de sortie - et évalue les résultats candidats, en jugeant si un résultat est vérifié et en surveillant les termes liés aux versions live, remix, reprises et enregistrements alternatifs. Cela réduit le risque de récupérer une vidéo sans rapport, mais aucun système de correspondance n’est parfait.

Contrôlez la correspondance avec --search-query (modèle personnalisé), --dont-filter-results, --only-verified-results, --album-type, ou une association manuelle YouTubeURL|SpotifyURL pour une source exacte.

spotDL télécharge l’audio disponible auprès du fournisseur sélectionné. Il ne télécharge pas les propres flux de Spotify et ne peut pas créer une qualité absente de la source. Les sources YouTube standard fournissent généralement jusqu’à 128 kbps ; les utilisateurs de YouTube Music Premium peuvent atteindre 256 kbps avec des cookies authentifiés et des réglages M4A ou Opus compatibles.

Choisir 320 kbps, FLAC ou WAV ne transforme pas une source à débit inférieur en une qualité supérieure - cela ne fait qu’un fichier plus volumineux. Pour un traitement minimal, utilisez M4A ou Opus avec la conversion désactivée ; pour une compatibilité maximale, utilisez le MP3 par défaut.

# ignorer la conversion inutile
spotdl download [URL] --format m4a --bitrate disable

# compatibilité maximale
spotdl download [URL] --format mp3

Le débit binaire accepte des débits constants de 8 à 320 kbps, des niveaux variables de 0 à 9, auto (correspondre à la source) ou disable. Avec M4A et Opus, auto ou disable peuvent ignorer la conversion lorsque la source est déjà compatible.

La pochette de l’album est intégrée par défaut. Pour les playlists, --playlist-numbering utilise le titre et l’image de la playlist comme album/pochette, tandis que --playlist-retain-track-cover conserve la pochette propre à chaque piste. Les paroles proviennent de Genius, Musixmatch ou AZLyrics par ordre de repli, et un fournisseur synchronisé peut générer des fichiers .lrc distincts.

spotdl download [query] --lyrics synced genius --generate-lrc

Contrôler les noms de fichiers et de dossiers

Le modèle par défaut est {artists} - {title}.{output-ext}. Un modèle personnalisé peut définir les noms de fichiers, les répertoires ou les deux - produisant une bibliothèque prévisible plutôt qu’un dossier unique.

spotdl download [query] \
  --output "{artist}/{album}/{track-number} - {title}.{output-ext}"

Limitez la longueur avec --max-filename-length et nettoyez les noms pour la compatibilité avec les appareils avec --restrict strict|ascii|none. Le système d’exploitation peut tout de même imposer un chemin maximal plus court.

Playlists M3U

Générez des fichiers M3U ou M3U8 en même temps que l’audio avec --m3u, choisissez un nom avec --m3u "My Playlist.m3u8", ou un fichier par liste avec --m3u "{list}". Enregistrez les chansons indisponibles dans les fichiers M3U et d’archive avec --add-unavailable.

Doublons & remplacement

Trois modes de remplacement - --overwrite skip (conserver l’existant), --overwrite metadata (actualiser les tags, conserver l’audio) et --overwrite force (retélécharger). Ajoutez --scan-for-songs pour détecter les pistes existantes, --archive pour enregistrer les téléchargements terminés, et --create-skip-file / --respect-skip-file pour des tâches par lots idempotentes.

Filtrer la collection

Ignorez les pistes explicites avec --skip-explicit, ignorez les albums avec --ignore-albums, récupérez les albums d’une chanson avec --fetch-albums, limitez le type de sortie avec --album-type single|album|compilation, n’acceptez que les résultats vérifiés avec --only-verified-results, ou désactivez le filtrage avec --dont-filter-results.

Gérer les erreurs lors de gros téléchargements

Les tâches longues peuvent contenir des pistes indisponibles, des restrictions régionales et des échecs de fournisseurs. Affichez un résumé avec --print-errors ou enregistrez-le avec --save-errors errors.txt, afin de traiter d’abord une grande collection puis d’examiner les exceptions ensuite.

Contrôles de téléchargement avancés

Ajustez le débit et le comportement avec --threads, --ffmpeg / --ffmpeg-args, --yt-dlp-args, --proxy http://host:port, --sponsor-block et --detect-formats. Les arguments d’outils personnalisés sont destinés aux utilisateurs expérimentés et peuvent entrer en conflit avec les valeurs par défaut de spotDL.

Lancer l’interface Web locale

Lancez l’interface de navigateur avec spotdl web. Elle est hébergée localement - pas sur un service de conversion distant - et convient surtout aux téléchargements simples de titres individuels. Configurez-la avec --host, --port (par défaut 8800), --keep-alive, --allowed-origins et les options TLS (--enable-tls, --cert-file, --key-file). Utilisez --web-use-output-dir pour suivre votre emplacement --output habituel.

Enregistrer la configuration une fois

Générez un fichier de configuration avec spotdl --generate-config ; il se charge automatiquement à chaque exécution. Il peut stocker les fournisseurs, formats, débit binaire, modèles de sortie, réglages FFmpeg/yt-dlp, threads, fichiers de cookies, proxy, règles de remplacement, comportement de synchronisation et réglages de l’interface Web. Désactivez le chargement automatique avec { "load_config": false }.

# emplacements de configuration par défaut
Windows:  C:\Users\<user>\.spotdl\config.json
Linux:    ~/.config/spotdl/config.json

Journalisation & diagnostics

Définissez la verbosité avec --log-level (CRITICAL → DEBUG, plus un niveau MATCH), simplifiez le terminal avec --simple-tui, personnalisez la sortie avec --log-format, profilez avec --profile, et voyez tout avec spotdl --help.