YouTube Player API Reference for iframe Embeds

L'IFrame Player API ti consente di incorporare un video player di YouTube nel tuo sito web e di controllare il player tramite JavaScript. A differenza delle Player API Flash e JavaScript, che richiedono l'incorporamento di un oggetto Flash nella pagina web, l'IFrame API inserisce i contenuti in un tag <iframe> sulla tua pagina. Questo approccio offre una maggiore flessibilità rispetto alle API disponibili in precedenza, dal momento che consente a YouTube di fornire un player HTML5 anziché un player Flash per i dispositivi mobili che non supportano Flash.

Tramite le funzioni JavaScript dell'API, puoi mettere in coda i video per riprodurre, mettere in pausa o interrompere tali video, regolare il volume del player oppure recuperare le informazioni sul video in riproduzione. Puoi anche aggiungere listener di eventi che verranno eseguiti in risposta a determinati eventi del player, ad esempio se cambia lo stato del player o la qualità di riproduzione di un video.

In questa guida viene illustrato come utilizzare l'IFrame.API, vengono identificati i diversi tipi di eventi che l'API può inviare e viene descritto come scrivere listener di eventi per rispondere a tali eventi. Contiene inoltre le informazioni dettagliate sulle diverse funzioni JavaScript che puoi chiamare per controllare il video player, nonché i parametri da utilizzare per personalizzare ulteriormente il player.

Requisiti

L'utente finale deve usare un browser che supporti la funzione postMessage di HTML5. I browser più moderni supportano la funzione postMessage, a eccezione di Internet Explorer 7.

Per i player incorporati, la visualizzazione deve essere di almeno 200 px per 200 px. Nel caso in cui siano presenti i controlli, il player dovrà avere dimensioni tali da mostrare i controlli senza ridurre la visualizzazione al di sotto del valore minimo. I player in formato 16:9 devono avere una larghezza minima di 480 pixel e un'altezza minima di 270 pixel.

Qualsiasi pagina web che utilizza l'IFrame API deve anche implementare la seguente funzione JavaScript:

  • onYouTubeIframeAPIReady - l'API chiama questa funzione quando la pagina termina il download di JavaScript per la Player API, che ti consente di usare l'API sulla tua pagina. In questo modo la funzione può creare gli oggetti player che intendi visualizzare al caricamento della pagina.

Guida introduttiva

La pagina HTML di esempio riportata di seguito permette di creare un player incorporato che carica un video, lo riproduce per sei secondi, quindi interrompe la riproduzione. I commenti numerati nell'HTML vengono spiegati nell'elenco riportato sotto l'esempio.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '360',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

Il seguente elenco fornisce ulteriori dettagli sull'esempio riportato sopra:

  1. Il tag <div> in questa sezione identifica la posizione in cui l'IFrame API inserirà il video player nella pagina. La funzione che crea l'oggetto player, descritta nella sezione Caricamento di un video player, identifica il tag <div> tramite l'id per garantire che l'API collochi l'elemento <iframe> nella posizione corretta. Nello specifico, l'IFrame API sostituisce il tag <div> con il tag <iframe>.

    In alternativa, puoi anche inserire l'elemento <iframe> direttamente nella pagina. Nella sezione Caricamento di un video player viene illustrato come procedere.

  2. Il codice in questa sezione consente di caricare il codice JavaScript dell'IFrame Player API. Nell'esempio viene utilizzata la modifica DOM per scaricare il codice dell'API e assicurare che il codice venga recuperato in modo asincrono. L'attributo async del tag <script>, che consente anche i download asincroni, non è ancora supportato in tutti i browser moderni, come illustrato in questa risposta di Stack Overflow.

  3. La funzione onYouTubeIframeAPIReady viene eseguita non appena viene scaricato il codice della Player API. Questa parte del codice definisce la variabile globale player, che fa riferimento al video player che stai incorporando, e la funzione crea quindi l'oggetto video player.

  4. La funzione onPlayerReady viene eseguita quando viene attivato l'evento onReady. In questo esempio, la funzione indica che la riproduzione deve iniziare quando il video player è pronto.

  5. L'API chiama la funzione onPlayerStateChange quando lo stato del player cambia, il che può indicare che il player è in riproduzione, in pausa, che ha completato la riproduzione e così via. La funzione indica che quando lo stato del player è 1 (in riproduzione), il player deve avviare la riproduzione per sei secondi, quindi chiamare la funzione stopVideo per interrompere il video.

Caricamento di un video player

Dopo il caricamento del codice JavaScript dell'API, quest'ultima chiama la funzione onYouTubeIframeAPIReady, consentendoti di creare un oggetto YT.Player per inserire un video player nella tua pagina. Il seguente estratto HTML mostra la funzione onYouTubeIframeAPIReady dell'esempio riportato sopra:

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '360',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

In fase di creazione del video player vengono specificati i seguenti parametri:

  1. Il primo parametro specifica l'elemento DOM o l'id dell'elemento HTML in cui l'API inserirà il tag <iframe> contenente il player.

    L'IFrame API sostituirà l'elemento specificato con l'elemento <iframe> contenente il player. Ciò potrebbe influire sul layout della tua pagina se l'elemento sostituito ha uno stile di visualizzazione diverso dall'elemento <iframe> inserito. Per impostazione predefinita, un <iframe> viene visualizzato come elemento inline-block.

  2. Il secondo parametro è un oggetto che specifica le opzioni del player. L'oggetto contiene le seguenti proprietà:
    • width (numero) - La larghezza del video player. Il valore predefinito è 640.
    • height (numero) - L'altezza del video player. Il valore predefinito è 360.
    • videoId (stringa) - L'ID del video di YouTube che identifica il video che verrà caricato dal player.
    • playerVars (oggetto) - Le proprietà dell'oggetto identificano i parametri del player che possono essere utilizzati per la personalizzazione.
    • events (oggetto) - Le proprietà dell'oggetto identificano gli eventi attivati dall'API e le funzioni (listener di eventi) chiamate dall'API quando si verificano tali eventi. Nell'esempio viene indicato che la funzione onPlayerReady verrà eseguita all'attivazione dell'evento onReady e che la funzione onPlayerStateChange verrà eseguita all'attivazione dell'evento onStateChange.

Come illustrato nella sezione Guida introduttiva, anziché scrivere un elemento <div> vuoto nella pagina, che verrà sostituito dal codice JavaScript della Player API con un elemento <iframe>, puoi creare autonomamente il tag <iframe>.

<iframe id="player" type="text/html" width="640" height="360"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

Se scrivi il tag <iframe>, durante la creazione dell'oggetto YT.Player non dovrai specificare né i valori per le proprietà width e height, specificati come attributi del tag <iframe>, né i parametri del player e videoId, specificati nell'URL src. Per una maggiore sicurezza, inserisci il parametro origin nell'URL, specificando lo schema dell'URL (http:// o https://) e il dominio completo della tua pagina host come valore del parametro. Nonostante il parametro origin sia facoltativo, il suo utilizzo consente di evitare l'introduzione nella pagina di codice JavaScript di terze parti dannoso, che può assumere il controllo del player di YouTube.

La sezione Esempi riporta alcuni esempi per la creazione di oggetti video player.

Operazioni

Per chiamare i metodi della Player API, devi prima ottenere un riferimento all'oggetto player che intendi controllare. Puoi ottenere il riferimento creando un oggetto YT.Player, come descritto nelle sezioni Guida introduttiva e Caricamento di un video player di questo documento.

Funzioni

Funzioni di accodamento

Le funzioni di accodamento ti consentono di caricare e riprodurre un video, una playlist o un altro elenco di video. Se per chiamare queste funzioni usi la sintassi dell'oggetto descritta di seguito, puoi anche mettere in coda o caricare un elenco di risultati di ricerca o un elenco di video caricati da un utente.

L'API supporta due diverse sintassi per chiamare le funzioni di accodamento.

  • La sintassi dell'argomento richiede che gli argomenti della funzione siano riportati in un ordine specifico.

  • La sintassi dell'oggetto consente di passare un oggetto come singolo parametro e di definire le proprietà dell'oggetto per gli argomenti della funzione da impostare. Inoltre, l'API può supportare funzionalità aggiuntive, che la sintassi dell'argomento non supporta.

Ad esempio, la funzione loadVideoById può essere chiamata in uno dei seguenti modi. Tieni presente che la sintassi dell'oggetto supporta la proprietà endSeconds, che non è supportata dalla sintassi dell'argomento.

  • Sintassi dell'argomento

    loadVideoById("bHQqvYy5KYo", 5, "large")
  • Sintassi dell'oggetto

    loadVideoById({'videoId': 'bHQqvYy5KYo',
                   'startSeconds': 5,
                   'endSeconds': 60,
                   'suggestedQuality': 'large'});

Funzioni di accodamento per i video

cueVideoById
  • Sintassi dell'argomento

    player.cueVideoById(videoId:String,
                        startSeconds:Number,
                        suggestedQuality:String):Void
  • Sintassi dell'oggetto

    player.cueVideoById({videoId:String,
                         startSeconds:Number,
                         endSeconds:Number,
                         suggestedQuality:String}):Void

Questa funzione consente di caricare la miniatura del video specificato e di preparare il player per la riproduzione del video. Il player non richiede l'FLV finché non viene chiamata la funzione playVideo() o seekTo().

  • Il parametro obbligatorio videoId specifica l'ID del video di YouTube da riprodurre. Nei feed video di YouTube Data API, il tag <yt:videoid> specifica l'ID.
  • Il parametro facoltativo startSeconds accetta numeri interi o decimali e specifica il punto da cui deve iniziare la riproduzione del video quando viene chiamata la funzione playVideo(). Se specifichi un valore startSeconds e chiami seekTo(), il player inizia la riproduzione dal punto specificato nella chiamata seekTo(). Quando il video viene messo in coda ed è pronto per la riproduzione, il player trasmette un evento video cued (5).
  • Il parametro facoltativo endSeconds, supportato solo nella sintassi dell'oggetto, accetta un numero intero o decimale e specifica il punto in cui deve essere interrotta la riproduzione del video quando viene chiamata la funzione playVideo(). Se specifichi un valore endSeconds e chiami seekTo(), il valore endSeconds non sarà più valido.
  • Il parametro facoltativo suggestedQuality specifica la qualità di riproduzione consigliata per il video. Per ulteriori informazioni sulla qualità di riproduzione, consulta la definizione della funzione setPlaybackQuality.

loadVideoById

  • Argument syntax

    player.loadVideoById(videoId:String,
                         startSeconds:Number,
                         suggestedQuality:String):Void
  • Object syntax

    player.loadVideoById({videoId:String,
                          startSeconds:Number,
                          endSeconds:Number,
                          suggestedQuality:String}):Void

Questa funzione consente di caricare e riprodurre il video specificato.

  • Il parametro obbligatorio videoId specifica l'ID del video di YouTube da riprodurre. Nei feed video di YouTube Data API, il tag <yt:videoid> specifica l'ID.
  • Il parametro facoltativo startSeconds accetta un numero intero o decimale. Se specificato, il video inizierà dal fotogramma chiave più vicino al punto specificato.
  • Il parametro facoltativo endSeconds accetta un numero intero o decimale. Se specificato, la riproduzione del video verrà interrotta nel punto indicato.
  • Il parametro facoltativo suggestedQuality specifica la qualità di riproduzione consigliata per il video. Per ulteriori informazioni sulla qualità di riproduzione, consulta la definizione della funzione setPlaybackQuality.

cueVideoByUrl

  • Argument syntax

    player.cueVideoByUrl(mediaContentUrl:String,
                         startSeconds:Number,
                         suggestedQuality:String):Void
  • Object syntax

    player.cueVideoByUrl({mediaContentUrl:String,
                          startSeconds:Number,
                          endSeconds:Number,
                          suggestedQuality:String}):Void

Questa funzione consente di caricare la miniatura del video specificato e di preparare il player per la riproduzione del video. Il player non richiede l'FLV finché non viene chiamata la funzione playVideo() o seekTo().

  • Il parametro obbligatorio mediaContentUrl specifica un URL completo del player di YouTube nel formato http://www.youtube.com/v/VIDEO_ID?version=3. Nei feed video di YouTube Data API, l'attributo url del tag <media:content> contiene un URL completo del player quando l'attributo format del tag ha il valore 5.
  • Il parametro facoltativo startSeconds accetta numeri interi o decimali e specifica il punto da cui deve iniziare la riproduzione del video quando viene chiamata la funzione playVideo(). Se specifichi startSeconds e chiami seekTo(), il player inizia la riproduzione dal punto specificato nella chiamata seekTo(). Quando il video viene messo in coda ed è pronto per la riproduzione, il player trasmette un evento video cued (5).
  • Il parametro facoltativo endSeconds, supportato solo nella sintassi dell'oggetto, accetta un numero intero o decimale e specifica il punto in cui deve essere interrotta la riproduzione del video quando viene chiamata la funzione playVideo(). Se specifichi un valore endSeconds e chiami seekTo(), il valore endSeconds non sarà più applicato.
  • Il parametro facoltativo suggestedQuality specifica la qualità di riproduzione consigliata per il video. Per ulteriori informazioni sulla qualità di riproduzione, consulta la definizione della funzione setPlaybackQuality.

loadVideoByUrl

  • Argument syntax

    player.loadVideoByUrl(mediaContentUrl:String,
                          startSeconds:Number,
                          suggestedQuality:String):Void
  • Object syntax

    player.loadVideoByUrl({mediaContentUrl:String,
                           startSeconds:Number,
                           endSeconds:Number,
                           suggestedQuality:String}):Void

Questa funzione consente di caricare e riprodurre il video specificato.

  • Il parametro obbligatorio mediaContentUrl specifica un URL completo del player di YouTube nel formato http://www.youtube.com/v/VIDEO_ID?version=3. Nei feed video di YouTube Data API, l'attributo url del tag <media:content> contiene un URL completo del player quando l'attributo format del tag ha il valore 5.
  • Il parametro facoltativo startSeconds accetta numeri interi o decimali e specifica il punto da cui deve iniziare la riproduzione del video. Se viene specificato il parametro startSeconds (il numero può essere decimale), il video inizierà dal fotogramma chiave più vicino al punto specificato.
  • Il parametro facoltativo endSeconds, supportato solo nella sintassi dell'oggetto, accetta un numero intero o decimale e specifica il punto in cui deve essere interrotta la riproduzione del video.
  • Il parametro facoltativo suggestedQuality specifica la qualità di riproduzione consigliata per il video. Per ulteriori informazioni sulla qualità di riproduzione, consulta la definizione della funzione setPlaybackQuality.

Funzioni di accodamento per gli elenchi

Le funzioni cuePlaylist e loadPlaylist consentono di caricare e riprodurre una playlist o un elenco di video. Se usi la sintassi dell'oggetto per chiamare queste funzioni, puoi anche mettere in coda (o caricare) un elenco di risultati di ricerca o l'elenco dei video caricati da un utente.

Dal momento che le funzioni operano diversamente a seconda che vengano chiamate tramite la sintassi dell'argomento o la sintassi dell'oggetto, entrambi i metodi di chiamata sono descritti di seguito.

cuePlaylist
  • Argument syntax

    player.cuePlaylist(playlist:String|Array,
                       index:Number,
                       startSeconds:Number,
                       suggestedQuality:String):Void
    Consente di mettere in coda la playlist specificata. Quando la playlist viene messa in coda ed è pronta per la riproduzione, il player trasmette un evento video cued (5).
    • Il parametro obbligatorio playlist specifica un array di ID video di YouTube. Nei feed di YouTube Data API, il tag <yt:videoid> specifica un ID video.

    • Il parametro facoltativo index specifica l'indice del primo video della playlist che verrà riprodotto. Il parametro usa un indice in base zero e il valore predefinito del parametro è 0, quindi il comportamento predefinito consiste nel caricamento e nella riproduzione del primo video della playlist.

    • Il parametro facoltativo startSeconds accetta numeri interi o decimali e specifica il punto da cui deve iniziare la riproduzione del primo video della playlist quando viene chiamata la funzione playVideo(). Se specifichi un valore startSeconds e chiami seekTo(), il player inizia la riproduzione dal punto specificato nella chiamata seekTo(). Se metti in coda una playlist e chiami la funzione playVideoAt(), il player inizia la riproduzione dall'inizio del video specificato.

    • Il parametro facoltativo suggestedQuality specifica la qualità di riproduzione consigliata per il video. Per ulteriori informazioni sulla qualità di riproduzione, consulta la definizione della funzione setPlaybackQuality.

  • Sintassi dell'oggetto

    player.cuePlaylist({listType:String,
                        list:String,
                        index:Number,
                        startSeconds:Number,
                        suggestedQuality:String}):Void
    Consente di mettere in coda l'elenco di video specificato. Può trattarsi di una playlist, di un feed di risultati di ricerca o di un feed di video caricati da un utente. Quando l'elenco viene messo in coda ed è pronto per la riproduzione, il player trasmette un evento video cued (5).
    • La proprietà facoltativa listType specifica il tipo di feed dei risultati che stai recuperando. I valori validi sono playlist, search e user_uploads. Il valore predefinito è playlist.

    • La proprietà obbligatoria list contiene una chiave che identifica l'elenco di video specifico che YouTube deve restituire.

      • Se il valore della proprietà listType è playlist, la proprietà list specifica l'ID della playlist o un array di ID video. Nei feed di YouTube Data API, il tag <yt:playlistid> specifica un ID playlist e il tag <yt:videoid> specifica un ID video.
      • Se il valore della proprietà listType è search, la proprietà list specifica la query di ricerca.
      • Se il valore della proprietà listType è user_uploads, la proprietà list identifica l'utente di cui verranno restituiti i video caricati.

    • La proprietà facoltativa index specifica l'indice del primo video dell'elenco che verrà riprodotto. Il parametro usa un indice in base zero e il valore predefinito del parametro è 0, quindi il comportamento predefinito consiste nel caricamento e nella riproduzione del primo video dell'elenco.

    • La proprietà facoltativa startSeconds accetta numeri interi o decimali e specifica il punto da cui deve iniziare la riproduzione del primo video dell'elenco quando viene chiamata la funzione playVideo(). Se specifichi un valore startSeconds e chiami seekTo(), il player inizia la riproduzione dal punto specificato nella chiamata seekTo(). Se metti in coda un elenco e chiami la funzione playVideoAt(), il player inizia la riproduzione dall'inizio del video specificato.

    • La proprietà facoltativa suggestedQuality specifica la qualità di riproduzione consigliata per i video dell'elenco. Per ulteriori informazioni sulla qualità di riproduzione, consulta la definizione della funzione setPlaybackQuality.

loadPlaylist
  • Argument syntax

    player.loadPlaylist(playlist:String|Array,
                        index:Number,
                        startSeconds:Number,
                        suggestedQuality:String):Void
    Questa funzione consente di caricare la playlist specificata e di riprodurla.
    • Il parametro obbligatorio playlist specifica un array di ID video di YouTube. Nei feed di YouTube Data API, il tag <yt:videoid> specifica un ID video.

    • Il parametro facoltativo index specifica l'indice del primo video della playlist che verrà riprodotto. Il parametro usa un indice in base zero e il valore predefinito del parametro è 0, quindi il comportamento predefinito consiste nel caricamento e nella riproduzione del primo video della playlist.

    • Il parametro facoltativo startSeconds accetta numeri interi o decimali e specifica il punto da cui deve iniziare la riproduzione del primo video della playlist.

    • Il parametro facoltativo suggestedQuality specifica la qualità di riproduzione consigliata per il video. Per ulteriori informazioni sulla qualità di riproduzione, consulta la definizione della funzione setPlaybackQuality.

  • Object syntax

    player.loadPlaylist({list:String,
                         listType:String,
                         index:Number,
                         startSeconds:Number,
                         suggestedQuality:String}):Void
    Questa funzione consente di caricare e riprodurre l'elenco specificato. Può trattarsi di una playlist, di un feed di risultati di ricerca o di un feed di video caricati da un utente.
    • La proprietà facoltativa listType specifica il tipo di feed dei risultati che stai recuperando. I valori validi sono playlist, search e user_uploads. Il valore predefinito è playlist.

    • La proprietà obbligatoria list contiene una chiave che identifica l'elenco di video specifico che YouTube deve restituire.

      • Se il valore della proprietà listType è playlist, la proprietà list specifica un ID playlist o un array di ID video. Nei feed di YouTube Data API, il tag <yt:playlistid> specifica un ID playlist e il tag <yt:videoid> specifica un ID video.
      • Se il valore della proprietà listType è search, la proprietà list specifica la query di ricerca.
      • Se il valore della proprietà listType è user_uploads, la proprietà list identifica l'utente di cui verranno restituiti i video caricati.

    • La proprietà facoltativa index specifica l'indice del primo video dell'elenco che verrà riprodotto. Il parametro usa un indice in base zero e il valore predefinito del parametro è 0, quindi il comportamento predefinito consiste nel caricamento e nella riproduzione del primo video dell'elenco.

    • La proprietà facoltativa startSeconds accetta numeri interi o decimali e specifica il punto da cui deve iniziare la riproduzione del primo video dell'elenco.

    • La proprietà facoltativa suggestedQuality specifica la qualità di riproduzione consigliata per i video dell'elenco. Per ulteriori informazioni sulla qualità di riproduzione, consulta la definizione della funzione setPlaybackQuality.

Controlli per la riproduzione e impostazioni del player

Riproduzione di un video

player.playVideo():Void
Consente di riprodurre il video attualmente in coda/caricato. Lo stato finale del player dopo l'esecuzione di questa funzione sarà playing (1).

Nota. Una riproduzione contribuisce al numero di visualizzazioni ufficiali di un video solo se avviata tramite un pulsante di riproduzione nativo del player.
player.pauseVideo():Void
Consente di mettere in pausa il video in riproduzione. Lo stato finale del player dopo l'esecuzione di questa funzione sarà paused (2), a meno che lo stato del player non sia ended (0) al momento della chiamata della funzione. In questo caso lo stato del player non cambia.
player.stopVideo():Void
Consente di interrompere e annullare il caricamento del video corrente. Questa funzione deve essere utilizzata esclusivamente nei casi in cui sei certo che l'utente non guarderà altri video nel player. Per mettere in pausa il video, basta chiamare la funzione pauseVideo. Se vuoi cambiare il video in riproduzione nel player, puoi chiamare una delle funzioni di coda, senza chiamare prima stopVideo.

Importante. A differenza della funzione pauseVideo che lascia il player nello stato paused (2), la funzione stopVideo può impostare il player in uno stato di "non riproduzione", come ended (0), paused (2), video cued (5) o unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Consente di passare a un punto specifico del video. Se il player è in pausa quando viene chiamata la funzione, resterà in pausa. Se la funzione viene chiamata da un altro stato (playing, video cued e così via), il player riprodurrà il video.
  • Il parametro seconds identifica il punto fino al quale il video deve andare avanti.

    Il player andrà avanti fino al fotogramma chiave più vicino prima di quel punto, a meno che non abbia già scaricato la parte del video richiesta dall'utente. In tal caso, il player andrà avanti fino al fotogramma chiave più vicino, prima o dopo il punto indicato, come definito dal metodo seek() dell'oggetto NetStream del player Flash. Per ulteriori informazioni, consulta la documentazione di Adobe.

  • Il parametro allowSeekAhead determina se il player deve effettuare una nuova richiesta al server quando il parametro seconds specifica un punto esterno all'intervallo di dati del video attualmente inseriti nel buffer.

    Ti consigliamo di impostare questo parametro su false quando l'utente trascina il mouse sulla barra di avanzamento del video e impostarlo su true quando l'utente rilascia il mouse. Questo approccio consente all'utente di passare a punti diversi di un video senza che siano richiesti nuovi stream video, spostandosi oltre i punti non inseriti nel buffer del video. Quando l'utente rilascia il pulsante del mouse, il player va avanti fino al punto desiderato del video e, se necessario, richiede un nuovo stream video.

player.clearVideo():Void
Consente di cancellare la visualizzazione del video. Questa funzione consente di cancellare il resto del video dopo la chiamata a stopVideo(). Questa funzione non è più supportata nell'ActionScript 3.0 Player API.

Riproduzione di un video in una playlist

player.nextVideo():Void
Questa funzione consente di caricare e riprodurre il video successivo della playlist.
  • Se viene chiamata la funzione player.nextVideo() mentre l'utente sta guardando l'ultimo video della playlist e la playlist è impostata per la riproduzione continua (loop), il player carica e riproduce il primo video dell'elenco.

  • Se viene chiamata la funzione player.nextVideo() mentre l'utente sta guardando l'ultimo video della playlist e la playlist non è impostata per la riproduzione continua, la riproduzione si interrompe.

player.previousVideo():Void
Questa funzione consente di caricare e riprodurre il video precedente della playlist.
  • Se viene chiamata la funzione player.previousVideo() mentre l'utente sta guardando il primo video della playlist e la playlist è impostata per la riproduzione continua (loop), il player carica e riproduce l'ultimo video dell'elenco.

  • Se viene chiamata la funzione player.previousVideo() mentre l'utente sta guardando il primo video della playlist e la playlist non è impostata per la riproduzione continua, il player riprodurrà nuovamente il primo video della playlist dall'inizio.

player.playVideoAt(index:Number):Void
Questa funzione consente di caricare e riprodurre il video specificato nella playlist.
  • Il parametro obbligatorio index specifica l'indice del video da riprodurre nella playlist. Tale parametro usa un indice in base zero, quindi il valore 0 identifica il primo video dell'elenco. Se per la playlist è impostata la riproduzione casuale, questa funzione consentirà di riprodurre il video nella posizione specificata nella playlist.

Modifica del volume del player

player.mute():Void
Consente di disattivare l'audio del player.
player.unMute():Void
Consente di attivare l'audio del player.
player.isMuted():Boolean
Restituisce il valore true se l'audio del player è disattivato, false in caso contrario.
player.setVolume(volume:Number):Void
Consente di impostare il volume. Accetta un numero intero compreso tra 0 e 100.
player.getVolume():Number
Restituisce il volume attuale del player, un numero intero compreso tra 0 e 100. getVolume() restituirà il volume anche se l'audio del player è disattivato.

Impostazione delle dimensioni del player

player.setSize(width:Number, height:Number):Object
Consente di impostare le dimensioni in pixel dell'elemento <iframe> che contiene il player.

Impostazione della velocità di riproduzione

player.getPlaybackRate():Number
Questa funzione consente di recuperare la velocità di riproduzione del video corrente. La velocità di riproduzione predefinita è 1, ovvero una velocità di riproduzione normale. La velocità di riproduzione può includere valori quali 0.25, 0.5, 1, 1.5 e 2.
player.setPlaybackRate(suggestedRate:Number):Void
Questa funzione consente di impostare la velocità di riproduzione consigliata per il video corrente. Se la velocità di riproduzione cambia, cambierà soltanto per il video già in coda o in riproduzione. Se imposti la velocità di riproduzione per un video in coda, la stessa velocità verrà applicata anche quando viene chiamata la funzione playVideo o l'utente avvia la riproduzione direttamente tramite i controlli del player. Inoltre, chiamando le funzioni per mettere in coda o caricare video o playlist (cueVideoById, loadVideoById e così via) la velocità di riproduzione viene reimpostata su 1.

Se chiami questa funzione non è garantito che la velocità di riproduzione cambi effettivamente. Tuttavia, se la velocità di riproduzione cambia, l'evento onPlaybackRateChange viene attivato e il codice deve rispondere all'evento anziché alla chiamata della funzione setPlaybackRate.

Il metodo getAvailablePlaybackRates restituisce le velocità di riproduzione possibili per il video in riproduzione. Tuttavia, se imposti il parametro suggestedRate su un valore intero o decimale non supportato, il player lo arrotonda per difetto al valore supportato più vicino a 1.
player.getAvailablePlaybackRates():Array
Questa funzione restituisce l'insieme di velocità di riproduzione disponibili per il video corrente. Il valore predefinito è 1 e indica che il video viene riprodotto a una velocità normale.

La funzione restituisce un array di numeri ordinati dalla velocità di riproduzione più lenta alla più veloce. Nonostante il player non supporti velocità di riproduzione variabili, l'array deve sempre contenere almeno un valore (1).

Impostazione di un comportamento di riproduzione per le playlist

player.setLoop(loopPlaylists:Boolean):Void

Questa funzione indica se il video player deve riprodurre una playlist in modo continuo o se deve interrompere la riproduzione al termine dell'ultimo video della playlist. Il comportamento predefinito non prevede il loop delle playlist.

Questa impostazione viene mantenuta anche se carichi o metti in coda una playlist diversa. Se quindi carichi una playlist, chiami la funzione setLoop con il valore true e successivamente carichi una seconda playlist, anche la seconda playlist sarà in loop.

Il parametro obbligatorio loopPlaylists identifica il comportamento di loop.

  • Se il valore del parametro è true, il video player riproduce le playlist in modo continuo. Dopo la riproduzione dell'ultimo video della playlist, il video player tornerà all'inizio della playlist e ricomincerà la riproduzione.

  • Se il valore del parametro è false, il video player terminerà la riproduzione dopo l'ultimo video della playlist.

player.setShuffle(shufflePlaylist:Boolean):Void

Questa funzione indica se i video di una playlist devono seguire una riproduzione casuale, e quindi un ordine diverso da quello indicato dal creatore della playlist. Se imposti la riproduzione casuale a riproduzione già iniziata, l'elenco verrà riordinato durante la riproduzione del video corrente. Il video successivo verrà quindi selezionato in base al nuovo elenco.

Questa impostazione non viene mantenuta se carichi o metti in coda una playlist diversa. Se quindi carichi una playlist, chiami la funzione setShuffle e successivamente carichi una seconda playlist, la seconda playlist non seguirà una riproduzione casuale.

Il parametro obbligatorio shufflePlaylist indica se YouTube deve applicare la riproduzione casuale alla playlist.

  • Se il valore del parametro è true, YouTube applicherà alla playlist la riproduzione casuale. Se indichi alla funzione di riprodurre in ordine casuale una playlist già in riproduzione casuale, YouTube applicherà un nuovo ordine casuale.

  • Se il valore del parametro è false, YouTube ripristinerà l'ordine iniziale per la playlist.

Stato della riproduzione

player.getVideoLoadedFraction():Float
Restituisce un numero compreso tra 0 e 1 che indica la percentuale del video inserita nel buffer. Questo metodo restituisce un numero più affidabile dei metodi getVideoBytesLoaded e getVideoBytesTotal, ormai obsoleti.
player.getPlayerState():Number
Restituisce lo stato del player. I valori possibili sono:
  • -1 – unstarted
  • 0 – ended
  • 1 – playing
  • 2 – paused
  • 3 – buffering
  • 5 – video cued
player.getCurrentTime():Number
Restituisce il tempo trascorso in secondi da quando è iniziata la riproduzione del video.
player.getVideoStartBytes():Number
Metodo obsoleto dal 31 ottobre 2012. Restituisce il numero di byte da cui è partito il caricamento del file video. Ormai questo metodo restituisce sempre il valore 0. Scenario di esempio: l'utente vuole passare a un punto non ancora caricato e il player effettua una nuova richiesta per riprodurre un segmento del video non ancora caricato.
player.getVideoBytesLoaded():Number
Metodo obsoleto dal 18 luglio 2012. Per stabilire la percentuale del video inserita nel buffer puoi usare il metodo alternativo getVideoLoadedFraction.

Questo metodo restituisce un valore compreso tra 0 e 1000 che rappresenta in modo approssimativo la porzione del video caricata. Puoi anche calcolare la frazione caricata del video dividendo il valore di getVideoBytesLoaded per il valore di getVideoBytesTotal.
player.getVideoBytesTotal():Number
Metodo obsoleto dal 18 luglio 2012. Per stabilire la percentuale del video inserita nel buffer puoi usare il metodo alternativo getVideoLoadedFraction.

Restituisce le dimensioni in byte del video attualmente caricato o in riproduzione oppure un valore approssimativo delle dimensioni del video.

Questo metodo restituisce sempre il valore 1000. Puoi anche calcolare la frazione caricata del video dividendo il valore di getVideoBytesLoaded per il valore di getVideoBytesTotal.

Qualità della riproduzione

player.getPlaybackQuality():String
Questa funzione consente di recuperare la qualità effettiva del video corrente. I valori restituiti possono essere highres, hd1080, hd720, large, medium e small. In assenza di un video corrente, viene restituito anche il valore undefined.
player.setPlaybackQuality(suggestedQuality:String):Void
Questa funzione consente di impostare la qualità consigliata per il video corrente. La funzione fa in modo che il video venga ricaricato alla posizione corrente con la nuova qualità. Se la qualità della riproduzione cambia, cambierà solo per il video in riproduzione. La chiamata di questa funzione non garantisce il cambio effettivo della qualità della riproduzione. Tuttavia, se la qualità di riproduzione cambia, viene attivato l'evento onPlaybackQualityChange e il codice deve rispondere all'evento anziché alla chiamata della funzione setPlaybackQuality.

Il valore del parametro suggestedQuality può essere small, medium, large, hd720, hd1080, highres o default. Ti consigliamo di impostare il valore del parametro su default, che indica a YouTube di selezionare la qualità di riproduzione più appropriata, la quale varia in base ai diversi utenti, video, sistemi e altre condizioni di riproduzione.

Quando consigli una qualità di riproduzione per un video, questa verrà applicata solo a quel video. Devi selezionare una qualità di riproduzione che corrisponda alle dimensioni del video player. Ad esempio, se la pagina visualizza un video player da 1280 x 720 px, un video con qualità hd720 si presenterà meglio di un video con qualità hd1080. Ti consigliamo di chiamare la funzione getAvailableQualityLevels() per determinare quali livelli di qualità sono disponibili per un video.

L'elenco riportato di seguito mostra i livelli di qualità della riproduzione che corrispondono alle diverse dimensioni standard del player. Ti consigliamo di impostare l'altezza del video player su uno dei valori riportati di seguito e di impostare le proporzioni 16:9. Come indicato in precedenza, anche se scegli le dimensioni standard del player, ti consigliamo di impostare il valore default per il parametro suggestedQuality per consentire a YouTube di selezionare la qualità di riproduzione più appropriata.

  • Livello di qualità small: l'altezza del player è 240 px e le dimensioni sono almeno 320 x 240 px con proporzioni 4:3.
  • Livello di qualità medium: l'altezza del player è 360 px e le dimensioni sono 640 x 360 px (con proporzioni 16:9) o 480 x 360 px (con proporzioni 4:3).
  • Livello di qualità large: l'altezza del player è 480 px e le dimensioni sono 853 x 480 px (con proporzioni 16:9) o 640 x 480 px (con proporzioni 4:3).
  • Livello di qualità hd720: l'altezza del player è 720 px e le dimensioni sono 1280 x 720 px (con proporzioni 16:9) o 960 x 720 px (con proporzioni 4:3).
  • Livello di qualità hd1080: l'altezza del player è 1080 px e le dimensioni sono 1920 x 1080 px (con proporzioni 16:9) o 1440 x 1080 px (con proporzioni 4:3).
  • Livello di qualità highres: l'altezza del player è superiore a 1080 px, il che significa che le proporzioni del player sono superiori a 1920 x 1080 px.
  • Livello di qualità default: YouTube seleziona la qualità di riproduzione appropriata. Questa impostazione ripristina in modo efficace il livello di qualità allo stato predefinito, annullando i tentativi precedenti di impostare la qualità della riproduzione usando le funzioni cueVideoById, loadVideoById o setPlaybackQuality.

Se chiami la funzione setPlaybackQuality con un livello suggestedQuality non disponibile per il video, la qualità verrà impostata al livello successivo più basso che risulta disponibile. Ad esempio, se richiedi il livello di qualità large che non è disponibile, la qualità di riproduzione verrà impostata su medium (purché sia disponibile).

Inoltre, l'impostazione della funzione suggestedQuality su un valore che non corrisponde a un livello di qualità riconosciuto equivale a impostare la funzione suggestedQuality sul valore default.
player.getAvailableQualityLevels():Array
Questa funzione restituisce l'insieme dei formati di qualità disponibili per il video corrente. Puoi usare questa funzione per determinare se il video è disponibile in una qualità superiore rispetto a quella in cui l'utente lo sta visualizzando e il player potrebbe visualizzare un pulsante o un altro elemento per consentire all'utente di regolare la qualità.

La funzione restituisce un array di stringhe ordinate dalla qualità più alta alla più bassa. I valori possibili per gli elementi dell'array sono highres, hd1080, hd720, large, medium e small. Questa funzione restituisce un array vuoto in assenza di un video corrente.

Il client non deve passare automaticamente alla qualità video più alta (o più bassa) o a nomi di formato sconosciuti. YouTube può espandere l'elenco dei livelli di qualità, includendo formati non appropriati al contesto del tuo player. In modo analogo, YouTube può rimuovere le opzioni di qualità potenzialmente controproducenti per l'esperienza utente. Se fai in modo che il client passi solo a formati noti e disponibili, sarai sicuro che le prestazioni non verranno compromesse dall'introduzione o dalla rimozione di livelli di qualità non appropriati del player.

Recupero delle informazioni sui video

player.getDuration():Number
Restituisce la durata in secondi del video in riproduzione. Il valore getDuration() restituisce 0 fino al caricamento dei metadati del video, cosa che di solito accade subito dopo l'inizio della riproduzione.

Se il video in riproduzione è un evento dal vivo, la funzione getDuration() restituisce il tempo trascorso dall'inizio della riproduzione in streaming del video dal vivo. Nello specifico, si tratta della durata della riproduzione in streaming del video senza reimpostazioni o interruzioni. Inoltre, questa durata è in genere superiore alla durata effettiva dell'evento, perché la riproduzione in streaming può iniziare prima dell'ora di inizio dell'evento.
player.getVideoUrl():String
Restituisce l'URL YouTube.com per il video attualmente caricato o in riproduzione.
player.getVideoEmbedCode():String
Restituisce il codice di incorporamento per il video attualmente caricato o in riproduzione.

Recupero delle informazioni sulla playlist

player.getPlaylist():Array
Questa funzione restituisce un array degli ID video nella playlist in base all'ordine attuale. Per impostazione predefinita, questa funzione restituisce gli ID video nell'ordine definito dal proprietario della playlist. Tuttavia, se hai chiamato la funzione setShuffle per la riproduzione casuale della playlist, il valore restituito dalla funzione getPlaylist() rispecchierà l'ordine casuale.
player.getPlaylistIndex():Number
Questa funzione restituisce l'indice del video della playlist attualmente in riproduzione.
  • Se non hai impostato la riproduzione casuale per la playlist, il valore restituito identificherà la posizione che il creatore della playlist ha assegnato al video. Il valore restituito usa un indice in base zero, quindi il valore 0 identifica il primo video della playlist.

  • Se hai impostato la riproduzione casuale per la playlist, il valore restituito identifica l'ordine del video nella playlist con riproduzione casuale.

Aggiunta o rimozione di un listener di eventi

player.addEventListener(event:String, listener:String):Void
Consente di aggiungere una funzione listener per l'elemento event specificato. La sezione Eventi riportata di seguito identifica i diversi eventi che il player può attivare. L'elemento listener è una stringa che specifica la funzione che viene eseguita quando si attiva l'evento specificato.
player.removeEventListener(event:String, listener:String):Void
Consente di rimuovere una funzione listener per l'elemento event specificato. L'elemento listener è una stringa che identifica la funzione che non viene più eseguita quando si attiva l'evento specificato.

Accesso e modifica dei nodi DOM

player.getIframe():Object
Questo metodo restituisce il nodo DOM per l'elemento <iframe> incorporato.
player.destroy():Void
Consente di rimuovere l'elemento <iframe> contenente il player.

Eventi

L'API attiva gli eventi per comunicare all'applicazione le modifiche apportate al player incorporato. Come indicato nella sezione precedente, puoi iscriverti agli eventi aggiungendo un listener di eventi durante la costruzione dell'oggetto YT.Player e puoi anche utilizzare la funzione addEventListener.

L'API passa un oggetto evento come unico argomento a ognuna di queste funzioni. L'oggetto evento dispone delle seguenti proprietà:

  • La proprietà target dell'evento che identifica il video player corrispondente all'evento.
  • La proprietà data dell'evento che specifica un valore relativo all'evento. Tieni presente che l'evento onReady non specifica una proprietà data.

Il seguente elenco definisce gli eventi attivati dall'API:

onReady
Questo evento viene attivato ogni volta che un player è pronto per iniziare a ricevere le chiamate API al termine del caricamento. L'applicazione deve implementare questa funzione se vuoi eseguire automaticamente determinate operazioni, ad esempio la riproduzione o la visualizzazione delle informazioni di un video non appena il player è pronto.

L'esempio seguente mostra una funzione di esempio per la gestione di questo evento. L'oggetto evento che l'API passa alla funzione dispone di una proprietà target che identifica il player. La funzione recupera il codice di incorporamento del video attualmente caricato, avvia la riproduzione del video e visualizza il codice di incorporamento nell'elemento della pagina con embed-code come valore dell'id.
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
Questo evento viene attivato ogni volta che lo stato del player cambia. La proprietà data dell'oggetto evento che l'API passa alla tua funzione listener di eventi specifica un valore intero che corrisponde al nuovo stato del player. I valori possibili sono:

  • -1 (unstarted)
  • 0 (ended)
  • 1 (playing)
  • 2 (paused)
  • 3 (buffering)
  • 5 (video cued).

Quando il player carica per la prima volta un video, trasmette un evento unstarted (-1). Quando un video viene messo in coda ed è pronto per la riproduzione, il player trasmette un evento video cued (5). Nel tuo codice puoi specificare i valori interi oppure utilizzare una delle seguenti variabili con spazi dei nomi:

  • YT.PlayerState.ENDED
  • YT.PlayerState.PLAYING
  • YT.PlayerState.PAUSED
  • YT.PlayerState.BUFFERING
  • YT.PlayerState.CUED

onPlaybackQualityChange
Questo evento viene attivato ogni volta che la qualità di riproduzione del video cambia. Ad esempio, se chiami la funzione setPlaybackQuality(suggestedQuality), questo evento viene attivato quando la qualità di riproduzione cambia effettivamente. L'applicazione deve rispondere all'evento e non deve presupporre che la qualità cambi automaticamente quando viene chiamata la funzione setPlaybackQuality(suggestedQuality). In modo analogo, il codice non deve presupporre che la qualità di riproduzione cambi solo in caso di chiamata esplicita a setPlaybackQuality o a qualsiasi altra funzione che consenta di impostare una qualità di riproduzione consigliata.

Il valore della proprietà data dell'oggetto evento che l'API passa alla funzione listener di eventi sarà una stringa che identifica la nuova qualità di riproduzione. I valori possibili sono:

  • small
  • medium
  • large
  • hd720
  • hd1080
  • highres

onPlaybackRateChange
Questo evento viene attivato ogni volta che la velocità di riproduzione del video cambia. Ad esempio, chiamando la funzione setPlaybackRate(suggestedRate), questo evento viene attivato se la velocità di riproduzione cambia effettivamente. L'applicazione deve rispondere all'evento e non deve presupporre che la velocità di riproduzione cambi automaticamente quando viene chiamata la funzione setPlaybackRate(suggestedRate). In modo analogo, il codice non deve presupporre che la velocità di riproduzione del video cambi solo in caso di chiamata esplicita alla funzione setPlaybackRate.

Il valore della proprietà data dell'oggetto evento che l'API passa alla funzione listener di eventi sarà un numero che identifica la nuova velocità di riproduzione. Il metodo getAvailablePlaybackRates restituisce un elenco di velocità di riproduzione valide per il video attualmente in riproduzione o in coda.
onError
Questo evento viene attivato se si verifica un errore nel player. L'API passa un oggetto event alla funzione listener di eventi. La proprietà data dell'oggetto specifica un numero intero che identifica il tipo di errore che si è verificato. I valori possibili sono:

  • 2 - La richiesta contiene un valore del parametro non valido. Questo errore si verifica ad esempio se specifichi un ID video che non ha una lunghezza di 11 caratteri o se l'ID video contiene caratteri non validi, come punti esclamativi o asterischi.
  • 5 - Non è possibile riprodurre i contenuti richiesti in un player HTML5 oppure si è verificato un altro errore relativo al player HTML5.
  • 100 - Il video richiesto non è stato trovato. Questo errore si verifica quando un video è stato rimosso (per un motivo qualsiasi) o è stato contrassegnato come privato.
  • 101 - Il proprietario del video richiesto non ne consente la riproduzione in player incorporati.
  • 150 - Questo errore è analogo al 101. Si presenta soltanto in modo diverso rispetto all'errore 101.

onApiChange
L'evento viene attivato per indicare che il player ha caricato (o scaricato) un modulo con metodi API esposti. L'applicazione può rimanere in attesa dell'evento e quindi eseguire il polling del player per stabilire quali sono le opzioni esposte per il modulo caricato di recente. A questo punto l'applicazione può recuperare o aggiornare le impostazioni esistenti per tali opzioni.

Il seguente comando recupera un array di nomi di moduli per cui puoi impostare le opzioni del player:
player.getOptions();
Attualmente puoi impostare le opzioni solo per il modulo cc, che gestisce i sottotitoli nel player. Alla ricezione di un evento onApiChange, l'applicazione può usare il seguente comando per definire quali opzioni possono essere impostate per il modulo cc:
player.getOptions('cc');
Se esegui il polling del player con questo comando, puoi accertarti che le opzioni a cui vuoi accedere siano effettivamente accessibili. I seguenti comandi consentono di recuperare e aggiornare le opzioni dei moduli:
Recupero di un'opzione:
player.getOption(module, option);

Impostazione di un'opzione
player.setOption(module, option, value);
La tabella riportata di seguito elenca le opzioni supportate dall'API:

Modulo Opzione Descrizione
cc fontSize Questa opzione consente di regolare le dimensioni del carattere dei sottotitoli visualizzati nel player.

I valori validi sono -1, 0, 1, 2 e 3. La dimensione predefinita è 0, mentre la più piccola è -1. Se imposti questa opzione su un numero intero inferiore a -1 verrà applicata la dimensione più piccola per i sottotitoli, mentre impostando questa opzione su un numero intero superiore a 3 verrà applicata la dimensione più grande per i sottotitoli.
cc reload Questa opzione consente di ricaricare i dati dei sottotitoli per il video in riproduzione. Il valore sarà null se recuperi il valore dell'opzione. Imposta il valore su true per ricaricare i dati dei sottotitoli.

Considerazioni sui dispositivi mobili

Riproduzione automatica e riproduzione con script

L'elemento <video> di HTML5, in alcuni browser per dispositivi mobili (ad esempio Chrome e Safari), consente solo la riproduzione avviata da un'interazione utente (ad esempio toccando il player). Ecco un estratto della documentazione Apple:

"Attenzione: per evitare download non richiesti sulle reti cellulari a spese dell'utente, non è possibile riprodurre automaticamente gli elementi multimediali incorporati in Safari nei dispositivi iOS. La riproduzione deve essere sempre avviata dall'utente".

A causa di questa limitazione, funzioni e parametri quali autoplay, playVideo(), loadVideoById() non funzionano in tutti gli ambienti mobili.

Esempi

Creazione di oggetti YT.Player

  • Esempio 1: riproduzione a volume elevato

    Questo esempio consente di creare un video player da 1280 x 720 pixel. Il listener di eventi per l'evento onReady chiama quindi la funzione setVolume per impostare il volume massimo.

    function onYouTubeIframeAPIReady() {
      var player;
      player = new YT.Player('player', {
        width: 1280,
        height: 720,
        videoId: 'M7lc1UVf-VE',
        events: {
          'onReady': onPlayerReady,
          'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
          'onStateChange': onPlayerStateChange,
          'onError': onPlayerError
        }
      });
    }
    
    function onPlayerReady(event) {
      event.target.setVolume(100);
      event.target.playVideo();
    }
  • Esempio 2: questo esempio consente di impostare i parametri del player per avviare la riproduzione automatica del video al termine del caricamento e per nascondere i controlli del video player. Aggiunge anche listener di eventi per tutti gli eventi trasmessi dall'API.

    function onYouTubeIframeAPIReady() {
      var player;
      player = new YT.Player('player', {
        videoId: 'M7lc1UVf-VE',
        playerVars: { 'autoplay': 1, 'controls': 0 },
        events: {
          'onReady': onPlayerReady,
          'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
          'onStateChange': onPlayerStateChange,
          'onError': onPlayerError
        }
      });
    }

Cronologia revisioni

Questa sezione contiene le modifiche apportate all'IFrame Player API di YouTube e gli aggiornamenti alla documentazione. Iscriviti a questo log delle modifiche. Subscribe

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

  • The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

July 23, 2013

This update contains the following changes:

  • The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.

October 31, 2012

This update contains the following changes:

  • The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

    In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)

  • When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.

  • The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

  • The example in the Loading a video player section that demonstrates how to manually create the <iframe> tag has been updated to include a closing </iframe> tag since the onYouTubeIframeAPIReady function is only called if the closing </iframe> element is present.

August 6, 2012

This update contains the following changes:

  • The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.

  • The API supports several new functions and one new event that can be used to control the video playback speed:

    • Functions

      • getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
      • getPlaybackRate – Retrieve the playback rate for the cued or playing video.
      • setPlaybackRate – Set the playback rate for the cued or playing video.

    • Events

July 19, 2012

This update contains the following changes:

  • The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.

  • The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.

  • The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

    Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.

  • The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

  • The Operations section now explains that the API supports the setSize() and destroy() methods. The setSize() method sets the size in pixels of the <iframe> that contains the player and the destroy() method removes the <iframe>.

June 6, 2012

This update contains the following changes:

  • We have removed the experimental status from the IFrame Player API.

  • The Loading a video player section has been updated to point out that when inserting the <iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.

    In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

March 30, 2012

This update contains the following changes:

  • The Operations section has been updated to explain that the IFrame API supports a new method, getIframe(), which returns the DOM node for the IFrame embed.

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size.