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.
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:
-
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. -
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. -
La funzione
onYouTubeIframeAPIReady
viene eseguita non appena viene scaricato il codice della Player API. Questa parte del codice definisce la variabile globaleplayer
, che fa riferimento al video player che stai incorporando, e la funzione crea quindi l'oggetto video player. -
La funzione
onPlayerReady
viene eseguita quando viene attivato l'eventoonReady
. In questo esempio, la funzione indica che la riproduzione deve iniziare quando il video player è pronto. -
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 funzionestopVideo
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:
-
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 elementoinline-block
. - 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 funzioneonPlayerReady
verrà eseguita all'attivazione dell'eventoonReady
e che la funzioneonPlayerStateChange
verrà eseguita all'attivazione dell'eventoonStateChange
.
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()
oseekTo()
.- 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 funzioneplayVideo()
. Se specifichi un valorestartSeconds
e chiamiseekTo()
, il player inizia la riproduzione dal punto specificato nella chiamataseekTo()
. Quando il video viene messo in coda ed è pronto per la riproduzione, il player trasmette un eventovideo 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 funzioneplayVideo()
. Se specifichi un valoreendSeconds
e chiamiseekTo()
, il valoreendSeconds
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 funzionesetPlaybackQuality
.
-
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 funzionesetPlaybackQuality
.
-
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()
oseekTo()
.- Il parametro obbligatorio
mediaContentUrl
specifica un URL completo del player di YouTube nel formatohttp://www.youtube.com/v/VIDEO_ID?version=3
. Nei feed video di YouTube Data API, l'attributourl
del tag<media:content>
contiene un URL completo del player quando l'attributoformat
del tag ha il valore5
. - 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 funzioneplayVideo()
. Se specifichistartSeconds
e chiamiseekTo()
, il player inizia la riproduzione dal punto specificato nella chiamataseekTo()
. Quando il video viene messo in coda ed è pronto per la riproduzione, il player trasmette un eventovideo 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 funzioneplayVideo()
. Se specifichi un valoreendSeconds
e chiamiseekTo()
, il valoreendSeconds
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 funzionesetPlaybackQuality
.
-
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 formatohttp://www.youtube.com/v/VIDEO_ID?version=3
. Nei feed video di YouTube Data API, l'attributourl
del tag<media:content>
contiene un URL completo del player quando l'attributoformat
del tag ha il valore5
. - 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 parametrostartSeconds
(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 funzionesetPlaybackQuality
.
-
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
Consente di mettere in coda la playlist specificata. Quando la playlist viene messa in coda ed è pronta per la riproduzione, il player trasmette un eventoplayer.cuePlaylist(playlist:String|Array, index:Number, startSeconds:Number, suggestedQuality:String):Void
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 funzioneplayVideo()
. Se specifichi un valorestartSeconds
e chiamiseekTo()
, il player inizia la riproduzione dal punto specificato nella chiamataseekTo()
. Se metti in coda una playlist e chiami la funzioneplayVideoAt()
, 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 funzionesetPlaybackQuality
.
-
-
Sintassi dell'oggetto
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 eventoplayer.cuePlaylist({listType:String, list:String, index:Number, startSeconds:Number, suggestedQuality:String}):Void
video cued
(5
).-
La proprietà facoltativa
listType
specifica il tipo di feed dei risultati che stai recuperando. I valori validi sonoplaylist
,search
euser_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.
- Se il valore della proprietà
-
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 funzioneplayVideo()
. Se specifichi un valorestartSeconds
e chiamiseekTo()
, il player inizia la riproduzione dal punto specificato nella chiamataseekTo()
. Se metti in coda un elenco e chiami la funzioneplayVideoAt()
, 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 funzionesetPlaybackQuality
.
-
-
loadPlaylist
-
-
Argument syntax
Questa funzione consente di caricare la playlist specificata e di riprodurla.player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number, suggestedQuality:String):Void
-
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 funzionesetPlaybackQuality
.
-
-
Object syntax
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.player.loadPlaylist({list:String, listType:String, index:Number, startSeconds:Number, suggestedQuality:String}):Void
-
La proprietà facoltativa
listType
specifica il tipo di feed dei risultati che stai recuperando. I valori validi sonoplaylist
,search
euser_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.
- Se il valore della proprietà
-
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 funzionesetPlaybackQuality
.
-
-
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 siaended
(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 primastopVideo
.
Importante. A differenza della funzionepauseVideo
che lascia il player nello statopaused
(2
), la funzionestopVideo
può impostare il player in uno stato di "non riproduzione", comeended
(0
),paused
(2
),video cued
(5
) ounstarted
(-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'oggettoNetStream
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 parametroseconds
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 sutrue
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 valore0
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
e100
.
player.getVolume():Number
- Restituisce il volume attuale del player, un numero intero compreso tra
0
e100
.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 quali0.25
,0.5
,1
,1.5
e2
.
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 su1
.
Se chiami questa funzione non è garantito che la velocità di riproduzione cambi effettivamente. Tuttavia, se la velocità di riproduzione cambia, l'eventoonPlaybackRateChange
viene attivato e il codice deve rispondere all'evento anziché alla chiamata della funzionesetPlaybackRate
.
Il metodogetAvailablePlaybackRates
restituisce le velocità di riproduzione possibili per il video in riproduzione. Tuttavia, se imposti il parametrosuggestedRate
su un valore intero o decimale non supportato, il player lo arrotonda per difetto al valore supportato più vicino a1
.
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 valoretrue
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
e1
che indica la percentuale del video inserita nel buffer. Questo metodo restituisce un numero più affidabile dei metodigetVideoBytesLoaded
egetVideoBytesTotal
, ormai obsoleti.
player.getPlayerState():Number
- Restituisce lo stato del player. I valori possibili sono:
-1
– unstarted0
– ended1
– playing2
– paused3
– buffering5
– 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 tra0
e1000
che rappresenta in modo approssimativo la porzione del video caricata. Puoi anche calcolare la frazione caricata del video dividendo il valore digetVideoBytesLoaded
per il valore digetVideoBytesTotal
.
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 valore1000
. Puoi anche calcolare la frazione caricata del video dividendo il valore digetVideoBytesLoaded
per il valore digetVideoBytesTotal
.
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
esmall
. In assenza di un video corrente, viene restituito anche il valoreundefined
.
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 funzionesetPlaybackQuality
.
Il valore del parametrosuggestedQuality
può esseresmall
,medium
,large
,hd720
,hd1080
,highres
odefault
. Ti consigliamo di impostare il valore del parametro sudefault
, 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 funzionegetAvailableQualityLevels()
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 valoredefault
per il parametrosuggestedQuality
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 funzionicueVideoById
,loadVideoById
osetPlaybackQuality
.
setPlaybackQuality
con un livellosuggestedQuality
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 sumedium
(purché sia disponibile).
Inoltre, l'impostazione della funzionesuggestedQuality
su un valore che non corrisponde a un livello di qualità riconosciuto equivale a impostare la funzionesuggestedQuality
sul valoredefault
. - Livello di qualità
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 sonohighres
,hd1080
,hd720
,large
,medium
esmall
. 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()
restituisce0
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 funzionegetDuration()
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 funzionegetPlaylist()
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'elementolistener
è 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'eventoonReady
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 conembed-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).
unstarted
(-1
). Quando un video viene messo in coda ed è pronto per la riproduzione, il player trasmette un eventovideo 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 funzionesetPlaybackQuality(suggestedQuality)
. In modo analogo, il codice non deve presupporre che la qualità di riproduzione cambi solo in caso di chiamata esplicita asetPlaybackQuality
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 funzionesetPlaybackRate(suggestedRate)
. In modo analogo, il codice non deve presupporre che la velocità di riproduzione del video cambi solo in caso di chiamata esplicita alla funzionesetPlaybackRate
.
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 metodogetAvailablePlaybackRates
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 al101
. Si presenta soltanto in modo diverso rispetto all'errore101
.
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:
Attualmente puoi impostare le opzioni solo per il moduloplayer.getOptions();
cc
, che gestisce i sottotitoli nel player. Alla ricezione di un eventoonApiChange
, l'applicazione può usare il seguente comando per definire quali opzioni possono essere impostate per il modulocc
:
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:player.getOptions('cc');
La tabella riportata di seguito elenca le opzioni supportate dall'API:Recupero di un'opzione: player.getOption(module, option); Impostazione di un'opzione player.setOption(module, option, value);
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
e3
. 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 a3
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 sutrue
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 funzionesetVolume
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.
April 28, 2014
This update contains the following changes:
-
The new removeEventListener function lets you remove a listener for a specified event.
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 whenplayVideo()
is called. -
The
getVideoStartBytes
method has been deprecated. The method now always returns a value of0
.
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 theonYouTubeIframeAPIReady
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
onPlaybackRateChange
– This event fires when the video's playback rate changes.
-
July 19, 2012
This update contains the following changes:
-
The new
getVideoLoadedFraction
method replaces the now-deprecatedgetVideoBytesLoaded
andgetVideoBytesTotal
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 of5
, 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 namedonYouTubePlayerAPIReady
. 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 anonYouTubePlayerAPIReady
function, both functions will be called, and theonYouTubeIframeAPIReady
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()
anddestroy()
methods. ThesetSize()
method sets the size in pixels of the<iframe>
that contains the player and thedestroy()
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 aninline-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.