Panoramica
In questo documento viene illustrato come incorporare il player di YouTube in un'applicazione e vengono definiti i parametri disponibili nel player incorporato di YouTube.
Aggiungendo alcuni parametri in coda all'URL del IFrame, puoi personalizzare l'esperienza di riproduzione offerta nell'applicazione. Il parametro autoplay
, ad esempio, consente di riprodurre automaticamente i video, mentre il parametro loop
determina la riproduzione reiterata di un video. Con il parametro enablejsapi
puoi inoltre abilitare la JavaScript API per il player.
In questa pagina sono definiti tutti i parametri supportati in qualsiasi player incorporato di YouTube. La definizione di ciascun parametro identifica i player che lo supportano.
Nota. 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.
Incorporamento di un player di YouTube
Best practice: per l'incorporamento di un player di YouTube ti consigliamo di utilizzare IFrame. IFrame, infatti, seleziona il player più adatto in base alle funzionalità del client e ai formati disponibili per i file di YouTube.
Per incorporare un player di YouTube in un'applicazione e specificarne i parametri, puoi scegliere uno dei seguenti metodi. Tieni presente che le istruzioni riportate di seguito spiegano come incorporare un player per il caricamento di un solo video. Fai riferimento alla sezione successiva per configurare il player in modo che carichi altri tipi di contenuti, ad esempio playlist e risultati di ricerca.
Incorporamenti IFrame con i tag <iframe>
Nell'applicazione definisci un tag <iframe>
in cui l'URL src
specifica i contenuti che verranno caricati dal player, nonché tutti gli altri parametri da impostare. I parametri height
e width
del tag <iframe>
specificano le dimensioni del player.
Se stai creando l'elemento <iframe>
da zero (senza utilizzare IFrame Player API), puoi aggiungere i parametri del player direttamente alla fine dell'URL. L'URL avrà quindi il seguente formato:
http://www.youtube.com/embed/VIDEO_ID
Il tag <iframe>
riportato qui sotto consente di caricare un player da 640 x 360 px per la riproduzione del video di YouTube M7lc1UVf-VE
. Dal momento che l'URL imposta il parametro autoplay
su 1
, il video si avvia automaticamente dopo il caricamento del player.
<iframe id="ytplayer" type="text/html" width="640" height="360" src="http://www.youtube.com/embed/M7lc1UVf-VE?autoplay=1&origin=http://example.com" frameborder="0"/>
Incorporamenti IFrame con IFrame Player API
Per inserire un video player nell'applicazione o nella pagina web dopo il caricamento del codice JavaScript di Player API, segui le istruzioni per l'IFrame Player API. Il secondo parametro nel costruttore per il video player è un oggetto che specifica le opzioni del player. All'interno di tale oggetto i parametri del player sono identificati dalla proprietà playerVars
.
In questo codice HTML e JavaScript di esempio, un player di YouTube viene inserito nell'elemento della pagina che presenta ytplayer
come valore id
. La funzione onYouTubePlayerAPIReady()
qui specificata viene chiamata automaticamente dopo il caricamento del codice dell'IFrame Player API. Questo codice non definisce i parametri del player o altri gestori eventi.
<div id="ytplayer"></div> <script> // Load the IFrame Player API code asynchronously. var tag = document.createElement('script'); tag.src = "https://www.youtube.com/player_api"; var firstScriptTag = document.getElementsByTagName('script')[0]; firstScriptTag.parentNode.insertBefore(tag, firstScriptTag); // Replace the 'ytplayer' element with an <iframe> and // YouTube player after the API code downloads. var player; function onYouTubePlayerAPIReady() { player = new YT.Player('ytplayer', { height: '360', width: '640', videoId: 'M7lc1UVf-VE' }); } </script>
Selezione dei contenuti da riprodurre
Puoi configurare il player incorporato in modo che carichi un video, una playlist, i video caricati da un utente o i risultati della ricerca per una query specifica.
Queste opzioni sono illustrate nell'elenco di seguito:
-
Caricamento di un video
Per un incorporamento IFrame, l'ID del video di YouTube che si desidera caricare è specificato nell'URL
src
di IFrame.http://www.youtube.com/embed/VIDEO_ID
Se utilizzi la YouTube Data API (v3), puoi creare questi URL a livello di codice recuperando gli ID dei video dai risultati di ricerca, dalle risorse degli elementi delle playlist, dalle risorse video o da altre risorse ancora. Dopo aver acquisito l'ID del video, inserisci tale valore al posto del testo
VIDEO_ID
negli URL riportati sopra per creare l'URL del player. -
Caricamento di una playlist
Imposta il parametro
listType
del player suplaylist
. Inoltre il parametrolist
deve essere impostato sull'ID della playlist
di YouTube che vuoi caricare.http://www.youtube.com/embed?listType=playlist&list=PLAYLIST_ID
Ricorda che è necessario anteporre le lettere
PL
all'ID della playlist, come illustrato nell'esempio seguente:http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6
Se utilizzi la YouTube Data API (v3), puoi creare questi URL a livello di codice recuperando gli ID delle playlist dai risultati di ricerca, dalle risorse canale o dalle risorse attività. Una volta ottenuto l'ID della playlist, inserisci tale valore al posto del testo
PLAYLIST_ID
nell'URL riportato sopra. -
Caricamento dei video caricati da un utente
Imposta il parametro
listType
del player suuser_uploads
. Il parametrolist
deve inoltre essere impostato sul nome utente di YouTube a cui appartengono i video che vuoi caricare.http://www.youtube.com/embed?listType=user_uploads&list=USERNAME
-
Caricamento dei risultati della ricerca per una query specifica
Imposta il parametro
listType
del player susearch
. Il parametrolist
deve inoltre essere impostato sul termine della query i cui risultati di ricerca devono essere caricati dal player.http://www.youtube.com/embed?listType=search&list=QUERY
Parametri
Tutti i parametri descritti di seguito sono facoltativi.
Parameters | |
---|---|
|
Valori: 0 o 1 . Il valore predefinito è 0 . Consente di abilitare o disabilitare l'avvio automatico del video iniziale al caricamento del player.
|
|
Valori: 1 . Il valore predefinito si basa sulla preferenza dell'utente. Se è impostato su 1 , i sottotitoli vengono visualizzati per impostazione predefinita anche se l'utente li ha disabilitati.
|
|
Questo parametro consente di specificare il colore che verrà utilizzato nella barra di avanzamento del player per evidenziare la percentuale già visualizzata del video. I valori validi per questo parametro sono red e white , ma per impostazione predefinita il player utilizzerà il colore rosso nella barra di avanzamento del video. Per ulteriori informazioni sui colori disponibili, consulta il blog su YouTube API.Nota. Se imposti il parametro color su white , l'opzione modestbranding verrà disabilitata.
|
|
Valori: 0 , 1 o 2 . Il valore predefinito è 1 . Questo parametro indica se abilitare o disabilitare la visualizzazione dei controlli del video player. Per gli incorporamenti IFrame che prevedono il caricamento di un Flash player, consente anche di definire quando vengono visualizzati i controlli e quando viene caricato il player:
1 e 2 del parametro hanno lo scopo di fornire un'esperienza utente identica, controls=2 offre un miglioramento delle prestazioni rispetto a controls=1 per gli incorporamenti IFrame. Al momento però i due valori conferiscono al player un aspetto leggermente diverso (variano, ad esempio, le dimensioni del carattere del titolo del video). Se la differenza tra i due valori risulta impercettibile per l'utente, il valore predefinito del parametro può variare da 1 a 2 .
|
|
Valori: 0 o 1 . Il valore predefinito è 0 . Se imposti questo parametro su 1 , i controlli da tastiera verranno disattivati. I controlli da tastiera sono i seguenti:
|
|
Valori: 0 o 1 . Il valore predefinito è 0 . Se imposti questo parametro su 1 , abiliti la Javascript API. Per ulteriori informazioni sulla Javascript API e sul suo utilizzo, consulta la documentazione della JavaScript API.
|
|
Valori: un numero intero positivo. Questo parametro specifica l'intervallo di tempo, espresso in secondi a partire dall'avvio del video, dopo il quale il player deve interrompere la riproduzione. Tieni presente che l'intervallo non viene misurato a partire dal valore del parametro start del player o del parametro startSeconds , utilizzati nelle funzioni della YouTube Player API per il caricamento o l'accodamento di un video, bensì viene calcolato in base all'inizio del video.
|
|
Valori: 0 o 1 . Il valore predefinito è 1 e determina la visualizzazione del pulsante a schermo intero. Se imposti questo parametro su 0 , il pulsante a schermo intero non viene visualizzato. |
|
Consente di impostare la lingua di interfaccia del player. Il valore del parametro corrisponde a un codice lingua ISO 639-1 di due lettere, ma possono essere compatibili anche altri codici di immissione lingua, ad esempio i tag di lingua IETF (BCP 47). Oltre a essere utilizzata per le descrizioni dei comandi, la lingua di interfaccia influisce anche sulla traccia predefinita dei sottotitoli. Tieni presente che in base alle preferenze linguistiche individuali e alla disponibilità delle tracce dei sottotitoli, YouTube potrebbe selezionare una traccia diversa per uno specifico utente. |
|
Valori: 1 o 3 . Il valore predefinito è 1 . Il valore 1 abilita la visualizzazione predefinita delle annotazioni video, mentre il valore 3 la disabilita.
|
|
Il parametro list , in combinazione con il parametro listType , identifica i contenuti che verranno caricati nel player.
list e listType , non è necessario includere un ID video nell'URL dell'incorporamento IFrame.
|
|
Il parametro listType , in combinazione con il parametro list , identifica i contenuti che verranno caricati nel player. I valori validi per questo parametro sono playlist , search e user_uploads .Se specifichi un valore per i parametri list e listType , non è necessario includere un ID video nell'URL dell'incorporamento IFrame.
|
|
Valori: 0 o 1 . Il valore predefinito è 0 . Nel caso di un player con un singolo video, il valore 1 determinerà la riproduzione continua di tale video. Se invece il player è personalizzato o riproduce una playlist, dopo la riproduzione completa della playlist verrà avviato di nuovo il primo video.Nota. Questo parametro è supportato solo parzialmente nel player AS3 e negli incorporamenti IFrame, che possono essere caricati con player AS3 o HTML5. Il parametro loop attualmente può essere utilizzato nel player AS3 solo in combinazione con il parametro playlist . Per ripetere un video a ciclo continuo, devi impostare il valore del parametro loop su 1 e quindi impostare il valore del parametro playlist in base all'ID video specificato nell'URL della Player API:http://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID |
|
Questo parametro ti permette di utilizzare un player di YouTube senza il logo di YouTube. Se imposti il valore del parametro su 1 , il logo di YouTube non viene visualizzato nella barra di controllo. Tieni presente che, se il video è in pausa, al passaggio del mouse sul player viene comunque visualizzata una piccola etichetta di testo con la dicitura YouTube nell'angolo in alto a destra.
|
|
Questo parametro, supportato solo per gli incorporamenti IFrame, fornisce una misura di sicurezza aggiuntiva per l'IFrame API. Se utilizzi l'IFrame API, e quindi hai impostato il parametro enablejsapi su 1 , devi sempre specificare il tuo dominio come valore del parametro origin .
|
|
Questo valore è costituito dall'elenco degli ID, separati da virgole, dei video da riprodurre. Se si specifica un valore, il primo video a essere riprodotto sarà quello corrispondente al valore VIDEO_ID indicato nel percorso dell'URL, mentre i video relativi al parametro playlist verranno riprodotti successivamente.
|
|
Questo parametro controlla se la riproduzione di un video avviene in linea o a schermo intero in un player HTML5 su iOS. I valori validi sono:
|
|
Valori: 0 o 1 . Il valore predefinito è 1 . Questo parametro indica se mostrare nel player i video correlati al termine della riproduzione del video iniziale.
|
|
Valori: 0 o 1 . Per questo parametro il valore predefinito è 1 . Se imposti il valore del parametro su 0 , il player non mostrerà determinate informazioni, ad esempio il titolo del video e l'autore del caricamento, prima dell'avvio della riproduzione.Nel caso di un player per una playlist, se imposti esplicitamente il valore di questo parametro su 1 , durante il caricamento verranno visualizzate anche le immagini delle miniature dei video inclusi nella playlist. Questa funzionalità è supportata soltanto per il player AS3, l'unico in grado di caricare una playlist.
|
|
Valori: un numero intero positivo. In base a questo parametro, il player avvia la riproduzione del video dopo un dato intervallo di tempo, espresso in secondi, dall'inizio del video. Come nel caso della funzione seekTo , il player individuerà il fotogramma chiave più vicino al valore temporale specificato. Ciò significa che talvolta la testina di riproduzione potrebbe posizionarsi immediatamente prima del momento richiesto, in genere non più di due secondi prima.
|
Cronologia revisioni
October 14, 2014
-
The HTML5 player now supports the
cc_load_policy
,disablekb
,end
,fs
,list
, andlistType
parameters. The parameter descriptions have been updated accordingly.
July 18, 2014
-
The new
hl
parameter can be used to set the player's interface language. The interface language is used for tooltips in the player and also affects the default caption track. The selected caption track may also depend on the availability of caption tracks and user's individual language preferences.The parameter's value is an ISO 639-1 two-letter language code, though other language input codes, such as IETF language tags (BCP 47) may also be handled properly.
-
The definition of the
playsinline
parameter, which only affects HTML5 players on iOS, has been modified slightly. The definition now notes that setting the parameter value to1
causes inline playback only forUIWebViews
created with theallowsInlineMediaPlayback
property set toTRUE
.
January 28, 2014
-
The
playsinline
parameter controls whether videos play inline or fullscreen in an HTML5 player on iOS. Setting the value to1
causes inline playback. -
The Selecting content to play section has been updated to explain how to find YouTube video IDs and playlist IDs using the YouTube Data API (v3) rather than the older API version.
-
The
controls
parameter's definition has been updated to reflect the fact that the parameter value only affects the time that the Flash player actually loads in IFrame embeds. In addition, for IFrame embeds, the parameter value also determines when the controls display in the player. If you set the parameter's value to2
, then the controls display and the Flash player loads after the user initiates the video playback.
May 10, 2013
This update contains the following changes:
-
YouTube no longer identifies experimental API features and services. Instead, we now provide a list of YouTube APIs that are subject to the deprecation policy.
July 20, 2012
This update contains the following changes:
-
The definition of the
controls
parameter has been updated to reflect support for a parameter value of2
and to explain that, for AS3 players, the parameter value determines the time when the Flash player actually loads. If thecontrols
parameter is set to0
or1
, the Flash player loads immediately. If the parameter value is2
, the Flash player does not load until the video playback is initiated.
June 5, 2012
This update contains the following changes:
-
The HTML5 player now supports the
color
,modestbranding
, andrel
parameters, and the definitions for these parameters have been updated accordingly. -
The definition of the
showinfo
parameter has been updated to explain how that if the player is loading a playlist, and you explicitly set the parameter value to1
, then, upon loading, the player will also display thumbnail images for the videos in the playlist. Note that this functionality is only supported for the AS3 player since that is the only player that can load a playlist.
May 4, 2012
This update contains the following changes:
-
The
showinfo
parameter's definition has been updated to reflect the fact that the HTML5 player supports this parameter.
May 3, 2012
This update contains the following changes:
-
The new
end
parameter specifies the time, measured in seconds from the start of the video, when the player should stop playing a video. Note that the time when playback is stopped is measured from the beginning of the video and not from the value of either thestart
player parameter or thestartSeconds
parameter, which is used in YouTube Player API functions for loading or queueing a video.
March 29, 2012
This update contains the following changes:
-
The new Embedding a YouTube player section explains different ways to embed a YouTube player in your application. This section covers manual IFrame embeds, IFrame embeds that use the IFrame Player API, and AS3 and AS2 object embeds. This section incorporates information from the old Example usage section, which has been removed.
-
The new Selecting content to play section explains how to configure the player to load a video, a playlist, search results for a specified query, or uploaded videos for a specified user.
-
The new
list
andlistType
parameters let you specify the content that the player should load. You can specify a playlist, a search query, or a particular user's uploaded videos. -
The definitions of the
fs
andrel
parameters have been updated to more clearly explain the default parameter values for the AS3 player. -
The
border
,color1
,egm
,hd
, andshowsearch
parameters, which are all only supported for the deprecated AS2 Player API, have been moved to a new section named deprecated parameters only used in the AS2 Player API. -
The document no longer provides a way to filter the parameter list to only display parameters supported in either the AS3, AS2, or HTML5 player. Instead, each parameter definition has been updated to identify the players that support that parameter.
August 11, 2011
This update contains the following changes:
-
The new
theme
andcolor
parameters let you customize the appearance of the embedded player's player controls. See the YouTube API blog for more information.
June 8, 2011
This update contains the following changes:
-
The new
modestbranding
parameter lets you use a YouTube player that does not show a YouTube logo. As of this release, the parameter was only supported for the AS3 embedded player and for IFrame embeds that loaded the AS3 player. As of June 5, 2012, the HTML5 player also supported this parameter.
February 14, 2011
This update contains the following changes:
-
The documentation has been updated to note that the AS2 Player API has been deprecated. The deprecation of the AS2 Player API was actually announced on October 14, 2009.
February 3, 2011
This update contains the following changes:
-
The documentation has been updated to identify parameters supported in the HTML5 (IFrame) embedded player.
-
The document now displays all of the parameters supported in any of YouTube's embedded players (HTML5, AS3, AS2).
-
The following parameters are supported in the AS2 player but have been deprecated for the newer AS3 and HTML5 players:
border
,color1
,color2
,egm
,hd
, andshowsearch
.In addition, the
loop
parameter has limited support in the AS3 player and in IFrame embeds, which could load either an AS3 or HTML player. Currently, theloop
parameter only works in the AS3 player when used in conjunction with theplaylist
parameter. To loop a single video, set theloop
parameter to1
and set theplaylist
parameter value to the same video ID already specified in the Player API URL:http://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID
Similarly, the
controls
andplaylist
parameters are supported in the AS3 and HTML5 players but are not and will not be supported in the AS2 player.As noted above, IFrame embeds can load either an AS3 or HTML5 player. Though some parameters are not supported in both players, an IFrame embed that loads the AS3 player will support all parameters that work with that player and ignore all other parameters. Similarly, an IFrame embed that loads the HTML5 player will support all parameters that work with that player while ignoring all other parameters.
-
The parameter list has been updated to include the
autohide
parameter, which indicates whether the player's video controls will automatically hide after a video begins playing. -
The parameter list has been updated to include the
controls
parameter, which indicates whether the player's video controls will display at all. (Player controls do display by default.) -
The parameter list has been updated to include the
playlist
parameter, which specifies a comma-separated list of video IDs to play. -
The definition of the
fs
has been updated to note that the fullscreen option will not work if you load the YouTube player into another SWF. -
The example at the end of the document has been updated to use the embedded AS3 player instead of the embedded AS2 player. The parameters used in the example have also been updated to only include parameters that the AS3 player supports.
In addition, the instructions for constructing the URLs that contain player parameters have been updated to reflect the URL formats used by the AS3 and AS2 embedded and chromeless players as well as by the HTML5 player.