Base de connaissancesCentre d’examen
FRFrançais
Choisir la langue13

CKTIS / JavaScript

HTMLMediaElement.play() — démarrer la lecture de façon asynchrone

La méthode play() demande le démarrage ou la reprise de la lecture audio ou vidéo. Elle renvoie une Promise : l’interface doit donc prendre en compte aussi bien le démarrage de la lecture que le rejet de la demande.

Version : ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

media.play() // Promise<undefined>; media is an HTMLAudioElement or HTMLVideoElement

HTMLMediaElement.play() est une méthode de l’API Web du navigateur pour les éléments audio et video, et non une fonction ECMAScript. Elle ne prend aucun argument. Elle renvoie une Promise qui est tenue avec la valeur undefined lorsque la lecture démarre — et non lorsque le média a fini.

Utilisez await media.play() dans un bloc try...catch. Ni le retour de l’appel ni paused === false ne confirment que la lecture a démarré. La promesse peut rester en attente pendant le chargement des données ; mettez l’interface à jour une fois qu’elle est résolue ou rejetée.

NotAllowedError signifie que la lecture n’est pas autorisée, par exemple en raison de la politique de lecture automatique. Appelez la méthode directement dans un gestionnaire de clic, tout en prévoyant le cas d’un refus. NotSupportedError concerne une source non prise en charge. L’interruption d’une demande en attente par pause() ou un rechargement peut provoquer AbortError.

L’exemple fournit volontairement du texte au lieu d’un enregistrement afin de montrer la gestion d’un rejet sans fichier externe. Il ne montre pas une lecture réussie. Cette API appartient au HTML Living Standard ; Node 24 dans un dépôt ne permet pas d’établir sa disponibilité dans un navigateur.

Exemples

const media = document.createElement('audio');
media.src = 'data:text/plain,not-media';
const button = document.createElement('button');
button.textContent = 'Test play()';
const status = document.createElement('pre');
document.body.append(button, status);

button.addEventListener('click', async () => {
  button.disabled = true;
  try {
    await media.play();
    status.textContent = 'Playback started';
  } catch (error) {
    status.textContent = `Rejected: ${error.name}`;
  } finally {
    button.disabled = false;
  }
});

Résultat

Rejected: NotSupportedError

Le code affiché et le résultat déclaré ont été vérifiés dans un environnement isolé selon la méthode consignée dans la preuve de vérification de cette version exacte.

Sources