Skip to Content
Lettore video (embed)API del lettore

API del player video incorporato

Puoi usare la nostra API JavaScript per ascoltare e controllare il player incorporato. Il nostro player iframe è compatibile con lo standard API player.js  di Embedly.

1. Configurazione iniziale

Per prima cosa includi la libreria player.js nella pagina:

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

Poi inizializza il player con il tuo 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
});

Attendi sempre l’evento ready prima di chiamare i metodi del player. Il player metterà in coda i messaggi finché non viene emesso ready.

2. Metodi

Questi sono i metodi che puoi chiamare sul player per controllare la riproduzione:

Controllo della riproduzione

play() - Avvia la riproduzione

player.play();

pause() - Mette in pausa la riproduzione

player.pause();

Controllo del volume

mute() - Disattiva l’audio del player

player.mute();

unmute() - Riattiva l’audio del player

player.unmute();

setVolume(volume) - Imposta il volume (0-100)

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

Posizionamento nella timeline

setCurrentTime(seconds) - Salta a un istante specifico

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

Lettura dello stato

getPaused(callback) - Verifica se il player è in pausa

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

getMuted(callback) - Verifica se l’audio è disattivato

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

getVolume(callback) - Ottiene il volume corrente (0-100)

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

getDuration(callback) - Ottiene la durata del video in secondi

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

getCurrentTime(callback) - Ottiene il tempo di riproduzione corrente

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

Text tracks (sottotitoli e didascalie)

I metodi per i Text tracks non fanno parte della libreria player.js integrata, quindi devi associarli una volta. Aggiungi la seguente funzione di supporto e chiamala all’interno del tuo 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);
});

Vengono esposti solo i Text tracks di tipo sottotitoli e didascalie. Le tracce dei capitoli sono escluse. Ogni traccia è un oggetto con i campi language, kind, label e mode.

getTextTracks(callback) - Ottiene tutti i Text tracks disponibili

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

getTextTrack(callback) - Ottiene il Text track attivo, oppure null quando i Text tracks sono disattivati

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

enableTextTrack(track, callback) - Attiva un Text track per lingua, oppure per lingua e tipo

Se passi solo una lingua e questa corrisponde a più tracce, il player preferisce una corrispondenza esatta della lingua e poi subtitles rispetto a captions. Il callback opzionale riceve la traccia attivata.

// 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() - Disattiva i Text tracks

player.disableTextTrack();

3. Eventi (listener)

Questi sono gli eventi a cui puoi sottoscriverti per i cambiamenti di stato del player:

Eventi di base

ready - Emesso quando il player è pronto a ricevere comandi

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

play - Emesso quando inizia la riproduzione

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

pause - Emesso quando la riproduzione va in pausa

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

ended - Emesso al termine della riproduzione

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

Eventi di avanzamento

timeupdate - Emesso durante la riproduzione con tempo corrente e durata

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 - Emesso durante il caricamento con dati sull’avanzamento del buffer

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

Eventi dei Text tracks

texttrackchange - Emesso quando il Text track attivo cambia, tramite l’API o i controlli del player

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 - Emesso quando enableTextTrack non trova una traccia corrispondente

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

Per gli streaming dal vivo, le tracce di sottotitoli vengono rilevate man mano che il manifest viene caricato e potrebbero non essere disponibili subito dopo ready. Interroga di nuovo getTextTracks una volta avviata la riproduzione per recuperare le tracce che arrivano più tardi. L’evento texttrackchange viene emesso solo quando cambia la traccia attiva, quindi non affidarti a esso per rilevare le tracce appena scoperte.

Gestione degli errori

error - Emesso in caso di errore

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

Esempio completo

Ecco un esempio completo che mostra come configurare e usare l’API del player:

// 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 hai più player nella stessa pagina con lo stesso src, puoi incontrare comportamenti incoerenti. Per evitarlo, aggiungi un identificatore univoco (UUID o timestamp) al src di ogni iframe.

ConfigurazioneAutenticazione