HTMLMediaElement : méthode play()

Baseline Large disponibilité

Cette fonctionnalité est bien établie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis juillet 2015.

La méthode play() de l'interface HTMLMediaElement tente de commencer la lecture du média. Elle retourne une promesse (Promise) qui est résolue lorsque la lecture a commencé avec succès.

Si la lecture ne peut pas commencer pour une raison quelconque, comme des problèmes de permission, la promesse est rejetée.

Syntaxe

play()

Valeur de retour

Une promesse (Promise) qui est résolue lorsque la lecture a commencé avec succès, ou rejetée si la lecture ne peut pas commencer pour une raison quelconque.

Note : Les navigateurs publiés avant 2019 peuvent ne pas retourner de valeur depuis play().

Le gestionnaire de rejet de la promesse est appelé avec un objet DOMException passé en tant que seul paramètre d'entrée (par opposition à une exception traditionnelle étant levée). Les erreurs possibles incluent :

NotAllowedError DOMException: Fournie si l'agent utilisateur (navigateur) ou le système d'exploitation n'autorise pas la lecture des médias dans le contexte ou la situation actuelle. Le navigateur peut exiger que l'utilisateur·ice démarre explicitement la lecture des médias en cliquant sur un bouton « lecture », par exemple en raison d'une Politique de permissions.
NotSupportedError DOMException: Fournie si la source du média (qui peut être définie comme un objet MediaStream, MediaSource, Blob ou File, par exemple) ne représente pas un format de média pris en charge.

D'autres exceptions peuvent être signalées, selon les détails d'implémentation du navigateur, de l'implémentation du lecteur multimédia, etc.

Notes d'utilisation

Bien que le terme « autoplay » soit généralement associé aux pages qui commencent immédiatement à lire des médias dès leur chargement, les politiques de lecture automatique des navigateurs s'appliquent également à toute lecture de médias initiée par un script, y compris les appels à play().

Si l'agent utilisateur est configuré pour ne pas autoriser la lecture automatique ou initiée par script des médias, l'appel à play() entraînera le rejet immédiat de la promesse retournée avec une NotAllowedError. Les sites Web doivent être prêts à gérer cette situation. Par exemple, un site ne doit pas présenter une interface utilisateur qui suppose que la lecture a commencé automatiquement, mais doit plutôt mettre à jour son interface en fonction de la réussite ou du rejet de la promesse retournée. Voir l'exemple ci-dessous pour plus d'informations.

Note : La méthode play() peut amener l'utilisateur·ice à être invité·e à accorder la permission de lire le média, ce qui peut entraîner un délai avant que la promesse retournée ne soit résolue. Assurez-vous que votre code ne s'attend pas à une réponse immédiate.

Pour des informations encore plus détaillées sur la lecture automatique et le blocage de la lecture automatique, consultez notre article Guide de la lecture automatique pour les API média et Web Audio.

Exemples

Confirmer la lecture et gérer les états

Cet exemple montre comment confirmer que la lecture a commencé et comment gérer, de manière élégante, les blocages de lecture automatique.

Lorsque cet exemple est exécuté, il commence par collecter des références à l'élément HTML <video> ainsi qu'au <button> utilisé pour basculer la lecture. Il configure ensuite un gestionnaire d'évènements pour l'évènement click sur le bouton de basculement et tente de commencer automatiquement la lecture en appelant la fonction async playVideo().

Une fonction d'aide toggleButton() nous permet de définir ce qui doit se passer dans le code lorsque nous lui passons une valeur booléenne représentant l'état de lecture (par exemple, toggleButton(true)). Si la lecture réussit, le texte du bouton et son aria-label changent pour « Pause ». Si la lecture échoue, le bouton et l'aria-label affichent « Lecture ». Cela garantit que le playButton correspond à l'état de lecture en surveillant la résolution ou le rejet de la Promise retournée par play() :

html

<div class="bloc-video">
  <video
    id="video"
    width="480"
    loop
    src="/shared-assets/videos/flower.mp4"></video>
  <button type="button" id="bouton-lecture" aria-label="Lecture"></button>
</div>

let elementVideo = document.getElementById("video");
let boutonLecture = document.getElementById("bouton-lecture");

boutonLecture.addEventListener("click", gererBoutonLecture);
playVideo();

function basculerBouton(playing) {
  if (playing) {
    boutonLecture.textContent = "Pause";
    boutonLecture.setAttribute("aria-label", "Pause");
  } else {
    boutonLecture.textContent = "Lecture";
    boutonLecture.setAttribute("aria-label", "Lecture");
  }
}

async function playVideo() {
  try {
    await elementVideo.play();
    basculerBouton(true);
  } catch (err) {
    basculerBouton(false);
  }
}

function gererBoutonLecture() {
  if (elementVideo.paused) {
    playVideo();
  } else {
    elementVideo.pause();
    basculerBouton(false);
  }
}

.bloc-video {
  position: relative;
}

#video {
  border: 2px solid black;
}

#bouton-lecture {
  position: absolute;
  top: 10px;
  left: 10px;
  padding: 8px 12px;
  background-color: black;
  color: white;
  border: none;
  cursor: pointer;
}