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.

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 ascoltatori di eventi che verranno eseguiti in risposta a determinati eventi del player, ad esempio una modifica dello stato del player.

Questa guida spiega come utilizzare l'API IFrame. Identifica i diversi tipi di eventi che l'API può inviare e spiega come scrivere ascoltatori di eventi per rispondere a questi 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

Il browser dell'utente deve supportare la funzionalità HTML5 postMessage. La maggior parte dei browser moderni supporta postMessage.

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 chiamerà questa funzione al termine del download del codice JavaScript per l'API del player, consentendoti di utilizzarla nella tua pagina. In questo modo la funzione può creare gli oggetti player che intendi visualizzare al caricamento della pagina.

Per iniziare

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: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          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 nella pagina in cui l'API IFrame inserirà il video player. Il costruttore dell'oggetto player, descritto nella sezione Caricare un video player, identifica il tag <div> tramite il relativo id per assicurarsi che l'API inserisca il <iframe> nella posizione corretta. Nello specifico, l'API IFrame sostituirà il tag <div> con il tag <iframe>.

    In alternativa, puoi anche inserire l'elemento <iframe> direttamente nella pagina. La sezione Caricare un video player spiega come procedere.

  2. Il codice in questa sezione consente di caricail 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 discusso in questa risposta di Stack Overflow.

  3. La funzione onYouTubeIframeAPIReady verrà eseguita non appena il codice API del player viene scaricato. Questa parte di codice definisce una variabile globale, player, che fa riferimento al video player che stai incorporando e la funzione costruisce l'oggetto video player.

  4. La funzione onPlayerReady verrà 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 chiamerà la funzione onPlayerStateChange quando cambia lo stato del player, il che può indicare che il player è in riproduzione, in pausa, terminato e così via. La funzione indica che quando lo stato del player è 1 (riproduzione), il player deve riprodurre per sei secondi e poi chiamare la funzione stopVideo per interrompere il video.

Caricamento di un video player

Dopo il caricamento del codice JavaScript dell'API, l'API chiamerà la funzione onYouTubeIframeAPIReady, a quel punto potrai creare un oggetto YT.Player per inserire un video player nella tua pagina. L'estratto HTML riportato di seguito mostra la funzione onYouTubeIframeAPIReady dell'esempio precedente:

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '390',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      'playsinline': 1
    },
    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'API IFrame sostituirà l'elemento specificato con l'elemento <iframe> contenente il player. Ciò potrebbe influire sul layout della 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 è 390.
    • videoId (stringa): l'ID 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 personalizzare il player.
    • events (oggetto): le proprietà dell'oggetto identificano gli eventi attivati dall'API e le funzioni (event listener) che l'API chiamerà quando si verificano questi eventi. Nell'esempio, il costruttore indica che la funzione onPlayerReady verrà eseguita quando viene attivato l'evento onReady e che la funzione onPlayerStateChange verrà eseguita quando viene attivato l'evento onStateChange.

Come accennato nella sezione Introduzione, anziché scrivere un elemento <div> vuoto nella pagina, che il codice JavaScript dell'API del player sostituirà con un elemento <iframe>, puoi creare autonomamente il tag <iframe>. Il primo esempio nella sezione Esempi mostra come eseguire questa operazione.

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

Tieni presente che, se scrivi il tag <iframe>, quando crei l'oggetto YT.Player non devi specificare valori per width e height, che sono specificati come attributi del tag <iframe>, o per i parametri videoId e del player, che sono specificati nell'URL src. Come misura di sicurezza aggiuntiva, devi includere anche il parametro origin nell'URL, specificando lo schema dell'URL (http:// o https://) e il dominio completo della pagina host come valore del parametro. Sebbene origin sia facoltativo, la sua inclusione protegge la tua pagina dall'inserimento di codice JavaScript dannoso di terze parti e dal controllo del player di YouTube.

Per altri esempi di creazione di oggetti video player, consulta la sezione Esempi.

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 Introduzione e Caricare 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 utilizzi la sintassi dell'oggetto descritta di seguito per chiamare queste funzioni, puoi anche mettere in coda o caricare un elenco dei 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 degli oggetti

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

Funzioni di accodamento per i video

cueVideoById

  • Sintassi dell'argomento

    player.cueVideoById(videoId:String,
                    startSeconds:Number):Void

  • Sintassi degli oggetti

    player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number}):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 il file FLV finché non viene chiamato playVideo() o seekTo().

  • Il parametro obbligatorio videoId specifica l'ID video di YouTube del video da riprodurre. Nell'API YouTube Data, la proprietà id di una risorsa video specifica l'ID.
  • Il parametro facoltativo startSeconds accetta un valore float/intero e specifica il momento in cui deve iniziare la riproduzione del video quando viene chiamato playVideo(). Se specifichi un valore startSeconds e poi chiami seekTo(), il player riproduce i contenuti a partire dal momento specificato nella chiamata seekTo(). Quando il video è pronto per essere riprodotto, il player trasmette un evento video cued (5).
  • Il parametro facoltativo endSeconds, supportato solo nella sintassi dell'oggetto, accetta un valore float/intero e specifica il momento in cui deve interrompersi la riproduzione del video quando viene chiamato playVideo(). Se specifichi un valore endSeconds e poi chiami seekTo(), il valore endSeconds non sarà più in vigore.

loadVideoById

  • Sintassi dell'argomento

    player.loadVideoById(videoId:String,
                     startSeconds:Number):Void

  • Sintassi degli oggetti

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

Questa funzione consente di caricare e riprodurre il video specificato.

  • Il parametro obbligatorio videoId specifica l'ID video di YouTube del video da riprodurre. Nell'API YouTube Data, la proprietà id di una risorsa video specifica l'ID.
  • Il parametro facoltativo startSeconds accetta un valore float/intero. Se specificato, il video inizierà dal fotogramma chiave più vicino al punto specificato.
  • Il parametro facoltativo endSeconds accetta un valore float/intero. Se specificato, la riproduzione del video verrà interrotta nel punto indicato.

cueVideoByUrl

  • Sintassi dell'argomento

    player.cueVideoByUrl(mediaContentUrl:String,
                     startSeconds:Number):Void

  • Sintassi degli oggetti

    player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number}):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 il file FLV finché non viene chiamato playVideo() o seekTo().

  • Il parametro mediaContentUrl obbligatorio specifica un URL del player di YouTube completo nel formato http://www.youtube.com/v/VIDEO_ID?version=3.
  • Il parametro facoltativo startSeconds accetta un valore float/intero e specifica il momento in cui deve iniziare la riproduzione del video quando viene chiamato playVideo(). Se specifichi startSeconds e poi chiami seekTo(), il player riproduce dal momento specificato nella chiamata seekTo(). Quando il video è a punto e pronto per essere riprodotto, il player trasmette un evento video cued (5).
  • Il parametro facoltativo endSeconds, supportato solo nella sintassi dell'oggetto, accetta un valore float/intero e specifica il momento in cui deve interrompersi la riproduzione del video quando viene chiamato playVideo(). Se specifichi un valore endSeconds e poi chiami seekTo(), il valore endSeconds non sarà più in vigore.

loadVideoByUrl

  • Sintassi dell'argomento

    player.loadVideoByUrl(mediaContentUrl:String,
                      startSeconds:Number):Void

  • Sintassi degli oggetti

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

Questa funzione consente di caricare e riprodurre il video specificato.

  • Il parametro mediaContentUrl obbligatorio specifica un URL del player di YouTube completo nel formato http://www.youtube.com/v/VIDEO_ID?version=3.
  • Il parametro facoltativo startSeconds accetta un valore float/intero e specifica il momento in cui deve iniziare la riproduzione del video. Se viene specificato startSeconds (il numero può essere un numero decimale), il video inizierà dal keyframe più vicino all'ora specificata.
  • Il parametro facoltativo endSeconds, supportato solo nella sintassi dell'oggetto, accetta un valore float/intero e specifica il momento in cui deve interrompersi la riproduzione del video.

Funzioni di accodamento per gli elenchi

Le funzioni cuePlaylist e loadPlaylist ti consentono di caricare e riprodurre una playlist. Se utilizzi la sintassi oggetto per chiamare queste funzioni, puoi anche mettere in coda (o caricare) un 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

  • Sintassi dell'argomento

    player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
     Mette in coda la playlist specificata. Quando la playlist è a punto ed è pronta per essere riprodotta, il player trasmette un evento video cued (5).

    • Il parametro obbligatorio playlist specifica un array di ID video di YouTube. Nell'API YouTube Data, la proprietà id della risorsa video identifica l'ID del video.

    • Il parametro facoltativo index specifica l'indice del primo video della playlist che verrà riprodotto. Il parametro utilizza un indice a partire da zero e il valore predefinito è 0, pertanto il comportamento predefinito è caricare e riprodurre il primo video della playlist.

    • Il parametro facoltativo startSeconds accetta un valore float/intero e specifica il momento a partire dal quale deve iniziare la riproduzione del primo video della playlist quando viene chiamata la funzione playVideo(). Se specifichi un valore startSeconds e poi chiami seekTo(), il player riproduce i contenuti a partire dal momento specificato nella chiamata seekTo(). Se cue una playlist e poi chiami la funzione playVideoAt(), il player inizierà a riprodurre il video specificato dall'inizio.

  • Sintassi degli oggetti

    player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
     Mette in coda l'elenco di video specificato. L'elenco può essere una playlist o il feed dei video caricati da un utente. La possibilità di mettere in coda un elenco di risultati di ricerca è deprecata e non sarà più supportata a partire dal 15 novembre 2020.

    Quando l'elenco è pronto per essere riprodotto, il player trasmette un evento video cued (5).

    • La proprietà facoltativa listType specifica il tipo di feed di risultati che stai recuperando. I valori validi sono playlist e user_uploads. A partire dal 15 novembre 2020, un valore deprecato, search, non sarà più supportato. Il valore predefinito è playlist.

    • La proprietà list obbligatoria contiene una chiave che identifica il particolare elenco di video 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. Nell'API YouTube Data, la proprietà id della risorsa playlist identifica l'ID di una playlist, mentre la proprietà id della risorsa video specifica un ID video.
      • Se il valore della proprietà listType è user_uploads, la proprietà list identifica l'utente i cui video caricati verranno restituiti.
      • Se il valore della proprietà listType è search, la proprietà list specifica la query di ricerca. Nota: questa funzionalità è ritirata e non sarà più supportata a partire dal 15 novembre 2020.

    • La proprietà facoltativa index specifica l'indice del primo video dell'elenco che verrà riprodotto. Il parametro utilizza un indice a partire da zero e il valore predefinito è 0, pertanto il comportamento predefinito è caricare e riprodurre il primo video nell'elenco.

    • La proprietà facoltativa startSeconds accetta un valore float/intero e specifica il momento a partire dal quale deve iniziare la riproduzione del primo video nell'elenco quando viene chiamata la funzione playVideo(). Se specifichi un valore startSeconds e poi chiami seekTo(), il player riproduce dal momento specificato nella chiamata seekTo(). Se inserisci un cue in un elenco e poi chiami la funzione playVideoAt(), il player inizierà a riprodurre il video specificato dall'inizio.

loadPlaylist

  • Sintassi dell'argomento

    player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
     Questa funzione carica e riproduce la playlist specificata.

    • Il parametro obbligatorio playlist specifica un array di ID video di YouTube. Nell'API di dati di YouTube, la proprietà id della risorsa video specifica un ID video.

    • Il parametro facoltativo index specifica l'indice del primo video della playlist che verrà riprodotto. Il parametro utilizza un indice a partire da zero e il valore predefinito è 0, pertanto il comportamento predefinito è caricare e riprodurre il primo video della playlist.

    • Il parametro facoltativo startSeconds accetta un valore float/intero e specifica l'ora a partire dalla quale deve iniziare la riproduzione del primo video nella playlist.

  • Sintassi degli oggetti

    player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
     Questa funzione carica e riproduce l'elenco specificato. L'elenco può essere una playlist o il feed dei video caricati da un utente. La possibilità di caricare un elenco di risultati di ricerca è deprecata e non sarà più supportata a partire dal 15 novembre 2020.

    • La proprietà facoltativa listType specifica il tipo di feed di risultati che stai recuperando. I valori validi sono playlist e user_uploads. A partire dal 15 novembre 2020, il valore deprecato search non sarà più supportato. Il valore predefinito è playlist.

    • La proprietà list obbligatoria contiene una chiave che identifica il particolare elenco di video che YouTube deve restituire.

      • Se il valore della proprietà listType è playlist, la proprietà list specifica un ID playlist o un array di ID video. Nell'API YouTube Data, la proprietà id della risorsa playlist specifica l'ID di una playlist, mentre la proprietà id della risorsa video specifica l'ID di un video.
      • Se il valore della proprietà listType è user_uploads, la proprietà list identifica l'utente i cui video caricati verranno restituiti.
      • Se il valore della proprietà listType è search, la proprietà list specifica la query di ricerca. Nota: questa funzionalità è ritirata e non sarà più supportata a partire dal 15 novembre 2020.

    • La proprietà facoltativa index specifica l'indice del primo video dell'elenco che verrà riprodotto. Il parametro utilizza un indice a partire da zero e il valore predefinito è 0, pertanto il comportamento predefinito è caricare e riprodurre il primo video nell'elenco.

    • La proprietà facoltativa startSeconds accetta un valore float/intero e specifica il momento a partire dal quale deve iniziare la riproduzione del primo video nell'elenco.

Controlli per la riproduzione e impostazioni del player

Riproduzione di un video

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

Nota: una riproduzione viene conteggiata ai fini del conteggio ufficiale delle visualizzazioni di un video solo se viene avviata tramite un pulsante di riproduzione nativo nel player.
player.pauseVideo():Void
Mette in pausa il video in riproduzione. Lo stato finale del player dopo l'esecuzione di questa funzione sarà paused (2), a meno che il player non sia nello stato ended (0) al momento dell'esecuzione della funzione, nel qual caso lo stato del player non cambierà.
player.stopVideo():Void
Interrompe e annulla 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. Se vuoi mettere in pausa il video, devi solo chiamare la funzione pauseVideo. Se vuoi cambiare il video riprodotto dal 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 potrebbe impostare il player su qualsiasi stato di non riproduzione, tra cui ended (0), paused (2), video cued (5) o unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Vai a un momento 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 momento fino al quale deve avanzare il player.

    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.

  • Il parametro allowSeekAhead determina se il player effettuerà una nuova richiesta al server se il parametro allowSeekAhead specifica un momento non compreso nei dati video attualmente memorizzati nella cache.seconds

    Ti consigliamo di impostare questo parametro su false mentre l'utente trascina il mouse lungo la barra di avanzamento di un video e poi 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.

Controllare la riproduzione dei video a 360°

Nota:l'esperienza di riproduzione dei video a 360° è supportata in modo limitato sui dispositivi mobili. Sui dispositivi non supportati, i video a 360 gradi appaiono distorti e non esiste alcun modo supportato per modificare la prospettiva di visualizzazione, nemmeno tramite l'API, utilizzando i sensori di orientamento o rispondendo alle azioni di tocco/trascinamento sullo schermo del dispositivo.

player.getSphericalProperties():Object
Recupero delle proprietà che descrivono la prospettiva o la visualizzazione corrente dello spettatore per la riproduzione di un video. Inoltre:
  • Questo oggetto viene compilato solo per i video a 360°, chiamati anche video sferici.
  • Se il video corrente non è un video a 360 gradi o se la funzione viene chiamata da un dispositivo non supportato, la funzione restituisce un oggetto vuoto.
  • Sui dispositivi mobili supportati, se la proprietà enableOrientationSensor è impostata su true, questa funzione restituisce un oggetto in cui la proprietà fov contiene il valore corretto e le altre proprietà sono impostate su 0.
L'oggetto contiene le seguenti proprietà:
Proprietà
yaw Un numero nell'intervallo [0, 360] che rappresenta l'angolo orizzontale della visualizzazione in gradi, che riflette la misura in cui l'utente ruota la visualizzazione verso sinistra o verso destra. La posizione neutra, rivolta verso il centro del video nella sua proiezione equirettangolare, rappresenta 0° e questo valore aumenta man mano che lo spettatore gira a sinistra.
pitch Un numero compreso nell'intervallo [-90, 90] che rappresenta l'angolo verticale della visualizzazione in gradi e riflette la misura in cui l'utente regola la visualizzazione per guardare verso l'alto o verso il basso. La posizione neutra, rivolta verso il centro del video nella sua proiezione equirettangolare, rappresenta 0° e questo valore aumenta man mano che lo spettatore alza lo sguardo.
roll Un numero nell'intervallo [-180, 180] che rappresenta l'angolo di rotazione in senso orario o antiorario della visualizzazione in gradi. La posizione neutra, con l'asse orizzontale nella proiezione equirettangolare parallelo all'asse orizzontale della visualizzazione, rappresenta 0°. Il valore aumenta man mano che la visualizzazione ruota in senso orario e diminuisce man mano che ruota in senso antiorario.

Tieni presente che il player incorporato non presenta un'interfaccia utente per regolare l'inclinazione della visualizzazione. La rotazione può essere regolata in uno dei seguenti modi mutuamente esclusivi:
  1. Utilizza il sensore di orientamento in un browser mobile per fornire il roll per la visualizzazione. Se il sensore di orientamento è attivo, la funzione getSphericalProperties restituisce sempre 0 come valore della proprietà roll.
  2. Se il sensore di orientamento è disattivato, imposta l'inclinazione su un valore diverso da zero utilizzando questa API.
fov Un numero compreso nell'intervallo [30, 120] che rappresenta il campo visivo della visualizzazione in gradi misurato lungo il lato più lungo dell'area visibile. Il lato più corto viene regolato automaticamente in modo da essere proporzionale alle proporzioni della visualizzazione.

Il valore predefinito è 100 gradi. Se diminuisci il valore, aumenti lo zoom sui contenuti video, mentre se lo aumenti, lo diminuisci. Questo valore può essere modificato utilizzando l'API o la rotellina del mouse quando il video è in modalità a schermo intero.
player.setSphericalProperties(properties:Object):Void
Imposta l'orientamento del video per la riproduzione di un video a 360°. Se il video corrente non è sferico, il metodo non esegue alcuna operazione, indipendentemente dall'input.

La visualizzazione del player risponde alle chiamate a questo metodo aggiornandosi in base ai valori di eventuali proprietà note nell'oggetto properties. La vista mantiene i valori per tutte le altre proprietà note non incluse nell'oggetto.

Inoltre:
  • Se l'oggetto contiene proprietà sconosciute e/o inaspettate, il player le ignora.
  • Come indicato all'inizio di questa sezione, l'esperienza di riproduzione dei video a 360° non è supportata su tutti i dispositivi mobili.
  • Per impostazione predefinita, sui dispositivi mobili supportati questa funzione imposta solo la proprietà fov e non influisce sulle proprietà yaw, pitch e roll per le riproduzioni di video a 360 gradi. Per ulteriori dettagli, consulta la proprietà enableOrientationSensor riportata di seguito.
L'oggetto properties passato alla funzione contiene le seguenti proprietà:
Proprietà
yaw Vedi la definizione sopra.
pitch Vedi la definizione sopra.
roll Vedi la definizione sopra.
fov Vedi la definizione sopra.
enableOrientationSensor Nota: questa proprietà influisce sull'esperienza di visualizzazione a 360° solo sui dispositivi supportati. Un valore booleano che indica se l'iframe incorporato deve rispondere a eventi che segnalano cambiamenti nell'orientamento di un dispositivo supportato, ad esempio DeviceOrientationEvent di un browser mobile. Il valore predefinito del parametro è true.

Dispositivi mobili supportati
  • Quando il valore è true, un player incorporato si basa solo sul movimento del dispositivo per regolare le proprietà yaw, pitch e roll per la riproduzione di video a 360°. Tuttavia, la proprietà fov può comunque essere modificata tramite l'API, che è infatti l'unico modo per modificare la proprietà fov su un dispositivo mobile. Questo è il comportamento predefinito.
  • Se il valore è false, il movimento del dispositivo non influisce sull'esperienza di visualizzazione a 360° e le proprietà yaw, pitch, roll e fov devono essere impostate tramite l'API.

Dispositivi mobili non supportati
Il valore della proprietà enableOrientationSensor non ha alcun effetto sull'esperienza di riproduzione.

Riproduzione di un video in una playlist

player.nextVideo():Void
Questa funzione carica e riproduce il video successivo nella playlist.

  • Se player.nextVideo() viene chiamato durante la visualizzazione dell'ultimo video della playlist e la playlist è impostata sulla riproduzione continua (loop), il player caricherà e riprodurrà il primo video dell'elenco.

  • Se player.nextVideo() viene chiamato durante la visione dell'ultimo video della playlist e la playlist non è impostata per la riproduzione continua, la riproduzione termina.

player.previousVideo():Void
Questa funzione carica e riproduce il video precedente nella playlist.

  • Se player.previousVideo() viene chiamato mentre viene guardato il primo video della playlist e la playlist è impostata sulla riproduzione continua (loop), il player caricherà e riprodurrà l'ultimo video dell'elenco.

  • Se player.previousVideo() viene chiamato durante la visione del primo video della playlist e la playlist non è impostata per la riproduzione continua, il player riavvierà il primo video della playlist dall'inizio.

player.playVideoAt(index:Number):Void
Questa funzione carica e riproduce il video specificato nella playlist.

  • Il parametro obbligatorio index specifica l'indice del video che vuoi riprodurre nella playlist. Il parametro utilizza un indice a partire da zero, pertanto un valore pari a 0 identifica il primo video nell'elenco. Se hai messo in riproduzione casuale la playlist, questa funzione riprodurrà il video nella posizione specificata nella playlist in riproduzione casuale.

Modifica del volume del player

player.mute():Void
Disattiva l'audio del player.
player.unMute():Void
Riattiva l'audio del player.
player.isMuted():Boolean
Restituisce true se l'audio del player è disattivato, false in caso contrario.
player.setVolume(volume:Number):Void
Imposta il volume. Accetta un numero intero compreso tra 0 e 100.
player.getVolume():Number
Restituisce il volume corrente del player, un numero intero compreso tra 0 e 100. Tieni presente che getVolume() restituisce il volume anche se il player è disattivato.

Impostazione delle dimensioni del player

player.setSize(width:Number, height:Number):Object
Imposta le dimensioni in pixel del <iframe> che contiene il player.

Impostazione della velocità di riproduzione

player.getPlaybackRate():Number
Questa funzione recupera la velocità di riproduzione del video attualmente in riproduzione. La velocità di riproduzione predefinita è 1, il che indica che il video viene riprodotto a velocità normale. Le frequenze di riproduzione possono includere valori come 0.25, 0.5, 1, 1.5 e 2.
player.setPlaybackRate(suggestedRate:Number):Void
Questa funzione imposta 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 a cui è stato associato un cue, questa velocità rimarrà in vigore quando viene chiamata la funzione playVideo o quando l'utente avvia la riproduzione direttamente tramite i controlli del player. Inoltre, le chiamate alle funzioni per mettere in coda o caricare video o playlist (cueVideoById, loadVideoById e così via) reimpostano la velocità di riproduzione su 1.

L'attivazione di questa funzione non garantisce che la velocità di riproduzione cambi effettivamente. Tuttavia, se la velocità di riproduzione cambia, viene attivato l'evento onPlaybackRateChange e il codice deve rispondere all'evento anziché al fatto che ha chiamato la funzione setPlaybackRate.

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

La funzione restituisce un array di numeri ordinati dalla velocità di riproduzione più lenta a quella più veloce. Anche se il player non supporta 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 cue una playlist diversa, il che significa che se carichi una playlist, chiami la funzione setLoop con un valore di true e poi carichi una seconda playlist, anche la seconda playlist verrà riprodotta in loop.

Il parametro loopPlaylists obbligatorio identifica il comportamento di ripetizione.

  • Se il valore del parametro è true, il video player riprodurrà continuamente le playlist. 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, le riproduzioni terminano dopo che il video player ha riprodotto l'ultimo video di una 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 dall'autore 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 inserisci in coda una playlist diversa, il che significa che se carichi una playlist, chiami la funzione setShuffle e poi carichi una seconda playlist, la seconda playlist non verrà mescolata.

Il parametro shufflePlaylist obbligatorio indica se YouTube deve riprodurre la playlist in modalità casuale.

  • Se il valore del parametro è true, YouTube mescola l'ordine della playlist. 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 originale della playlist.

Stato della riproduzione

player.getVideoLoadedFraction():Float
Restituisce un numero compreso tra 0 e 1 che specifica la percentuale del video mostrata dal player come memorizzata nella cache. Questo metodo restituisce un numero più affidabile rispetto ai metodi getVideoBytesLoaded e getVideoBytesTotal ora non più supportati.
player.getPlayerState():Number
Restituisce lo stato del player. I valori possibili sono:
  • -1 – non avviata
  • 0 – ended
  • 1 – playing
  • 2 – paused
  • 3 – buffering
  • 5 – video cued
player.getCurrentTime():Number
Restituisce il tempo trascorso in secondi dall'inizio della riproduzione del video.
player.getVideoStartBytes():Number
Ritiro previsto per il 31 ottobre 2012. Restituisce il numero di byte da cui è partito il caricamento del file video. (Questo metodo ora restituisce sempre un valore 0.) Scenario di esempio: l'utente esegue la ricerca in avanti fino 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
Ritiro previsto per il 18 luglio 2012. Utilizza invece il metodo getVideoLoadedFraction per determinare la percentuale di video memorizzata nella cache.

Questo metodo restituisce un valore compreso tra 0 e 1000 che approssima la quantità di video caricata. Puoi calcolare la frazione del video caricata dividendo il valore getVideoBytesLoaded per il valore getVideoBytesTotal.
player.getVideoBytesTotal():Number
Ritiro previsto per il 18 luglio 2012. Utilizza invece il metodo getVideoLoadedFraction per determinare la percentuale di video memorizzata nella cache.

Restituisce le dimensioni in byte del video attualmente caricato/riprodotto o un'approssimazione delle dimensioni del video.

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

Recupero delle informazioni sui video

player.getDuration():Number
Restituisce la durata in secondi del video attualmente in riproduzione. Tieni presente che getDuration() restituirà 0 finché non verranno caricati i metadati del video, cosa che di solito avviene subito dopo l'inizio della riproduzione.

Se il video attualmente in riproduzione è un evento dal vivo, la funzione getDuration() restituisce il tempo trascorso dall'inizio dello stream 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 di YouTube.com del video attualmente caricato/riprodotto.
player.getVideoEmbedCode():String
Restituisce il codice di incorporamento del video attualmente caricato/riprodotto.

Recupero delle informazioni sulla playlist

player.getPlaylist():Array
Questa funzione restituisce un array degli ID video nella playlist nell'ordine in cui sono attualmente disposti. Per impostazione predefinita, questa funzione restituisce gli ID video nell'ordine definito dal proprietario della playlist. Tuttavia, se hai chiamato la funzione setShuffle per mescolare l'ordine della playlist, il valore restituito dalla funzione getPlaylist() rifletterà l'ordine mescolato.
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
Aggiunge una funzione di ascoltatore per event specificato. La sezione Eventi di seguito identifica i diversi eventi che il player potrebbe 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
Rimuove una funzione di listener per event specificato. listener è una stringa che identifica la funzione che non verrà più eseguita quando viene attivato l'evento specificato.

Accesso e modifica dei nodi DOM

player.getIframe():Object
Questo metodo restituisce il nodo DOM per il <iframe> incorporato.
player.destroy():Void
Rimuove il <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 gestore 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à:

  • Il valore target dell'evento identifica il video player corrispondente all'evento.
  • data dell'evento specifica un valore pertinente all'evento. Tieni presente che gli eventi onReady e onAutoplayBlocked non specificano una proprietà data.

Il seguente elenco definisce gli eventi attivati dall'API:

onReady
Questo evento viene attivato ogni volta che un player ha completato il caricamento ed è pronto per iniziare a ricevere chiamate API. La tua applicazione deve implementare questa funzione se vuoi eseguire automaticamente determinate operazioni, come riprodurre il video o visualizzare informazioni sul 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 ha una proprietà target che identifica il player. La funzione recupera il codice di incorporamento del video attualmente caricato, avvia la riproduzione del video e mostra il codice di incorporamento nell'elemento della pagina con un valore id pari a embed-code. 
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 cambia lo stato del player. La proprietà data dell'oggetto evento che l'API passa alla funzione di ascoltatore di eventi specifica un numero intero che corrisponde al nuovo stato del player. I valori possibili sono:

  • -1 (non avviato)
  • 0 (ended)
  • 1 (playing)
  • 2 (in pausa)
  • 3 (buffering)
  • 5 (video cued).

Quando il player carica un video per la prima volta, trasmette un evento unstarted (-1). Quando un video è a punto ed è pronto per essere riprodotto, il player emette 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. Potrebbe indicare una modifica nell'ambiente di riproduzione dello spettatore. Per ulteriori informazioni sui fattori che influiscono sulle condizioni di riproduzione o che potrebbero attivare l'evento, consulta il Centro assistenza YouTube.

Il valore della proprietà data dell'oggetto evento che l'API passa alla funzione di ascoltatore 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, se chiami la funzione setPlaybackRate(suggestedRate), questo evento viene attivato se la velocità di riproduzione cambia effettivamente. L'applicazione deve rispondere all'evento e non deve presumere che la velocità di riproduzione cambierà automaticamente quando viene chiamata la funzione setPlaybackRate(suggestedRate). Analogamente, il codice non deve presupporre che la frequenza di riproduzione dei video cambierà solo in seguito a una chiamata esplicita a setPlaybackRate.

Il valore della proprietà data dell'oggetto evento che l'API passa alla funzione di ascoltatore di eventi sarà un numero che identifica la nuova velocità di riproduzione. Il metodo getAvailablePlaybackRates restituisce un elenco delle frequenze 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 passerà un oggetto event alla funzione di ascoltatore 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. È solo un errore 101 mascherato.
onApiChange
Questo 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 i quali puoi impostare le opzioni del player:
player.getOptions();
 Al momento, l'unico modulo per cui puoi impostare le opzioni è il modulo captions, che gestisce i sottotitoli codificati nel player. Al ricevimento di un evento onApiChange, l'applicazione può utilizzare il seguente comando per determinare quali opzioni possono essere impostate per il modulo captions:
player.getOptions('captions');
 Effettuando il polling del player con questo comando, puoi verificare che le opzioni a cui vuoi accedere siano effettivamente accessibili. I seguenti comandi recuperano e aggiornano le opzioni del modulo:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
 Nella tabella seguente sono elencate le opzioni supportate dall'API:

Modulo Opzione Descrizione
sottotitoli fontSize Questa opzione regola le dimensioni dei caratteri dei sottotitoli codificati visualizzati nel player.

I valori validi sono -1, 0, 1, 2 e 3. La dimensione predefinita è 0, mentre la dimensione minima è -1. Se imposti questa opzione su un numero intero inferiore a -1, verranno visualizzate le dimensioni dei sottotitoli codificati più piccole, mentre se imposti questa opzione su un numero intero superiore a -1, verranno visualizzate le dimensioni dei sottotitoli codificati più grandi.3
sottotitoli 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 codificati.
onAutoplayBlocked
Questo evento viene attivato ogni volta che il browser blocca le funzionalità di riproduzione automatica o di riproduzione di video basati su script, collectively referred to as "autoplay". Sono incluse le riproduzioni tentate con una delle seguenti API di player:

La maggior parte dei browser dispone di criteri che possono bloccare la riproduzione automatica su computer, dispositivi mobili e altri ambienti se si verificano determinate condizioni. Le istanze in cui questo criterio può essere attivato includono la riproduzione con audio riattivato senza interazione dell'utente o quando non è stato impostato un criterio di autorizzazione per consentire la riproduzione automatica in un iframe cross-origin.

Per informazioni dettagliate, consulta le norme specifiche del browser (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) e la guida all'autoplay di Mozilla.

Esempi

Creazione di oggetti YT.Player

  • Esempio 1: utilizza l'API con <iframe> esistente

    In questo esempio, un elemento <iframe> nella pagina definisce già il player con cui verrà utilizzata l'API. Tieni presente che l'URL src del player deve impostare il parametro enablejsapi su 1 o l'attributo enablejsapi dell'elemento <iframe> deve essere impostato su true.

    La funzione onPlayerReady cambia il colore del bordo attorno al player in arancione quando il player è pronto. La funzione onPlayerStateChange cambia quindi il colore del bordo attorno al player in base allo stato corrente del player. Ad esempio, il colore è verde quando il player è in riproduzione, rosso quando è in pausa, blu durante il buffering e così via.

    Questo esempio utilizza il seguente codice:

    <iframe id="existing-iframe-example"
        width="640" height="360"
        src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1"
        frameborder="0"
        style="border: solid 4px #37474F"
></iframe>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player('existing-iframe-example', {
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange
        }
    });
  }
  function onPlayerReady(event) {
    document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00';
  }
  function changeBorderColor(playerStatus) {
    var color;
    if (playerStatus == -1) {
      color = "#37474F"; // unstarted = gray
    } else if (playerStatus == 0) {
      color = "#FFFF00"; // ended = yellow
    } else if (playerStatus == 1) {
      color = "#33691E"; // playing = green
    } else if (playerStatus == 2) {
      color = "#DD2C00"; // paused = red
    } else if (playerStatus == 3) {
      color = "#AA00FF"; // buffering = purple
    } else if (playerStatus == 5) {
      color = "#FF6DOO"; // video cued = orange
    }
    if (color) {
      document.getElementById('existing-iframe-example').style.borderColor = color;
    }
  }
  function onPlayerStateChange(event) {
    changeBorderColor(event.data);
  }
</script>

  • Esempio 2: Riproduzione ad alto volume

    Questo esempio consente di creare un video player da 1280 x 720 pixel. L'ascoltatore di eventi per l'evento onReady chiama quindi la funzione setVolume per regolare il volume sull'impostazione più alta.

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

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

  • Esempio 3: questo esempio imposta i parametri del player in modo che il video venga riprodotto automaticamente al caricamento e che i controlli del video player vengano nascosti. Aggiunge inoltre listener di eventi per diversi eventi trasmessi dall'API.

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

Controllare i video a 360°

Questo esempio utilizza il seguente codice:

<style>
  .current-values {
    color: #666;
    font-size: 12px;
  }
</style>
<!-- The player is inserted in the following div element -->
<div id="spherical-video-player"></div>

<!-- Display spherical property values and enable user to update them. -->
<table style="border: 0; width: 640px;">
  <tr style="background: #fff;">
    <td>
      <label for="yaw-property">yaw: </label>
      <input type="text" id="yaw-property" style="width: 80px"><br>
      <div id="yaw-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="pitch-property">pitch: </label>
      <input type="text" id="pitch-property" style="width: 80px"><br>
      <div id="pitch-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="roll-property">roll: </label>
      <input type="text" id="roll-property" style="width: 80px"><br>
      <div id="roll-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="fov-property">fov: </label>
      <input type="text" id="fov-property" style="width: 80px"><br>
      <div id="fov-current-value" class="current-values"> </div>
    </td>
    <td style="vertical-align: bottom;">
      <button id="spherical-properties-button">Update properties</button>
    </td>
  </tr>
</table>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov'];
  var updateButton = document.getElementById('spherical-properties-button');

  // Create the YouTube Player.
  var ytplayer;
  function onYouTubeIframeAPIReady() {
    ytplayer = new YT.Player('spherical-video-player', {
        height: '360',
        width: '640',
        videoId: 'FAtdv94yzp4',
    });
  }

  // Don't display current spherical settings because there aren't any.
  function hideCurrentSettings() {
    for (var p = 0; p < PROPERTIES.length; p++) {
      document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = '';
    }
  }

  // Retrieve current spherical property values from the API and display them.
  function updateSetting() {
    if (!ytplayer || !ytplayer.getSphericalProperties) {
      hideCurrentSettings();
    } else {
      let newSettings = ytplayer.getSphericalProperties();
      if (Object.keys(newSettings).length === 0) {
        hideCurrentSettings();
      } else {
        for (var p = 0; p < PROPERTIES.length; p++) {
          if (newSettings.hasOwnProperty(PROPERTIES[p])) {
            currentValueNode = document.getElementById(PROPERTIES[p] +
                                                       '-current-value');
            currentValueNode.innerHTML = ('current: ' +
                newSettings[PROPERTIES[p]].toFixed(4));
          }
        }
      }
    }
    requestAnimationFrame(updateSetting);
  }
  updateSetting();

  // Call the API to update spherical property values.
  updateButton.onclick = function() {
    var sphericalProperties = {};
    for (var p = 0; p < PROPERTIES.length; p++) {
      var propertyInput = document.getElementById(PROPERTIES[p] + '-property');
      sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value);
    }
    ytplayer.setSphericalProperties(sphericalProperties);
  }
</script>

Integrazione dell'API Android WebView Media Integrity

YouTube ha esteso l'API Android WebView Media Integrity per consentire ai player multimediali incorporati, inclusi gli incorporamenti del player di YouTube nelle applicazioni Android, di verificare l'autenticità dell'app di incorporamento. Con questa modifica, le app incorporate inviano automaticamente a YouTube un ID app verificato. I dati raccolti tramite l'utilizzo di questa API sono i metadati dell'app (nome del pacchetto, numero di versione e certificato di firma) e un token di attestazione del dispositivo generato da Google Play Services.

I dati vengono utilizzati per verificare l'integrità dell'applicazione e del dispositivo. Sono criptati, non vengono condivisi con terze parti ed eliminati al termine di un periodo di conservazione fisso. Gli sviluppatori di app possono configurare l'identità della propria app nell'API WebView Media Integrity. La configurazione supporta un'opzione di disattivazione.

Cronologia delle revisioni

June 24, 2024

The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 15 November 2020. After that time, calls to the cuePlaylist or loadPlaylist functions that set the listType property to search will generate a 4xx response code, such as 404 (Not Found) or 410 (Gone). This change also affects the list property for those functions as that property no longer supports the ability to specify a search query.

As an alternative, you can use the YouTube Data API's search.list method to retrieve search results and then load selected videos in the player.

October 24, 2019

The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.

The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:

  • The getPlaybackQuality, setPlaybackQuality, and getAvailableQualityLevels functions are no longer supported. In particular, calls to setPlaybackQuality will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience.
  • The queueing functions for videos and playlists -- cueVideoById, loadVideoById, etc. -- no longer support the suggestedQuality argument. Similarly, if you call those functions using object syntax, the suggestedQuality field is no longer supported. If suggestedQuality is specified, it will be ignored when the request is handled. It will not generate any warnings or errors.
  • The onPlaybackQualityChange event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.

May 16, 2018

The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:

  • The getSphericalProperties function retrieves the current orientation for the video playback. The orientation includes the following data:
    • yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
    • pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
    • roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
    • fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
  • The setSphericalProperties function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond to DeviceOrientationEvents on supported mobile devices.

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

  • Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.

August 11, 2016

This update contains the following changes:

  • The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

    The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

June 29, 2016

This update contains the following changes:

  • The documentation has been corrected to note that the onApiChange method provides access to the captions module and not the cc module.

June 24, 2016

The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe> element.

January 6, 2016

The clearVideo function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

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.