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

The HTML5 player now supports the cc_load_policy, disablekb, end, fs, list, and listType 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 to 1 causes inline playback only for UIWebViews created with the allowsInlineMediaPlayback property set to TRUE.