Parametri del player

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 su playlist. Inoltre il parametro list 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 su user_uploads. Il parametro list 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 su search. Il parametro list 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

autoplay

Valori: 0 o 1. Il valore predefinito è 0. Consente di abilitare o disabilitare l'avvio automatico del video iniziale al caricamento del player.

cc_load_policy

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.

color

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.

controls

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:

  • controls=0: i controlli del player non vengono visualizzati. Per gli incorporamenti IFrame, il Flash player viene caricato immediatamente.
  • controls=1: i controlli vengono visualizzati nel player. Per gli incorporamenti IFrame, la visualizzazione dei controlli del video e il caricamento del Flash player hanno luogo immediatamente.
  • controls=2: i controlli vengono visualizzati nel player. Per gli incorporamenti IFrame, la visualizzazione dei controlli del video e il caricamento del Flash player hanno luogo all'avvio della riproduzione.

Nota. Anche se i valori 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.

disablekb

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:

  • Barra spaziatrice: Play/Pausa
  • Freccia sinistra: Torna indietro del 10% nel video corrente
  • Freccia destra: Vai avanti del 10% nel video corrente
  • Freccia su: Alza volume
  • Freccia giù: Riduci volume

enablejsapi

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.

end

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.

fs

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.

hl

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.

iv_load_policy

Valori: 1 o 3. Il valore predefinito è 1. Il valore 1 abilita la visualizzazione predefinita delle annotazioni video, mentre il valore 3 la disabilita.

list

Il parametro list, in combinazione con il parametro listType, identifica i contenuti che verranno caricati nel player.

  • Se il valore del parametro listType è search, il valore del parametro list specificherà la query di ricerca.
  • Se il valore del parametro listType è user_uploads, il valore del parametro list identificherà il canale YouTube a cui appartengono i video che verranno caricati.
  • Se il valore del parametro listType è playlist, il valore del parametro list specificherà l'ID di una playlist di YouTube. Come illustrato nell'esempio qui sotto, è necessario anteporre le lettere PL all'ID della playlist.
    http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6

Nota. Se specifichi un valore per i parametri list e listType, non è necessario includere un ID video nell'URL dell'incorporamento IFrame.

listType

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.

loop

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

modestbranding

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.

origin

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.

playlist

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.

playsinline

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:

  • 0: questo valore attiva la riproduzione a schermo intero. Si tratta del valore predefinito, che è soggetto tuttavia a modifiche.
  • 1: questo valore attiva la riproduzione in linea per gli elementi UIWebViews creati impostando su TRUE la proprietà allowsInlineMediaPlayback.

rel

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.

showinfo

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.

start

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

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 to 1 causes inline playback only for UIWebViews created with the allowsInlineMediaPlayback property set to TRUE.

January 28, 2014

  • The playsinline parameter controls whether videos play inline or fullscreen in an HTML5 player on iOS. Setting the value to 1 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 to 2, 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:

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 of 2 and to explain that, for AS3 players, the parameter value determines the time when the Flash player actually loads. If the controls parameter is set to 0 or 1, the Flash player loads immediately. If the parameter value is 2, 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, and rel 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 to 1, 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 the start player parameter or the startSeconds 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 and listType 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 and rel parameters have been updated to more clearly explain the default parameter values for the AS3 player.

  • The border, color1, egm, hd, and showsearch 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 and color 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, and showsearch.

    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, the loop parameter only works in the AS3 player when used in conjunction with the playlist parameter. To loop a single video, set the loop parameter to 1 and set the playlist 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 and playlist 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.