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

CKTIS / JavaScript

Événements de HTMLMediaElement

Utilisez neuf événements audio et vidéo pour synchroniser la position, la durée et les commandes, et détecter une réinitialisation, la fin de la lecture ou une erreur.

Version : ECMAScript 2024 and the current web platform; runtime support varies

Syntaxe

media.addEventListener(type, (event) => { /* read event.currentTarget here */ });
// type: "timeupdate" | "loadedmetadata" | "durationchange" | "emptied"
//     | "play" | "pause" | "volumechange" | "ended" | "error"

HTMLMediaElement est l’interface du navigateur commune aux éléments audio et video, et non une fonctionnalité d’ECMAScript. Utilisez addEventListener() directement sur l’élément multimédia, de préférence avant de définir src : ces événements ne remontent pas vers les ancêtres et ne sont pas annulables. Dans chaque gestionnaire, lisez l’état actuel de l’élément plutôt que de le déduire de l’ordre des événements.

loadedmetadata indique que les métadonnées, comme les dimensions de la vidéo, sont disponibles, pas que la lecture peut commencer. durationchange signale une durée nouvellement connue ou révisée : duration est exprimée en secondes, vaut NaN en l’absence de données et Infinity si la fin n’est pas bornée. emptied indique que l’état de la ressource a été réinitialisé, par exemple lors d’un rechargement. Effacez alors les anciennes informations de l’interface : la seule réinitialisation ne déclenche pas nécessairement durationchange.

À la réception de timeupdate, lisez currentTime en secondes pour rafraîchir l’indicateur de position. L’événement peut survenir pendant la lecture ou un déplacement sur la piste ; ce n’est ni une minuterie régulière ni un signal par image. play indique que paused est passé à false, pas que la lecture a effectivement commencé (playing). pause signale le passage à l’état en pause, pas un manque temporaire de données. Pour volumechange, lisez volume et muted : la modification de l’un ou de l’autre peut le déclencher.

ended signale que la fin est atteinte, pas une pause ordinaire, même si pause peut aussi survenir à la fin. Si loop vaut true et que playbackRate est positif ou nul, ended ne se déclenche pas. Pour error, examinez media.error, par exemple media.error?.code : ce MediaError concerne la ressource. Traitez séparément les rejets de la promesse renvoyée par play() : par exemple, NotAllowedError peut résulter des règles de lecture automatique sans déclencher d’événement multimédia error.

Exemples

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>HTMLMediaElement events</title>
</head>
<body>
<script>
(() => {
  const panel = document.createElement('div');
  const audio = document.createElement('audio');
  audio.controls = true;
  audio.preload = 'metadata';
  panel.append(audio);

  // Generate three seconds of silence as mono, 8-bit PCM WAV.
  const rate = 8000;
  const samples = 3 * rate;
  const bytes = new Uint8Array(44 + samples);
  const view = new DataView(bytes.buffer);
  const tag = (offset, text) => bytes.set(new TextEncoder().encode(text), offset);
  const u16 = (offset, value) => view.setUint16(offset, value, true);
  const u32 = (offset, value) => view.setUint32(offset, value, true);
  tag(0, 'RIFF'); u32(4, 36 + samples); tag(8, 'WAVE');
  tag(12, 'fmt '); u32(16, 16); u16(20, 1); u16(22, 1);
  u32(24, rate); u32(28, rate); u16(32, 1); u16(34, 8);
  tag(36, 'data'); u32(40, samples); bytes.fill(128, 44);
  const wav = URL.createObjectURL(new Blob([bytes], { type: 'audio/wav' }));
  const bad = URL.createObjectURL(new Blob(['not audio'], { type: 'audio/wav' }));

  const listeners = new AbortController();
  const types = ['timeupdate', 'loadedmetadata', 'durationchange', 'emptied',
    'play', 'pause', 'volumechange', 'ended', 'error'];
  for (const type of types) {
    audio.addEventListener(type, ({ currentTarget: media }) => {
      console.log(type, {
        currentTime: media.currentTime, duration: media.duration,
        paused: media.paused, ended: media.ended,
        volume: media.volume, muted: media.muted,
        errorCode: media.error?.code ?? null
      });
    }, { signal: listeners.signal });
  }

  function button(label, action) {
    const control = document.createElement('button');
    control.type = 'button';
    control.textContent = label;
    control.addEventListener('click', action);
    panel.append(control);
  }
  button('Mute / unmute', () => { audio.muted = !audio.muted; });
  button('Reload', () => { audio.src = wav; });
  button('Load invalid audio', () => { audio.src = bad; });
  button('Remove demo', () => {
    listeners.abort();
    audio.removeAttribute('src');
    audio.load();
    panel.remove();
    URL.revokeObjectURL(wav);
    URL.revokeObjectURL(bad);
  });
  document.body.prepend(panel);
  audio.src = wav;
})();
</script>
</body>
</html>

Résultat

Expected observations, not a fixed transcript (each event name is logged with a state object):
- Initial load: durationchange and loadedmetadata; duration is 3 seconds at loadedmetadata.
- Play, pause, resume, and let the clip finish: play, timeupdate (repeated), pause, play again, and eventually ended. A pause event can also occur at the end.
- Mute / unmute: volumechange; muted toggles.
- Reload after metadata is available: emptied, then fresh durationchange and loadedmetadata.
- Load invalid audio: error with a non-null errorCode; emptied can appear first.

Enregistrez l’exemple dans un fichier HTML et ouvrez-le dans un navigateur qui prend en charge le WAV PCM et autorise les médias `blob:`. Consultez les événements dans la console de développement. Utilisez les commandes intégrées pour lire et mettre en pause. La démo génère trois secondes de silence sans télécharger de fichier ; le moment et le nombre des événements peuvent varier. `Remove demo` retire les commandes et libère les URL d’objet.

Leçons associées

  • JavaScript · Leçon 28 · Intermédiaire · Version : 3

Sources