Comandos

Comandos

qobuz-dl <comando> [opções]

Comando	Aliases	O que faz
dl	—	baixa a partir de URLs do Qobuz
interactive	i, fun	busca e seleção interativa
lucky	—	baixa os primeiros resultados de uma busca
import-playlist	ip	importa playlist de outra plataforma
sync-playlist	sp	espelha uma pasta local com uma playlist
lyrics	—	injeta letras em arquivos já baixados
radar	—	descobre lançamentos via feed RSS
stats	—	estatísticas da biblioteca

Sempre disponível: qobuz-dl <comando> --help.

As flags globais de saída (-v, --quiet, --no-color) funcionam antes ou depois do subcomando. Veja Saída no Terminal.

---

dl — download direto

Aceita URLs de álbum, faixa, artista, gravadora ou playlist; várias separadas por espaço; ou um arquivo de texto com uma URL por linha.

qobuz-dl dl https://open.qobuz.com/album/xxxxx
qobuz-dl dl url1 url2 url3
qobuz-dl dl minha-lista.txt

URL de artista baixa a discografia inteira. URL de gravadora baixa o catálogo.

Filtros de seleção

Flag	Efeito
--dry-run	mostra o que seria baixado, sem baixar
--since DATE	só lançamentos a partir da data (YYYY-MM-DD ou YYYY)
--before DATE	só lançamentos anteriores à data
--albums-only	ignora singles, EPs e coletâneas VA
-s, --smart-discography	filtra tributos, karaokê e spam em discografias
-b, --blacklist ARQUIVO	palavras-chave a ignorar (veja blacklist_example.txt)
--booklet-only	baixa apenas encarte e PDFs, sem áudio

Sempre rode --dry-run antes de uma discografia grande. Ele mostra a decisão completa sem gastar banda nem tempo.

Reprocessamento

Flag	Efeito
--tag-only	reaplica tags nos arquivos existentes sem baixar; pula ausentes
--verify-download	decodifica com ffmpeg após cada faixa, detectando corrupção real no áudio
--musicbrainz	embute MBIDs via ISRC (~1 s por faixa, requer internet)

--tag-only é o comando para depois de mudar preferências de tag: corrige a biblioteca inteira sem consumir banda.

Desempenho

Flag	Padrão	Observação
--max-workers N	1	downloads paralelos; valores altos aumentam risco de bloqueio pela API
--segment-workers N	—	threads do fallback de download segmentado
--delay SEGUNDOS	—	pausa entre faixas

O download segmentado é um fallback automático: quando a Akamai (CDN do Qobuz) bloqueia o download direto, o arquivo passa a ser buscado em partes paralelas.

Esse caminho estava completamente quebrado até a 2.4.8.2 por um erro de desempacotamento que falhava na primeira linha da função. Se você já viu downloads falharem misteriosamente, era isso.

Organização

Flag	Efeito
-d, --directory PATH	pasta de destino
-ff, --folder-format	ver Qualidade e Formatação
-fbff, --fallback-folder-format	padrão alternativo quando o principal falha
-tf, --track-format	formato do nome da faixa
--no-m3u	não gera .m3u em playlists
--playlist-as-albums	organiza itens de playlist na estrutura do álbum original
--no-db	ignora o banco: baixa mesmo o que já existe
--multiple-disc-prefix CD	prefixo das pastas de disco
--multiple-disc-one-dir	todos os discos numa pasta só
--multiple-disc-track-format	formato de faixa para múltiplos discos

Também aceita todas as opções de Metadados e Tags, Letras e Tradução e capas.

---

interactive — busca interativa

qobuz-dl i
qobuz-dl i -l 50

Aliases: i, fun (este por retrocompatibilidade com o projeto original).

Interface de seleção com questionary: pesquise, navegue com as setas, marque vários itens com espaço, confirme. Aceita as mesmas opções de download do dl.

Flag	Padrão
-l, --limit	20

---

lucky — "estou com sorte"

Baixa direto os primeiros resultados, sem menu:

qobuz-dl lucky "Cowboy Bebop OST"
qobuz-dl lucky "Yoko Kanno" -t artist -n 3

Flag	Padrão	Valores
-t, --type	album	artist, album, track, playlist
-n, --number	1	quantos baixar

Ideal para caçar trilhas sonoras em lote a partir de uma lista de nomes — veja Receitas.

---

import-playlist — trazer playlists de fora

Migra playlists de Spotify, Deezer e Apple Music, por URL ou arquivo exportado:

qobuz-dl ip https://open.spotify.com/playlist/xxxxx
qobuz-dl ip minha-playlist.csv --name "Favoritas 2026"
qobuz-dl ip export.json --auto

Formatos de arquivo

Formato	Detalhes
.txt	uma entrada por linha: Artista - Título ou Artista: Título; linhas com # são comentários
.csv	qualquer export com colunas artist e title (Exportify, Soundiiz, TuneMyMusic); separador , ; ou tab detectado automaticamente
.json	exports do Spotify e exportify.net; entende [{artist,title}], [{trackName,artistName}] e [{track:{name,artists:[{name}]}}]

Cada faixa passa por correspondência aproximada contra o catálogo do Qobuz — o mesmo pipeline usado na integração com o Last.fm. Quando a confiança é baixa, o programa pergunta.

Flag	Efeito
--auto	aceita automaticamente correspondências com ≥60% de similaridade
--name, -n	pasta de destino (padrão: nome do arquivo)

--auto acelera muito, mas erra em faixas de nome genérico ou com muitas regravações. Na primeira importação de uma playlist grande, vale rodar sem ele.

---

sync-playlist — espelhar uma playlist

Mantém uma pasta local idêntica a uma playlist do Qobuz:

qobuz-dl sp https://play.qobuz.com/playlist/12345
qobuz-dl sp <url> --yes

Compara local com remoto, baixa o que falta, apaga o que saiu da playlist e limpa pastas vazias.

⚠️ Isso deleta arquivos locais. Rode sem --yes na primeira vez para revisar o que ele pretende remover. O --yes existe para uso em cron, depois que você confia no comportamento.

Aceita todas as opções de download do dl.

---

lyrics — letras retroativas

qobuz-dl lyrics
qobuz-dl lyrics "/caminho/da/musica"

Escaneia a pasta (padrão: QobuzDownloads), recupera o ID da faixa do Qobuz gravado nas tags, busca as letras e injeta.

Inspeciona o que já existe antes de agir, para não substituir uma letra sincronizada boa por uma versão simples. Detalhes em Letras e Tradução.

---

radar — lançamentos novos

qobuz-dl radar

Trabalha a partir de um feed RSS de lançamentos. Na primeira execução pede a URL e a salva no config.ini.

Fluxo:

1. Lê e interpreta o feed.
2. Pesquisa cada lançamento no Qobuz — sequencialmente de propósito, para não disparar muitas buscas simultâneas contra a API.
3. Monta um menu com o que encontrou para você escolher.

---

stats — estatísticas

qobuz-dl stats
qobuz-dl stats --artistas

Leitura puramente local: não precisa de rede nem de login.

Mostra total de downloads, álbuns, faixas avulsas, artistas e álbuns únicos, distribuição por qualidade e formato com medidores visuais, e o ranking dos artistas mais baixados. --artistas lista todos.

---

Operações globais de manutenção

Não são subcomandos — são flags do comando principal. Documentadas em Manutenção da Biblioteca.

Flag	O que faz
--sync-db [PATH]	reconstrói o banco a partir dos arquivos em disco
--find-duplicates [PATH]	detecta duplicatas por impressão digital acústica
--watch [PATH]	vigia a pasta e aplica letras automaticamente
-p, --purge	apaga o banco de dados
-r, --reset	recria o config.ini
-sc, --show-config	mostra a configuração atual