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="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: '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

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.