Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Eventos de HTMLMediaElement

Usa nueve eventos de audio y vídeo para mantener sincronizados la posición, la duración y los controles, y detectar un reinicio, el fin de la reproducción o un error.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

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

HTMLMediaElement es la interfaz del navegador que comparten los elementos audio y video, no una parte de ECMAScript. Usa addEventListener() directamente en el elemento multimedia, preferiblemente antes de asignar src: estos eventos no se propagan hacia los ancestros ni se pueden cancelar. En cada manejador, consulta el estado actual del elemento en lugar de inferirlo del orden de los eventos.

loadedmetadata indica que hay metadatos disponibles, como las dimensiones del vídeo, no que la reproducción esté lista. durationchange señala que se ha determinado o actualizado la duración: duration se expresa en segundos, vale NaN cuando no hay datos e Infinity si no hay un final delimitado. emptied indica que se ha reiniciado el estado del recurso, por ejemplo al recargar. Borra entonces de la interfaz los datos del recurso anterior: el reinicio por sí solo no tiene por qué disparar durationchange.

Con timeupdate, lee currentTime en segundos para actualizar el indicador de posición. Puede dispararse al reproducir o al saltar a otro punto; no es un temporizador de frecuencia fija ni una señal por fotograma. play indica que paused pasó a false, no que la reproducción haya comenzado (playing). pause indica la transición al estado de pausa, no una falta temporal de datos. Con volumechange, lee tanto volume como muted: un cambio en cualquiera puede dispararlo.

ended indica que se alcanzó el final, no una pausa normal, aunque al final también puede producirse pause. Si loop es true y playbackRate no es negativo, ended no se dispara. Con error, consulta media.error, por ejemplo media.error?.code; este MediaError se refiere al recurso multimedia. Gestiona por separado los rechazos de la promesa de play(): por ejemplo, NotAllowedError puede deberse a la política de reproducción automática sin disparar un evento multimedia error.

Ejemplos

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

Resultado

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.

Guarda el ejemplo como archivo HTML y ábrelo en un navegador que admita WAV PCM y permita recursos multimedia `blob:`. Consulta los eventos en la consola de desarrollo. Usa los controles integrados para reproducir y pausar. La demo genera tres segundos de silencio sin descargar archivos; el momento y el número de eventos pueden variar. `Remove demo` elimina los controles y libera las URL de objeto.

Lecciones relacionadas

  • JavaScript · Lección 28 · Intermedio · Versión: 3

Fuentes