CKTIS / JavaScript
HTMLMediaElement: `paused` y los eventos `play`, `pause`, `ended` y `error`
Distingue el estado actual del medio de sus eventos y del resultado de llamar a `play()`. Aprende a reconocer una pausa, el final natural y un fallo del recurso.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
media.paused
media.ended
media.error
media.play() // Promise<void>
media.pause() // undefined
media.addEventListener("play", listener)
media.addEventListener("pause", listener)
media.addEventListener("ended", listener)
media.addEventListener("error", listener)HTMLMediaElement es la interfaz de la plataforma web para los elementos de audio y vídeo; no forma parte de ECMAScript. La propiedad booleana de solo lectura media.paused vale true al principio. Si vale false, el elemento no está en pausa, pero eso no garantiza que la reproducción avance: puede estar esperando datos.
play() intenta iniciar o reanudar la reproducción. Devuelve una promesa que se cumple cuando la reproducción se inicia correctamente o se rechaza si falla, por ejemplo con NotAllowedError si la política de reproducción automática bloquea la solicitud. El evento play se pone en cola cuando paused cambia de true a false. No es lo mismo que playing, que señala el inicio o la reanudación tras esperar datos. pause() devuelve undefined y no produce otra transición si el elemento ya está en pausa. El evento pause se emite después de entrar en ese estado.
ended indica el final de la reproducción, no una pausa normal. Al llegar al final natural de la reproducción hacia delante, pause puede preceder a ended sin llamar a pause(); ended no se emite si loop === true y playbackRate es no negativo. El booleano media.ended representa un estado, no un evento.
Escucha estos cuatro eventos directamente en el elemento: no se propagan hacia arriba en el DOM y no son cancelables. El evento error señala un fallo del recurso, por ejemplo al cargarlo o decodificarlo. Consulta media.error: contiene un MediaError con code, o null si no hay ningún error registrado. Gestiona el rechazo de play() por separado: el bloqueo de la reproducción automática no implica por sí solo un fallo del recurso.
Ejemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Media playback events</title>
</head>
<body>
<audio id="media"></audio>
<button id="start" type="button">Run media demo</button>
<script>
(() => {
// Build one second of silent, unsigned 8-bit mono PCM WAV.
const rate = 8000;
const wav = new Uint8Array(44 + rate);
const view = new DataView(wav.buffer);
const text = (offset, value) => {
for (let i = 0; i < value.length; i++) wav[offset + i] = value.charCodeAt(i);
};
text(0, "RIFF");
view.setUint32(4, wav.length - 8, true);
text(8, "WAVEfmt ");
view.setUint32(16, 16, true);
view.setUint16(20, 1, true);
view.setUint16(22, 1, true);
view.setUint32(24, rate, true);
view.setUint32(28, rate, true);
view.setUint16(32, 1, true);
view.setUint16(34, 8, true);
text(36, "data");
view.setUint32(40, rate, true);
wav.fill(128, 44);
const media = document.getElementById("media");
const start = document.getElementById("start");
media.addEventListener("play", () => console.log(`play: paused=${media.paused}`));
media.addEventListener("pause", () => console.log(`pause: paused=${media.paused}`));
media.addEventListener("ended", () => {
console.log(`ended: ended=${media.ended}`);
media.src = "data:text/plain,not-a-media-file";
}, { once: true });
media.addEventListener("error", () => console.log(`error: code=${media.error?.code}`));
start.addEventListener("click", async () => {
start.remove();
console.log(`paused=${media.paused}`);
media.src = `data:audio/wav;base64,${btoa(String.fromCharCode(...wav))}`;
try {
await media.play();
} catch (error) {
console.log(`play() rejected: ${error.name}`);
}
}, { once: true });
})();
</script>
</body>
</html>Resultado
paused=true play: paused=false pause: paused=true ended: ended=true error: code=4
Guarda el ejemplo como `media-demo.html` y ábrelo en un navegador. Abre la consola del navegador y haz clic en `Run media demo`. La secuencia esperada presupone compatibilidad con WAV PCM, permiso para cargar medios con URL `data:` y reproducción sin interrupciones. Tras un segundo de silencio, el final natural genera `pause` antes de `ended`; solo entonces el código asigna una fuente deliberadamente no válida. Si `play()` se rechaza, revisa el nombre del error en vez de esperar la secuencia completa.
Lecciones relacionadas
- JavaScript · Lección 34 · Avanzado · Versión: 4