𝗤𝗢𝗕𝗨𝗭-𝗗𝗟 𝗨𝗟𝗧𝗥𝗔

📑 Índice

• ✨ Funcionalidades

  • 🎧 Mecanismo Audiófilo e de Metadados
  • 🚀 Mecanismo de Download Resiliente
  • 📁 Formatação Avançada e Armazenamento
  • ❤️ Sincronização Nativa de Favoritos e Menu Interativo
  • 🌉 Integração Inteligente com Last.fm e Modo Interativo
  • 🛡️ Gerenciamento de Pastas À Prova de Falhas e Retomada Inteligente

• 📥 Instalação e Configuração

  • Opção A: 📦 Pacote PyPI (Recomendado)
  • Opção B: Código-fonte Python (Avançado)
  • Opção C: 🐳 Uso com Docker
  • ⚙️ Configuração e Caminhos Personalizados
  • 🔑 Como obter seu Auth Token

• 💻 Uso e Exemplos Rápidos

  • 🗄️ Gerenciamento de Banco de Dados e Biblioteca
  • 🛠️ Principais Variáveis de Formatação

• 🔧 Solução de Problemas: Ambientes Headless e Servidores

• 🏆 Créditos

• ⚠️ Isenção de Responsabilidade (Aviso Legal)

Pesquise, explore e baixe músicas Lossless e Hi-Res do Qobuz.

✨ Funcionalidades

🎧 Mecanismo Audiófilo e de Metadados

• Otimizado para Roon e DAP: Metadados, capas e letras são meticulosamente formatados para garantir integração perfeita e imediata com servidores Roon e Tocadores de Áudio Digital (DAPs).
• Tagging Direto de URL do Álbum: Gera e incorpora automaticamente um link clicável direto QOBUZ ALBUM URL nos metadados da faixa (Vorbis Comments para FLAC, quadro TXXX para MP3). Isso permite o acesso com um clique à página original do álbum no Qobuz diretamente de editores de tags como o Mp3tag ou reprodutores audiófilos compatíveis. Você pode opcionalmente desativar essa tag não padrão usando a flag --no-album-url-tag (ou no_album_url_tag = true no arquivo de configuração).
• Letras Sincronizadas Prontas para o Roon: O mecanismo formata e incorpora inteligentemente dados .lrc com marcação de tempo diretamente nos arquivos de áudio (Vorbis Comments [LYRICS]), garantindo que o Roon exiba nativamente letras roláveis em estilo karaokê na visualização “Tocando Agora” (Now Playing). Se você preferir uma estrutura de pastas minimalista e organizada, pode desativar totalmente a geração de arquivos .lrc externos via CLI (--no-lrc-files). Por outro lado, se preferir arquivos externos sem inflar os metadados do áudio, use a nova flag --no-embed-lyrics (ou defina embed_lyrics = false na configuração).
• Controle Amplo de Tags: O mecanismo de tags reformulado suporta metadados altamente detalhados de música clássica. Quase todas as tags podem ser ativadas/desativadas via argumentos de linha de comando (CLI).
• Tradução Inteligente de Gêneros: Traduz automaticamente gêneros persistentes em francês (ex.: Électronique, Bande Originale) para o inglês padrão, garantindo que sua biblioteca permaneça consistente e pesquisável.
• Tagging Nativo Multi-Artista / Multi-Valor e Análise Profunda de Intérpretes: Detecta e separa automaticamente artistas principais, participações especiais e extrai todos os compositores/letristas de strings de metadados complexas do Qobuz. Com a nova flag CLI --multi-tags, o mecanismo divide inteligentemente metadados separados por vírgula em tags multi-valor discretas para FLAC (Vorbis Comments) e MP3 (ID3v2.4), garantindo interpretação impecável da biblioteca por players avançados como Roon, MusicBee ou Plexamp.
• Suporte Nativo a ReplayGain: Extrai e incorpora automaticamente as tags REPLAYGAIN_TRACK_GAIN e REPLAYGAIN_TRACK_PEAK diretamente dos dados ocultos da API do Qobuz. Isso garante nivelamento de volume perfeito e não destrutivo de fábrica para tocadores de áudio digital (DAPs) de alta fidelidade e servidores audiófilos como o Roon.
• Mecanismo Automático de Letras e Tagger Retroativo: Busca e injeta letras sincronizadas (.lrc) e não sincronizadas usando o LRCLIB (com fallback para a API do Genius). Inclui o comando dedicado lyrics para escanear retroativamente e injetar letras ausentes em sua biblioteca local existente sem precisar baixar novamente o áudio.
• Encartes Digitais Aprimorados (Digital Booklets): Compila automaticamente um arquivo .txt formatado com lista de faixas completa, duração, créditos detalhados, metadados e resenhas. Ao concluir, o mecanismo varre a pasta, remove as marcações de tempo dos arquivos .lrc e anexa as letras em texto puro de todo o álbum diretamente no encarte. “Goodies” oficiais em PDF também são baixados junto. Agora você pode usar a flag --booklet-only para baixar exclusivamente esses arquivos de metadados, capas e PDFs, ignorando graciosamente todas as faixas de áudio pesadas.
• Correção do Campo de Compositor: Extrai meticulosamente cada compositor individual da string completa de intérpretes, acabando com o problema de metadados de compositores truncados ou “aleatórios”.
• Formatação Inteligente de Datas: Padroniza as datas de lançamento em entradas únicas e limpas, evitando conflitos de tags duplicadas de ano/data em softwares de reprodução.
• Modo Bit-Perfect & Purista: Desative completamente as tags de volume ReplayGain e Peak usando a flag CLI --no-replaygain-tag (ou no_replaygain_tag = true na configuração). Isso garante que seus arquivos de áudio permaneçam estritamente bit-perfect e intocados por quaisquer instruções de nivelamento de volume via software, ideal para DACs de alta fidelidade e DAPs dedicados.

🚀 Mecanismo de Download Resiliente

• Fila À Prova de Falhas: Tratamento avançado de exceções no nível da faixa. Se uma única faixa estiver bloqueada geograficamente ou ausente nos servidores (erro 404), o mecanismo a pula normalmente e continua baixando o restante do seu álbum ou playlist sem travar.
• Recuperação e Sincronização de Banco de Dados: Inclui um mecanismo especializado --sync-db para restaurar entradas ausentes em seu banco de dados local escaneando suas pastas de música existentes.
• Sincronização Bidirecional de Playlists (sync-playlist): Um poderoso mecanismo de espelhamento para playlists dinâmicas. Mantenha suas pastas locais perfeitamente sincronizadas com as alterações online (baixando novas faixas e excluindo de forma limpa as que foram removidas). A v2.0.1 introduz a Lógica Inteligente de Pastas (Smart Folder Logic): ao usar -d . ou caminhos genéricos, ele cria automaticamente uma subpasta com o nome da playlist, evitando a exclusão acidental de arquivos no seu diretório raiz.
• Tabela Profissional de Faixas Ausentes: Se o mecanismo de sincronização detectar faixas na sua playlist online que estejam ausentes no seu disco local, ele gera uma tabela ASCII limpa e colorida com Título, Artista e ID para fácil acompanhamento.
• Busca Reversa Inteligente (Reverse Lookup): Identifica automaticamente arquivos antigos lendo suas tags ISRC ou UPC e consultando a API do Qobuz para restaurar os IDs corretos no banco de dados.
• Validação Inteligente Prévia de Configuração: Introduzido na v2.0.3, um sistema de validação inteligente verifica as strings de formatação do seu config.ini antes de iniciar qualquer download. Se detectar uma variável não reconhecida, o mecanismo aborta o processo com segurança e usa difflib para sugerir inteligentemente a variável correta, evitando exceções KeyError silenciosas.
• Download Segmentado e Remuxagem: Contorna a limitação de velocidade (throttling) da CDN da Akamai com um mecanismo de download segmentado de alta velocidade e remuxagem automática via FFmpeg.
• Download Multithread: Downloads simultâneos de faixas para obtenção ultrarrápida de álbuns.
• Interface Limpa para Multithreading: Alterna de forma inteligente para um sistema de registros estático e limpo exibindo tamanhos precisos de arquivo (MB) durante downloads concorrentes. Isso evita falhas visuais no terminal e conflitos com o mecanismo de letras, enquanto preserva as barras de progresso animadas clássicas para downloads sequenciais (--delay).
• Recuperação de Terminal (Correção do Raw Mode): Corrigido um bug crítico de interface onde a interrupção do prompt de busca interativo (modo fun) com CTRL+C deixava o terminal do sistema operacional em um estado quebrado. O mecanismo agora aciona com segurança uma saída graciosa do sistema, restaurando a disciplina de linha padrão do terminal.
• Fallback Inteligente de Qualidade: Reduz automaticamente para a próxima melhor qualidade disponível caso o nível solicitado seja restrito pelo servidor, garantindo que sua fila de download nunca trave.
• Bypass de Autenticação: Faça login com segurança usando o Token de Autenticação (Auth Token) do seu navegador caso a autenticação padrão por senha esteja bloqueada. Suporta perfeitamente contas Free e Studio.
• Armazenamento Seguro de Credenciais (Keyring do SO): Diga adeus às senhas em texto puro. Os tokens de autenticação (Qobuz e Genius) são criptografados com segurança e armazenados nativamente no gerenciador de credenciais do seu sistema operacional (Windows Credential Manager, macOS Keychain ou Linux Secret Service). Recurso da Edição Ultimate: Suporte nativo para ambientes headless (NAS/Docker/WSL). Se o sistema não tiver um daemon de chaveiro seguro, a opção disable_keyring permite persistir tokens sem criptografia no config.ini; use-a apenas quando necessário e proteja esse arquivo.
• Camuflagem Anti-Banimento (Stealth Spoofing): WAFs (Web Application Firewalls) modernas bloqueiam requisições de API originadas de scripts headless. Este mecanismo conta com camuflagem criptográfica completa, injetando Client Hints exatos do Windows/Chrome (Sec-Ch-Ua, Sec-Fetch-Site) para tornar sua sessão indistinguível de um usuário legítimo navegando no Qobuz Web Player, reduzindo significativamente erros 403 e prevenindo banimentos de conta.
• Playlists Sem Limites: Supera as restrições da API do Qobuz paginando dinamicamente as requisições em blocos, permitindo que você enfileire e baixe playlists massivas sem o gargalo padrão de 50 faixas.
• Retomada Inteligente (Sem Sobrescritas): Detecta inteligentemente arquivos existentes no seu disco local e os ignora automaticamente. Se o download de uma discografia massiva for interrompido, ele é retomado instantaneamente sem desperdiçar tempo ou largura de banda baixando faixas existentes.
• Mecanismo de Blacklist Anti-Spam: Filtre automaticamente lançamentos indesejados (“lixo”, como versões em Karaokê, covers instrumentais, álbuns de tributo) ao baixar discografias completas de artistas ou catálogos de gravadoras. Você pode passar um arquivo .txt contendo suas palavras-chave personalizadas (ex.: Karaoke, (Live), Original Soundtrack) pela flag CLI -b ou configurá-lo permanentemente no seu config.ini. O mecanismo combina dinamicamente o título principal e as tags de versão, garantindo filtragem perfeita antes que um único byte de áudio seja baixado.
• Download em Lote com Estado (Memória em Arquivo de Texto): Ao baixar filas massivas a partir de um arquivo .txt, o mecanismo atua como um banco de dados vivo. Ele valida URLs automaticamente e anexa uma tag [DONE] ao lado dos links concluídos diretamente dentro do arquivo de texto. Se sua conexão cair ou você abortar o processo, basta rodar novamente o comando: o mecanismo pulará instantaneamente os links concluídos e continuará a fila exatamente de onde parou.
• Geração Impecável de .m3u: Gera automaticamente arquivos de playlist com caminhos relativos corretos. A v2.0.1 apresenta um algoritmo robusto de correspondência em 4 etapas (ID -> ISRC -> Título -> Nome do arquivo) que garante que o arquivo .m3u espelhe com precisão a ordem da API, mesmo quando as faixas não possuem prefixos numéricos em seus nomes.
• Mecanismo de Correspondência O(1) Ultrarrápido: O gerador de playlists agora utiliza indexação de dicionário de alto desempenho. Ele identifica arquivos locais instantaneamente, reduzindo o tempo de processamento de playlists grandes de segundos para milissegundos. (Agradecimentos a marrobHD)
• Arquivos Temporários Compatíveis com NAS e macOS: Arquivos temporários de download agora usam um prefixo padrão ~tmp_ em vez de um ponto inicial. Isso impede que sistemas baseados em Unix (macOS, Synology SMB/Samba) apliquem permanentemente atributos de sistema “Oculto” aos seus arquivos de áudio, eliminando a necessidade de comandos de limpeza no terminal.

📁 Formatação Avançada e Armazenamento

O Qobuz-DL Ultra permite profunda personalização da estrutura da sua biblioteca usando variáveis.

• Suporte a Playlists Reais (Nativo): Lida perfeitamente com playlists do Qobuz e Last.fm com uma lógica especializada projetada para organização de biblioteca (Resolve a issue #257).
• Estrutura de Pasta Plana (Flat): Baixa automaticamente todas as faixas em um único diretório nomeado com o título da playlist, evitando a criação de dezenas de subpastas de álbuns dispersas.
• Nomenclatura Independente de Posição: Arquivos de áudio são salvos de forma limpa (ex.: Artista - Título.flac) sem prefixos numéricos fixos. Essa abordagem padrão da indústria garante que, se a ordem da playlist mudar online, seus arquivos locais sejam reconhecidos instantaneamente, evitando downloads duplicados em massa.
• .m3u Inteligente Baseado na API: A ordem de reprodução é garantida por um arquivo .m3u gerado dinamicamente que espelha com perfeição a sequência exata ditada pelos servidores do Qobuz, independentemente dos nomes físicos dos arquivos.
• Gerenciamento Inteligente de Capas: Elimina o bug de “Conflito de Capas”. O mecanismo gerencia dinamicamente as artes incorporadas, garantindo que cada faixa receba sua capa exclusiva correta sem deixar arquivos cover.jpg duplicados na pasta.
• Substituição de Modo de Álbum (--playlist-as-albums): Novo recurso. Se você usa playlists para buscar músicas específicas, essa flag ignora completamente a lógica de Pasta Plana. O mecanismo vai “explodir” a playlist, direcionando cada faixa para sua respectiva pasta de álbum original usando o seu folder_format padrão, mantendo os números de faixa originais e baixando a capa específica de cada álbum.
• Variáveis Poderosas: folder_format e track_format agora suportam dezenas de novas variáveis (ex.: {isrc}, {barcode}, {label}, {track_composer}).
• Tipo de Lançamento ({release_type}): Identifica automaticamente a categoria de publicação a partir das APIs do Qobuz (ex.: Album, EP, Single), permitindo que você encaminhe dinamicamente downloads para subdiretórios ou use como prefixo de nomenclatura sem impor uma estrutura fixa.   * Exemplo de Pasta (Subdiretório): folder_format = {release_type}/{album_artist} - {album_title} ➔ Album/Daft Punk - Discovery   * Exemplo de Pasta (Prefixo): folder_format = {release_type} - {album_artist} - {album_title} ➔ Single - Gorillaz - Silent Running
• Tag Explícita ({explicit} ou {ExplicitFlag}): Adiciona automaticamente uma tag [E] se a faixa ou álbum tiver aviso parental no Qobuz. Se o conteúdo for limpo, a variável permanece vazia sem deixar espaços finais indesejados. Você pode aplicar isso permanentemente adicionando as variáveis ao seu arquivo config.ini, ou temporariamente via CLI usando as flags -ff e -tf.   * Exemplo de Pasta: folder_format = {artist} - {album} {ExplicitFlag} ➔ Eminem - The Eminem Show [E]   * Exemplo de Faixa: track_format = {track_number} - {track_title} {ExplicitFlag} ➔ 02 - Without Me [E].flac
• Tag de Versão do Álbum ({version_tag}): Adiciona automaticamente a versão do álbum (ex.: Live, Remastered, Deluxe Edition) ao nome da pasta ou faixa. Se o lançamento for uma edição padrão, a variável permanece completamente vazia, evitando espaços ou hifens indesejados.   * Exemplo de Pasta (Padrão): folder_format = {album_artist} - {album_title}{version_tag} ➔ The Sunset Violent   * Exemplo de Pasta (Edição Especial): folder_format = {album_artist} - {album_title}{version_tag} ➔ The Sunset Violent - Live in Heidelberg
• Roteamento Multi-Disco: Armazene lançamentos com múltiplos discos em um único diretório ou divida-os usando prefixos personalizáveis (ex.: CD 01).
• Geração Universal de Playlists: Arquivos .m3u são rigorosamente codificados em UTF-8, garantindo 100% de estabilidade mesmo com caracteres Unicode complexos ou japoneses (Resolve a issue #304).
• Substituição de Caracteres Legados (legacy_charmap): Por padrão, a Edição Ultimate usa caracteres Unicode de largura total elegantes (ex.: ／) para contornar com segurança as restrições de nomes de arquivos do SO sem perder a estética do título original. No entanto, puristas podem ativar a opção legacy_charmap = true no seu config.ini para forçar substituições padrão em ASCII (ex.: substituir / por - ou remover ?), restaurando a convenção de nomenclatura clássica do qobuz-dl original.

❤️ Sincronização Nativa de Favoritos e Menu Interativo

Conecte perfeitamente seus hábitos de escuta móvel com sua biblioteca local offline. Em vez de copiar URLs manualmente, inicie o Modo Interativo (fun) para acessar sua conta pessoal do Qobuz com segurança e navegar pelos seus Álbuns, Faixas, Artistas e Playlists Favoritos diretamente do terminal.

• Fluxo de Trabalho Sem Digitação: Acesse sua biblioteca privada com um único clique sem nunca sair do terminal.
• Download em Lote Massivo: Use a Barra de Espaço para selecionar múltiplos lançamentos favoritos a partir da interface limpa e minimalista e enfileirar todos para download em segundos.
• Filtro Inteligente de Lançamentos (Mecanismo Heurístico): Ao buscar a discografia de um artista, o mecanismo executa um algoritmo heurístico local ultrarrápido para categorizar os lançamentos (Álbuns, EPs, Singles, Ao Vivo). Ele apresenta instantaneamente uma interface de caixas de seleção, permitindo filtrar singles ou compilações indesejados antes mesmo do início do download, economizando tempo e armazenamento.

🌉 Integração Inteligente com Last.fm e Modo Interativo

Conecte seu mundo do Last.fm ao Qobuz perfeitamente. Baixe suas playlists personalizadas e “Faixas Favoritas” (Loved Tracks) com facilidade.  Para evitar o download de músicas incorretas, este fork utiliza um Algoritmo Matemático de Correspondência Difusa (Fuzzy Matching):

• Aceitação Automática (> 75%): Correspondências perfeitas são enfileiradas automaticamente.
• Pulo Automático (< 60%): Faixas completamente erradas são ignoradas automaticamente.
• Seleção Interativa (60% - 74%): Para correspondências limítrofes, o mecanismo pausa e ativa um prompt interativo permitindo que você aprove ou rejeite manualmente a faixa ([y/n]).

🛡️ Gerenciamento de Pastas À Prova de Falhas e Retomada Inteligente

Diga adeus a bibliotecas desorganizadas e downloads corrompidos. O baixador agora conta com um sistema dinâmico de 3 estágios de estado de pasta para manter sua biblioteca perfeitamente organizada:

• [IN PROGRESS]: Pastas são marcadas enquanto o download está em andamento.
• [INCOMPLETE]: Se você abortar o processo (tratamento suave de CTRL+C) ou se algumas faixas forem puladas (ex.: bloqueio regional ou indisponibilidade), a pasta é marcada com segurança como incompleta. 
• Estado Limpo (Clean State): Somente quando um álbum for baixado com 100% de sucesso a pasta será renomeada para seu estado final limpo (ex.: Artista - Álbum).

Nota: O mecanismo é inteligente o suficiente para retomar downloads diretamente em pastas [INCOMPLETE] ou [IN PROGRESS] na sua próxima execução!

📥 Instalação e Configuração

⚠️ Requisito: Você precisa de uma assinatura ativa do Qobuz.

Opção A: 📦 Pacote PyPI (Recomendado para todas as plataformas)

A maneira mais fácil e oficial de instalar a Edição Ultimate. Abra seu terminal e execute:

pip install qobuz-dl-ultra

Após a instalação, você pode iniciar o programa de qualquer pasta no seu computador digitando simplesmente qobuz-dl ou qdl.

Opção B: Código-fonte Python (Avançado)

Clone este repositório e instale as dependências necessárias:

git clone https://github.com/kaduvercosa/qobuz-dl-ultra.git
cd qobuz-dl-ultra
pip3 install -r requirements.txt

Execute o programa usando: python -m qobuz_dl

Opção C: 🐳 Uso com Docker (NAS e Servidores Caseiros)

A Edição Ultimate é totalmente conteinerizada e inclui todas as dependências (Python, FFmpeg). Este é o método de instalação recomendado para Synology, QNAP, Unraid e servidores headless.

# Baixar a imagem oficial mais recente
docker pull ghcr.io/kaduvercosa/qobuz-dl-ultra:latest

# Exemplo: Executar um download e mapeá-lo para a pasta de músicas do seu NAS
docker run -it --rm \
  -v /caminho/para/suas/musicas/no/nas:/home/qobuz/QobuzDownloads \
  -v /caminho/para/config:/home/qobuz/.config/qobuz-dl \
  ghcr.io/kaduvercosa/qobuz-dl-ultra:latest dl "https://play.qobuz.com/album/..."

⚙️ Configuração e Caminhos Personalizados

Se você deseja definir uma pasta de download personalizada, pode editar seu arquivo config.ini e usar a chave directory. Caminhos absolutos e o operador ~ (para macOS/Linux) são totalmente suportados!

💡 Dica para usuários que estão atualizando: Para acessar as opções de configuração mais recentes (como embed_lyrics e multi_value_tags), basta executar qobuz-dl -r para redefinir e gerar um novo arquivo config.ini, ou adicioná-las manualmente na seção [qobuz].

[qobuz]
directory = ~/Music/Qobuz_Lossless

# Defina como ‘true’ se estiver executando em um servidor headless (NAS/Docker/WSL) 
# para salvar tokens sem criptografia no config.ini em vez do Keyring do SO.
disable_keyring = false

# Defina como ‘true’ para restaurar substituições clássicas de caracteres ASCII
legacy_charmap = false

# Defina como ‘true’ para desativar a geração de arquivos .lrc externos
no_lrc_files = true

# Defina como ‘true’ para restaurar substituições clássicas de caracteres ASCII (ex.: substituir ‘/‘ por ‘-‘)
legacy_charmap = false

# Defina como ‘true’ para desativar a geração de arquivos .lrc externos (as letras serão incorporadas apenas nas tags FLAC/MP3)
no_lrc_files = true

# Defina como ‘true’ para desativar estritamente tags de volume ReplayGain para reprodução bit-perfect em hardware
no_replaygain_tag = true

# Defina como ‘true’ para desativar a gravação da tag não padrão “QOBUZ ALBUM URL” nos arquivos
no_album_url_tag = true

# Defina como ‘true’ para desativar a extração de metadados de música clássica
no_conductor_tag = true
no_ensemble_tag = true
no_work_tag = true

(Nota: Se você estiver atualizando de uma versão anterior, a chave legada default_folder ainda é totalmente suportada para compatibilidade retroativa.)

🔒 Nota de Segurança: Com o Keyring ativo, auth_token e genius_token são migrados para o gerenciador de credenciais do sistema. Com disable_keyring = true, eles permanecem sem criptografia no config.ini; a permissão 0600 restringe quem pode abrir o arquivo, mas não criptografa seu conteúdo.

🔑 Como obter seu Auth Token

Como o Qobuz bloqueou logins diretos por senha para aplicativos de terceiros, você precisa fornecer o Token de Autenticação do seu navegador durante a configuração inicial. Veja como encontrá-lo facilmente:

1. Abra o Qobuz Web Player no seu navegador e faça login.
2. Pressione F12 para abrir as Ferramentas de Desenvolvedor (Developer Tools).
3. Vá para a aba Application (Chrome/Edge) ou Storage / Armazenamento (Firefox).
4. Na barra lateral esquerda, expanda Local Storage (Armazenamento Local) e clique em https://play.qobuz.com.
5. Na lista de chaves, procure por localuser.
6. Na parte inferior do painel (ou expandindo o valor JSON), localize a string token.
7. Abra o terminal e force o assistente de login executando qobuz-dl -r (ou --reset). Quando o prompt aparecer, selecione o método Auth Token e cole sua sequência alfanumérica!

💻 Uso e Exemplos Rápidos

[Comandos Globais e Gerenciamento de Banco de Dados]
usage: python -m qobuz_dl [-h] [-r] [-p] [--sync-db [PATH]] [-sc] {interactive,i,fun,dl,lucky,lyrics,sync-playlist,sp,stats} ...

[Uso de Download]
usage: python -m qobuz_dl dl [-h] [-d PATH] [-q int] [--albums-only] [--no-m3u] [--no-fallback] [--no-db] 
                             [-ff PATTERN] [-tf PATTERN] [-s] [-e] [--no-cover]
                             [-b PATH]
                             [--embedded-art-size {50,100,150,300,600,max,org}] 
                             [--saved-art-size {50,100,150,300,600,max,org}] 
                             [--multiple-disc-prefix PREFIX] [--multiple-disc-one-dir] 
                             [--no-lyrics] [--no-lrc-files] [--native-lang] [--no-credits] [--with-credits] [--booklet-only] [--delay SECONDS] [--playlist-as-albums]
                             [--no-album-artist-tag] [--no-track-composer-tag] ... 
                             SOURCE [SOURCE ...]

Sincronização Bidirecional de Playlist: (Dica: Adicione -y para ignorar os avisos de confirmação. A flag -d opera com segurança, criando automaticamente uma subpasta para a playlist).

python -m qobuz_dl sp "URL" -d "C:\Caminho\Para\Pasta\Local\Da\Playlist"

                          Download Básico de Álbum/Playlist:

python -m qobuz_dl dl https://play.qobuz.com/album/qxjbxh1dc3xyb

Explodir Playlists em Álbuns: Por padrão, as playlists são baixadas em uma única pasta plana. Use esta flag se você usa playlists como uma “ferramenta de descoberta” e deseja que o mecanismo encaminhe dinamicamente cada faixa para sua respectiva pasta de álbum original, com sua arte de capa específica e metadados originais da faixa.

python -m qobuz_dl dl "URL_DA_PLAYLIST" --playlist-as-albums

Download em Massa / Lote (Retomada Inteligente): Tem uma lista enorme de lançamentos para baixar? Crie um arquivo de texto comum (ex.: list.txt), cole suas URLs do Qobuz e do Last.fm nele (uma por linha) e passe-o para o mecanismo. O analisador inteligente baixará automaticamente seus links do Qobuz e roteará perfeitamente as playlists do Last.fm pelo mecanismo de Fuzzy Matching para processar toda a sua fila de uma só vez! Recurso da Edição Ultimate: O arquivo de texto atua como um banco de dados vivo. Assim que um lançamento ou playlist completa é baixado com sucesso, o mecanismo anexa uma tag [DONE] ao lado da URL no arquivo. Se sua conexão cair ou você interromper o processo (CTRL+C), basta executar exatamente o mesmo comando novamente e o mecanismo pulará instantaneamente os links concluídos, retomando perfeitamente de onde parou.

python -m qobuz_dl dl list.txt

Blacklist de Discografia e Modo Anti-Spam: Está baixando a discografia completa de um artista, mas quer evitar gastar espaço com versões de Karaokê, Tributo ou Instrumentais? Crie um arquivo de texto (ex.: blacklist.txt) contendo as palavras-chave indesejadas (uma por linha) e passe-o para o mecanismo. Ele inspecionará automaticamente cada lançamento e pulará o conteúdo indesejado! (Dica: Você pode definir blacklist = blacklist.txt no seu config.ini para tornar isso automático em cada download).

python -m qobuz_dl dl https://play.qobuz.com/artist/123456 -b blacklist.txt

Modo Anti-Ban Supremo (Camuflagem + Delay): Embora o mecanismo mascare nativamente sua pegada digital (Stealth Spoofing) para simular um navegador Chrome real, baixar 100 faixas em 10 segundos ainda é fisicamente impossível para um ser humano e pode acionar banimentos baseados em volume. Use este comando para grandes discografias para desativar o multithreading e adicionar um intervalo forçado entre as faixas, garantindo a máxima segurança para sua conta.

python -m qobuz_dl dl <URL> --delay 1

Forçar Encartes e Créditos (Substituição de Configuração): Se você definiu no_credits = true no seu config.ini para manter suas pastas limpas, pode substituir temporariamente esse comportamento para forçar a geração do Encarte Digital e do Tracklist.txt para uma obra-prima específica.

python -m qobuz_dl dl <URL> --with-credits

Análise de Múltiplas Tags e Intérpretes: Use a flag --multi-tags para garantir que faixas complexas com múltiplos artistas e compositores sejam divididas em campos limpos e individuais nas tags de áudio.

python -m qobuz_dl dl "URL" --multi-tags

Modo Apenas Metadados e Encarte: Quer completar os metadados da sua biblioteca sem baixar gigabytes de áudio? Este comando busca apenas a arte da capa, gera o encarte com lista de faixas/créditos, baixa os Goodies em PDF oficiais e ignora com segurança todas as faixas de áudio.

python -m qobuz_dl dl https://play.qobuz.com/album/qxjbxh1dc3xyb --booklet-only

Modo de Pasta Minimalista (Sem arquivos .lrc externos): Baixa o álbum e injeta as letras sincronizadas exclusivamente nos metadados do FLAC/MP3, mantendo suas pastas completamente limpas de arquivos de texto externos.

python -m qobuz_dl dl https://play.qobuz.com/album/qxjbxh1dc3xyb --no-lrc-files

Roteamento Avançado de Discografia: Salve múltiplos discos de um lançamento em uma única pasta em vez de dividi-los.

python -m qobuz_dl dl https://play.qobuz.com/artist/2038380 --multiple-disc-one-dir

Modo Interativo Last.fm (Modo Fun): (Dica: No modo interativo, use Espaço para selecionar múltiplos álbuns para baixar de uma vez!)

python -m qobuz_dl fun -l 10

Modo Audiófilo Purista (Sem ReplayGain): Baixe uma faixa mantendo o arquivo estritamente bit-perfect, sem gravar quaisquer tags de nivelamento de volume (útil para DSPs e DAPs de hardware).

python -m qobuz_dl dl "URL" --no-replaygain-tag

🗄️ Gerenciamento de Banco de Dados e Biblioteca

A Edição Ultra inclui poderosos gerenciadores de biblioteca local para acompanhar seus downloads, evitar duplicatas e corrigir seus metadados retroativamente.

• Sincronização Inteligente de Biblioteca (--sync-db):   Já possui uma biblioteca local de FLACs baixados? Não precisa começar do zero. Execute este comando para realizar uma Busca Reversa no seu diretório de downloads. O mecanismo escaneará seus arquivos existentes e os injetará automaticamente no banco de dados local para evitar downloads duplicados no futuro.   bash   python -m qobuz_dl --sync-db      (Nota: Você também pode especificar um caminho personalizado para escanear, ex.: --sync-db "/caminho/para/suas/musicas")

• Sincronização Dinâmica de Playlists (sync-playlist / sp):   Playlists são entidades vivas. Em vez de baixar novamente uma playlist inteira toda vez que o autor adiciona uma nova música, aponte este comando para a sua pasta existente. Ele escaneará as tags locais, consultará a API do Qobuz e calculará o delta exato: baixando apenas as faixas ausentes, excluindo de forma limpa as removidas (junto com seus respectivos arquivos .lrc) e regenerando a ordem no .m3u.   bash   python -m qobuz_dl sp "URL_DA_PLAYLIST" -d "/caminho/para/sua/pasta/local"   

• Tagger Retroativo de Letras (lyrics):   Tem uma biblioteca de músicas local existente que não possui letras sincronizadas? O novo comando lyrics funciona como um mecanismo autônomo de metadados. Ele varre recursivamente qualquer diretório local, detecta arquivos FLAC/MP3 sem letras e as injeta de forma inteligente nos arquivos de áudio usando letras nativas do Qobuz (e quando disponível também injeta a tradução) tendo como Fallback o LRCLIB e a API do Genius sem baixar novamente nenhuma música. Atualmente o comando lê a pasta raiz configurada no ’config.ini’   bash   python -m qobuz_dl lyrics “/caminho/para/sua/pasta/local/de/musica”   

• Limpar Banco de Dados (-p, --purge):   Se você precisar recomeçar do zero, limpar seu histórico de downloads ou corrigir um estado corrompido, pode apagar instantaneamente o banco de dados local com um único comando.   bash   python -m qobuz_dl --purge   

• Estatísticas do Usuário (stats):   Curioso sobre seus hábitos de download? Este comando consulta instantaneamente seu banco de dados SQLite local para exibir estatísticas dos seus downloads, incluindo o número total de artistas únicos baixados e uma lista alfabética completa da sua biblioteca.   bash   python -m qobuz_dl stats   

🗂️ Catálogo Local, Scan e Sync de Favoritos (novo na 2.6)

Inspirado no libsync, agora existe um catálogo local (library.db, ao lado do config.ini) que responde: "o que eu tenho na conta vs. o que eu tenho no disco?".

qobuz-dl sync-favorites                  # mostra o diff (novos/removidos) e atualiza o catálogo
qobuz-dl sync-favorites --download-new   # baixa o que foi favoritado desde a última vez
qobuz-dl sync-favorites --download-missing --limit 20 -y
qobuz-dl sync-favorites --download-new --every 60   # modo contínuo (NAS/servidor)
qobuz-dl sync-favorites --dry-run        # só simula

qobuz-dl scan "/musica"                  # casa pastas do disco com o catálogo (offline)
qobuz-dl scan --dry-run --json rel.json  # classifica sem gravar e salva o relatório

qobuz-dl library                         # status do catálogo
qobuz-dl library missing                 # favoritos ainda não baixados
qobuz-dl library history                 # últimas sincronizações
qobuz-dl library reconcile [DIR] [--fix] # sentinelas do disco ⇄ catálogo
qobuz-dl library reset-stuck             # destrava álbuns presos após um CTRL+C
qobuz-dl library unmark <ID>             # desmarca um álbum (e remove a sentinela)

qobuz-dl doctor [--json]                 # diagnóstico: ambiente, config, keyring, bancos

Primeira vez com uma biblioteca grande: rode sync-favorites (sem download) e depois scan, para marcar o que você já tem antes de usar --download-missing.

Como o scan decide. Ordem: tag QOBUZALBUMID → UPC (BARCODE) → nome exato normalizado → fuzzy. Só marca sozinho quando o match é único e a profundidade de bits e o número de faixas batem; qualquer dúvida (2 candidatos, faixas faltando, pasta [INCOMPLETE], fuzzy) vai para revisão manual. Álbuns multi-disco (CD 01, CD 02) contam como um só. Pastas com tag de ID que não estão nos favoritos são adotadas (--no-adopt desativa).

Sentinela. Cada álbum baixado recebe um .streamrip.json (mesmo formato do libsync) com serviço, ID e faixas. Serve para reconstruir o estado após perder o banco e detectar pastas movidas. Desative com --no-sentinel ou write_sentinel = false no config.ini (útil em montagens somente-leitura).

🛠️ Principais Variáveis de Formatação

Você pode personalizar profundamente seu config.ini ou usar as flags CLI -ff (Formato de Pasta) e -tf (Formato de Faixa) usando as variáveis abaixo. Você também pode usar o caractere / para criar subdiretórios aninhados automaticamente!

📝 Tabela de Referência de Variáveis Completas

💡 Exemplos Práticos

1. A Estratégia “Arquivo Audiófilo” (Pastas Aninhadas) Organiza por Gênero, depois Artista, depois Álbum com especificações técnicas completas:

• folder_format = {album_genre}/{album_artist}/{album_artist} - {album_title}{version_tag} ({year}) [{bit_depth}B-{sampling_rate}kHz]
• Saída: Electronic/Daft Punk/Daft Punk - Random Access Memories - Deluxe (2013) [24B-88.2kHz]

2. A Estratégia “Biblioteca Limpa” (Tags Inteligentes de Versão e Conteúdo Explícito) Mantém simples, mas adiciona [E] somente se explícito e versões sem deixar hifens vazios:

• folder_format = {album_artist} - {album_title_base}{version_tag} {ExplicitFlag}
• Saída: Eminem - The Eminem Show [E]

3. A Estratégia de Faixa “Arquivista”

• track_format = {track_number} - {track_title} [{isrc}]
• Saída: 08 - Get Lucky [USSM11302305].flac

🔧 Solução de Problemas: Ambientes Headless e Servidores

Se você estiver executando o qobuz-dl em um NAS, Docker ou em um sistema Linux headless (como WSL sem daemon de chaveiro de interface gráfica), você poderá encontrar erros 401 Unauthorized após redefinir a configuração.

A Solução: Ao executar python -m qobuz_dl -r, o assistente de configuração agora perguntará:  ”Disable OS Keyring and save tokens in config.ini?” (Desativar Keyring do SO e salvar tokens no config.ini?) Selecione yes se estiver em um ambiente de servidor ou NAS. Isso ignora o chaveiro do sistema e persiste tokens sem criptografia no config.ini. A permissão 0600 restringe o acesso ao usuário atual, mas não criptografa o conteúdo; proteja e nunca compartilhe esse arquivo.

🩺 Verificação manual de integridade de áudio

A verificação de integridade por decodificação real pode ser ativada em cada download com --verify-download (ou verify_after_download = true no config.ini). O utilitário manual não é instalado pelo pacote nem incluído na imagem Docker; a partir de um checkout do código-fonte, rode:

python check_audio.py

É interativo: pergunta a pasta de música (sugerindo a do config.ini ou o diretório atual), varre as subpastas em busca de arquivos de áudio, e mostra um menu pra você escolher qual inspecionar. Reusa a mesma lógica de qobuz_dl/utils.py usada pelo downloader via FFmpeg.

🏆 Créditos

• vitiko98: Criador do projeto original.
• xwell: Pela grande reformulação do mecanismo de tags e integração com os “Goodies”.
• catap: Pelo patch de download segmentado.
• JosiahDanger: Relatórios de bugs e sugestões de recursos.
• Sorrow446 e DashLt: O qobuz-dl é inspirado no projeto descontinuado Qo-DL-Reborn. Esta ferramenta utiliza o módulo principal de API qopy, originalmente escrito por eles.

⚠️ Isenção de Responsabilidade (Aviso Legal)

• Esta ferramenta foi desenvolvida para fins educacionais.
• O qobuz-dl não é afiliado ao Qobuz.

🖥️ Qobuz-DL Studio — interface web local

O Qobuz-DL Ultra inclui uma interface visual local inspirada em interfaces de áudio industrial monocromáticas: matriz de glifos, alto contraste e vermelho pontual. Ela cobre navegação e busca, reprodução direta compatível, downloads, favoritos, biblioteca, e também sincronização, scan, diagnóstico, estatísticas, playlists, letras, inspeção e manutenção do catálogo pela seção Ferramentas. A configuração de conta pode ser feita em Preferências; e-mail/token são validados antes de serem salvos localmente e não são enviados a nenhum serviço intermediário.

Instalação e inicialização

Instale o extra da interface e inicie o servidor local:

python -m pip install -e '.[gui]'
qobuz-dl-studio

O navegador abre em http://127.0.0.1:8787. Por padrão, o servidor escuta somente no loopback, não na rede local. Na primeira utilização, abra Preferências → Conectar ou configurar conta e informe e-mail e token Qobuz. O token é validado antes de ser armazenado no cofre do sistema (recomendado) ou, por escolha explícita, no config.ini com permissões restritas. Pasta, qualidade, letras, capas, tags, paralelismo, padrões de nomes e outras opções ficam em gui.json, sem sobrescrever o restante do config.ini.

Operações em Ferramentas usam a mesma CLI interna com argumentos validados, sem shell arbitrário; saídas e processos ficam na página e tarefas longas (como monitoramento) podem ser paradas pelo próprio painel. Downloads e alterações de arquivos começam bloqueados até a confirmação explícita no controle correspondente. A simulação vem ligada onde o comando a suporta.

Para explorar a aparência sem conectar uma conta (busca demonstrativa; não toca nem baixa conteúdo):

qobuz-dl-studio --demo

Notas

• Downloads passam pelo QobuzDL.download_from_id existente e são bloqueados até conectar a conta local.
• O player do navegador solicita URLs de reprodução somente ao cliente Qobuz existente, que valida a disponibilidade/assinatura. Ele tenta reproduzir formatos diretos MP3/FLAC; áudio Hi-Res segmentado que exija decodificação proprietária não é reproduzido pela GUI. Nesse caso, use a fila de download no formato escolhido.
• As preferências escolhidas na GUI são salvas em gui.json no diretório de configuração do aplicativo, com permissões restritas quando suportadas pelo sistema.
• A interface lê até 500 arquivos locais compatíveis com Mutagen. Escolher uma pasta pelo navegador do sistema não é possível por uma limitação de segurança do browser; informe o caminho local em Preferências.
• Não exponha a porta para a internet nem execute a interface em computador compartilhado. Os downloads seguem os termos da conta/serviço Qobuz.