API do leitor de vídeo para incorporação

Podes usar a nossa API JavaScript para ouvires e controlares o leitor incorporado. O nosso leitor em iframe é compatível com o standard da API player.js da Embedly.

1. Configuração

Primeiro, inclui a biblioteca player.js na tua página:

CDN


<script type="text/javascript" src="//cdn.embed.ly/player-0.1.0.min.js"></script>

Segue-se, inicializa o leitor com o teu iframe:


// Get reference to your iframe element
const iframe = document.getElementById('your-iframe-id');
 
// Create player instance
const player = new playerjs.Player(iframe);
 
// Wait for player to be ready before interacting
player.on('ready', () => {
  console.log('Player is ready!');
  // Now you can safely use player methods
});

Espera sempre pelo evento ready antes de chamares métodos do leitor. O leitor vai enfileirar mensagens até que o evento ready seja disparado.

2. Eventos (Métodos)

Estes são os métodos que podes invocar no leitor para controlar a reprodução:

Controlo da reprodução

play() - Iniciar a reprodução


player.play();

pause() - Pausar a reprodução


player.pause();

Controlo do volume

mute() - Silenciar o leitor


player.mute();

unmute() - Ativar o som do leitor


player.unmute();

setVolume(volume) - Definir o volume (0-100)


player.setVolume(50); // Set to 50%

Posicionamento

setCurrentTime(seconds) - Saltar para um instante específico


player.setCurrentTime(30); // Seek to 30 seconds

Consultas de estado

getPaused(callback) - Verificar se o leitor está em pausa


player.getPaused((paused) => {
  console.log('Player is paused:', paused);
});

getMuted(callback) - Verificar se o leitor está silenciado


player.getMuted((muted) => {
  console.log('Player is muted:', muted);
});

getVolume(callback) - Obter o volume atual (0-100)


player.getVolume((volume) => {
  console.log('Current volume:', volume);
});

getDuration(callback) - Obter a duração do vídeo em segundos


player.getDuration((duration) => {
  console.log('Video duration:', duration, 'seconds');
});

getCurrentTime(callback) - Obter o instante atual de reprodução


player.getCurrentTime((time) => {
  console.log('Current time:', time, 'seconds');
});

Text tracks (legendas e captions)

Os métodos de Text track não fazem parte da biblioteca player.js integrada, por isso precisas de os associar uma vez. Adiciona a seguinte função auxiliar e chama-a dentro do teu handler ready:


function bindTextTrackMethods(player) {
  player.enableTextTrack = (value, callback) =>
    player.send({ method: 'enableTextTrack', value }, callback);
  player.disableTextTrack = () => player.send({ method: 'disableTextTrack' });
  player.getTextTracks = (callback) => player.send({ method: 'getTextTracks' }, callback);
  player.getTextTrack = (callback) => player.send({ method: 'getTextTrack' }, callback);
}
 
player.on('ready', () => {
  bindTextTrackMethods(player);
});

São expostos apenas os Text tracks do tipo legendas e captions. As faixas de capítulos são excluídas. Cada faixa é um objeto com os campos language, kind, label e mode.

getTextTracks(callback) - Obter todos os Text tracks disponíveis


player.getTextTracks((tracks) => {
  // [{ language, kind, label, mode }, ...]
  console.log('Available text tracks:', tracks);
});

getTextTrack(callback) - Obter o Text track ativo, ou null quando os Text tracks estão desativados


player.getTextTrack((track) => {
  console.log('Active text track:', track);
});

enableTextTrack(track, callback) - Ativar um Text track por idioma, ou por idioma e tipo

Se passares apenas um idioma e este corresponder a mais do que uma faixa, o leitor prefere uma correspondência exata de idioma e depois subtitles em vez de captions. O callback opcional recebe a faixa ativada.


// Enable by language
player.enableTextTrack('en');
 
// Enable by language and kind (when both exist for the same language)
player.enableTextTrack({ language: 'en', kind: 'captions' });
 
// Read the enabled track from the optional callback
player.enableTextTrack('en', (track) => {
  console.log('Enabled text track:', track);
});

disableTextTrack() - Desativar os Text tracks


player.disableTextTrack();

3. Listeners (Eventos)

Estes são os eventos aos quais podes subscrever-te para alterações de estado do leitor:

Eventos básicos

ready - Disparado quando o leitor está pronto a receber comandos


player.on('ready', () => {
  console.log('Player is ready for interaction');
});

play - Disparado quando a reprodução inicia


player.on('play', () => {
  console.log('Playback started');
});

pause - Disparado quando a reprodução é pausada


player.on('pause', () => {
  console.log('Playback paused');
});

ended - Disparado quando a reprodução termina


player.on('ended', () => {
  console.log('Playback finished');
});

Eventos de progresso

timeupdate - Disparado durante a reprodução com dados de instante e duração


player.on('timeupdate', (data) => {
  console.log('Current time:', data.seconds);
  console.log('Duration:', data.duration);
  
  // Calculate progress percentage
  const progress = (data.seconds / data.duration) * 100;
  console.log('Progress:', progress + '%');
});

progress - Disparado durante o carregamento com dados de progresso da memória intermédia


player.on('progress', (data) => {
  console.log('Buffering progress:', data.percent * 100 + '%');
});

Eventos de Text track

texttrackchange - Disparado quando o Text track ativo muda, através da API ou dos controlos do leitor


player.on('texttrackchange', (track) => {
  // `track` is the active track object, or null when text tracks are off
  console.log('Active text track:', track ? track.language : 'off');
});

texttrackerror - Disparado quando enableTextTrack não encontra uma faixa correspondente


player.on('texttrackerror', (error) => {
  // error.name: 'InvalidTrackLanguageError' | 'InvalidTrackError'
  console.error('Text track error:', error.name);
});

Nas transmissões em direto, as faixas de legendas são detetadas à medida que o manifesto é carregado e podem não estar disponíveis imediatamente após ready. Consulta novamente getTextTracks assim que a reprodução começar para obter as faixas que chegam mais tarde. O evento texttrackchange só é disparado quando a faixa ativa muda, por isso não dependas dele para detetar faixas recém-descobertas.

Tratamento de erros

error - Disparado quando ocorre um erro


player.on('error', (error) => {
  console.error('Player error:', error);
});

Exemplo completo

Eis um exemplo completo que mostra como configurar e usar a API do leitor:


// Initialize player
const iframe = document.getElementById('video-player');
const player = new playerjs.Player(iframe);
 
// Bind the text track methods (not part of the built-in player.js library)
function bindTextTrackMethods(player) {
  player.enableTextTrack = (value, callback) =>
    player.send({ method: 'enableTextTrack', value }, callback);
  player.disableTextTrack = () => player.send({ method: 'disableTextTrack' });
  player.getTextTracks = (callback) => player.send({ method: 'getTextTracks' }, callback);
  player.getTextTrack = (callback) => player.send({ method: 'getTextTrack' }, callback);
}
 
// Set up event listeners
player.on('ready', () => {
  console.log('Player ready!');
 
  bindTextTrackMethods(player);
 
  // Get initial state
  player.getDuration((duration) => {
    console.log('Video duration:', duration);
  });
  
  player.getVolume((volume) => {
    console.log('Current volume:', volume);
  });
 
  // List available text tracks
  player.getTextTracks((tracks) => {
    console.log('Text tracks:', tracks);
  });
});
 
player.on('play', () => {
  console.log('Started playing');
});
 
player.on('pause', () => {
  console.log('Paused');
});
 
player.on('timeupdate', (data) => {
  // Update progress bar
  const progress = (data.seconds / data.duration) * 100;
  document.getElementById('progress-bar').style.width = progress + '%';
});
 
player.on('ended', () => {
  console.log('Video finished');
});
 
player.on('texttrackchange', (track) => {
  console.log('Active text track:', track ? track.language : 'off');
});
 
player.on('texttrackerror', (error) => {
  console.error('Text track error:', error.name);
});
 
player.on('error', (error) => {
  console.error('Error:', error);
});
 
// Example control functions
function playVideo() {
  player.play();
}
 
function pauseVideo() {
  player.pause();
}
 
function setVolume(volume) {
  player.setVolume(volume);
}
 
function seekTo(seconds) {
  player.setCurrentTime(seconds);
}
 
function enableSubtitles(language) {
  player.enableTextTrack(language);
}
 
function disableSubtitles() {
  player.disableTextTrack();
}

Se tiveres vários leitores na mesma página com o mesmo src, podes deparar-te com inconsistências. Para evitar isto, acrescenta um identificador único (UUID ou timestamp) ao src de cada iframe.