API lecteur vidéo intégré

Tu peux utiliser notre API JavaScript pour écouter et contrôler le lecteur intégré. Notre lecteur iframe est compatible avec la norme API player.js d’Embedly.

1. Mise en place

D’abord, inclus la bibliothèque player.js dans ta page :

CDN


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

Ensuite, initialise le lecteur avec ton 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
});

Attends toujours l’événement ready avant d’appeler les méthodes du lecteur. Le lecteur met les messages en file d’attente jusqu’à l’émission de ready.

2. Méthodes

Voici les méthodes que tu peux appeler sur le lecteur pour contrôler la lecture :

Contrôle de la lecture

play() — Démarre la lecture


player.play();

pause() — Met la lecture en pause


player.pause();

Contrôle du volume

mute() — Coupe le son du lecteur


player.mute();

unmute() — Rétablit le son du lecteur


player.unmute();

setVolume(volume) — Règle le volume (0-100)


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

Repositionnement

setCurrentTime(seconds) — Va à un instant précis


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

Consultation de l’état

getPaused(callback) — Indique si le lecteur est en pause


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

getMuted(callback) — Indique si le lecteur est muet


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

getVolume(callback) — Obtient le volume actuel (0-100)


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

getDuration(callback) — Obtient la durée de la vidéo en secondes


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

getCurrentTime(callback) — Obtient la position de lecture actuelle


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

Text tracks (sous-titres et légendes)

Les méthodes de Text track ne font pas partie de la bibliothèque player.js intégrée. Tu dois donc les lier une seule fois. Ajoute la fonction utilitaire suivante et appelle-la dans ton gestionnaire 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);
});

Seuls les Text tracks de type sous-titres et légendes sont exposés. Les pistes de chapitres sont exclues. Chaque piste est un objet avec les champs language, kind, label et mode.

getTextTracks(callback) — Récupère tous les Text tracks disponibles


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

getTextTrack(callback) — Récupère le Text track actif, ou null si les Text tracks sont désactivés


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

enableTextTrack(track, callback) — Active un Text track par langue, ou par langue et type

Si tu passes uniquement une langue et qu’elle correspond à plusieurs pistes, le lecteur privilégie une correspondance de langue exacte, puis subtitles plutôt que captions. Le callback optionnel reçoit la piste activée.


// 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() — Désactive les Text tracks


player.disableTextTrack();

3. Événements

Voici les événements auxquels tu peux t’abonner pour suivre les changements d’état du lecteur :

Événements de base

ready — Émis lorsque le lecteur est prêt à recevoir des commandes


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

play — Émis au démarrage de la lecture


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

pause — Émis lors d’une mise en pause


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

ended — Émis à la fin de la lecture


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

Événements de progression

timeupdate — Émis pendant la lecture avec la position et la durée


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 — Émis pendant le chargement avec la progression du tampon


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

Événements de Text track

texttrackchange — Déclenché lorsque le Text track actif change, via l’API ou les commandes du lecteur


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 — Déclenché lorsque enableTextTrack ne trouve pas de piste correspondante


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

Pour les diffusions en direct, les pistes de sous-titres sont détectées au fur et à mesure du chargement du manifeste et peuvent ne pas être disponibles immédiatement après ready. Interroge à nouveau getTextTracks une fois la lecture démarrée pour récupérer les pistes qui arrivent plus tard. L’événement texttrackchange ne se déclenche que lorsque la piste active change : ne compte donc pas dessus pour détecter les pistes nouvellement découvertes.

Gestion des erreurs

error — Émis en cas d’erreur


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

Exemple complet

Voici un exemple complet montrant comment configurer et utiliser l’API du lecteur :


// 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 tu as plusieurs lecteurs sur la même page avec la même valeur src, tu peux observer des incohérences. Pour éviter cela, ajoute un identifiant unique (UUID ou horodatage) au src de chaque iframe.