YouTube Player API Reference for iframe Embeds

L'API Player iFrame vous permet d'intégrer un lecteur vidéo YouTube sur votre site Web et de le contrôler à l'aide de JavaScript. Contrairement aux API Player Flash et JavaScript, qui impliquent l'intégration d'un objet Flash sur votre page Web, l'API Player iFrame publie des contenus sur votre page dans une balise <iframe>. Cette méthode offre plus de flexibilité que les précédentes API disponibles, car elle permet à YouTube d'afficher un lecteur HTML5 plutôt qu'un lecteur Flash sur les appareils mobiles non compatibles avec Flash.

Les fonctions de l'API JavaScript vous permettent d'ajouter des vidéos en file d'attente, de lire, de mettre en pause ou d'arrêter ces vidéos, de régler le volume du lecteur, ou de récupérer des informations sur la vidéo en cours de lecture. Vous pouvez également ajouter des écouteurs d'événements qui s'exécutent en réponse à certains événements déclenchés sur le lecteur, tels que la modification de l'état du lecteur ou de la qualité de lecture d'une vidéo.

Ce guide décrit le fonctionnement de l'API iFrame. Il présente les différents types d'événements que l'API peut envoyer et explique comment définir des écouteurs d'événements pour y répondre. Il présente également en détail les différentes fonctions JavaScript que vous pouvez appeler pour contrôler le lecteur vidéo, ainsi que les paramètres du lecteur que vous pouvez utiliser pour le personnaliser.

Configuration requise

L'utilisateur final doit utiliser un navigateur compatible avec la fonctionnalité postMessage de HTML5. Les navigateurs les plus récents sont compatibles avec postMessage, bien qu'Internet Explorer 7 ne le soit pas.

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.

Les pages Web qui utilisent l'API iFrame doivent également mettre en œuvre la fonction JavaScript suivante :

onYouTubeIframeAPIReady : l'API appelle cette fonction lorsque la page a terminé de télécharger le fichier JavaScript pour l'API Player, ce qui vous permet d'utiliser l'API sur votre page. Par conséquent, cette fonction peut créer les objets de lecteur que vous souhaitez afficher lors du chargement de la page.

Premiers pas

L'exemple de page HTML ci-dessous permet de créer un lecteur intégré qui charge une vidéo, la lit pendant six secondes, puis arrête la lecture. Les commentaires numérotés dans le code HTML sont expliqués dans la liste apparaissant sous l'exemple.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '360',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

Cet exemple de code est expliqué plus en détail dans la liste ci-dessous :

La balise <div> de cette section identifie l'emplacement sur la page où l'API iFrame doit afficher le lecteur vidéo. Le constructeur de l'objet de type lecteur, décrit dans la section Charger un lecteur vidéo, identifie la balise <div> avec son id pour garantir que l'API place la balise <iframe> au bon endroit. Plus précisément, l'API iFrame remplace la balise <div> par la balise <iframe>.

L'autre solution consiste à placer l'élément <iframe> directement sur la page. Cette procédure est décrite dans la section Charger un lecteur vidéo.
Le code expliqué dans cette section permet de charger le code JavaScript de l'API Player iFrame. Dans cet exemple, une modification du DOM est utilisée pour télécharger le code de l'API afin de garantir la récupération asynchrone du code. (L'attribut async de la balise <script>, qui permet également des téléchargements asynchrones, n'est pas encore compatible avec tous les navigateurs récents tel qu'expliqué dans cette réponse publiée sur le site Stack Overflow.
La fonction onYouTubeIframeAPIReady s'exécute dès que le code de l'API Player est téléchargé. Cette partie du code définit une variable globale, player, qui fait référence au lecteur vidéo à intégrer. La fonction crée ensuite l'objet de type lecteur vidéo.
La fonction onPlayerReady s'exécute lorsque l'événement onReady se déclenche. Dans cet exemple, cette fonction indique que la lecture doit être lancée lorsque le lecteur vidéo est prêt.
L'API appelle la fonction onPlayerStateChange lorsque l'état du lecteur change, ce qui peut indiquer que le lecteur est en lecture, mis en pause, arrêté, etc. La fonction indique que, lorsque l'état du lecteur est 1 (en lecture), le lecteur doit lire la vidéo pendant six secondes, puis appeler la fonction stopVideo pour arrêter la vidéo.

Charger un lecteur vidéo

Une fois le code JavaScript de l'API chargé, l'API appelle la fonction onYouTubeIframeAPIReady, dans laquelle vous pouvez créer un objet YT.Player pour intégrer un lecteur vidéo sur votre page. L'extrait de code HTML suivant illustre la fonction onYouTubeIframeAPIReady de l'exemple ci-dessus :

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '360',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

Le constructeur du lecteur vidéo définit les paramètres suivants :

Le premier paramètre spécifie l'élément DOM ou l'id de l'élément HTML où l'API doit insérer la balise <iframe> contenant le lecteur.

L'API iFrame remplace l'élément spécifié par l'élément <iframe> contenant le lecteur. Cette opération peut modifier la disposition de votre page si le style d'affichage de l'élément remplacé est différent de celui de l'élément <iframe> inséré. Par défaut, une balise <iframe> s'affiche sous forme d'élément inline-block.
Le second paramètre est un objet permettant de définir les options du lecteur. Cet objet comporte les propriétés suivantes :
- width (nombre) : largeur du lecteur vidéo. La valeur par défaut est 640.
- height (nombre) : hauteur du lecteur vidéo. La valeur par défaut est 360.
- videoId (chaîne de caractères) : ID YouTube de la vidéo que le lecteur doit charger.
- playerVars (objet) : les propriétés de cet objet définissent les paramètres du lecteur qui peuvent être utilisés pour personnaliser le lecteur.
- events (objet) : les propriétés de cet objet définissent les événements déclenchés par l'API et les fonctions (écouteurs d'événements) qu'elle appelle lorsqu'ils surviennent. Dans l'exemple ci-dessus, le constructeur indique que la fonction onPlayerReady s'exécute lorsque l'événement onReady survient et que la fonction onPlayerStateChange s'exécute lorsque l'événement onStateChange survient.

Comme mentionné dans la section Premiers pas, au lieu d'écrire un élément <div> vide sur votre page, qui sera ensuite remplacé par un élément <iframe> du code JavaScript de l'API Player, vous pouvez créer vous-même la balise <iframe>.

<iframe id="player" type="text/html" width="640" height="360"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

Si vous écrivez une balise <iframe>, lors de la construction de l'objet YT.Player, vous n'avez pas besoin de spécifier des valeurs pour les propriétés width et height, qui sont définies comme attributs de la balise <iframe>, ni la propriété videoId, ni les paramètres du lecteur, qui sont définis dans l'URL src. Pour une sécurité renforcée, vous devez également ajouter le paramètre origin à l'URL en spécifiant le schéma de l'URL (http:// ou https://) et le nom de domaine complet de votre page Web comme valeur de ce paramètre. Bien que le paramètre origin soit facultatif, il permet d'empêcher l'insertion sur votre page de code JavaScript tiers malveillant susceptible de prendre le contrôle de votre lecteur YouTube.

La section Exemples présente quelques autres exemples illustrant la construction d'objets de type lecteur vidéo.

Opérations

Pour appeler les fonctions de l'API Player, vous devez d'abord obtenir la référence de l'objet de type de lecteur que vous souhaitez contrôler. Pour obtenir cette référence, créez un objet YT.Player comme décrit dans les sections Premiers pas et Charger un lecteur vidéo de ce document.

Fonctions

Fonctions de mise en file d'attente

Les fonctions de mise en file d'attente permettent de charger et de lire une vidéo, une playlist ou une autre liste de vidéos. Si vous utilisez la syntaxe d'objets décrite ci-dessous pour appeler ces fonctions, vous pouvez également mettre en file d'attente ou charger des vidéos correspondant à des résultats de recherche ou mises en ligne par un autre utilisateur.

Pour appeler les fonctions de mise en file d'attente, deux syntaxes différentes sont possibles dans l'API.

La syntaxe d'argument nécessite que les arguments de la fonction soient définis dans un ordre déterminé.
La syntaxe d'objet permet de passer un objet en un seul paramètre et de définir des propriétés d'objet correspondant aux arguments de la fonction que vous souhaitez configurer. De plus, il est possible que certaines fonctionnalités supplémentaires soient compatibles avec l'API, mais pas avec la syntaxe d'argument.

Par exemple, la fonction loadVideoById peut être appelée à l'aide des deux méthodes suivantes. Sachez que la propriété endSeconds est compatible avec la syntaxe d'objet, mais pas avec la syntaxe d'argument.

Syntaxe d'argument

loadVideoById("bHQqvYy5KYo", 5, "large")

Syntaxe d'objet

loadVideoById({'videoId': 'bHQqvYy5KYo',
               'startSeconds': 5,
               'endSeconds': 60,
               'suggestedQuality': 'large'});

Fonctions de mise en file d'attente de vidéos

cueVideoById

Syntaxe d'argument

player.cueVideoById(videoId:String,
                    startSeconds:Number,
                    suggestedQuality:String):Void

Syntaxe d'objet

player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number,
                     suggestedQuality:String}):Void

Cette fonction permet de charger la miniature de la vidéo spécifiée et de préparer le lecteur à lire la vidéo. Le lecteur ne nécessite pas de fichier FLV tant que les fonctions playVideo() ou seekTo() ne sont pas appelées.

Le paramètre obligatoire videoId spécifie l'ID vidéo YouTube de la vidéo à lire. Dans les flux vidéo de l'API YouTube Data, l'ID vidéo est spécifié dans la balise <yt:videoid>.
La valeur du paramètre facultatif startSeconds peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la vidéo doit être lancée lorsque la fonction playVideo() est appelée. Si vous spécifiez une valeur pour le paramètre startSeconds, puis que vous appelez la fonction seekTo(), la lecture démarre au moment spécifié dans la fonction seekTo(). Lorsque la vidéo est en file d'attente et prête à être lue, le lecteur envoie un événement video cued (5).
La valeur du paramètre facultatif endSeconds, uniquement compatible avec la syntaxe d'objet, peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la vidéo doit s'arrêter lorsque la fonction playVideo() est appelée. Si vous spécifiez une valeur pour le paramètre endSeconds, puis que vous appelez la fonction seekTo(), la valeur du paramètre endSeconds n'est pas prise en compte.
Le paramètre facultatif suggestedQuality spécifie la qualité de lecture recommandée pour la vidéo. Pour en savoir plus sur la qualité de la lecture, consultez la définition de la fonction setPlaybackQuality.

loadVideoById

Argument syntax

player.loadVideoById(videoId:String,
                     startSeconds:Number,
                     suggestedQuality:String):Void

Object syntax

player.loadVideoById({videoId:String,
                      startSeconds:Number,
                      endSeconds:Number,
                      suggestedQuality:String}):Void

Cette fonction permet de charger et de lire la vidéo spécifiée.

Le paramètre obligatoire videoId spécifie l'ID vidéo YouTube de la vidéo à lire. Dans les flux vidéo de l'API YouTube Data, l'ID vidéo est spécifié dans la balise <yt:videoid>.
La valeur du paramètre facultatif startSeconds peut être un nombre flottant ou entier. Si ce paramètre est défini, la lecture de la vidéo commence à partir de l'image clé la plus proche du moment spécifié.
La valeur du paramètre facultatif endSeconds peut être un nombre flottant ou entier. Si ce paramètre est défini, la lecture de la vidéo s'arrête au moment spécifié.
Le paramètre facultatif suggestedQuality spécifie la qualité de lecture recommandée pour la vidéo. Pour en savoir plus sur la qualité de la lecture, consultez la définition de la fonction setPlaybackQuality.

cueVideoByUrl

Argument syntax

player.cueVideoByUrl(mediaContentUrl:String,
                     startSeconds:Number,
                     suggestedQuality:String):Void

Object syntax

player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number,
                      suggestedQuality:String}):Void

Le paramètre obligatoire mediaContentUrl spécifie l'URL complète du lecteur YouTube au format http://www.youtube.com/v/VIDEO_ID?version=3. Dans les flux vidéo de l'API YouTube Data, l'attribut url de la balise <media:content> présente l'URL complète du lecteur lorsque la valeur de l'attribut format est 5.
La valeur du paramètre facultatif startSeconds peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la vidéo doit être lancée lorsque la fonction playVideo() est appelée. Si vous spécifiez une valeur pour le paramètre startSeconds, puis que vous appelez la fonction seekTo(), la lecture démarre au moment spécifié dans la fonction seekTo(). Lorsque la vidéo est en file d'attente et prête à être lue, le lecteur envoie un événement video cued (5).
La valeur du paramètre facultatif endSeconds, uniquement compatible avec la syntaxe d'objet, peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la vidéo doit s'arrêter lorsque la fonction playVideo() est appelée. Si vous spécifiez une valeur pour le paramètre endSeconds, puis que vous appelez la fonction seekTo(), la valeur du paramètre endSeconds ne sera pas prise en compte.
Le paramètre facultatif suggestedQuality spécifie la qualité de lecture recommandée pour la vidéo. Pour en savoir plus sur la qualité de la lecture, consultez la définition de la fonction setPlaybackQuality.

loadVideoByUrl

Argument syntax

player.loadVideoByUrl(mediaContentUrl:String,
                      startSeconds:Number,
                      suggestedQuality:String):Void

Object syntax

player.loadVideoByUrl({mediaContentUrl:String,
                       startSeconds:Number,
                       endSeconds:Number,
                       suggestedQuality:String}):Void

Cette fonction permet de charger et de lire la vidéo spécifiée.

Le paramètre obligatoire mediaContentUrl spécifie l'URL complète du lecteur YouTube au format http://www.youtube.com/v/VIDEO_ID?version=3. Dans les flux vidéo de l'API YouTube Data, l'attribut url de la balise <media:content> présente l'URL complète du lecteur lorsque la valeur de l'attribut format est 5.
La valeur du paramètre facultatif startSeconds peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la vidéo doit être lancée. Si une valeur (qui peut être un nombre flottant) est définie pour le paramètre startSeconds, la lecture de la vidéo commence à partir de l'image clé la plus proche du moment spécifié.
La valeur du paramètre facultatif endSeconds, uniquement compatible avec la syntaxe d'objet, peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la vidéo doit s'arrêter.
Le paramètre facultatif suggestedQuality spécifie la qualité de lecture recommandée pour la vidéo. Pour en savoir plus sur la qualité de la lecture, consultez la définition de la fonction setPlaybackQuality.

Fonctions de mise en file d'attente de listes de vidéos

Les fonctions cuePlaylist et loadPlaylist permettent de charger et de lire une playlist ou une liste de vidéos. Si vous utilisez la syntaxe d'objet pour appeler ces fonctions, vous pouvez également ajouter à la file d'attente (ou charger) des vidéos correspondant aux résultats d'une recherche ou mises en ligne par un autre utilisateur.

Étant donné que ces fonctions ont un fonctionnement différent selon la syntaxe utilisée pour les appeler (syntaxe d'argument ou syntaxe d'objet), ces deux méthodes sont décrites ci-dessous.

cuePlaylist

Argument syntax
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number,
                   suggestedQuality:String):Void
```
Cette fonction permet d'ajouter à la file d'attente la playlist spécifiée. Lorsque la playlist est en file d'attente et prête à être lue, le lecteur envoie un événement video cued (5).
- Le paramètre obligatoire playlist spécifie une série d'ID vidéo YouTube. Dans les flux de l'API YouTube Data, les ID vidéo sont spécifiés dans la balise <yt:videoid>.
- Le paramètre facultatif index définit l'index de la première vidéo à lire dans la playlist. Il utilise un index de base zéro et sa valeur par défaut est 0. Ainsi, par défaut, le lecteur charge et lit la première vidéo de la playlist.
- La valeur du paramètre facultatif startSeconds peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la première vidéo de la playlist doit être lancée lorsque la fonction playVideo() est appelée. Si vous spécifiez une valeur pour le paramètre startSeconds, puis que vous appelez la fonction seekTo(), la lecture démarre au moment spécifié dans la fonction seekTo(). Si vous ajoutez une playlist à la file d'attente, puis que vous appelez la fonction playVideoAt(), la lecture de la playlist démarre au début de la vidéo spécifiée.
- Le paramètre facultatif suggestedQuality spécifie la qualité de lecture recommandée pour la vidéo. Pour en savoir plus sur la qualité de la lecture, consultez la définition de la fonction setPlaybackQuality.
Syntaxe d'objet
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String}):Void
```
Cette fonction permet d'ajouter à la file d'attente la liste de vidéos spécifiée. Cette liste peut correspondre à une playlist, à un flux de résultats de recherche ou à un flux de vidéos mises en ligne par un autre utilisateur. Lorsque la liste est en file d'attente et prête à être lue, le lecteur envoie un événement video cued (5).
- La propriété facultative listType définit le type de flux à récupérer. Les valeurs possibles sont playlist, search et user_uploads. La valeur par défaut est playlist.
- La propriété obligatoire list contient une clé qui identifie la liste de vidéos spécifique que YouTube doit renvoyer.
  - Si la valeur de la propriété listType est playlist, la propriété list spécifie l'ID de la playlistlistlist ou une série d'ID vidéo. Dans les flux de l'API YouTube Data, la balise <yt:playlistid> spécifie un ID de playlist et la balise <yt:videoid> un ID vidéo.
  - Si la valeur de la propriété listType est search, la propriété list spécifie la requête de recherche.
  - Si la valeur de la propriété listType est user_uploads, la propriété list identifie l'utilisateur dont les vidéos mises en ligne doivent être lues.
- La propriété facultative index spécifie l'index de la première vidéo à lire dans la liste. Elle utilise un index de base zéro et sa valeur par défaut est 0. Ainsi, par défaut, le lecteur charge et lit la première vidéo de la liste.
- La valeur de la propriété facultative startSeconds peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la première vidéo doit être lancée lorsque la fonction playVideo() est appelée. Si vous spécifiez une valeur pour le paramètre startSeconds, puis que vous appelez la fonction seekTo(), la lecture démarre au moment spécifié dans la fonction seekTo(). Si vous ajoutez une liste de vidéos à la file d'attente, puis que vous appelez la fonction playVideoAt(), la lecture de la liste de vidéos démarre au début de la vidéo spécifiée.
- La propriété facultative suggestedQuality spécifie la qualité de lecture recommandée pour la liste de vidéos. Pour en savoir plus sur la qualité de la lecture, consultez la définition de la fonction setPlaybackQuality.

loadPlaylist

Argument syntax
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String):Void
```
Cette fonction permet de charger la playlist spécifiée et de la lire.
- Le paramètre obligatoire playlist spécifie une série d'ID vidéo YouTube. Dans les flux de l'API YouTube Data, les ID vidéo sont spécifiés dans la balise <yt:videoid>.
- Le paramètre facultatif index définit l'index de la première vidéo à lire dans la playlist. Il utilise un index de base zéro et sa valeur par défaut est 0. Ainsi, par défaut, le lecteur charge et lit la première vidéo de la playlist.
- La valeur du paramètre facultatif startSeconds peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la première vidéo de la playlist doit être lancée.
- Le paramètre facultatif suggestedQuality spécifie la qualité de lecture recommandée pour la vidéo. Pour en savoir plus sur la qualité de la lecture, consultez la définition de la fonction setPlaybackQuality.
Object syntax
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number,
                     suggestedQuality:String}):Void
```
Cette fonction permet de charger la liste de vidéos spécifiée et de la lire. Cette liste peut correspondre à une playlist, à un flux de résultats de recherche ou à un flux de vidéos mises en ligne par un autre utilisateur.
- La propriété facultative listType définit le type de flux à récupérer. Les valeurs possibles sont playlist, search et user_uploads. La valeur par défaut est playlist.
- La propriété obligatoire list contient une clé qui identifie la liste de vidéos spécifique que YouTube doit renvoyer.
  - Si la valeur de la propriété listType est playlist, la propriété list spécifie un ID de playlistlistlist ou une série d'ID vidéo. Dans les flux de l'API YouTube Data, la balise <yt:playlistid> spécifie un ID de playlist et la balise <yt:videoid> un ID vidéo.
  - Si la valeur de la propriété listType est search, la propriété list spécifie la requête de recherche.
  - Si la valeur de la propriété listType est user_uploads, la propriété list identifie l'utilisateur dont les vidéos mises en ligne doivent être lues.
- La propriété facultative index spécifie l'index de la première vidéo à lire dans la liste. Elle utilise un index de base zéro et sa valeur par défaut est 0. Ainsi, par défaut, le lecteur charge et lit la première vidéo de la liste.
- La propriété facultative startSeconds peut être un nombre flottant ou entier ; elle spécifie le moment auquel la lecture de la première vidéo de la liste doit être lancée.
- La propriété facultative suggestedQuality spécifie la qualité de lecture recommandée pour la liste de vidéos. Pour en savoir plus sur la qualité de la lecture, consultez la définition de la fonction setPlaybackQuality.

Commandes de lecture et paramètres du lecteur

Lire une vidéo

player.playVideo():Void: Cette fonction permet de lancer la lecture de la vidéo actuellement en file d'attente/chargée. L'état final du lecteur après l'exécution de cette fonction est playing (1).

Remarque : Une lecture n'est comptabilisée dans le nombre de vues officiel d'une vidéo que lorsqu'elle est lancée avec le bouton de lecture natif du lecteur.

player.pauseVideo():Void: Cette fonction permet de mettre en pause la vidéo en cours de lecture. L'état final du lecteur après l'exécution de cette fonction est paused (2), sauf si l'état du lecteur est ended (0) lorsque la fonction est appelée, auquel cas l'état du lecteur ne sera pas modifié.

player.stopVideo():Void: Cette fonction permet d'arrêter et d'annuler le chargement de la vidéo en cours. Elle doit être utilisée dans les rares situations où vous savez que l'utilisateur ne regardera pas d'autres vidéos dans le lecteur. Si vous souhaitez mettre en pause la vidéo, vous devez simplement appeler la fonction pauseVideo. Si vous souhaitez modifier la vidéo en cours de lecture, vous pouvez appeler l'une des fonctions de mise en file d'attente sans avoir d'abord à appeler la fonction stopVideo.

Important : Contrairement à la fonction pauseVideo, qui définit l'état du lecteur sur paused (2), la fonction stopVideo peut définir le lecteur sur différents états de non-lecture, comme ended (0), paused (2), video cued (5) ou unstarted (-1).

player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void

Cette fonction permet d'avancer à un moment spécifié d'une vidéo. Si elle est appelée alors que le lecteur est en pause, celui-ci reste en pause. Si elle est appelée alors que le lecteur est dans un autre état (playing, video cued, etc.), la lecture de la vidéo démarre.

Le paramètre seconds identifie le moment de la vidéo auquel le lecteur doit avancer.

Si le lecteur n'a pas encore téléchargé la partie de la vidéo que l'utilisateur souhaite atteindre, le lecteur avance jusqu'à l'image clé la plus proche avant le moment défini. Dans le cas contraire, le lecteur avance jusqu'à l'image clé la plus proche avant ou après le moment défini, comme le veut la méthode seek() de l'objet NetStream du lecteur Flash. (Pour en savoir plus, consultez la documentation d'Adobe.)
Le paramètre allowSeekAhead détermine si le lecteur envoie une nouvelle requête au serveur lorsque le paramètre seconds définit un moment ne figurant pas dans les données vidéo déjà mises en mémoire tampon.

Nous vous recommandons de définir ce paramètre sur false lorsque l'utilisateur fait glisser avec la souris le curseur de la barre de progression d'une vidéo, puis de le définir sur true lorsque l'utilisateur relâche le bouton de la souris. Cette méthode permet aux utilisateurs de faire défiler une vidéo sans demander de nouveaux flux vidéo en accédant aux parties précédentes non mises en mémoire tampon de la vidéo. Lorsque l'utilisateur relâche le bouton de la souris, le lecteur avance la lecture au moment souhaité et envoie une requête de nouveau flux vidéo, si nécessaire.

player.clearVideo():Void: Cette fonction permet de masquer l'affichage d'une vidéo. Elle est utile si vous souhaitez ne pas afficher le reste de la vidéo après avoir appelé la fonction stopVideo(). Sachez que cette fonction n'est plus disponible dans l'API Player ActionScript 3.0.

Lire une vidéo d'une playlist

player.nextVideo():Void

Cette fonction permet de charger et de lire la prochaine vidéo de la playlist.

Si la fonction player.nextVideo() est appelée alors que la dernière vidéo de la playlist est en cours de lecture et que la playlist est configurée pour être lue en continu (loop), le lecteur charge et lit la première vidéo de la playlist.
Si la fonction player.nextVideo() est appelée alors que la dernière vidéo de la playlist est en cours de lecture et que la playlist n'est pas configurée pour être lue en continu, la lecture s'arrête.

player.previousVideo():Void

Cette fonction permet de charger et de lire la vidéo précédente de la playlist.

Si la fonction player.previousVideo() est appelée alors que la première vidéo de la playlist est en cours de lecture et que la playlist est configurée pour être lue en continu (loop), le lecteur charge et lit la dernière vidéo de la playlist.
Si la fonction player.previousVideo() est appelée alors que la première vidéo de la playlist est en cours de lecture et que la playlist n'est pas configurée pour être lue en continu, le lecteur relance la lecture de la première vidéo depuis le début.

player.playVideoAt(index:Number):Void

Cette fonction permet de charger et de lire la vidéo spécifiée dans la playlist.

Le paramètre obligatoire index spécifie l'index de la vidéo à lire dans la playlist. Il utilise des index de base zéro. Ainsi, la valeur 0 identifie la première vidéo de la playlist. Si la playlist est configurée pour une lecture aléatoire, cette fonction lit la vidéo correspondant à la position définie dans la playlist en mode aléatoire.

Régler le volume du lecteur

player.mute():Void: Cette fonction permet de couper le son du lecteur.

player.unMute():Void: Cette fonction permet de réactiver le son du lecteur.

player.isMuted():Boolean: Cette fonction renvoie la valeur true si le son du lecteur est coupé et false dans le cas contraire.

player.setVolume(volume:Number):Void: Cette fonction permet de définir le niveau du volume. La valeur peut être un entier compris entre 0 et 100.

player.getVolume():Number: Cette fonction renvoie le niveau actuel du volume du lecteur, à savoir un entier compris entre 0 et 100. Sachez que la fonction getVolume() renvoie le niveau du volume même si le son du lecteur est coupé.

Définir la taille du lecteur

player.setSize(width:Number, height:Number):Object: Cette fonction permet de définir la taille en pixels de l'élément <iframe> comportant le lecteur.

Définir la vitesse de lecture

player.getPlaybackRate():Number: Cette fonction permet de récupérer la vitesse de lecture de la vidéo en cours. La vitesse de lecture par défaut est 1, ce qui indique que la vidéo est lue à une vitesse normale. Les valeurs de vitesse de lecture peuvent être les suivantes : 0.25, 0.5, 1, 1.5 et 2.

player.setPlaybackRate(suggestedRate:Number):Void: Cette fonction permet de spécifier la vitesse de lecture recommandée pour la vidéo. Si la vitesse de lecture est modifiée, elle l'est uniquement pour la vidéo qui est déjà en file d'attente ou en lecture. Si vous définissez la vitesse de lecture d'une vidéo en file d'attente, cette vitesse s'applique toujours lorsque la fonction playVideo est appelée ou lorsque l'utilisateur lance la lecture à l'aide des commandes du lecteur. De plus, si vous appelez des fonctions pour ajouter à la file d'attente ou charger des vidéos ou des playlists (cueVideoById, loadVideoById, etc.), la vitesse de lecture est redéfinie sur 1.

Cette fonction ne garantit pas la modification effective de la vitesse de lecture. Cependant, si la vitesse de lecture est modifiée, l'événement onPlaybackRateChange se déclenche et votre code doit répondre à l'événement plutôt que réagir à l'appel de la fonction setPlaybackRate.

La méthode getAvailablePlaybackRates renvoie les vitesses de lecture possibles pour la vidéo en cours de lecture. Cependant, si vous utilisez un nombre entier ou flottant non compatible comme valeur pour le paramètre suggestedRate, le lecteur arrondit cette valeur à la valeur inférieure compatible la plus proche de 1.

player.getAvailablePlaybackRates():Array: Cette fonction renvoie la liste des vitesses de lecture disponibles pour la vidéo en cours. La valeur par défaut est 1, ce qui indique que la vidéo est lue à une vitesse normale.

Cette fonction renvoie une série de nombres correspondant aux différentes vitesses de lecture, de la plus lente à la plus rapide. Même si le lecteur n'autorise pas les vitesses de lecture variables, cette série de nombres doit toujours contenir au moins une valeur (1).

Définir les paramètres de lecture des playlists

player.setLoop(loopPlaylists:Boolean):Void

Cette fonction indique si le lecteur vidéo doit lire la playlist en continu ou s'il doit arrêter sa lecture une fois la dernière vidéo terminée. Par défaut, les playlists ne sont pas lues en boucle.

Ce paramètre reste activé même si vous chargez une autre playlist ou si vous en ajoutez une nouvelle à la file d'attente. Ainsi, si vous chargez une playlist, appelez la fonction setLoop avec la valeur true, puis chargez une seconde playlist : cette dernière sera également lue en boucle.

Le paramètre obligatoire loopPlaylists détermine si les playlists doivent être lues en boucle.

Si la valeur du paramètre est true, le lecteur vidéo lit les playlists en boucle. Après la lecture de la dernière vidéo, le lecteur relance la lecture de la playlist à partir du début.
Si la valeur du paramètre est false, la lecture de la playlist s'arrête après que le lecteur vidéo a lu la dernière vidéo.

player.setShuffle(shufflePlaylist:Boolean):Void

Cette fonction détermine si les vidéos d'une playlist doivent être lues en mode aléatoire, ce qui signifie qu'elles seront lues dans un ordre différent de celui défini par le créateur de la playlist. Si vous activez le mode aléatoire pour une playlist en cours de lecture, l'ordre de lecture des vidéos est modifié pendant la lecture de la vidéo en cours. La prochaine vidéo à être lue sera sélectionnée en fonction de ce nouvel ordre.

Ce paramètre ne reste pas activé si vous chargez une autre playlist ou si vous en ajoutez une nouvelle à la file d'attente. Par conséquent, si vous chargez une playlist, appelez la fonction setShuffle, puis chargez une seconde playlist : cette dernière ne sera pas lue en mode aléatoire.

Le paramètre obligatoire shufflePlaylist détermine si YouTube doit lire la playlist en mode aléatoire.

Si la valeur du paramètre est true, YouTube utilise un ordre de lecture aléatoire pour la playlist. Si vous demandez à cette fonction de définir en mode aléatoire une playlist déjà en mode aléatoire, YouTube redéfinit l'ordre de lecture de façon aléatoire.
Si la valeur du paramètre est false, YouTube remplace l'ordre de lecture de la playlist par son ordre de lecture d'origine.

État de la lecture

player.getVideoLoadedFraction():Float: Cette fonction renvoie un nombre compris entre 0 et 1 spécifiant le pourcentage de la vidéo mis en mémoire tampon affiché dans le lecteur. Le nombre renvoyé avec cette méthode est plus fiable qu'avec les méthodes getVideoBytesLoaded et getVideoBytesTotal, désormais obsolètes.

player.getPlayerState():Number

Cette fonction renvoie l'état du lecteur. Les valeurs possibles sont :

-1 : non démarré
0 : arrêté
1 : en lecture
2 : en pause
3 : en mémoire tampon
5 : en file d'attente

player.getCurrentTime():Number: Cette fonction renvoie la durée écoulée en secondes depuis le début de la lecture de la vidéo.

player.getVideoStartBytes():Number: Fonction obsolète depuis le 31 octobre 2012 qui permettait de renvoyer le nombre d'octets à partir duquel le fichier vidéo a commencé à se charger. (Cette méthode renvoie désormais systématiquement la valeur 0.) Exemple de cas : l'utilisateur accède à un moment de la vidéo qui n'a pas encore été chargé et le lecteur envoie une nouvelle requête pour lire cette partie de la vidéo.

player.getVideoBytesLoaded():Number: Fonction obsolète depuis le 18 juillet 2012. Utilisez à la place la méthode getVideoLoadedFraction pour déterminer le pourcentage de la vidéo mis en mémoire tampon.

Cette méthode renvoie une valeur comprise entre 0 et 1000 estimant la proportion de la vidéo déjà chargée. Vous pouvez calculer la fraction de la vidéo qui a été chargée en divisant la valeur de getVideoBytesLoaded par la valeur de getVideoBytesTotal.

player.getVideoBytesTotal():Number: Fonction obsolète depuis le 18 juillet 2012. Utilisez à la place la méthode getVideoLoadedFraction pour déterminer le pourcentage de la vidéo mis en mémoire tampon.

Cette fonction renvoie la taille en octets (exacte ou approximative) de la vidéo en cours de chargement/de lecture.

Cette méthode renvoie systématiquement la valeur 1000. Vous pouvez calculer la fraction de la vidéo qui a été chargée en divisant la valeur de getVideoBytesLoaded par la valeur de getVideoBytesTotal.

Qualité de la lecture

player.getPlaybackQuality():String: Cette fonction permet de récupérer la qualité réelle de la vidéo en cours de lecture. Les valeurs possibles sont les suivantes : highres, hd1080, hd720, large, medium et small. La valeur undefined peut également être récupérée si aucune vidéo n'est lue.

player.setPlaybackQuality(suggestedQuality:String):Void

Cette fonction définit la qualité recommandée pour la vidéo en cours de lecture. Elle entraîne le rechargement de la vidéo à sa position actuelle dans la qualité nouvellement définie. Si la qualité de la lecture est modifiée, elle l'est uniquement pour la vidéo en cours de lecture. Cette fonction ne garantit pas la modification effective de la qualité de la lecture. Cependant, si la qualité de la lecture est modifiée, l'événement onPlaybackQualityChange se déclenche et votre code doit répondre à l'événement plutôt que réagir à l'appel de la fonction setPlaybackQuality.

Les valeurs possibles pour le paramètre suggestedQuality sont les suivantes : small, medium, large, hd720, hd1080, highres ou default. Nous vous conseillons de définir la valeur du paramètre sur default. Ainsi, YouTube pourra sélectionner la qualité de lecture la plus adaptée, qui peut varier selon les utilisateurs, les vidéos, les systèmes et d'autres conditions de lecture.

Si vous définissez une qualité de lecture recommandée pour une vidéo, celle-ci s'applique uniquement à la vidéo en question. Vous devez sélectionner une qualité de lecture qui correspond à la taille de votre lecteur vidéo. Par exemple, si votre page affiche un lecteur vidéo de 1 280 x 720 pixels, une vidéo en qualité hd720 s'affiche mieux qu'une vidéo en qualité hd1080. Nous vous conseillons d'appeler la fonction getAvailableQualityLevels() pour déterminer les différentes qualités disponibles pour une vidéo.

La liste ci-dessous répertorie les niveaux de qualité de lecture correspondant aux différentes tailles de lecteur standards. Nous vous conseillons d'utiliser l'une de ces valeurs pour définir la hauteur de votre lecteur vidéo et le format 16:9. Comme nous l'expliquons précédemment, même si vous sélectionnez une taille de lecteur standard, nous vous conseillons également de définir la valeur du paramètre suggestedQuality sur default pour permettre à YouTube de sélectionner la qualité de lecture la plus adaptée.

Niveau de qualité small : la hauteur du lecteur est de 240 pixels, et ses dimensions sont de 320 x 240 pixels minimum au format 4:3.
Niveau de qualité medium : la hauteur du lecteur est de 360 pixels, et ses dimensions sont de 640 x 360 pixels (au format 16:9) ou de 480 x 360 pixels (au format 4:3).
Niveau de qualité large : la hauteur du lecteur est de 480 pixels, et ses dimensions sont de 853 x 480 pixels (au format 16:9) ou de 640 x 480 pixels (au format 4:3).
Niveau de qualité hd720 : la hauteur du lecteur est de 720 pixels, et ses dimensions sont de 1 280 x 720 pixels (au format 16:9) ou de 960 x 720 pixels (au format 4:3).
Niveau de qualité hd1080 : la hauteur du lecteur est de 1 080 pixels, et ses dimensions sont de 1 920 x 1 080 pixels (au format 16:9) ou de 1 440 x 1 080 pixels (au format 4:3).
Niveau de qualité highres : la hauteur du lecteur est supérieure à 1 080 pixels, ce qui signifie que le format du lecteur est supérieur à 1 920 x 1 080 pixels.
Niveau de qualité default : YouTube sélectionne la qualité de lecture appropriée. Cette valeur rétablit la qualité au niveau par défaut et annule les paramétrages précédents de la qualité de lecture utilisant les fonctions cueVideoById, loadVideoById ou setPlaybackQuality.

Si vous appelez la fonction setPlaybackQuality avec un niveau de qualité suggestedQuality non disponible pour la vidéo, la qualité sera définie au niveau inférieur le plus proche disponible. Par exemple, si vous définissez le niveau de qualité large et que ce niveau n'est pas disponible pour la vidéo, la qualité de lecture est définie sur medium (si ce niveau est disponible).

De plus, si le paramètre suggestedQuality est défini sur une valeur non valide comme niveau de qualité, cela revient à définir le paramètre suggestedQuality sur default.

player.getAvailableQualityLevels():Array: Cette fonction renvoie la liste des formats de qualité disponibles pour la vidéo en cours de lecture. Vous pouvez utiliser cette fonction pour déterminer si la vidéo est disponible dans une meilleure qualité que celle actuellement utilisée pour son visionnage. Votre lecteur peut afficher un bouton ou un autre élément permettant aux utilisateurs de régler la qualité de lecture.

Cette fonction renvoie une série de chaînes de caractères qui classent les niveaux de qualité du plus élevé au plus bas. La valeur des éléments de la série peut être highres, hd1080, hd720, large, medium et small. Cette fonction renvoie une série vide si aucune vidéo n'est en cours de lecture.

Faites en sorte que votre client ne passe pas automatiquement à la qualité vidéo la plus élevée (ou la plus basse), ou à un format inconnu. YouTube peut élargir la liste des niveaux de qualité pour inclure des formats non adaptés au contexte de votre lecteur. De même, YouTube peut supprimer les options de qualité qui altèrent l'expérience de visionnage des utilisateurs. En veillant à ce que votre client utilise uniquement des formats connus et disponibles, vous pouvez garantir que ses performances ne seront pas altérées par l'ajout ou la suppression de niveaux de qualité non adaptés au contexte d'affichage de votre lecteur.

Récupérer des informations sur la vidéo

player.getDuration():Number: Cette fonction renvoie la durée en secondes de la vidéo en cours de lecture. Sachez que la fonction 0 renvoie la valeur 0 jusqu'à ce que les métadonnées de la vidéo soient chargées, normalement juste après le lancement de la lecture.

Si la vidéo en cours de lecture est un événement en direct, la fonction getDuration() renvoie la durée écoulée depuis le début de la diffusion en direct. Il s'agit précisément de la durée pendant laquelle la vidéo a été diffusée sans avoir été réinitialisée ou suspendue. De plus, cette durée est généralement plus longue que la durée réelle de l'événement, car la diffusion peut commencer avant le début de l'événement.

player.getVideoUrl():String: Cette fonction renvoie l'URL YouTube.com de la vidéo en cours de chargement/de lecture.

player.getVideoEmbedCode():String: Cette fonction renvoie le code d'intégration de la vidéo en cours de chargement/de lecture.

Récupérer des informations sur la playlist

player.getPlaylist():Array: Cette fonction renvoie la liste des ID vidéo d'une playlist dans l'ordre dans lequel les vidéos correspondantes apparaissent. Par défaut, cette fonction renvoie les ID vidéo dans l'ordre défini par le propriétaire de la playlist. Cependant, si vous appelez la fonction setShuffle pour lire la playlist de façon aléatoire, la valeur renvoyée par la fonction getPlaylist() représente l'ordre de lecture aléatoire des vidéos.

player.getPlaylistIndex():Number

Cette fonction renvoie l'index de la vidéo en cours de lecture dans la playlist.

Si la lecture de la playlist n'est pas aléatoire, la valeur renvoyée identifie la position à laquelle le créateur de la playlist a placé la vidéo. Les index renvoyés sont de type base zéro. Ainsi, la valeur 0 identifie la première vidéo de la playlist.
Si la lecture de la playlist est aléatoire, la valeur renvoyée identifie la position des vidéos dans la playlist selon l'ordre redéfini par le mode aléatoire.

Ajouter ou supprimer un écouteur d'événements

player.addEventListener(event:String, listener:String):Void: Ce paramètre ajoute une fonction d'écouteur pour l'événement event spécifié. La section Événements ci-dessous identifie les différents événements que le lecteur peut déclencher. L'écouteur correspond à une chaîne de caractères spécifiant la fonction qui s'exécute lorsque l'événement spécifié est déclenché.

player.removeEventListener(event:String, listener:String):Void: Ce paramètre supprime une fonction d'écouteur pour l'événement event spécifié. L'élément listener correspond à une chaîne de caractères identifiant la fonction qui ne s'exécute plus lorsque l'événement spécifié est déclenché.

Accéder à des nœuds DOM et les modifier

player.getIframe():Object: Cette méthode renvoie le nœud DOM de l'élément <iframe> intégré.

player.destroy():Void: Cette méthode supprime l'élément <iframe> contenant le lecteur.

Événements

L'API déclenche des événements pour informer votre application des modifications apportées au lecteur intégré. Comme nous l'avons expliqué dans la section précédente, vous pouvez activer les événements en ajoutant un écouteur d'événements lors de la construction de l'objet YT.Player, ou en utilisant la fonction addEventListener.

L'API utilise un objet de type événement comme seul argument de chacune de ces fonctions. L'objet de type événement comporte les propriétés suivantes :

La propriété target identifie le lecteur vidéo correspondant à l'événement.
La propriété data spécifie une valeur pertinente pour l'événement. Sachez que l'événement onReady ne permet de définir aucune propriété data.

La liste suivante répertorie les événements déclenchés par l'API :

onReady

Cet événement se déclenche dès que le lecteur est chargé et prêt à recevoir des appels de l'API. Votre application doit mettre en œuvre cette fonction si vous souhaitez exécuter automatiquement certaines opérations dès que le lecteur est prêt, telles que la lecture de la vidéo ou l'affichage d'informations sur celle-ci.

L'exemple ci-dessous présente une fonction permettant de traiter cet événement. L'objet de type événement que l'API envoie à la fonction comporte une propriété target qui identifie le lecteur. La fonction récupère le code d'intégration de la vidéo actuellement chargée, lance sa lecture et affiche le code d'intégration sur l'élément de page dont la valeur id est embed-code.

function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}

onStateChange

Cet événement se déclenche dès que l'état du lecteur change. La valeur de la propriété data de l'objet de type événement envoyée par l'API à la fonction de votre écouteur d'événements est un entier correspondant au nouvel état du lecteur. Les valeurs possibles sont :

-1 : non démarré
0 : arrêté
1 : en lecture
2 : en pause
3 : en mémoire tampon
5 : en file d'attente

Lorsque le lecteur charge une vidéo, il envoie un événement unstarted (-1). Lorsqu'une vidéo est en file d'attente et prête à être lue, le lecteur envoie un événement video cued (5). Dans votre code, vous pouvez spécifier les entiers possibles comme valeur ou utiliser les variables d'espace de nom suivantes :

YT.PlayerState.ENDED
YT.PlayerState.PLAYING
YT.PlayerState.PAUSED
YT.PlayerState.BUFFERING
YT.PlayerState.CUED

onPlaybackQualityChange

Cet événement se déclenche dès que la qualité de lecture d'une vidéo est modifiée. Par exemple, si vous appelez la fonction setPlaybackQuality(suggestedQuality), cet événement se déclenche si la qualité de lecture change réellement. Vous devez configurer votre application de façon qu'elle réponde à cet événement en sachant que la qualité ne sera pas automatiquement modifiée lorsque la fonction setPlaybackQuality(suggestedQuality) sera appelée. De même, rédigez votre code en partant du principe que la qualité de la lecture ne sera pas modifiée uniquement si la fonction setPlaybackQuality, ou une autre fonction permettant de définir une qualité de lecture recommandée, est explicitement appelée.

La valeur de la propriété data de l'objet de type événement envoyée par l'API à la fonction de l'écouteur d'événements est une chaîne de caractères spécifiant la nouvelle qualité de lecture. Les valeurs possibles sont :

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: Cet événement se déclenche dès que la vitesse de lecture de la vidéo est modifiée. Par exemple, si vous appelez la fonction setPlaybackRate(suggestedRate), cet événement se déclenche si la vitesse de lecture est réellement modifiée. Vous devez configurer votre application de sorte qu'elle réponde à cet événement en sachant que la vitesse de lecture ne sera pas automatiquement modifiée lorsque la fonction setPlaybackRate(suggestedRate) sera appelée. De même, rédigez votre code en partant du principe que la vitesse de lecture ne sera pas modifiée uniquement si la fonction setPlaybackRate est explicitement appelée.

La valeur de la propriété data de l'objet de type événement envoyée par l'API à la fonction de l'écouteur d'événements est un nombre spécifiant la nouvelle vitesse de lecture. La fonction getAvailablePlaybackRates renvoie la liste des vitesses de lecture valides pour la vidéo en file d'attente ou en cours de lecture.

onError

Cet événement se déclenche si une erreur se produit sur le lecteur. L'API envoie un objet event à la fonction de l'écouteur d'événements. La valeur de la propriété data de cet objet est un entier qui identifie le type de l'erreur qui s'est produite. Les valeurs possibles sont :

2 : la requête contient une valeur incorrecte pour un paramètre. Par exemple, cette erreur se produit si vous spécifiez un ID vidéo ne comportant pas 11 caractères, ou si l'ID vidéo contient des caractères incorrects, tels que des points d'exclamation ou des astérisques.
5 : le contenu demandé ne peut pas être lu dans un lecteur HTML5 ou une autre erreur liée au lecteur HTML5 s'est produite.
100 : impossible de trouver la vidéo demandée. Cette erreur se produit lorsqu'une vidéo a été supprimée (pour une raison quelconque) ou a été rendue privée.
101 : le propriétaire de la vidéo demandée n'autorise pas sa lecture dans des lecteurs intégrés.
150 : cette erreur est la même que celle définie par la valeur 101. Il s'agit simplement d'une erreur 101 masquée.

onApiChange

Cet événement se déclenche pour indiquer que le lecteur a chargé (ou déchargé) un module avec des méthodes d'API exposées. Votre application peut répondre à cet événement en interrogeant le lecteur pour déterminer les options exposées pour le module récemment chargé, puis récupérer ou mettre à jour les paramètres existants de ces options.

La commande suivante permet de récupérer une série de noms de modules pour lesquels vous pouvez définir les options du lecteur :

player.getOptions();

À l'heure actuelle, le module cc, qui gère les sous-titres dans le lecteur, est le seul module dont vous pouvez définir les options. Dès la réception d'un événement onApiChange, votre application peut utiliser la commande suivante pour déterminer les options qui peuvent être définies pour le module cc :

player.getOptions('cc');

En interrogeant le lecteur avec cette commande, vous pouvez confirmer que les options auxquelles vous souhaitez accéder sont bien disponibles. Les commandes suivantes permettent de récupérer et de mettre à jour les options du module :

Récupérer une option :
player.getOption(module, option);

Définir une option :
player.setOption(module, option, value);

Le tableau suivant répertorie les options compatibles avec l'API :

Module	Option	Description
cc	fontSize	Cette option permet de définir la taille de la police des sous-titres dans le lecteur. Les valeurs valides sont `-1`, `0`, `1`, `2` et `3`. La taille par défaut est `0`, la taille minimum étant `-1`. Si la valeur de cette option est un entier inférieur à `-1`, les sous-titres s&#`3`9;affichent dans la taille de police la plus petite ; si la valeur de cette option est un entier supérieur à `3`, les sous-titres s'affichent dans la taille de police la plus grande.
cc	reload	Cette option permet de recharger les données relatives aux sous-titres pour la vidéo en cours de lecture. L'option est définie sur `null` si vous récupérez la valeur de l'option. Définissez la valeur sur `true` pour recharger les données relatives aux sous-titres.

Remarques concernant les appareils mobiles

Lecture automatique et lecture avec script

Dans certains navigateurs mobiles (tels que Chrome et Safari), l'élément <video> d'un code HTML5 n'autorise la lecture que si celle-ci est lancée par l'utilisateur (en appuyant sur le lecteur, par exemple). Voici un extrait de la documentation d'Apple relatif à ce sujet :

"Avertissement : pour empêcher les téléchargements non souhaités sur les réseaux mobiles aux frais de l'utilisateur, la lecture de fichiers multimédias intégrés ne peut pas être lancée automatiquement dans Safari pour iOS. Seul l'utilisateur peut lui-même lancer la lecture."

En raison de ces restrictions, les fonctions et les paramètres comme autoplay, playVideo() et loadVideoById() ne fonctionnent pas sur l'ensemble des appareils mobiles.

Exemples

Créer des objets YT.Player

Exemple 1 : lecture avec un volume élevé

L'exemple de code ci-dessous permet de créer un lecteur vidéo de 1 280 x 720 pixels. L'écouteur de l'événement onReady appelle ensuite la fonction setVolume pour régler le volume au niveau le plus élevé.

function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

Exemple 2 : dans cet exemple, le lecteur est configuré de manière à lire automatiquement la vidéo lors de son chargement et à masquer les commandes du lecteur. Des écouteurs d'événements sont également ajoutés pour tous les événements envoyés par l'API.

function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

Historique des révisions

Cette section répertorie les modifications apportées à l'API Player iFrame YouTube et à la documentation. S'abonner à ce journal des modifications