Paramètres du lecteur

Sommaire

Ce document présente la procédure à suivre pour intégrer un lecteur YouTube dans votre application et définit les paramètres disponibles pour celui-ci.

En ajoutant des paramètres à l'URL iFrame, vous pouvez également personnaliser la lecture de vidéos dans votre application. Par exemple, vous pouvez automatiquement lancer la lecture de vidéos via le paramètre autoplay ou répéter la lecture d'une seule vidéo via le paramètre loop. Vous pouvez également activer l'API JavaScript pour le lecteur à l'aide du paramètre enablejsapi.

Cette page définit l'ensemble des paramètres actuellement compatibles avec les lecteurs YouTube intégrés. Chaque définition de paramètre indique les lecteurs compatibles avec le paramètre en question.

Remarque : La taille de la fenêtre d'affichage des lecteurs intégrés doit être de 200 x 200 pixels minimum. Si les commandes sont définies pour s'afficher, le lecteur doit être assez grand pour les afficher sans réduire la fenêtre d'affichage en deçà de sa taille minimale. Les dimensions recommandées des lecteurs 16:9 sont de 480 pixels de large et de 270 pixels de haut.

Intégration d'un lecteur YouTube

Pour intégrer un lecteur YouTube dans votre application et spécifier ses paramètres, vous pouvez utiliser l'une des méthodes décrites ci-dessous. Sachez que ces consignes s'appliquent à l'intégration d'un lecteur pour la lecture d'une seule vidéo. La section suivante décrit comment configurer votre lecteur pour lire d'autres types de contenus, tels que des playlists et des résultats de recherche.

Intégrations iFrame à l'aide des balises `<iframe>`

Dans votre application, utilisez une balise <iframe> pour définir l'URL src des contenus que le lecteur devra lire, ainsi que d'autres paramètres. Les paramètres height et width de la balise <iframe> spécifient les dimensions du lecteur.

Si vous créez vous-même l'élément <iframe> (plutôt que d'utiliser l'API iFrame Player), vous pouvez ajouter les paramètres du lecteur directement à la fin de l'URL. L'URL se présente au format suivant :

http://www.youtube.com/embed/VIDEO_ID

Dans l'exemple ci-dessous, la balise <iframe> permet de charger un lecteur de 640 x 360 pixels pour la lecture de la vidéo YouTube M7lc1UVf-VE. Étant donné que l'URL définit le paramètre autoplay sur 1, la lecture de la vidéo sera automatiquement lancée une fois le lecteur chargé.

<iframe id="ytplayer" type="text/html" width="640" height="360"
  src="?url=http%3A%2F%2Fwww.youtube.com%2Fembed%2FM7lc1UVf-VE%3Fautoplay%3D1%26amp%3Borigin%3Dhttp%3A%2F%2Fexample.com"
  frameborder="0"/>

Intégrations iFrame à l'aide de l'API iFrame Player

Suivez les consignes relatives à l'API iFrame Player pour intégrer un lecteur vidéo sur votre page Web ou dans votre application une fois le code JavaScript de l'API Player chargé. Le deuxième paramètre devant apparaître pour l'intégration du lecteur vidéo est un objet définissant les options du lecteur. Dans cet objet, la propriété playerVars spécifie les paramètres du lecteur.

Le code HTML et JavaScript ci-dessous offre un exemple simple d'intégration d'un lecteur YouTube sur un élément de page dont la valeur id est ytplayer. La fonction onYouTubePlayerAPIReady() définie dans cet exemple est automatiquement appelée lorsque le code de l'API iFrame Player a été chargé. Ce code ne définit aucun paramètre du lecteur, ni d'autres gestionnaires d'événements.

<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>

Sélection des contenus à lire

Vous pouvez configurer votre lecteur intégré pour lire une vidéo, une playlist, des vidéos mises en ligne par un utilisateur ou des vidéos correspondant aux résultats d'une recherche particulière.

Ces options sont présentées ci-dessous :

Lecture d'une vidéo

Avec une intégration iFrame, l'ID vidéo YouTube de la vidéo à lire est défini dans l'URL src de l'iFrame.
```
http://www.youtube.com/embed/VIDEO_ID
```
Si vous utilisez l'API YouTube Data (v3), vous pouvez créer ces URL de façon programmée en récupérant les ID vidéo des résultats de recherche, des ressources des éléments d'une playlist, des ressources d'une vidéo ou d'autres ressources. Une fois l'ID vidéo récupéré, remplacez VIDEO_ID dans les URL ci-dessus par cette valeur pour créer l'URL du lecteur.
Lecture d'une playlist

Définissez le paramètre listType du lecteur sur playlist. Utilisez également l'ID de la playlist YouTube à charger pour définir le paramètre list.
```
http://www.youtube.com/embed?listType=playlist&list=PLAYLIST_ID
```
Sachez que vous devez ajouter les lettres PL au début de l'ID de playlist, tel qu'illustré dans l'exemple ci-dessous :
```
http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6
```
Si vous utilisez l'API YouTube Data (v3), vous pouvez créer ces URL de façon programmée en récupérant les ID de playlist des résultats de recherche, des ressources de la chaîne ou des ressources des activités. Une fois l'ID de la playlist récupéré, remplacez PLAYLIST_ID dans l'URL ci-dessus par cette valeur.
Lecture de vidéos mises en ligne par un utilisateur

Définissez le paramètre listType du lecteur sur user_uploads. Utilisez également le nom de l'utilisateur YouTube qui a mis en ligne les vidéos à charger pour définir le paramètre list du lecteur.
```
http://www.youtube.com/embed?listType=user_uploads&list=USERNAME
```
Lecture de vidéos correspondant aux résultats d'une recherche spécifique

Définissez le paramètre listType du lecteur sur search. Utilisez également le terme de recherche utilisé pour trouver les vidéos à charger pour définir le paramètre list du lecteur.
```
http://www.youtube.com/embed?listType=search&list=QUERY
```

Paramètres

Les paramètres suivants sont facultatifs.

Parameters
`autoplay`	Valeurs : `0` ou `1`. La valeur par défaut est `0`. Ce paramètre détermine si la lecture de la première vidéo doit être lancée automatiquement lors du chargement du lecteur.
`cc_load_policy`	Valeur : `1`. La valeur par défaut correspond aux préférences définies par l'utilisateur. La valeur `1` de ce paramètre permet d'afficher les sous-titres par défaut, même si l'internaute les a désactivés.
`color`	Ce paramètre détermine la couleur dans laquelle la barre de progression (qui indique la proportion de la vidéo déjà regardée) doit s'afficher dans le lecteur. Les valeurs valides pour ce paramètre sont `red` et `white`. Par défaut, la barre de progression s'affiche en rouge. Consultez le blog relatif aux API YouTube pour en savoir plus sur les options des couleurs. Remarque : Si la valeur du paramètre `color` est `white`, l'option `modestbranding` est désactivée.
`controls`	Valeurs : `0`, `1` ou `2`. La valeur par défaut est `1`. Ce paramètre détermine si les commandes du lecteur vidéo doivent s'afficher. Pour les intégrations iFrame destinées à charger un lecteur Flash, il permet également de définir quand les commandes s'affichent sur le lecteur et quand le lecteur se charge : `controls=0` : les commandes ne s'affichent pas sur le lecteur. Pour les intégrations iFrame, le lecteur Flash se charge directement. `controls=1` : les commandes s'affichent sur le lecteur. Pour les intégrations iFrame, les commandes s'affichent immédiatement et le lecteur Flash se charge également directement. `controls=2` : les commandes s'affichent sur le lecteur. Pour les intégrations iFrame, les commandes s'affichent et le lecteur Flash se charge lorsque l'internaute lance la lecture de la vidéo. Remarque : Les valeurs `1` et `2` permettent une expérience de visionnage identique, mais le paramètre `controls=2` offre de meilleures performances comparé au paramètre `controls=1` utilisé dans les intégrations iFrame. Ces deux valeurs présentent actuellement quelques différences visuelles sur le lecteur, telles que la taille de la police du titre de la vidéo. Cependant, lorsque les différences entre les deux valeurs sont évidentes pour les internautes, la valeur par défaut `1` pour ce paramètre peut être remplacée par `2`.
`disablekb`	Valeurs : `0` ou `1`. La valeur par défaut est `0`. Si le paramètre est défini sur `1`, les raccourcis clavier permettant de contrôler le lecteur sont désactivés. Les raccourcis clavier correspondant aux commandes du lecteur sont les suivants : Barre d'espace : lecture/pause Flèche gauche : retour de 10 % dans la lecture de la vidéo Flèche droite : avance de 10 % dans la lecture de la vidéo Flèche vers le haut : augmentation du volume Flèche vers le bas : diminution du volume
`enablejsapi`	Valeurs : `0` ou `1`. La valeur par défaut est `0`. Si la valeur de ce paramètre est `1`, l'API JavaScript est activée. Pour en savoir plus sur l'API JavaScript et son utilisation, consultez la documentation relative aux API JavaScript.
`end`	Valeurs : un entier positif. Ce paramètre définit la durée, en secondes, après laquelle le lecteur doit arrêter la lecture de la vidéo. Sachez que la durée commence à partir du début de la vidéo et non à partir de la valeur définie pour les paramètres `start` ou `startSeconds`, utilisés dans les fonctions de l'API YouTube Player pour charger une vidéo ou en ajouter une à la file d'attente.
`fs`	Valeurs : `0` ou `1`. La valeur par défaut `1` permet d'afficher le bouton du mode plein écran. Si la valeur de ce paramètre est `0`, le bouton du mode plein écran ne s'affiche pas.
`hl`	Ce paramètre permet de définir la langue de l'interface du lecteur. Sa valeur doit correspondre à un code de langue ISO 639-1 à deux lettres, bien que d'autres codes de langue, tels que les étiquettes d'identification de langues IETF (BCP 47), puissent également fonctionner correctement. La langue de l'interface correspond à celle des info-bulles qui s'affichent dans le lecteur et de la piste de sous-titres par défaut. Sachez que YouTube peut sélectionner une autre piste de sous-titres pour un internaute spécifique en fonction de sa langue et de la disponibilité des pistes de sous-titres.
`iv_load_policy`	Valeurs : `1` ou `3`. La valeur par défaut est `1`. Si la valeur est `1`, les annotations vidéo s'affichent par défaut ; à l'inverse, si la valeur est `3`, les annotations vidéo ne s'affichent pas par défaut.
`list`	Le paramètre `list`, associé au paramètre `listType`, définit le contenu chargé dans le lecteur. Si la valeur du paramètre `listType` est `search`, la valeur du paramètre `list` spécifie la requête de recherche. Si la valeur du paramètre `listType` est `user_uploads`, la valeur du paramètre `list` définit la chaîne YouTube dont les vidéos mises en ligne seront chargées. Si la valeur du paramètre `listType` est `playlist`, la valeur du paramètre `list` spécifie l'ID d'une playlist YouTube. Pour cette valeur, vous devez ajouter au début de l'ID de playlist les lettres `PL`, tel qu'illustré dans l'exemple ci-dessous. http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6 Remarque : Si vous définissez des valeurs pour les paramètres `list` et `listType`, il n'est pas nécessaire de définir un ID vidéo pour l'URL de l'intégration iFrame.
`listType`	Le paramètre `listType`, associé au paramètre `list`, définit le contenu chargé dans le lecteur. Les valeurs valides pour ce paramètre sont `playlist`, `search` et `user_uploads`. Si vous définissez des valeurs pour les paramètres `list` et `listType`, il n'est pas nécessaire de définir un ID vidéo pour l'URL de l'intégration iFrame.
`loop`	Valeurs : `0` ou `1`. La valeur par défaut est `0`. Pour les lecteurs ne chargeant qu'une seule vidéo, si la valeur est `1`, la vidéo sera lue indéfiniment. Pour les lecteurs de playlists (ou les lecteurs personnalisés), la playlist est lue dans son intégralité, puis la lecture reprend à partir de la première vidéo. Remarque : Ce paramètre n'est pas complètement compatible avec les lecteurs AS3 et les intégrations iFrame, qui peuvent charger des lecteurs AS3 ou HTML5. Le paramètre `loop` ne fonctionne actuellement qu'avec les lecteurs AS3 lorsqu'il est associé au paramètre `playlist`. Pour lire en boucle une vidéo, définissez le paramètre `loop` sur `1` et utilisez le même ID vidéo que dans l'URL de l'API Player pour définir le paramètre `playlist` : http://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID
`modestbranding`	Ce paramètre vous permet d'utiliser un lecteur YouTube qui ne présente aucun logo YouTube. Définissez le paramètre sur `1` pour que le logo YouTube ne s'affiche pas dans la barre de commandes. Sachez que le texte `YouTube` s'affiche quand même en petit dans l'angle supérieur droit d'une vidéo mise en pause lorsque l'utilisateur passe sa souris sur le lecteur.
`origin`	Ce paramètre fournit une mesure de sécurité supplémentaire pour l'API iFrame et n'est compatible qu'avec les intégrations iFrame. Si vous utilisez l'API iFrame et ainsi définissez le paramètre `enablejsapi` sur `1`, vous devez toujours spécifier votre domaine dans le paramètre `origin`.
`playlist`	La valeur doit correspondre à une liste d'ID vidéo séparés par une virgule. Si vous spécifiez une valeur, la première vidéo à être lue correspond à la valeur `VIDEO_ID` spécifiée dans l'URL, et les vidéos définies avec le paramètre `playlist` sont lues ensuite.
`playsinline`	Ce paramètre permet de lire les vidéos de façon intégrée ou en mode plein écran dans un lecteur HTML5 sous iOS. Les valeurs valides sont les suivantes : `0` : cette valeur permet d'activer la lecture en mode plein écran. Elle constitue actuellement la valeur par défaut, bien que cela soit susceptible de changer. `1` : cette valeur permet d'activer la lecture intégrée pour les objets `UIWebViews` créés avec la propriété `allowsInlineMediaPlayback` définie sur `TRUE`.
`rel`	Valeurs : `0` ou `1`. La valeur par défaut est `1`. Ce paramètre détermine si le lecteur doit afficher des vidéos similaires à la fin de la lecture d'une vidéo.
`showinfo`	Valeurs : `0` ou `1`. La valeur par défaut de ce paramètre est `1`. Si la valeur de ce paramètre est `0`, le lecteur n'affiche aucune information, comme le titre de la vidéo et l'utilisateur l'ayant mise en ligne, avant le lancement de la lecture. Si le lecteur charge une playlist et que le paramètre est explicitement défini sur `1`, le lecteur affiche également les miniatures des vidéos de la playlist après son chargement. Sachez que cette fonctionnalité n'est compatible qu'avec les lecteurs AS3, car ce sont les seuls lecteurs à pouvoir charger des playlists.
`start`	Valeurs : un entier positif. Ce paramètre permet de définir le moment (en secondes) auquel la lecture de la vidéo doit démarrer. De même qu'avec la fonction `seekTo`, le lecteur recherche l'image clé la plus proche du moment spécifié. Ainsi, la lecture peut parfois démarrer juste avant le moment défini, mais pas plus de deux secondes avant.

Historique des révisions

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.