API del reproductor de video incrustado

Puedes usar nuestra API de JavaScript para escuchar y controlar el reproductor incrustado. Nuestro reproductor iframe es compatible con el estándar de API player.js de Embedly.

1. Configuración

Primero, incluye la biblioteca player.js en tu página:

CDN


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

A continuación, inicializa el reproductor con tu 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
});

Siempre espera al evento ready antes de llamar a métodos del reproductor. El reproductor pondrá en cola los mensajes hasta que se dispare ready.

2. Eventos (métodos)

Estos son los métodos que puedes llamar en el reproductor para controlar la reproducción:

Control de reproducción

play() - Iniciar reproducción


player.play();

pause() - Pausar reproducción


player.pause();

Control de volumen

mute() - Silenciar el reproductor


player.mute();

unmute() - Activar el sonido del reproductor


player.unmute();

setVolume(volume) - Establecer el volumen (0-100)


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

Búsqueda de posición

setCurrentTime(seconds) - Ir a un instante concreto


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

Consultas de estado

getPaused(callback) - Comprobar si el reproductor está en pausa


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

getMuted(callback) - Comprobar si el reproductor está silenciado


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

getVolume(callback) - Obtener el volumen actual (0-100)


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

getDuration(callback) - Obtener la duración del video en segundos


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

getCurrentTime(callback) - Obtener el tiempo de reproducción actual


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

Text tracks (subtítulos y captions)

Los métodos de Text track no forman parte de la biblioteca player.js integrada, así que debes vincularlos una vez. Añade la siguiente función auxiliar y llámala dentro de tu controlador 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);
});

Solo se exponen los Text tracks de tipo subtítulos y subtítulos cerrados (captions). Las pistas de capítulos se excluyen. Cada pista es un objeto con los campos language, kind, label y mode.

getTextTracks(callback) - Obtener todos los Text tracks disponibles


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

getTextTrack(callback) - Obtener el Text track activo, o null cuando los Text tracks están desactivados


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

enableTextTrack(track, callback) - Activar un Text track por idioma, o por idioma y tipo

Si pasas solo un idioma y coincide con más de una pista, el reproductor prefiere una coincidencia exacta de idioma y luego subtitles antes que captions. El callback opcional recibe la pista activada.


// 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() - Desactivar los Text tracks


player.disableTextTrack();

3. Escuchas (eventos)

Estos son los eventos a los que puedes suscribirte para los cambios de estado del reproductor:

Eventos básicos

ready - Se dispara cuando el reproductor está listo para recibir comandos


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

play - Se dispara cuando comienza la reproducción


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

pause - Se dispara cuando se pausa la reproducción


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

ended - Se dispara cuando termina la reproducción


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

Eventos de progreso

timeupdate - Se dispara durante la reproducción con datos de tiempo actual y duración


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 - Se dispara durante la carga con datos del progreso del almacenamiento en búfer


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

Eventos de Text track

texttrackchange - Se dispara cuando cambia el Text track activo, ya sea a través de la API o de los controles del reproductor


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 - Se dispara cuando enableTextTrack no encuentra una pista coincidente


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

En las transmisiones en vivo, las pistas de subtítulos se detectan a medida que se carga el manifiesto y pueden no estar disponibles inmediatamente después de ready. Vuelve a consultar getTextTracks una vez iniciada la reproducción para recoger las pistas que llegan más tarde. El evento texttrackchange solo se dispara cuando cambia la pista activa, así que no dependas de él para detectar pistas recién descubiertas.

Manejo de errores

error - Se dispara cuando ocurre un error


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

Ejemplo completo

Aquí tienes un ejemplo completo que muestra cómo configurar y usar la API del reproductor:


// 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();
}

Si tienes varios reproductores en la misma página con el mismo src, puedes encontrar inconsistencias. Para evitarlo, añade un identificador único (UUID o marca de tiempo) al src de cada iframe.