Ajustes do player

Este guia cobre o player instalável. Todos os ajustes são feitos no segundo argumento do construtor — um objeto entre chaves, no qual você liga, desliga ou combina o que quiser:

const player = new SpallaPlayer('#player', {
  autoplay: true,
  muted: true,
  resume: true,
});

A regra de ouro: o que você informar aqui sempre vence o que foi configurado no backend da Spalla para aquele conteúdo. O que você omitir fica como o backend configurou (ou com o padrão do recurso). Um cuidado importante: omitir é diferente de desligar — { autoplay: false } desliga de propósito, enquanto não escrever a chave preserva a configuração do conteúdo. false e 0 são valores explícitos, não ausência.

Receitas prontasCopiar link da seção

Copie, cole e combine:

// Toca sozinho, sem som (evita o bloqueio do navegador)
new SpallaPlayer('#player', { autoplay: true, muted: true });

// Começa no minuto 1:30 (90 segundos)
new SpallaPlayer('#player', { startTime: 90 });

// Retoma de onde o espectador parou
new SpallaPlayer('#player', { resume: true });

// Repete em loop (útil para vitrines e telões)
new SpallaPlayer('#player', { loop: true });

// Legendas em português já ligadas, abaixo do vídeo
new SpallaPlayer('#player', {
  subtitleLanguage: 'pt-br',
  subtitlePosition: 'outer',
});

// Botões de saltar 10 segundos para frente e para trás
new SpallaPlayer('#player', { showSeekButtons: true });

// Menu de velocidade com opções próprias
new SpallaPlayer('#player', { playbackSpeeds: [0.5, 1, 1.5, 2] });

// Interface em inglês ou espanhol (padrão: idioma do navegador)
new SpallaPlayer('#player', { language: 'en' });

Todas as opções, em linguagem simplesCopiar link da seção

A barra de controlesCopiar link da seção

A lista de botões é sua para escolher — a ordem do array é a ordem visual na tela:

new SpallaPlayer('#player', {
  controls: ['play_pause', 'time_and_duration', 'spacer', 'mute_volume', 'quality', 'fullscreen'],
});

player.setControls(['play_pause', 'spacer', 'fullscreen']); // troca em runtime
player.setControls([]);   // volta ao padrão da skin/dispositivo
player.setControls(false); // esconde a barra inteira

Nomes aceitos:

Mais os botões dos plugins ativos, quando existirem: ai, audio_description, comments, libras, like, playlist, statistics, voice.

Para criar um botão próprio na barra, use player.addControlButton(...) — veja Interface, na referência da API.

A cor de destaque do player também muda em runtime, sem recarregar:

player.setTheme({ accent: '#ff0055' });
player.setSkin('tv'); // troca a skin com o vídeo tocando

Miniplayer e janela flutuanteCopiar link da seção

Os dois modos automáticos são independentes e desligados por padrão:

• autoPipViewport: true — quando o espectador rola a página e o vídeo sai totalmente da área visível, ele flutua no canto inferior direito (largura máxima de 320px, adaptada à janela). Rolar de volta devolve o vídeo ao lugar. Pausar depois de abrir mantém o miniplayer; conteúdo já pausado não abre sozinho.
• autoPipBlur: true — quando o espectador troca de aba, o player pede ao navegador uma janela flutuante (picture-in-picture). A abertura não é garantida: depende de suporte, permissão e engajamento que o navegador concede (no Chrome desktop, a mídia precisa estar na página principal, tocando e audível recentemente). Uma recusa não interrompe o vídeo.

new SpallaPlayer('#player', {
  autoPipViewport: true,
  autoPipBlur: true,
});

O backend da Spalla também pode ligar os modos por conteúdo, com as flags sp_player_auto_pip_viewport e sp_player_auto_pip_blur — a precedência é sempre: construtor > URL > flags do backend.

Recuperação automática de redeCopiar link da seção

Falhas transitórias de transporte (inclusive durante autorização e configuração) são retomadas sozinhas: por padrão, três retentativas extras após 2, 4 e 8 segundos — além das tentativas internas de cada requisição. A espera começa após a falha anterior.

const player = new SpallaPlayer('#player', {
  autoRetry: {
    maxRetries: 3,       // limite de retentativas
    baseDelay: 2000,     // espera inicial, em ms
    backoffFactor: 2,    // multiplicador da espera a cada tentativa
    maxDelay: 30000,     // teto da espera
  },
});

• Omitir a opção ou passar autoRetry: true usa esses padrões.
• autoRetry: false ou maxRetries: 0 desliga o automático.
• VOD conserva a posição e a intenção de reprodução; live retorna ao ponto ao vivo.
• load(), stop(), unload() e destroy() cancelam a recuperação anterior; retry() antecipa uma espera.

Não são repetidos automaticamente: HTTP 401/403/404, bloqueios de acesso, mídia inválida, erros de DRM e erros de publicidade. Enquanto a recuperação roda, a tela de erro fica oculta; esgotado o limite, o botão Tentar novamente inicia outro ciclo.

Configurar pela URL (avançado)Copiar link da seção

O player pode ler ajustes da própria URL da página — ?muted=1, ?t=30, ?skin=minimal — mas isso é opt-in: sem allowUrlParams: true no construtor, a URL é ignorada.

new SpallaPlayer('#player', { allowUrlParams: true });

A precedência é sempre a mesma: opção do construtor > parâmetro de URL > configuração do backend. Uma opção do construtor vence mesmo quando omitida dentro de um objeto — se você quer que a URL decida algo, não escreva a chave no construtor.

Parâmetros aceitos: t, language, debug, aid, device, autoplay, autoplay_mudo, muted, loop, resume, skin, enableLikes, enableForm, enableLogo, libras, playbackSpeeds, subtitles, subtitleLanguage, subtitlePosition, enableCc, aiSearch, bar, controls — e, nas versões com miniplayer automático, autoPipViewport e autoPipBlur.

O parâmetro debug também aceita silent, error, warn, info e debug como valores (?debug=1 equivale a debug).

Exemplos:

?skin=minimal
?controls=play_pause,spacer,fullscreen
?controls=0         // esconde a barra inteira (ou ?controls=-)
?bar=1              // liga os botões de salto de dez segundos
?t=30               // começa em 30 segundos (só no primeiro VOD)
?subtitleLanguage=en

Testando e aparelhos de TVCopiar link da seção

• Para investigar comportamento estranho, abra o console do navegador (F12) com debug: 'info' no construtor e veja Solução de problemas.
• Apps empacotados para TVs LG e Samsung usam deviceClass: 'tv', isApp e possivelmente apiKey — veja Apps de TV.