Referência da API do player

Referência técnica do player instalável. Para as opções do construtor em linguagem simples, veja Ajustes do player; para ouvir o que acontece com o vídeo, veja Eventos do player.

ConstrutorCopiar link da seção

new SpallaPlayer(elementoOuSeletor, opcoes);

O primeiro argumento é um seletor CSS ou um elemento DOM. O segundo é opcional; qualquer opção informada aqui sempre vence o que o backend da Spalla configurou para aquele conteúdo.

O construtor também aceita o formato de uma integração anterior (videoId, liveId, playlistId e aliases) — ver compatibilidade com o player anterior.

Carregando conteúdoCopiar link da seção

await player.load('019e6f63-…');                    // detecta live, VOD ou playlist pelo ID
await player.load({ contentId: '019e…' });
await player.load({ contentId: '019e…', contentKind: 'video' }); // ou 'live'
await player.load({ playlistId: '01a0…', startIndex: 3 });
await player.load({ url: 'https://…/playlist.m3u8' }); // manifesto direto

IDs precisam ser UUIDs completos. Se você informar contentKind e ele divergir do que a Spalla retorna para aquele ID, o carregamento é recusado — prefira deixar o player autodetectar quando não tiver certeza.

Várias instâncias na mesma páginaCopiar link da seção

SpallaPlayer.getPlayers();                  // todas as instâncias vivas
SpallaPlayer.getPlayerById('spalla-player-1');
SpallaPlayer.getPlayerByElement(el);
await SpallaPlayer.destroyAll();            // destrói todas as instâncias
SpallaPlayer.isSupported();                 // navegador atende os requisitos mínimos
SpallaPlayer.version;                       // versão do player em uso

ReproduçãoCopiar link da seção

Propriedades (leitura, e escrita quando indicado):

Para desenhar controles próprios, player.media é o elemento de mídia efetivo (equivalente a um <video>) e player.engine é o motor de reprodução interno — durante uma sessão de Chromecast, os dois passam a apontar para o dispositivo remoto automaticamente, sem precisar tratar os dois casos no seu código.

Live e DVRCopiar link da seção

FaixasCopiar link da seção

PlaylistCopiar link da seção

InterfaceCopiar link da seção

Adicionar um botão próprio à barra:

player.addControlButton({
  name: 'ajuda',
  label: 'Ajuda',
  icon: 'M11 18h2v-2h-2v2zm1-16A10…', // atributo `d` de um path SVG, viewBox 24x24
  onClick: () => player.toast('olá'),
});
player.removeControlButton('ajuda');

setControls(nomes) troca a lista inteira de controles da barra (a ordem do array é a ordem visual). Botões de plugin, rewind_10 e forward_10 não são reinseridos automaticamente — quem quiser mantê-los precisa nomeá-los. A lista completa de nomes aceitos está em Ajustes do player.

player.setControls(['play_pause', 'time_and_duration', 'spacer', 'fullscreen']);
player.setControls([]);   // volta ao padrão da skin/dispositivo
player.setControls(false); // mantém a barra oculta

Em lives, com ou sem DVR, a seleção de velocidade fica oculta por padrão em todas as skins. Para habilitá-la, inclua playback_rate na lista explícita de controls do construtor ou de setControls.

Publicidade e castCopiar link da seção

DiagnósticoCopiar link da seção

Estáticos:

Vídeos 360 grausCopiar link da seção

Conteúdos marcados como sp_video_360 no backend ativam projeção equiretangular e navegação circular com quatro direções — arraste com mouse/toque, WASD e zoom com roda ou pinça.

• O botão cardboard oferece tela dividida para visores simples (não é WebXR imersivo). Nas skins embarcadas ele entra automaticamente com os plugins; se informar uma lista personalizada de controles, inclua esse nome.
• Durante anúncios, a projeção é suspensa e volta com direção e zoom preservados.
• PiP, Cast, AirPlay e fullscreen exclusivo do vídeo (iPhone) ficam bloqueados nesses conteúdos; fullscreen por container permanece disponível.
• Sem WebGL ou com DRM, há aviso e reprodução plana. TVs exibem vídeo plano, sem navegação por D-pad nesta etapa.
• features: { 'video-360': false } desativa projeção e navegação. Fontes por URL direta não ativam 360 graus — a ativação depende da configuração do conteúdo.

ChromecastCopiar link da seção

O envio replica o estado do player para o dispositivo — a API pública inteira segue a sessão. Com cast ativo, player.currentTime é o tempo na TV, player.volume = 0.5 mexe no volume da TV e player.on('timeupdate') dispara com os eventos que vêm de lá. Controles próprios funcionam iguais nos dois modos:

player.on('timeupdate', () => (barra.value = player.currentTime));
botaoPlay.onclick = () => player.togglePlay(); // local ou na TV, tanto faz

Quem precisa do elemento real — para PiP, AirPlay ou desenhar num canvas — usa player.video, que é sempre o <video> local, mesmo durante o cast.

Um evento não atravessa para o Cast: durationchange. A duração continua correta em player.duration, só a notificação de mudança não chega.

App ID padrão do receptor Spalla: 3C6B9439. Para usar outro:

new SpallaPlayer('#player', { cast: { receiverAppId: 'XXXXXXXX' } });