---

Sumário

• O que é
• Recursos
• Capturas de tela
• Como funciona
• Instalação
• Levar sua biblioteca para outra instância (backup)
• Atalhos de teclado
• Configuração
• API
• Estrutura do projeto
• Solução de problemas
• Roadmap
• Aviso legal
• Licença

O que é

O Musike nasceu da ideia dos antigos bots de música do Discord: um servidor que busca o áudio direto do YouTube e o entrega pronto para tocar. Em vez de um chat, a interface é um player completo, rápido e simples, com cara de app moderno e um toque gamer.

• Sem anúncios e sem conta: o servidor obtém o stream original com o yt-dlp e repassa os bytes ao player.
• Música ou clipe: troque entre Áudio e Vídeo a qualquer momento, do mesmo ponto da faixa. Para músicas, o Musike encontra o clipe oficial do artista.
• Em qualquer tela: layout pensado para celulares de todos os tamanhos, tablets, notebooks e monitores grandes.
• Seu, de verdade: roda no seu computador. Playlists e favoritas ficam num arquivo local que você pode exportar e levar para qualquer outra instância.

Recursos

Ouvir

• Busca no YouTube Music com abas Músicas e Vídeos e sugestões enquanto você digita
• Cole um link do YouTube na busca para tocar direto
• Explorar por gênero: o filtro Gêneros na busca abre os gêneros do YouTube Music (Rock, Sertanejo, MPB, Metal...). Cada um mostra as bandas e artistas do gênero (toque em um para ver os maiores sucessos) ou todas as músicas numa lista só, com seleção para tocar, favoritar ou mandar para uma playlist
• Buscar lista: escreva várias músicas separadas por vírgula ("Evidências, Trem-Bala, ..."); o Musike busca cada uma, já seleciona o melhor resultado (dá para trocar) e você toca, favorita ou manda as selecionadas para uma playlist nova ou existente
• Fila com tocar a seguir, aleatório e repetir (fila ou faixa)
• Rádio automático: quando a fila acaba, continua com músicas parecidas
• Avanço e retrocesso instantâneos (streaming com HTTP Range) e próxima faixa pré-carregada

Vídeo

• Modo Vídeo no painel lateral, na tela cheia do celular ou num mini player flutuante
• Clipe oficial encontrado automaticamente para faixas da aba Músicas (só aceita o canal do próprio artista)
• Modo cinema: maximize o clipe (botão, duplo clique ou tecla F), com controles que somem enquanto você assiste e tela cheia de verdade
• Qualidade SD (começa rápido) ou HD 720p (com cache local)

Biblioteca

• Playlists, Favoritas e histórico de tocadas recentemente
• Backup em arquivo para levar tudo a outra instância: juntar ou substituir, com prévia antes de importar

Interface

• Em inglês por padrão, com troca de idioma em Ajustes > Language (English e Português do Brasil). A escolha vale por aparelho e traduz também as mensagens do servidor e os nomes de gêneros e biografias que vêm do YouTube Music
• Tema escuro e claro, layout responsivo do celular de 320 px ao monitor ultrawide
• Controles na tela de bloqueio, fones e teclas de mídia (Media Session)
• Retoma a fila e a posição de onde você parou
• Instalável como app no celular (PWA) e atalhos de teclado no computador

App desktop (Windows)

• Janela nativa com barra de título própria, sem navegador
• Instalador que cria o atalho na área de trabalho
• Baixa e mantém sozinho as ferramentas de que precisa (yt-dlp, Deno, FFmpeg)

Manutenção

• Tela Ajustes mostra a versão do yt-dlp, avisa quando há atualização e atualiza com um clique (canal Estável ou Nightly)
• Erros de reprodução oferecem o botão "Atualizar" direto no aviso

Capturas de tela

Como funciona

flowchart LR
  subgraph Clientes
    W["Web / PWA<br/>React + Vite"]
    D["App desktop<br/>Electron"]
  end
  subgraph S["Servidor Musike (Fastify)"]
    API["API REST"]
    P["Proxy de stream<br/>HTTP Range"]
    L[("library.json")]
  end
  YTM["YouTube Music<br/>youtubei.js"]
  T["yt-dlp + Deno + FFmpeg"]
  YT[("YouTube / googlevideo")]

  W --> API
  D -- "servidor embutido" --> API
  API -- "busca, sugestões, rádio, clipes" --> YTM
  API -- "resolve streams, junta HD" --> T
  T --> YT
  P --> YT
  API --> L

1. Busca: o servidor consulta o YouTube Music com o youtubei.js (busca, sugestões, rádio e escolha do clipe oficial).
2. Reprodução: o yt-dlp resolve as URLs do stream (áudio AAC, vídeo MP4). Essas URLs ficam presas ao IP de quem as resolveu, então o servidor faz o proxy dos bytes, repassando o cabeçalho Range para que o avanço seja instantâneo.
3. Vídeo HD e clipes sem versão SD: o yt-dlp baixa e junta vídeo + áudio com FFmpeg, guarda em cache (LRU, 2 GB por padrão) e o servidor entrega o arquivo com suporte a Range.
4. Biblioteca: playlists, favoritas e histórico ficam em library.json, gravado de forma atômica.
5. Web: um único elemento <video> é movido no DOM entre painel, tela cheia, mini player e modo cinema sem interromper a reprodução.

Instalação

Opção 1: app de computador (Windows)

Gere o instalador (ou baixe-o na página de Releases, se publicado):

pnpm install
pnpm installer   # cria desktop\release\Musike-Setup-<versão>.exe

O instalador:

• instala só para o usuário atual (não pede administrador) e deixa escolher a pasta;
• cria o atalho Musike na área de trabalho e no Menu Iniciar e abre o app ao terminar;
• desinstala pelo Windows em Configurações > Aplicativos.

Na primeira abertura, uma tela mostra o download das ferramentas oficiais: yt-dlp e Deno (cerca de 60 MB) e, em segundo plano, FFmpeg (cerca de 80 MB, para vídeo HD). Tudo fica em %APPDATA%\Musike:

Atualizar é só instalar a versão nova por cima. A pasta %APPDATA%\Musike fica fora da pasta do programa e nem a atualização nem a desinstalação a apagam. Por segurança, antes de trocar a versão o instalador ainda copia a biblioteca para backups\library-before-install-<versão>.json, e o app guarda outra cópia datada na primeira abertura de cada versão (mantém as 5 mais recentes). Para restaurar uma delas, feche o Musike e copie o arquivo por cima de data\library.json.

O instalador não é assinado digitalmente. Na primeira execução o Windows mostra "O Windows protegeu o computador": clique em Mais informações e depois Executar assim mesmo.

Opção 2: servidor + navegador (computador e celular)

Requisitos:

pnpm install
pnpm build   # compila a interface
pnpm start   # http://localhost:4180

O servidor mostra os endereços de rede ao iniciar. Abra o endereço Rede: no celular conectado ao mesmo Wi-Fi (permita o Node no firewall em redes privadas). O servidor encontra o yt-dlp mesmo em terminais abertos antes da instalação, lendo o PATH do registro do Windows.

Fora de casa: instale o Tailscale no computador e no celular. Para instalar como app (PWA) no celular, o navegador exige HTTPS: rode tailscale serve --bg 4180 e use o endereço https://...ts.net.

Não hospede em VPS ou nuvem: o YouTube bloqueia IPs de datacenter ("Sign in to confirm you're not a bot"). Rodar no seu computador usa seu IP residencial.

Desenvolvimento

pnpm dev        # servidor (4180) + Vite com recarga automática (5173)
pnpm desktop    # abre o app Electron em modo de desenvolvimento
pnpm typecheck  # checa os três pacotes

Levar sua biblioteca para outra instância (backup)

Enquanto a sincronização em nuvem não existe, o Musike exporta tudo num arquivo que qualquer instância lê: web, desktop, outro computador.

1. Na instância de origem, abra Ajustes > Seus dados > Exportar (ou o ícone de banco de dados na Biblioteca). Um arquivo musike-backup-AAAA-MM-DD.musike.json é salvo.
2. Na instância de destino, Ajustes > Seus dados > Importar e escolha o arquivo.
3. Confira a prévia (quantas playlists, faixas, favoritas) e escolha:
   • Juntar com a minha biblioteca (padrão): adiciona o que falta e nunca apaga. Playlists com o mesmo nome ganham as faixas novas; importar duas vezes não duplica nada.
   • Substituir tudo: deixa a biblioteca exatamente como no backup (pede confirmação).
4. Opcionalmente, aplica também o tema e as preferências do player.

O arquivo é JSON legível e versionado:

{
  "format": "musike-backup",
  "version": 1,
  "exportedAt": "2026-10-12T22:33:00.000Z",
  "app": "Musike 0.1.0",
  "library": {
    "favorites": [{ "id": "UpvruBhcH38", "title": "Oceano", "artist": "Djavan", "duration": 297, "thumb": "https://...", "art": "https://...", "kind": "song" }],
    "playlists": [{ "id": "…", "name": "Foco", "createdAt": 1791842422955, "updatedAt": 1791842422955, "tracks": [] }],
    "history": []
  },
  "settings": { "theme": "dark", "preferVideo": false, "quality": "sd", "autoRadio": true, "volume": 0.9 }
}

Na importação o servidor valida cada faixa (ID do YouTube, tamanhos, só imagens https://), descarta entradas inválidas em vez de recusar o arquivo inteiro e recusa backups de versões mais novas com uma mensagem clara.

Atalhos de teclado

Configuração

Variáveis de ambiente do servidor (todas opcionais):

API

Todas as rotas respondem JSON. Erros vêm como { "error": "mensagem", "code"?: "tool_missing" | "maybe_outdated" | "bot_check" }.

Estrutura do projeto

musike/
├─ server/            Fastify + yt-dlp + youtubei.js
│  └─ src/
│     ├─ app.ts         rotas e inicialização (usado pelo CLI e pelo desktop)
│     ├─ ytdlp.ts       resolução de streams, cache HD, tradução de erros
│     ├─ stream.ts      proxy com HTTP Range
│     ├─ search.ts      busca, sugestões, rádio e escolha do clipe oficial
│     ├─ library.ts     playlists, favoritas, histórico e import de backup
│     ├─ tools.ts       localiza yt-dlp, Deno, FFmpeg (registro do Windows, winget)
│     ├─ bootstrap.ts   baixa as ferramentas para o app desktop
│     └─ system.ts      versão e atualização do yt-dlp
├─ web/               React 19 + Vite + Tailwind v4 + Motion + Phosphor (PWA)
│  └─ src/
│     ├─ player/        motor de reprodução (áudio, vídeo, fila, Media Session)
│     ├─ components/    player, painéis, modo cinema, Ajustes, backup
│     ├─ views/         Início, Buscar, Biblioteca, playlists
│     └─ stores/        estado (zustand)
├─ desktop/           Electron: janela, servidor embutido, instalador NSIS
└─ docs/              benchmark de UX, design system e capturas de tela

Stack: TypeScript em tudo · Fastify 5 · youtubei.js · yt-dlp · React 19 · Vite 8 · Tailwind CSS 4 · Motion · Zustand · React Router · Phosphor Icons · Geist · Electron 44 · electron-builder.

Design: a identidade (marca de equalizador em M, cor Volt, Geist) e as regras de layout estão em docs/design-system.md. O estudo de UX que guiou o layout está em docs/ux-benchmark.md: observação do web player do Spotify, sem descompilar código.

Solução de problemas

Parou de tocar ou "O YouTube recusou o stream" O YouTube muda com frequência e o yt-dlp acompanha. Abra Ajustes e toque em Atualizar. Se a correção ainda não chegou ao canal Estável, escolha Nightly.

"O YouTube pediu verificação anti-bot" Passe cookies de um navegador logado (o Firefox funciona melhor no Windows):

$env:YTDLP_EXTRA_ARGS = "--cookies-from-browser firefox"; pnpm start

"yt-dlp não encontrado" No app desktop, use Instalar em Ajustes. No servidor, instale com winget install yt-dlp.yt-dlp ou defina YTDLP_PATH.

O vídeo demora para começar Muitos vídeos não têm versão SD combinada; o servidor baixa e junta vídeo e áudio antes de tocar (alguns segundos na primeira vez, instantâneo depois, pelo cache).

"Esta música não tem clipe no YouTube" O Musike só aceita clipes publicados pelo canal do próprio artista, para não tocar covers ou versões erradas. A música continua tocando em áudio.

iPhone O iOS limita a reprodução em segundo plano de PWAs; o modo Áudio funciona melhor que o Vídeo.

Roadmap

• Sincronização da biblioteca em nuvem (hoje: backup em arquivo)
• Baixar faixas em MP3 / MP4
• Importar playlists do YouTube por link
• Instaladores para macOS e Linux
• Atualização automática do app desktop

Aviso legal

O Musike é um projeto para uso pessoal e educacional. Reproduzir conteúdo do YouTube sem anúncios por extração de stream viola os Termos de Serviço do YouTube; serviços públicos que fizeram isso, como os bots Groovy e Rythm, foram encerrados após notificação do Google. Não publique o Musike como serviço, não o monetize e respeite os direitos dos artistas. O projeto não hospeda, distribui nem armazena conteúdo do YouTube além do cache local temporário de quem o executa.

Licença

MIT © 2026 Ernani Neto