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.

Vous pouvez intégrer des lecteurs YouTube sur des pages Web à l'aide de balises <iframe> ou <object>. En ajoutant des paramètres à l'URL iFrame ou SWF, 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

Bonnes pratiques : les intégrations iFrame sont recommandées pour intégrer un lecteur YouTube, car elles permettent de sélectionner le lecteur adapté aux capacités du client et les formats de fichiers YouTube disponibles.

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 390 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="390"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?autoplay=1&origin=http://example.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: '390',
      width: '640',
      videoId: 'M7lc1UVf-VE'
    });
  }
</script>

Intégrations d'objets AS3

Les intégrations d'objets utilisent une balise <object> pour spécifier les dimensions et les paramètres du lecteur. L'exemple de code ci-dessous montre comment utiliser une intégration d'objet pour charger un lecteur AS3 qui lancera automatiquement la lecture d'une même vidéo comme dans les deux exemples précédents.

<object width="640" height="390">
  <param name="movie"
         value="https://www.youtube.com/v/M7lc1UVf-VE?version=3&autoplay=1"></param>
  <param name="allowScriptAccess" value="always"></param>
  <embed src="https://www.youtube.com/v/M7lc1UVf-VE?version=3&autoplay=1"
         type="application/x-shockwave-flash"
         allowscriptaccess="always"
         width="640" height="390"></embed>
</object>

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. Cependant, les options autres que la lecture d'une seule vidéo ne sont disponibles que dans les intégrations d'objets AS3 et les intégrations iFrame chargeant des lecteurs AS3. (Les intégrations iFrame peuvent également charger des lecteurs HTML5.)

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. Avec une intégration d'objet AS3, l'ID vidéo est défini dans l'URL SWF du lecteur.
```
IFrame embed:
http://www.youtube.com/embed/VIDEO_ID

Embedded AS3 player:
http://www.youtube.com/v/VIDEO_ID?version=3

Chromeless AS3 player:
http://www.youtube.com/apiplayer?video_id=VIDEO_ID&version=3
```
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. Cette liste répertorie les paramètres compatibles avec tous les lecteurs intégrés YouTube. Si un paramètre particulier n'est pas compatible avec certains lecteurs, ces derniers seront précisés dans la définition du paramètre. Sachez que ces paramètres ne sont officiellement compatibles qu'avec les lecteurs intégrés. Cependant, des sous-groupes de ces paramètres peuvent également fonctionner avec d'autres lecteurs, comme le lecteur de playlist.

Remarque : Les intégrations iFrame peuvent permettre de charger des lecteurs HTML5 ou AS3. Bien que certains paramètres ne soient pas compatibles avec ces deux lecteurs, une intégration iFrame permettant de charger un lecteur AS3 sera compatible avec tous les paramètres qui fonctionnent avec ce lecteur et ignorera tous les autres. De même, une intégration iFrame permettant de charger un lecteur HTML5 sera compatible avec tous les paramètres qui fonctionnent avec ce lecteur et ignorera tous les autres.

Par exemple, le lecteur HTML5 n'est actuellement pas compatible avec le paramètre playerapiid, mais vous pouvez quand même spécifier ce paramètre lors de la création d'une intégration iFrame. Si l'intégration est destinée à charger un lecteur AS3, ce paramètre sera pris en compte ; si l'intégration est destinée à charger un lecteur HTML5, ce paramètre sera ignoré.

Parameters

`autohide`

Lecteurs compatibles : HTML5, AS3

Description

Valeurs : 2 (par défaut), 1 et 0. Ce paramètre détermine si les commandes du lecteur doivent être automatiquement masquées après le lancement de la lecture d'une vidéo. La valeur par défaut (autohide=2) permet de masquer par fondu la barre de progression de la vidéo, alors que les commandes du lecteur (bouton de lecture, contrôle du volume, etc.) restent visibles.

Si la valeur de ce paramètre est 1, la barre de progression de la vidéo et les commandes du lecteur disparaissent au bout de quelques secondes après le lancement de la lecture. Elles ne réapparaissent que si l'internaute passe la souris sur le lecteur vidéo ou appuie sur une touche de son clavier.
Si la valeur de ce paramètre est 0, la barre de progression de la vidéo et les commandes du lecteur restent visibles pendant l'intégralité de la lecture et en mode plein écran.

`autoplay`

Lecteurs compatibles :	HTML5, AS3
Description	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`

Lecteurs compatibles :	HTML5, AS3
Description	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`

Lecteurs compatibles : HTML5, AS3

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

Lecteurs compatibles : HTML5, AS3

Description

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`

Lecteurs compatibles : HTML5, AS3

Description

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`

Lecteurs compatibles :	HTML5, AS3
Description	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`

Lecteurs compatibles : HTML5, AS3

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

Lecteurs compatibles :	HTML5, AS3
Description	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`

Lecteurs compatibles :

HTML5, AS3

Description

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`

Lecteurs compatibles :	HTML5, AS3
Description	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`

Lecteurs compatibles : HTML5, AS3

Description

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`

Lecteurs compatibles :	HTML5, AS3
Description	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`

Lecteurs compatibles : HTML5, AS3

Description

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`

Lecteurs compatibles :	HTML5, AS3
Description	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`

Lecteurs compatibles :	HTML5, AS3
Description	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`.

`playerapiid`

Lecteurs compatibles :	AS3
Description	La valeur peut être une chaîne alphanumérique. Ce paramètre est utilisé avec l'API JavaScript. Consultez la documentation relative aux API JavaScript pour en savoir plus.

`playlist`

Lecteurs compatibles :	HTML5, AS3
Description	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`

Lecteurs compatibles : HTML5

Description

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`

Lecteurs compatibles :	HTML5, AS3
Description	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`

Lecteurs compatibles : HTML5, AS3

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

Lecteurs compatibles :	HTML5, AS3
Description	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.

`theme`

Lecteurs compatibles : HTML5, AS3

Description Ce paramètre détermine si les commandes (par exemple, le bouton de lecture ou le contrôle du volume) du lecteur intégré doivent s'afficher dans une barre foncée ou claire. Les valeurs valides pour ce paramètre sont dark et light. Par défaut, le thème dark est utilisé pour l'affichage des commandes du lecteur. Consultez le blog relatif aux API YouTube pour en savoir plus sur les thèmes "foncé" et "clair".

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.