Masquer

YouTube JavaScript Player API Reference

L'API JavaScript permet aux utilisateurs de contrôler les lecteurs vidéo YouTube intégrés et Chromeless via JavaScript. Des fonctions peuvent être appelées pour lire une vidéo, la mettre en pause, atteindre certains passages, régler le volume, couper le son et utiliser d'autres fonctionnalités utiles.

Configuration requise

L'utilisateur final doit disposer de Flash Player 10.1 ou version ultérieure pour afficher correctement le lecteur. Nous vous conseillons donc d'utiliser la méthode SWFObject pour intégrer le fichier SWF et détecter la version de Flash Player utilisée par l'internaute.

De plus, les pages HTML contenant un lecteur YouTube doivent mettre en œuvre la fonction JavaScript onYouTubePlayerReady. L'API appelle cette fonction lorsque le lecteur est entièrement chargé et qu'elle est prête à recevoir des appels. Consultez la section Gestionnaires d'événements pour en savoir plus.

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.

Premiers pas

Remarque : Pour tester ces appels, votre fichier doit s'exécuter sur un serveur Web, car le lecteur Flash restreint les appels entre fichiers locaux et Internet.

Vous pouvez activer les gestionnaires de l'API JavaScript pour les lecteurs Chromeless et intégrés. Pour cela, ajoutez le paramètre enablejsapi=1 à l'URL du lecteur.

  • Activer l'API JavaScript pour un lecteur Chromeless

    Utilisez l'URL ci-dessous pour charger un lecteur Chromeless dans votre application et activer les gestionnaires de l'API JavaScript dans le lecteur. Vous pouvez construire vos commandes personnalisées du lecteur à l'aide de JavaScript.

    http://www.youtube.com/apiplayer?enablejsapi=1&version=3
  • Activer l'API JavaScript pour un lecteur intégré

    Pour charger un lecteur vidéo intégré, utilisez l'URL ci-dessous en remplaçant la chaîne VIDEO_ID par l'ID vidéo YouTube de 11 caractères identifiant la vidéo à lire.

    http://www.youtube.com/v/VIDEO_ID?version=3&enablejsapi=1

Lorsque le lecteur est prêt, l'API appelle la fonction de rappel onYouTubePlayerReady. Vous pouvez ajouter le paramètre facultatif playerapiid à l'URL du lecteur pour renvoyer une valeur, comme l'ID du lecteur, à la fonction de rappel.

http://www.youtube.com/v/VIDEO_ID?enablejsapi=1&version=3&playerapiid=ytplayer

Une fois le lecteur SWF chargé, vous pouvez utiliser les fonctions de mise en file d'attente (cueVideoById(), loadVideoById(), cueVideoByUrl(), loadVideoByUrl(), cuePlaylist() ou loadPlaylist()) pour charger une vidéo ou une playlist YouTube spécifiques.

La démo de l'API Player vous permet de comparer les lecteurs vidéo Chromeless et intégrés, et les exemples ci-dessous expliquent de façon détaillée comment intégrer un lecteur YouTube SWF sur votre page. Vous pouvez également créer une expérience utilisateur entièrement personnalisée en utilisant les paramètres du lecteur pour contrôler son comportement.

Opérations

Pour appeler les méthodes de l'API Player, vous devez d'abord obtenir une référence de l'objet du lecteur que vous souhaitez contrôler. Si vous utilisez la méthode SWFObject pour intégrer le lecteur SWF, vous pouvez obtenir la référence de l'objet du lecteur en appelant la fonction getElementById() dans les balises <object> ou <embed> contenant le lecteur SWF.

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

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

Remarque : Bien que le lecteur AS3 soit compatible avec les commandes de vitesse de lecture, seul le lecteur HTML5 est compatible avec les vitesses variables.

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 fonction renvoie le nombre d'octets chargés de la vidéo en cours.
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 fonction offre spécifiquement une estimation de la taille totale de la vidéo lorsque la valeur de player.getVideoStartBytes() est supérieure à zéro. Elle ne peut fournir qu'une approximation de la taille de la vidéo, car la taille réelle est uniquement transmise au lecteur lorsque la vidéo est lue depuis le début.

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

Événements

onStateChange
Cet événement se déclenche dès que l'état du lecteur change. La valeur 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 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 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.

Remarque : Bien que le lecteur AS3 soit compatible avec ce type d'événement, les vitesses variables sont actuellement uniquement compatibles avec le lecteur HTML5.

onError
Cet événement se déclenche si une erreur se produit sur le lecteur. La valeur envoyée par l'API à la fonction de l'écouteur d'événements 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.
  • 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&#39;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.

Gestionnaires d'événements

Les pages HTML qui affichent le lecteur Chromeless doivent mettre en œuvre la fonction de rappel onYouTubePlayerReady. L'API appelle cette fonction lorsque le lecteur est entièrement chargé et qu'elle est prête à recevoir des appels.

onYouTubePlayerReady(playerid)
Cette fonction est appelée lorsque le lecteur est entièrement chargé et que l'API est prête à recevoir des appels. Si le paramètre playerapiid est utilisé dans les arguments de l'URL du lecteur, il sera transmis à cette fonction.

Exemples

Intégrer le lecteur YouTube avec la méthode SWFObject

Nous recommandons d'utiliser la méthode SWFObject pour intégrer des lecteurs accessibles à l'aide de l'API JavaScript. Cela permet de détecter la version de Flash Player de l'utilisateur final (l'API JavaScript nécessite Flash Player version 8 ou ultérieure) et d'empêcher l'affichage du message "Cliquez pour activer cette commande" lors de l'utilisation du lecteur avec Internet Explorer. Pour activer l'API dans le SWF, vous devez utiliser le paramètre enablejsapi=1.

L'exemple ci-dessous illustre l'utilisation du script pour intégrer un lecteur YouTube avec l'API JavaScript activée et le paramètre playerapiid défini sur ytplayer.

  <script type="text/javascript" src="swfobject.js"></script>
  <div id="ytapiplayer">
    You need Flash player 8+ and JavaScript enabled to view this video.
  </div>

  <script type="text/javascript">

    var params = { allowScriptAccess: "always" };
    var atts = { id: "myytplayer" };
    swfobject.embedSWF("http://www.youtube.com/v/VIDEO_ID?enablejsapi=1&playerapiid=ytplayer&version=3",
                       "ytapiplayer", "425", "356", "8", null, null, params, atts);

  </script>

Le paramètre allowScriptAccess du code est requis pour permettre au lecteur SWF d'appeler des fonctions sur la page HTML le contenant, car le lecteur n'est pas hébergé sur le même domaine que la page.

Le seul attribut utilisé est l'id de l'objet intégré soit, dans cet exemple, myytplayer. Cet ID permet d'obtenir une référence du lecteur à l'aide de la fonction getElementById().

swfobject.embedSWF charge le lecteur depuis YouTube et l'intègre à votre page.

swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

  • swfUrlStr : spécifie l'URL du fichier SWF. Sachez que nous avons ajouté les paramètres enablejsapi et playerapiid à l'URL YouTube du fichier SWF pour activer les appels de l'API JavaScript.
  • replaceElemIdStr : spécifie l'ID de l'élément HTML DIV à remplacer par le contenu intégré. Dans l'exemple ci-dessus, il s'agit de ytapiplayer.
  • widthStr : spécifie la largeur du lecteur.
  • heightStr : spécifie la hauteur du lecteur.
  • swfVersionStr : spécifie la version minimum dont doit disposer l'utilisateur pour afficher le contenu. Dans cet exemple, la version 8 ou une version ultérieure est requise. Si l'utilisateur ne dispose pas de l'une de ces versions, le texte par défaut défini dans l'élément HTML DIV s'affiche.
  • xiSwfUrlStr : (facultatif) spécifie l'URL de votre fichier SWF d'installation express. Cet argument n'est pas utilisé dans cet exemple.
  • flashVarsObj : (facultatif) spécifie les valeurs FlashVars avec une association nom:valeur. Cet argument n'est pas utilisé dans cet exemple.
  • parObj : (facultatif) spécifie les paramètres de l'objet intégré. Dans cet exemple, allowScriptAccess est utilisé.
  • AttObj : (facultatif) spécifie les attributs de l'objet intégré. Dans cet exemple, l'ID est défini sur myytplayer.

Consultez la documentation relative à la méthode SWFObject pour en savoir plus.

Obtenir la référence du lecteur

Lorsque le lecteur est prêt, il appelle la fonction onYouTubePlayerReady.

Pour obtenir la référence du lecteur, utilisez la fonction getElementById(). Dès que vous avez reçu l'objet, vous pouvez commencer à effectuer des appels de fonctions avec l'API.

    function onYouTubePlayerReady(playerId) {
      ytplayer = document.getElementById("myytplayer");
    }

Appeler des fonctions

Vous pouvez désormais appeler des fonctions en utilisant la référence du lecteur. Par exemple, pour lire la vidéo lorsqu'un utilisateur clique sur son lien, le code apparaît comme suit :

function play() {
  if (ytplayer) {
    ytplayer.playVideo();
  }
}

<a href="javascript:void(0);" onclick="play();">Play</a>

Ou tout simplement :

<a href="javascript:ytplayer.playVideo()">Play</a>

Activer les événements

Pour activer les événements, ajoutez un écouteur d'événements à la référence du lecteur. Par exemple, pour recevoir une notification lorsque l'état du lecteur change, ajoutez un écouteur d'événements pour l'événement onStateChange et une fonction de rappel.

function onYouTubePlayerReady(playerId) {
  ytplayer = document.getElementById("myytplayer");
  ytplayer.addEventListener("onStateChange", "onytplayerStateChange");
}

function onytplayerStateChange(newState) {
   alert("Player's new state: " + newState);
}

Démo

Vous pouvez utiliser la démo YouTube Player pour tester les fonctionnalités de l'API JavaScript avec un lecteur intégré ou Chromeless.

Historique des révisions

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

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

  • The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

October 31, 2012

This update contains the following changes:

  • The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

    In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)

  • When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.

  • The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 6, 2012

This update contains the following changes:

  • The API supports several new functions and one new event that can be used to control the video playback speed. However, note that variable playback speeds are currently only supported in the HTML5 player.

    • Functions

      • getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
      • getPlaybackRate – Retrieve the playback rate for the cued or playing video.
      • setPlaybackRate – Set the playback rate for the cued or playing video.

    • Events

July 19, 2012

This update contains the following changes:

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size. 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.

December 21, 2011

This update contains the following changes:

  • The Requirements section has been updated to note that the end user must have Flash Player 10.1 or higher installed for the player to display everything correctly.

December 19, 2011

This update contains the following changes:

  • The AS3 Player API now supports an object syntax for calling the cuePlaylist and loadPlaylist functions.

    The object syntax lets you pass an object as the only argument to a function. The object's properties specify the function arguments that you wish to set.

  • The cuePlaylist and loadPlaylist functions both support additional functionality when called using the object syntax. Specifically, when using the object syntax, you can use both functions to retrieve either a playlist, a list of search results, or a list of a user's uploaded videos. If you are using the argument syntax, you can only retrieve a playlist.

    To support this functionality, the object syntax defines a listType property that can be used to specify whether the player is retrieving a playlist, a list of search results, or a list of a user's uploaded videos. The object's list property then specifies the playlist ID, search query, or username that identifies the desired feed.

    To properly reflect this functionality, the Queueing functions for playlists section has been renamed to Queueing functions for lists. Within that section, the cuePlaylist and loadPlaylist functions are each defined twice to explain how to call each function using either the argument syntax or the object syntax.

December 5, 2011

This update contains the following changes:

  • The definition of the seekTo function has been updated to indicate that if the player is paused when the function is called, the player will remain paused after the function executes.

November 17, 2011

This update contains the following changes:

  • The definitions of the cueVideoByUrl and loadVideoByUrl functions have been updated in two ways:

    • The definition of the mediaContentUrl argument for each function has been updated to note that the value must specify the version parameter. As such, the argument's value must be a fully qualified YouTube player URL in the format http://www.youtube.com/v/VIDEO_ID?version=3.
    • Both functions support a suggestedQuality parameter. This parameter specifies the suggested playback quality for the video.
  • The definition of the setSize function has been removed from the documentation. If you are using the JavaScript Player API, the player will automatically resize if the height and width properties of the containing elements in the embed code are modified. Since the setSize function does not currently alter the size of those containing elements, it is unlikely to have the expected effect.

  • The definition of the getDuration function has been updated to explain that if the currently playing video is a live event, the function will return the elapsed time since the video stream began.

July 29, 2011

This update contains the following changes:

  • The following API functions have been added to support playlist players:

    • The cuePlaylist function loads the thumbnail image for the first video in the specified playlist and prepares the player to play the playlist. However, the player does not request the video until your application calls either the playVideo, playVideoAt, or seekTo function.

    • The loadPlaylist function loads and plays the specified playlist.

    • The getPlaylist function plays the currently cued playlist. The final player state after this function executes will be playing (1).

    • The getPlaylistIndex function returns the position in which the current video appears in the playlist. The first video will have a position of 1, the second video will have a position of 2, and so forth.

    • The nextVideo function instructs the player to load and play the next video in the playlist.

    • The previousVideo function instructs the player to load and play the previous video in the playlist.

    • The playVideoAt function instructs the player to load and play a specific video in the playlist.

    • The setLoop function lets you dynamically instruct the player to continuously play the playlist or, alternately, to sto playing after the playlist has played all of the videos in the playlist.

    • The setShuffle function instructs YouTube to play the videos in the playlist in random order (or to play them in their designated order.

February 17, 2011

This update contains the following changes:

  • If you link to the Player Parameters document from this document, the page will now display parameters supported in any version of the player. You can use the pulldown menu in the Overview section of that document to only see parameters supported in the AS3 player (or in the HTML5 or AS2) players.

February 3, 2011

This update contains the following changes:

  • The definition of the playVideo function has been updated to note that YouTube only counts playbacks that are initiated through a native play button in either the embedded or chromeless player.

  • If you link to the Player Parameters document from either the link in the Getting started section or from this paragraph, the page will initially only display parameters supported in the AS3 player. You can use the pulldown menu in the Overview section of that document to see parameters supported in other players (HTML5 or AS2) or all parameters.