Metaphi: YouTube Jukebox V3

01

Instalação

Um arquivo só. Baixe para o seu projeto (recomendado: você controla a versão e não depende de outro site) ou carregue direto do metaphi.tech.

<script type="module" src="https://metaphi.tech/jukebox/v3/metaphi-jukebox.min.js"></script>

02

Músicas

Cada música é um disco no leque. Use o id do vídeo ou o link inteiro. Um disco com playlist toca vários vídeos em sequência, e o próprio player passa de um ao outro (no celular, sem precisar de outro toque).

<metaphi-jukebox accent="#2d81ff" position="bottom-left">
  <script type="application/json">
    {
      "tracks": [
        { "id": "https://youtu.be/Wv5kt7d8p1A", "title": "City Ghosts", "subtitle": "NEROX · Gangster Trap" },
        { "id": "7MHgdIu7FlI", "title": "Soft Collision", "subtitle": "Titan Beats · Deep House Mix" },
        {
          "title": "Playlist da casa",
          "subtitle": "Shuffle · 3 faixas",
          "playlist": ["Tx9zMFodNtA", "SAd_oy2Sc3Y", "NEMsIHVejWM"],
          "cover": { "lg": "/musica/capa.webp", "sm": "/musica/capa-sm.webp" }
        }
      ]
    }
  </script>
</metaphi-jukebox>

Músicas sem direitos autorais já usadas

Mixes da FreeWave Music, marcados pelo canal como "No Copyright" e já usados pelo autor em outro sistema. Confira sempre a licença na descrição do vídeo antes de usar.

• Morning Chill House #12FreeWave Music · No Copyrightyoutu.be/_3cu8xOA-Tk
• Morning Chill House #4FreeWave Music · No Copyrightyoutu.be/fUHjIZNKTaY
• Morning Chill House #14FreeWave Music · No Copyrightyoutu.be/cCvrx1N5R2g
• Morning Chill House #8FreeWave Music · No Copyrightyoutu.be/wy9mFK5a6JA
• Morning Chill House #13FreeWave Music · No Copyrightyoutu.be/tbLHqmwFfm0
• Sunset Drive #9FreeWave Music · No Copyrightyoutu.be/-jYPxknmhmI
• Sunny Road Trip #5FreeWave Music · No Copyrightyoutu.be/gCHg8E9CFMg

Playlist com músicas curtas

Músicas comuns, de 3 a 5 minutos, acabam rápido e pediriam um toque a cada troca. O disco-playlist resolve: um disco só, com a pilha de capas e o selo "Playlist · N", que toca vários vídeos em sequência. A lista vai inteira para o player do YouTube, que passa de uma faixa à outra sozinho (no celular, sem precisar de outro toque) e recomeça no fim. É o que a METAPHI Playlist desta página faz, com 11 faixas.

1. Crie um disco com playlist: a lista dos vídeos, por id ou link (youtu.be, watch?v=, /shorts). Dê um title, um subtitle e, de preferência, uma cover própria (sem ela, vale a miniatura do primeiro vídeo).

2. A ordem é sorteada a cada vez que o disco começa (shuffle, ligado por padrão). Para tocar na ordem da lista, use shuffle="false".

3. Vídeo indisponível dentro da lista é pulado. Para esconder os discos-playlist sem tirá-los do código, use show-playlists="false" (o Customize desta página tem as duas chaves no grupo Playlist).

<metaphi-jukebox shuffle>
  <script type="application/json">
    {
      "tracks": [
        { "id": "Wv5kt7d8p1A", "title": "City Ghosts", "subtitle": "NEROX · Gangster Trap" },
        {
          "title": "Playlist da casa",
          "subtitle": "Shuffle · 4 faixas",
          "cover": { "lg": "/musica/playlist.webp", "sm": "/musica/playlist-sm.webp" },
          "playlist": [
            "https://youtu.be/SAd_oy2Sc3Y",
            "https://www.youtube.com/watch?v=NEMsIHVejWM",
            "6QBy_Oa5ZmM",
            "YrLk4vdY28Q"
          ]
        }
      ]
    }
  </script>
</metaphi-jukebox>

Links de playlist do YouTube (list=…) não servem: liste os vídeos um a um. Dá para ter mais de um disco-playlist no leque. Com "continuar de onde parou", a playlist volta no mesmo disco, com a ordem sorteada de novo.

Mídia própria (arquivos de áudio)

No lugar do vídeo, use src com o endereço de um arquivo de áudio no seu servidor (mp3, m4a, ogg). O disco toca por<audio>: sem bloqueios do YouTube e com os controles do sistema na tela de bloqueio (Media Session). Com a opçãobackground, a música continua com a página em segundo plano ou a tela bloqueada. Discos do YouTube e de mídia própria podem ficar juntos no mesmo leque.

<metaphi-jukebox background>
  <script type="application/json">
    {
      "tracks": [
        { "src": "/musica/abertura.mp3", "title": "Abertura", "subtitle": "Trilha da casa", "cover": "/musica/abertura.webp" },
        { "src": "/musica/foco.m4a", "title": "Foco", "subtitle": "Trilha da casa" },
        { "id": "_3cu8xOA-Tk", "title": "Morning Chill House #12", "subtitle": "FreeWave Music · No Copyright" }
      ]
    }
  </script>
</metaphi-jukebox>

O servidor precisa responder pedidos com Range (status 206), como fazem os servidores de arquivos estáticos e as CDNs: o Safari exige isso para tocar áudio. No iPhone, o volume é o do aparelho (o Safari ignora o volume definido pela página).

03

Parâmetros

No HTML, como atributos em kebab-case (cover-size="64", allow-custom). Por JavaScript, em camelCase (coverSize: 64). Mude qualquer um depois com jukebox.update({ … }) ou trocando o atributo.

04

Recursos para sistemas

Dois recursos para quem volta sempre: a pessoa traz a própria música (mixes e sets com mais de 25 minutos) e a música continua de onde parou depois de recarregar a página. Os dois começam desligados.

Exemplos para testar

Na janela de envio, o botão Exemplos mostra estes três vídeos longos: tocar num deles já preenche o link e envia. Para trocar a lista, use a opção examples; para tirar o botão, show-examples="false".

• Sia · Unstoppable (Lyrics) · 30 MinGospel Lyrics · 29:58youtu.be/78kO0d0FxYo
• Músicas internacionais românticas · anos 70, 80 e 90Música internacional romântica imortal · 1h15youtu.be/kDd2FhSeptY
• Grupo Menos é Mais · Churrasquinho Menos é Mais 3 (DVD completo)Grupo Menos é Mais · 42 minyoutu.be/qPgwDlqdiD0

O primeiro tem 29:58, por isso a duração mínima padrão é mais de 25 minutos. Commin-duration="30", ele seria recusado com a mensagem de vídeo curto.

Músicas guardadas no seu servidor

Com storage: 'none', o navegador não guarda as músicas enviadas: o seu sistema salva na conta da pessoa (e elas aparecem em qualquer aparelho). onTrackAdd roda antes de guardar: devolva a música salva ou lance um erro com a mensagem para a pessoa. Confira de novo no servidor o id (/^[\w-]{11}$/) e a duração recebida.

import { createJukebox } from './metaphi-jukebox.js';

// sistema com login: as músicas enviadas ficam na conta da pessoa, no seu servidor
const jukebox = createJukebox({
  tracks,                       // as músicas da casa
  allowCustom: true,            // botão "Adicionar música"
  minDuration: 25,              // só mixes e sets com mais de 25 minutos
  maxCustom: 8,                 // ficam as 8 últimas
  resume: true,                 // continuar de onde parou
  storage: 'none',              // o navegador não guarda as músicas: o servidor guarda
  storageKey: `app:${user.id}`, // o ponto de parada, separado por pessoa
  customTracks: await fetch('/api/musicas').then((r) => r.json()),
  // salve e devolva a música (ou lance um erro: a mensagem aparece para a pessoa)
  onTrackAdd: async (track) => {
    const r = await fetch('/api/musicas', { method: 'POST', body: JSON.stringify(track) });
    if (!r.ok) throw new Error('Não deu para salvar agora. Tente de novo.');
    return r.json();
  },
  onTrackRemove: (id) => fetch('/api/musicas', { method: 'DELETE', body: JSON.stringify({ id }) }),
});

05

API JavaScript

O próprio elemento é a API: document.querySelector('metaphi-jukebox') ou o retorno de createJukebox(). Tocar e trocar de disco precisam acontecer dentro de um clique ou toque, por causa das regras de som dos navegadores.

06

Eventos

Disparados no elemento, com bubbles e composed: dá para ouvir no próprio elemento ou no document. O painel Ao vivo, no topo, mostra cada um acontecendo.

07

Vídeos na página

Se a página tem vídeos ou áudios próprios, a música sai da frente enquanto eles tocam. hold() pausa sem contar como "a pessoa desligou"; release() volta, se ela não tiver desligado nesse meio-tempo.

const jukebox = document.querySelector('metaphi-jukebox');
const video = document.querySelector('video');

// o vídeo da página toca: a música pausa; parou: a música volta (se a pessoa não tiver desligado)
video.addEventListener('play', () => jukebox.hold());
video.addEventListener('pause', () => jukebox.release());
video.addEventListener('ended', () => jukebox.release());

08

Estilo

O componente usa Shadow DOM: o CSS do site não quebra o toca-discos, e o dele não vaza. As cores vêm das opções (accent, surface, ink); as fontes, as partes internas e o estado ficam abertos para o site.

/* fontes do site dentro do componente (herdam para o Shadow DOM) */
metaphi-jukebox {
  --jukebox-font: 'Inter', sans-serif;
  --jukebox-font-mono: 'Geist Mono', monospace;
  --jukebox-font-display: 'Archivo', sans-serif;
}

/* partes internas */
metaphi-jukebox::part(panel) { box-shadow: 0 40px 120px -40px #000; }

/* o site reage à música */
body:has(metaphi-jukebox[data-playing]) .equalizer { animation-play-state: running; }

• data-playing, data-open, data-ready e data-status ficam no próprio elemento.
• Cliques dentro de elementos com data-jukebox-keep-open não fecham o painel (como o Customize desta página).
• Quem prefere menos movimento (prefers-reduced-motion) vê o leque sem animação e o disco parado.

09

Navegadores e YouTube

• Nada do YouTube carrega antes da hora. No computador, o player entra na primeira interação com a página; no celular, logo depois do carregamento, para o primeiro toque já tocar (prepare).
• O som começa dentro do gesto. Se o navegador pedir outro, o botão de som pisca (waiting) e o próximo toque toca. Ao voltar para a aba, a música continua.
• Domínio do player. No computador, youtube.com (vale o login do YouTube do navegador, o que evita a checagem anti-robô); no celular, youtube-nocookie.com.
• Áudio melhor. O player invisível tem 640 × 360, reduzido na tela: o YouTube escolhe a qualidade do áudio pelo tamanho do player.
• Requisitos: Chrome e Edge 111+, Safari 16.4+, Firefox 113+.

Content Security Policy

Nenhum script do YouTube é carregado: basta liberar o player e as capas. O connect-src só serve para mostrar o canal das músicas enviadas; sem ele, elas entram sem o canal.

Content-Security-Policy:
  frame-src https://www.youtube.com https://www.youtube-nocookie.com;
  img-src 'self' https://i.ytimg.com;
  connect-src 'self' https://www.youtube.com;  # opcional: canal das músicas enviadas (oEmbed)

10

Perguntas frequentes

11

Licença e créditos

Uso livre: você pode usar, copiar, modificar e distribuir, inclusive em projetos comerciais, desde que mantenha o aviso de copyright e o texto da licença (o comentário no topo do arquivo, com os créditos). O componente é fornecido como está, sem garantia. O arquivo publicado é minificado e ofuscado; o código-fonte não é distribuído.

Licença

Licença MIT MIT

Autor

Deivison Arthur

E-mail

deivison@metaphi.tech

LinkedIn

linkedin.com/in/deivisonarthur

Site

metaphi.tech

Bugs e melhorias

jukebox@metaphi.tech

O texto completo da licença e os créditos estão no cabeçalho do arquivo (comentário /*! … */), que acompanha todas as cópias: mantê-lo é a condição da licença. O ícone de link no painel de discos leva para esta página.