Cliente TUI minimalista e rápido para YouTube Music, direto no terminal: busca, reprodução (mpv), download de músicas e álbuns (yt-dlp + ffmpeg) e biblioteca local — sem precisar de conta do Google.

⚠️ Aviso de honestidade: este projeto é ~80% "vibe-coded"

A maior parte deste código foi escrita em vibe coding — conversando com um assistente de IA, com revisão, ajustes e testes manuais do autor no meio do caminho. São 542 testes automatizados e uso real no dia a dia, então funciona de verdade — mas espere arestas: bugs ocasionais, código "com cara de IA" aqui e ali e funcionalidades faltando (veja Limitações). Achou um bug? Abra uma issue. PRs são muito bem-vindos! 💜

• 🎵 Reprodução de música via mpv (streaming direto, qualidade selecionável)
• 🔍 Busca de músicas (25) e álbuns (15) em paralelo, com tipo e ano nos álbuns (💿 My Dear Melancholy, — The Weeknd (EP, 2018))
• 💿 Aba de álbum: abra um álbum da busca e veja faixas, artista e ano — Enter toca (com fila contínua) e A baixa o álbum inteiro, pulando faixas já baixadas
• 📥 Download via yt-dlp + ffmpeg: melhor stream disponível → MP3 320 kbps (ou opus/m4a/flac), com tags ID3 e capa embutida
• 📚 Biblioteca local em SQLite (nada de nuvem): faixas baixadas, curtidas locais e reprodução do arquivo local
• 📊 Aba de Downloads com progresso em tempo real e downloads simultâneos configuráveis
• 🚫 Sem login: busca, reprodução e download operam anonimamente
• ⌨️ Interface Textual responsiva, com mouse (abas, listas, botões) e atalhos estilo vim
• ⚡ Leve: sem Electron, sem navegador — só Python + mpv

 ⭘                                      YouTube Music TUI                                  04:43:20
  🏠 Início    🔍 Busca    📚 Biblioteca    📥 Downloads    ⚙️ Config
━━━━━━━━━━━━━━╸━━━━━━━━╺━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
 │  my dear melancholy                                                                            │
 └────────────────────────────────────────────────────────────────────────────────────────────────┘

 ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
 │                                                                                                │
 │  🎵 Músicas                                                                                    │
 │ ┌────────────────────────────────────────────────────────────────────────────────────────────┐ │
 │ │ I Was Never There — The Weeknd, Gesaffelstein  (4:02)                                      │ │
 │ │ Try Me — The Weeknd  (3:42)                                                                │ │
 │ │ my dear melancholy — msht  (2:16)                                                          │ │
 │ │ Wasted Times — The Weeknd  (3:41)                                                        ▆▆│ │
 │ │ Hurt You — The Weeknd, Gesaffelstein  (3:51)                                               │ │
 │ │ TMJ (Acoustic Version) — MOHXSIN  (2:22)                                                   │ │
 │ │ Privilege — The Weeknd  (2:51)                                                             │ │
 │ │ my dear melancholy (slowed) — msht  (2:33)                                                 │ │
 │ │ Rockstar without guitar (Remix) — MOHXSIN  (3:10)                                          │ │
 │ └────────────────────────────────────────────────────────────────────────────────────────────┘ │
 │  💿 Álbuns                                                                                     │
 │ ┌────────────────────────────────────────────────────────────────────────────────────────────┐ │
 │ │ 💿 My Dear Melancholy, — The Weeknd  (EP, 2018)                                            │ │
 │ │ 💿 my dear melancholy — msht  (EP, 2026)                                                   │ │
 │ └────────────────────────────────────────────────────────────────────────────────────────────┘ │
 │                                                                                                │
 └────────────────────────────────────────────────────────────────────────────────────────────────┘

────────────────────────────────────────────────────────────────────────────────────────────────────
                                             ┌───┐ ┌───┐ ┌───┐            0:00   ━━━━━━━━━━━━━━━━━
                                             │ ⏮ │ │ ⏯ │ │ ⏭ │
                                             └───┘ └───┘ └───┘

 ⭘                                      YouTube Music TUI                                  04:43:21
  🏠 Início    🔍 Busca    💿 My Dear Melancholy    📚 Biblioteca    📥 Downloads    ⚙️ Config
━━━━━━━━━━━━━━━━━━━━━━━━━━╸━━━━━━━━━━━━━━━━━━━━━╺━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 💿 My Dear Melancholy, — The Weeknd · 2018 · 6 faixas

 ┌────────────────────────────┐
 │ ⬇ Baixar álbum inteiro (a) │
 └────────────────────────────┘

 ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
 │ Call Out My Name — The Weeknd  (3:49)                                                          │
 │ Try Me — The Weeknd  (3:42)                                                                    │
 │ Wasted Times — The Weeknd  (3:41)                                                              │
 │ I Was Never There — The Weeknd, Gesaffelstein  (4:02)                                          │
 │ Hurt You — The Weeknd, Gesaffelstein  (3:51)                                                   │
 │ Privilege — The Weeknd  (2:51)                                                                 │
 │                                                                                                │
 │                                                                                                │
 │                                                                                                │
 │                                                                                                │
 │                                                                                                │
 │                                                                                                │
 │                                                                                                │
 │                                                                                                │
 │                                                                                                │
 │                                                                                                │
 │                                                                                                │
 └────────────────────────────────────────────────────────────────────────────────────────────────┘

────────────────────────────────────────────────────────────────────────────────────────────────────
                                             ┌───┐ ┌───┐ ┌───┐            0:00   ━━━━━━━━━━╺━━━━━━
                                             │ ⏮ │ │ ⏯ │ │ ⏭ │
                                             └───┘ └───┘ └───┘

(Capturas do app real, com dados ao vivo da API; as cores variam conforme o tema do seu terminal.)

• Python 3.11+
• mpv (com libmpv) — é o player. Na maioria das distros o pacote mpv já inclui a libmpv (se o app não abrir, veja Problemas comuns na instalação)
• ffmpeg — conversão e marcação dos downloads
• Dependências Python (ytmusicapi, textual, yt-dlp, sqlalchemy…) são instaladas via pip/pipx junto com o app
• Terminal com cores (256/true color) e Unicode — mínimo 80×24, recomendado 100×30+

Combinações validadas (o conjunto exato de dependências Python usado no CI está no uv.lock; os pisos, no pyproject.toml):

O yt-dlp muda com frequência (o YouTube muda as regras do jogo): mantenha-o atualizado — o Dependabot já abre PR semanal e uma atualização que quebre a reprodução aparece no CI antes do merge.

# Ubuntu / Debian / Linux Mint / LMDE
sudo apt install mpv ffmpeg python3-venv

# Arch / Manjaro / EndeavourOS
sudo pacman -S mpv ffmpeg python

# Fedora
sudo dnf install mpv ffmpeg python3

# openSUSE
sudo zypper install mpv ffmpeg python3

# macOS (Homebrew)
brew install mpv ffmpeg python

Opção A — pipx (recomendada, ambiente isolado):

pipx install git+https://github.com/pr0sthetics/ytmusic-tui

Opção B — pip:

pip install --user git+https://github.com/pr0sthetics/ytmusic-tui

Opção C — do código-fonte (para desenvolver):

git clone https://github.com/pr0sthetics/ytmusic-tui
cd ytmusic-tui
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/ytmusic-tui    # ou: .venv/bin/python main.py

O app funciona sem nenhuma configuração. Se quiser ajustar player, downloads e interface:

mkdir -p ~/.config/ytmusic-tui
cp config.example.toml ~/.config/ytmusic-tui/config.toml

• Cannot find libmpv in the usual places (ou mensagem parecida do python-mpv) ao abrir o app: o Python não encontrou a libmpv. No Ubuntu/Debian instale também sudo apt install libmpv-dev — ele fornece o link libmpv.so que o Python procura (no Ubuntu 24.04, por exemplo, o pacote mpv sozinho nem sempre basta).
• A música não toca / o stream falha: quase sempre é o yt-dlp desatualizado em relação a alguma mudança do YouTube — atualize o app e o yt-dlp no mesmo ambiente de instalação (pip install -U yt-dlp no venv, ou pipx upgrade + pipx runpip ytmusic-tui install -U yt-dlp).

ytmusic-tui              # instalado via pip/pipx
python -m ytmusic_tui    # como módulo
python main.py           # direto do código-fonte (usa src/, sem instalar o pacote)

1. Ctrl+S para ir à busca → digite e Enter
2. Enter numa música toca; → / ← navegam pela fila
3. Enter num álbum abre a aba 💿 com as faixas; A (ou o botão) baixa o álbum inteiro
4. Ctrl+D baixa a música em reprodução — acompanhe na aba 📥 Downloads
5. Ctrl+L abre a biblioteca local: toque direto dos arquivos baixados

O mouse também funciona: clique nas abas, nos resultados e nos botões.

Arquivo: ~/.config/ytmusic-tui/config.toml (todas as chaves são opcionais). A aba Config do app edita as principais opções e grava nesse mesmo arquivo na hora.

Variáveis de ambiente com prefixo YTMUSIC_ têm prioridade sobre o TOML (útil para testar isolado):

YTMUSIC_DOWNLOAD_DIR=/tmp/teste YTMUSIC_DATA_DIR=/tmp/teste ytmusic-tui

(Em macOS/Windows são usados os caminhos equivalentes do platformdirs.)

Erros internos (por exemplo, falha ao acessar o banco da biblioteca) aparecem na própria interface e no log do app — veja as duas seções abaixo antes de abrir uma issue.

O log é JSON Lines: cada linha é um objeto JSON com campos fixos (ts, level, component, operation_id, event, error_code, message e, em erros, detail com o traceback). Eventos importantes — subida/parada do app (com as versões), download iniciado/concluído/falhou, retentativas da API, migrações do banco, erros de banco, quarentena e recuperação — têm event e error_code próprios, o que deixa o diagnóstico greppável:

jq -c 'select(.event != null)' ~/.local/state/ytmusic-tui/log/ytmusic-tui.log | tail

A privacidade é aplicada pelo próprio app ao gravar: o HOME vira ~, URLs perdem query/token e cabeçalhos de credencial viram [REDACTED] — nada disso fica cru no arquivo. O log é 0600, com rotação de 1 MB × 3 backups (máximo de 4 MB no total).

O comando ytmusic-tui doctor (ou python -m ytmusic_tui doctor) diagnostica o ambiente sem abrir a interface — as verificações não criam, alteram nem baixam arquivos: versões (app, Python, ytmusicapi, yt-dlp), libmpv e binários mpv/ffmpeg, diretórios (existência, escrita, modo), banco da biblioteca em somente leitura (integrity_check + versão do esquema × app) e resíduos de manutenção (quarentena, backups, log).

ytmusic-tui doctor

A saída é mascarada (mesmas regras do log) e feita para colar numa issue — ainda assim, revise antes de compartilhar. Exit code 0 = nada essencial quebrado; 1 = algo essencial (libmpv ou dependência ausente, diretório sem escrita, banco ilegível/corrompido ou mais novo que o app).

• ytmusicapi (não oficial) em modo anônimo para busca e metadados — a busca dispara pedidos em paralelo e leva ~2s
• mpv (via libmpv/python-mpv) toca os streams; o mpv usa o yt-dlp instalado junto com o app como extrator (ytdl_hook-ytdl_path), então a reprodução acompanha o yt-dlp atualizado em vez do extrator embutido e velho do mpv
• yt-dlp + ffmpeg baixam o melhor stream de áudio e convertem para o formato configurado, com capa e tags
• SQLAlchemy + SQLite guardam a biblioteca local (faixas baixadas, curtidas)

Por que sem login? O Google desativou a autenticação OAuth do ytmusicapi em 2025 — os tokens passaram a ser rejeitados com HTTP 400 ( Read the rest on GitHub