Downloader de Spotify
O spotDL é um downloader de Spotify gratuito e de código aberto que transforma faixas, álbuns, playlists e artistas em ficheiros de áudio locais e organizados - com metadados, capa do álbum e letras incluídos.
O Spotify fornece as informações da faixa e da playlist. O áudio provém do YouTube Music, do YouTube ou de outro fornecedor configurado - não do Spotify.
Links do Spotify à entrada. Ficheiros bem organizados à saída.
O streaming é ótimo para descobrir e organizar música, mas não lhe dá ficheiros de áudio comuns que possa gerir por conta própria. O spotDL liga esses dois fluxos de trabalho.
Um link do Spotify fornece detalhes estruturados - título da música, artista, álbum, data de lançamento, número da faixa e capa. O spotDL procura uma correspondência adequada num fornecedor suportado, transfere o áudio, converte-o quando necessário e incorpora os metadados. O resultado é uma coleção de música portátil, e não uma pasta cheia de transferências por identificar.
Como funciona o spotDL
Três passos de um link do Spotify até um ficheiro de música etiquetado e pronto a reproduzir.
Adicione um link do Spotify ou uma pesquisa
Cole um link de uma faixa, álbum, playlist ou artista - ou encontre uma música com uma simples pesquisa de texto. Vários links e pesquisas podem ser incluídos no mesmo comando.
O spotDL encontra o áudio
O spotDL lê os metadados do Spotify e pesquisa no YouTube Music por predefinição. A correspondência e a filtragem distinguem a gravação pretendida de covers, remisturas, versões ao vivo e resultados não relacionados.
Guarde um ficheiro de música completo
O áudio é processado com o FFmpeg e, em seguida, os metadados, a capa e as letras disponíveis são incorporados automaticamente - com o formato, as pastas, os nomes de ficheiros e o comportamento de substituição totalmente configuráveis.
Mais do que um simples downloader
Uma aplicação focada em transformar links do Spotify numa biblioteca de música estruturada e fácil de manter.
Faixas, álbuns, playlists e artistas
Aceita URLs do Spotify de faixas individuais, álbuns completos, playlists e páginas de artistas - além de pesquisas de texto e lotes mistos.
Correspondência automática de faixas
Os metadados do Spotify constroem e filtram a pesquisa para identificar uma gravação adequada, em vez do primeiro vídeo vagamente relacionado.
Metadados incorporados
Título, artistas, álbum, artista do álbum, capa, números de faixa e de disco, ano, género, editora, ISRC, ID do Spotify e letras.
Letras e ficheiros .lrc sincronizados
Recolha letras do Genius, Musixmatch ou AZLyrics e gere ficheiros .lrc sincronizados separados para leitores compatíveis.
Seis formatos de saída
MP3, M4A, Opus, OGG, FLAC e WAV - escolha o que o seu leitor ou fluxo de trabalho precisa.
Nomes de ficheiros e pastas configuráveis
Os modelos de saída criam uma biblioteca {artist}/{album} previsível, em vez de uma pasta única com nomes inconsistentes.
Geração de playlists M3U
Crie ficheiros de playlist M3U ou M3U8 juntamente com o áudio, incluindo um ficheiro separado por lista num trabalho com várias listas.
Controlo de duplicados e substituição
Ignore, atualize os metadados, force uma nova transferência, procure músicas existentes ou mantenha um arquivo das transferências concluídas.
Vários fornecedores de áudio
YouTube Music por predefinição, com YouTube, SoundCloud, Bandcamp, Piped e slider.kz como alternativas ou recursos secundários.
Sincronização de playlists
Um ficheiro de sincronização .spotdl mantém uma pasta local alinhada com uma playlist ou álbum do Spotify que muda ao longo do tempo.
Configuração reutilizável
Guarde uma vez os formatos, modelos, fornecedores, threads e regras preferidos - são carregados automaticamente em cada execução.
Interface Web local
Uma interface de navegador simples para transferências individuais, alojada no seu próprio computador - não um serviço de conversão remoto.
Transferir o spotDL
Aplicação pré-compilada: abri-la sem argumentos inicia a interface Web local para transferências simples de faixas individuais. A sincronização de playlists, os trabalhos em lote e os controlos avançados estão na linha de comandos. O FFmpeg continua a ser necessário (spotdl --download-ffmpeg) e o Deno é recomendado (spotdl --download-deno).
Instalar com o Python
A instalação através do Python é recomendada para uso regular, atualizações, automação e o conjunto completo de funcionalidades da linha de comandos. Requisitos: Python 3.10-3.14, FFmpeg 4.2+, Deno recomendado e o Visual C++ Redistributable no Windows.
Docker
Uma imagem mantida é adequada para servidores, sistemas NAS e ambientes reproduzíveis. A pasta de música montada tem de ter permissão de escrita para o utilizador do contentor.
Termux, Arch e compilação a partir do código-fonte
O spotDL também se instala no Android via Termux, através do Arch User Repository, ou compilando o executável a partir do código-fonte com o uv.
Componentes necessários
FFmpeg
O FFmpeg é necessário para processar, converter e etiquetar áudio. Instale-o diretamente na pasta do spotDL ou em todo o sistema através do seu gestor de pacotes.
Deno
O Deno é fortemente recomendado: as transferências atuais do YouTube através do yt-dlp podem exigir um runtime de JavaScript. Sem ele, algumas faixas podem falhar, incluindo certos vídeos marcados como destinados a crianças.
Autenticação no Spotify
Os links públicos funcionam para os fluxos de trabalho padrão de faixas, álbuns, playlists, artistas e pesquisas. O acesso a dados privados da conta - músicas adicionadas aos Gostos, playlists pessoais, artistas seguidos, álbuns guardados - requer autenticação no Spotify, e alguns atalhos precisam também da opção da API oficial do Spotify com credenciais válidas.
Comece com um único comando
A operação predefinida é download. Os ficheiros são guardados na pasta onde executa o spotDL, a menos que defina um caminho com --output.
Se o comando spotdl não estiver disponível mas o pacote estiver instalado, execute-o como módulo com python -m spotdl [query] (ou python3 -m spotdl no macOS / Linux).
Escolher uma correspondência específica do YouTube
A correspondência automática procura a gravação pretendida, mas pode associar uma fonte específica do YouTube aos metadados do Spotify quando quer um controlo exato sobre o áudio utilizado.
Transferir uma biblioteca pessoal do Spotify
Os atalhos autenticados podem processar músicas adicionadas aos Gostos, todas as suas playlists, playlists guardadas, artistas seguidos e álbuns guardados. Estes requerem autenticação no Spotify; o atual fluxo de trabalho com a API oficial destina-se a contas Spotify Premium.
As flags de autenticação incluem --user-auth, --use-official-api, --client-id, --client-secret, --auth-token, --cache-path, --no-cache, --headless e --max-retries. Trate as credenciais e os tokens como privados - nunca os submeta num repositório público.
Seis operações principais
download
Transfere o áudio e incorpora os metadados disponíveis.
save
Recolhe os metadados do Spotify num ficheiro .spotdl sem transferir o áudio.
sync
Mantém uma pasta local alinhada com uma playlist ou álbum do Spotify.
meta
Atualiza os metadados, a capa e as etiquetas de ficheiros de áudio existentes.
url
Resolve as músicas de uma pesquisa para os respetivos URLs de áudio.
web
Inicia a interface Web local no navegador.
Mantenha as playlists locais sincronizadas
Uma playlist transferida não tem de se tornar um retrato desatualizado. A operação sync compara a sua pasta local com a fonte atual do Spotify: as novas faixas são transferidas e as faixas removidas da fonte podem ser removidas localmente.
Por predefinição, a sincronização espelha a fonte e pode eliminar as faixas removidas do Spotify. Use --sync-without-deleting para manter os ficheiros locais, ou --sync-remove-lrc para remover também os ficheiros .lrc correspondentes quando as músicas são removidas. Ideal para playlists que mudam todas as semanas e para atualizações automáticas da biblioteca.
Como funciona a correspondência de faixas
O spotDL cria uma pesquisa a partir dos detalhes do Spotify - título, artistas, álbum, duração, tipo de lançamento - e avalia os resultados candidatos, ponderando se um resultado é verificado e atento a termos associados a versões ao vivo, remisturas, covers e gravações alternativas. Reduz o risco de obter um carregamento não relacionado, mas nenhum sistema de correspondência é perfeito.
Controle a correspondência com --search-query (modelo personalizado), --dont-filter-results, --only-verified-results, --album-type ou uma associação manual YouTubeURL|SpotifyURL para uma fonte exata.
Fornecedores de áudio
O YouTube Music é a predefinição. Configure vários fornecedores por ordem de recurso - se o primeiro não conseguir devolver um resultado adequado, o spotDL tenta o seguinte.
A disponibilidade dos fornecedores, o acesso regional, a autenticação, a qualidade do áudio e a precisão da pesquisa variam. Não há garantia de que uma faixa do Spotify esteja disponível num determinado fornecedor de áudio.
Seis formatos de saída
Escolha o formato de que o seu leitor ou fluxo de trabalho precisa. Defina-o com --format.
MP3
A predefinição. Ampla compatibilidade com leitores, automóveis, telemóveis, servidores multimédia e hardware mais antigo.
M4A
Útil quando a fonte já é compatível e se pretende evitar a transcodificação desnecessária.
Opus
Compressão eficiente que pode preservar a fonte sem outra conversão, quando as definições o permitem.
OGG
Para leitores e fluxos de trabalho que exigem um formato de contentor aberto.
FLAC
Para etiquetagem e uniformização da biblioteca. Converter uma fonte com perdas para FLAC não recupera o áudio perdido.
WAV
PCM não comprimido para aplicações que o exigem. Ficheiros maiores, sem ganho de qualidade face a uma fonte com perdas.
Qualidade do áudio, sem afirmações enganosas
O spotDL transfere o áudio disponível no fornecedor selecionado. Não transfere as transmissões do próprio Spotify e não consegue criar qualidade que não exista na fonte. As fontes padrão do YouTube fornecem geralmente até 128 kbps; os utilizadores do YouTube Music Premium podem chegar aos 256 kbps com cookies autenticados e definições compatíveis de M4A ou Opus.
Escolher 320 kbps, FLAC ou WAV não transforma uma fonte de menor débito em maior qualidade - apenas cria um ficheiro maior. Para um processamento mínimo, use M4A ou Opus com a conversão desativada; para máxima compatibilidade, use o MP3 predefinido.
O débito binário aceita taxas constantes de 8-320 kbps, níveis variáveis de 0-9, auto (corresponder à fonte) ou disable. Com M4A e Opus, auto ou disable podem saltar a conversão quando a fonte já é compatível.
Metadados, capa e letras
Os ficheiros podem incluir tudo o que um leitor e um gestor de bibliotecas modernos esperam. Os metadados também podem ser aplicados a áudio existente com a operação meta.
A capa do álbum é incorporada por predefinição. Para playlists, --playlist-numbering usa o título e a imagem da playlist como álbum/capa, enquanto --playlist-retain-track-cover mantém a capa de cada faixa. As letras vêm do Genius, Musixmatch ou AZLyrics por ordem de recurso, e um fornecedor sincronizado pode gerar ficheiros .lrc separados.
Controlar os nomes de ficheiros e pastas
O modelo predefinido é {artists} - {title}.{output-ext}. Um modelo personalizado pode definir nomes de ficheiros, pastas ou ambos - produzindo uma biblioteca previsível em vez de uma pasta única.
| Variável | Significado |
|---|---|
{title} | Título da música |
{artists} | Todos os artistas da música |
{artist} | Artista principal |
{album} | Título do álbum |
{album-artist} | Artista principal do álbum |
{genre} | Género |
{year} | Ano de lançamento |
{original-date} | Data de lançamento original |
{track-number} | Número da faixa no álbum |
{tracks-count} | Total de faixas no álbum |
{disc-number} | Número do disco |
{isrc} | Código Internacional Normalizado de Gravação (ISRC) |
{track-id} | ID da faixa no Spotify |
{publisher} | Editora ou etiqueta discográfica |
{list-name} | Nome da playlist ou coleção |
{list-position} | Posição na playlist |
{output-ext} | Extensão do ficheiro de saída |
Limite o comprimento com --max-filename-length e higienize os nomes para compatibilidade com dispositivos usando --restrict strict|ascii|none. O sistema operativo pode ainda impor um caminho máximo mais curto.
Controlos de biblioteca e automação
Playlists M3U
Gere ficheiros M3U ou M3U8 juntamente com o áudio com --m3u, escolha um nome com --m3u "My Playlist.m3u8", ou um ficheiro por lista com --m3u "{list}". Registe as músicas indisponíveis nos ficheiros M3U e de arquivo com --add-unavailable.
Duplicados e substituição
Três modos de substituição - --overwrite skip (manter o existente), --overwrite metadata (atualizar as etiquetas, manter o áudio) e --overwrite force (transferir de novo). Adicione --scan-for-songs para detetar faixas existentes, --archive para registar as transferências concluídas e --create-skip-file / --respect-skip-file para trabalhos em lote idempotentes.
Filtrar a coleção
Ignore faixas explícitas com --skip-explicit, ignore álbuns com --ignore-albums, obtenha os álbuns de uma música com --fetch-albums, limite o tipo de lançamento com --album-type single|album|compilation, aceite apenas resultados verificados com --only-verified-results, ou desative a filtragem com --dont-filter-results.
Gerir erros em transferências grandes
Os trabalhos longos podem conter faixas indisponíveis, restrições regionais e falhas dos fornecedores. Imprima um resumo com --print-errors ou guarde-o com --save-errors errors.txt, para poder processar primeiro uma coleção grande e rever as exceções depois.
Controlos avançados de transferência
Ajuste o desempenho e o comportamento com --threads, --ffmpeg / --ffmpeg-args, --yt-dlp-args, --proxy http://host:port, --sponsor-block e --detect-formats. Os argumentos personalizados das ferramentas destinam-se a utilizadores experientes e podem entrar em conflito com as predefinições do spotDL.
Executar a interface Web local
Inicie a interface de navegador com spotdl web. É alojada localmente - não num serviço de conversão remoto - e é ideal para transferências simples de faixas individuais. Configure-a com --host, --port (predefinição 8800), --keep-alive, --allowed-origins e opções TLS (--enable-tls, --cert-file, --key-file). Use --web-use-output-dir para seguir a sua localização --output habitual.
Guardar a configuração uma vez
Gere um ficheiro de configuração com spotdl --generate-config; é carregado automaticamente em cada execução. Pode guardar fornecedores, formatos, débito binário, modelos de saída, definições do FFmpeg/yt-dlp, threads, ficheiros de cookies, proxy, regras de substituição, comportamento de sincronização e definições da interface Web. Desative o carregamento automático com { "load_config": false }.
Registos e diagnóstico
Defina o detalhe com --log-level (CRITICAL → DEBUG, mais um nível MATCH), simplifique o terminal com --simple-tui, personalize a saída com --log-format, faça profiling com --profile e veja tudo com spotdl --help.
Concebido para bibliotecas de música reais
Leve uma playlist selecionada para offline
Converta uma playlist do Spotify em ficheiros padrão para um portátil, telemóvel, automóvel, leitor portátil ou biblioteca offline.
Transfira lançamentos completos
Processe um álbum como um único trabalho, preservando os números de faixa e de disco, as informações de lançamento e a capa.
Crie uma coleção de um artista
Use um link de artista para processar o catálogo disponível sem submeter cada lançamento individualmente.
Mova música entre dispositivos
Os ficheiros não estão presos a uma aplicação - copie-os, faça cópias de segurança, mude-lhes o nome, indexe-os e reproduza-os em qualquer lado.
Mantenha uma biblioteca auto-alojada
Os modelos personalizados e os metadados padrão adequam-se a servidores de música, coleções em NAS e pastas de arquivo.
Automatize fluxos de trabalho recorrentes
Os ficheiros de configuração, arquivos, ficheiros de exclusão, metadados guardados e comandos de sincronização tornam os trabalhos repetidos reproduzíveis.
Resolução de problemas
Soluções rápidas para os problemas de instalação e transferência mais comuns.
O 'spotdl' não é reconhecido no Windows+
O Python ou a respetiva pasta Scripts não está no PATH. Reinstale o Python a partir de python.org, marque “Add Python to PATH” e reinicie o terminal. O Python da Microsoft Store pode causar problemas na resolução do comando.
spotdl: comando não encontrado no Linux/macOS+
A pasta bin da instalação do utilizador não está no PATH. Adicione-a e recarregue a configuração da shell:
Dependências do yt-dlp em falta+
Instale ou atualize os pacotes necessários:
AudioProviderError: YT-DLP download error+
Algumas transferências do YouTube precisam de um runtime de JavaScript, incluindo certos vídeos marcados como destinados a crianças. Instale o Deno:
Erro HTTP 404 nos metadados do Spotify / erro de recursão+
Uma versão antiga pode depender de um comportamento da API que mudou. Atualize o spotDL:
SSL: CERTIFICATE_VERIFY_FAILED+
Atualize o arquivo de certificados do sistema operativo e o pacote de certificados do Python. No macOS, execute o script de instalação de certificados incluído na sua instalação do Python. Desativar a verificação não é uma solução segura.
Erro _raw_ecb / Cryptodome no Apple Silicon+
O Python e uma dependência compilada foram instalados para arquiteturas diferentes. Use um Python nativo para Apple Silicon e reinstale as dependências afetadas no mesmo ambiente.
YouTube Music KeyError: 'header'+
Atualize o ytmusicapi e, se persistir, force a reinstalação do spotDL. O YouTube Music pode ocasionalmente alterar a sua resposta ou acionar comportamentos anti-bot; tentar mais tarde pode resolver.
Perguntas frequentes
O que é o spotDL?+
O spotDL é um downloader de Spotify gratuito e de código aberto que transforma faixas, álbuns, playlists e links de artistas do Spotify em ficheiros de áudio locais e organizados. Usa o Spotify para identificar a música e recolher os metadados e, em seguida, encontra o áudio correspondente através de fornecedores suportados, como o YouTube Music.
O spotDL transfere o áudio diretamente do Spotify?+
Não. O Spotify fornece informações como o título da faixa, o artista, o álbum, a data de lançamento, o número da faixa e a capa. O áudio em si é transferido do YouTube Music, do YouTube ou de outro fornecedor configurado quando existe uma correspondência adequada.
O spotDL consegue transferir uma playlist inteira do Spotify?+
Sim. Um link de playlist pode ser processado como um único trabalho. O spotDL encontra o áudio correspondente, transfere cada faixa disponível, incorpora os metadados e organiza os ficheiros de acordo com as suas definições de saída. As playlists grandes demoram, e algumas faixas podem ser ignoradas quando não é encontrada uma correspondência fiável.
As playlists transferidas podem ser atualizadas mais tarde?+
Sim. A operação de sincronização compara uma coleção local guardada com a playlist atual do Spotify. As novas faixas são transferidas automaticamente e as faixas removidas do Spotify também podem ser eliminadas da pasta. A eliminação pode ser desativada com --sync-without-deleting.
Que formatos de áudio o spotDL suporta?+
O spotDL suporta MP3, M4A, Opus, OGG, FLAC e WAV. O MP3 é a predefinição e oferece a maior compatibilidade. O M4A e o Opus podem reduzir conversões desnecessárias quando usados com definições de fonte compatíveis.
O spotDL consegue transferir áudio a 320 kbps ou sem perdas?+
O spotDL não consegue criar qualidade que não exista na fonte. As fontes padrão do YouTube fornecem geralmente até 128 kbps, enquanto as fontes autenticadas do YouTube Music Premium podem chegar aos 256 kbps. Selecionar 320 kbps, FLAC ou WAV apenas converte a fonte existente num ficheiro diferente (muitas vezes maior) - não recupera o áudio em falta.
O spotDL adiciona capa do álbum, letras e metadados?+
Sim. Consoante a disponibilidade e a configuração, os ficheiros podem incluir o título, os artistas, o álbum, o artista do álbum, a capa, os números de faixa e de disco, a data de lançamento, o género, a editora, o ISRC, o ID da faixa no Spotify e as letras. O spotDL também pode criar ficheiros de letras .lrc sincronizados.
Qual é a precisão da correspondência de faixas?+
O spotDL utiliza os metadados do Spotify para pesquisar e avaliar os resultados disponíveis antes de transferir, o que ajuda a distinguir a gravação de estúdio de covers, remisturas, versões ao vivo e vídeos não relacionados. A correspondência não é infalível - pode associar um URL específico do YouTube a uma faixa do Spotify quando é necessário um controlo exato.
Existe uma interface gráfica?+
Sim. O spotDL inclui uma interface Web local para transferências individuais simples, que corre no seu próprio computador em vez de um serviço remoto. A linha de comandos disponibiliza o conjunto completo de funcionalidades, incluindo a sincronização de playlists, o processamento em lote, fornecedores avançados e a configuração.
Que sistemas operativos suportam o spotDL?+
O spotDL funciona no Windows, macOS e Linux, com opções de instalação para Docker, Termux, Arch Linux e compilação a partir do código-fonte. A compatibilidade depende do método escolhido e dos componentes necessários, como o Python e o FFmpeg.
O que é necessário para executar o spotDL?+
O FFmpeg é necessário para o processamento, conversão e etiquetagem do áudio (instale-o com "spotdl --download-ffmpeg"). O Deno é fortemente recomendado, porque algumas transferências do YouTube precisam de um runtime de JavaScript ("spotdl --download-deno"). A instalação recomendada é "pip install spotdl".
O spotDL é gratuito?+
Sim. O spotDL é distribuído sob a Licença MIT e pode ser transferido, usado, inspecionado, modificado e redistribuído nos termos dessa licença. Não existe uma subscrição paga do spotDL. As plataformas externas, fornecedores ou contas premium podem ter os seus próprios termos e custos separados.
O spotDL está associado ao Spotify ou ao YouTube?+
Não. O spotDL é um projeto independente de código aberto e não está associado, patrocinado nem aprovado pelo Spotify, YouTube, Google ou por qualquer editora discográfica. O Spotify e o YouTube são marcas comerciais dos respetivos proprietários.
É legal usar o spotDL?+
O spotDL é uma ferramenta de software de uso geral. Se uma determinada transferência é permitida depende da música, da fonte, da utilização pretendida, da legislação de direitos de autor aplicável e dos termos das plataformas em causa. Transferir um ficheiro não confere propriedade nem direitos de redistribuição. Use o spotDL apenas para áudio que tenha permissão legal para transferir, copiar ou processar.
Crie uma biblioteca de música que se mantém portátil
Comece com uma música, converta uma playlist completa ou crie um fluxo de trabalho local repetível com controlo total sobre formatos, metadados, nomes de ficheiros e sincronização.