🎵 CLI YT

O player de música do YouTube que roda no seu terminal, feito com Textual.

Busque uma música, dê Enter e a faixa toca na hora — com fila de relacionadas montada sozinha.

📸 Preview

Captura real do app em execução: busca, fila da Mix e player no rodapé.

✨ Recursos

• 🎯 Busca só de música — tudo é filtrado pela categoria Música do YouTube (categoryId=10), sem vídeos aleatórios no meio.
• 🎧 Mix automática — ao escolher uma faixa de uma busca, o app monta sozinho uma fila com músicas relacionadas e continua tocando sem parar. Ao escolher uma faixa de uma playlist ou das Curtidas, ele toca a própria lista na ordem original, a partir da faixa escolhida.
• ❤️ Curtidas — carrega os vídeos que você curtiu, em ordem, com paginação.
• 📂 Playlists — painel lateral com Curtidas primeiro e as playlists da sua conta.
• 🔐 Login com OAuth — o token fica salvo só na sua máquina (~/.config/meu-player-tui/token.json).
• 🛟 Fallback automático — quando a API do YouTube fica sem cota, a busca e a Mix caem para o yt-dlp sozinhas, e o app avisa que os resultados vieram do fallback.
• ➕ Carregar mais — cada página traz 15 resultados, com busca paginada.
• ⌨️ Player completo — play/pause, volume, próxima/anterior, avançar e voltar 10s, tudo por teclado.

☕ Apoie o projeto

Se o CLI YT te economiza uma aba de browser, um café ajuda a manter ele vivo.

🚀 Executar

Via Node (recomendado) — o launcher cria um ambiente Python isolado e instala as dependências sozinho:

npx git-cli-yt

Diretamente com Python:

git clone https://github.com/bruno2711/CLI-YT.git
cd CLI-YT
python -m pip install -r requirements.txt
python main.py

Requisitos: Python 3.9 ou superior. O Node.js só é necessário para o launcher npx / node bin/cli.js.

🔑 Configuração

O login (usado para abrir as Curtidas) funciona out of the box: o app já vem com um cliente OAuth do tipo Desktop embutido, com o escopo mínimo youtube.readonly. Instale e clique em 🔑 Fazer Login com Google — não é preciso criar nada no Google Cloud Console, nem preencher .env, nem configurar credenciais na mão.

Por que o app pode distribuir um client OAuth: o client_secret de um cliente do tipo Desktop/Installed não é segredo por definição — é o Google que define que ele identifica o aplicativo, não o usuário, e por isso pode vir junto com o app. O que de fato nunca sai da sua máquina é o seu token de acesso/refresh, gravado em ~/.config/meu-player-tui/token.json com permissão 600.

Se você quiser usar o seu próprio app OAuth (outra conta, escopos diferentes, cliente ainda não verificado), a tela de Login tem ⚙️ Usar Credenciais OAuth Próprias (opcional). As fontes são consultadas nesta ordem de prioridade:

1. Pela interface — seção 🔑 Login → ⚙️ Usar Credenciais OAuth Próprias (opcional). Cole o Client ID e o Client Secret e salve. O app grava em ~/.config/meu-player-tui/client_secret.json.

2. Pelo .env — crie um .env na pasta do projeto:

   YOUTUBE_CLIENT_ID=seu_client_id
   YOUTUBE_CLIENT_SECRET=seu_client_secret
   YOUTUBE_API_KEY=sua_api_key_opcional

3. Pelo client_secret.json — o arquivo baixado do Google Cloud Console, na raiz do projeto.

4. Padrão — o cliente embutido no pacote (youtube/oauth_client.py).

| Fonte | Obrigatória | Para quê | | --- | --- | --- | | cliente embutido | — | Login já funciona sem configurar nada | | YOUTUBE_CLIENT_ID | não | Sobrescreve o cliente embutido | | YOUTUBE_CLIENT_SECRET | não | Idem | | YOUTUBE_API_KEY | não | Habilita a busca pública mesmo sem login |

Também valem os prefixos GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET e GOOGLE_API_KEY. O OAuth é obrigatório só para abrir as Curtidas; sem ele, a busca segue funcionando com a API key ou, na falta dela, com o yt-dlp.

🎹 Controles

| Tecla | Ação | | --- | --- | | Enter | Envia a busca (com o cursor na busca) ou toca a faixa (com o cursor na lista) | | ↓ / ↑ | Navega a lista de resultados | | Esc | Devolve o cursor para a busca | | Espaço | Tocar / pausar | | N / P | Próxima / anterior | | F / B | Avançar / retroceder 10s | | Ctrl+↑ / Ctrl+↓ | Volume | | ? | Abre e fecha a ajuda de atalhos | | Ctrl+Q / Ctrl+C | Sair |

As letras acima valem quando o foco não está no campo de busca — é por isso que o Enter da busca devolve o cursor para a lista e o Esc traz de volta.

🧱 Como funciona

| Camada | Papel | | --- | --- | | app.py | Interface Textual, navegação e player | | youtube/search.py | Busca paginada (YouTube Data API v3 com fallback yt-dlp) | | youtube/liked.py | Vídeos curtidos via API | | youtube/playlist.py | Playlists da conta e faixas de uma playlist | | mix/mix_service.py | Monta a fila de relacionadas | | audio/audio_player.py | Reprodução, volume e seek |

🔒 Privacidade

O app não tem servidor: as buscas vão direto do seu terminal para o YouTube e o token OAuth fica só no seu disco. Detalhes em PRIVACY_POLICY.md.

📄 Licença

MIT © Bruno Soares