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

CKTIS / JavaScript

HTMLMediaElement: tiempo, volumen y eventos de reproducción

HTMLMediaElement ofrece la API común para los elementos de audio y vídeo. Permite consultar el estado de reproducción, cambiar la posición y silenciar, y actualizar la interfaz a partir de eventos en vez de dar por hecho que un comando de reproducción se ha completado de inmediato.

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

Sintaxis

media.currentTime = seconds; media.volume = 0.5; media.muted = true; media.addEventListener("timeupdate", render);

HTMLMediaElement es la interfaz común para los elementos de audio y vídeo. Es una API web definida por HTML, no una característica de una edición concreta de ECMAScript. Tener Node 24 no demuestra que sea compatible con un navegador. La interfaz básica está ampliamente disponible, pero volume tiene limitaciones de compatibilidad; comprueba los navegadores y dispositivos de destino.

HTMLMediaElement.currentTime indica la posición en segundos. Cuando readyState vale HAVE_NOTHING, como en el elemento sin fuente del ejemplo, la asignación guarda la posición de inicio de reproducción predeterminada en lugar de iniciar un salto. En los demás estados, la asignación solicita un salto dentro de la línea de tiempo disponible. HTMLMediaElement.duration es de solo lectura: segundos, NaN si no hay datos disponibles o Infinity si la duración es indefinida. Calcula el porcentaje de progreso solo cuando la duración sea finita y positiva. HTMLMediaElement.volume acepta valores de 0 a 1. HTMLMediaElement.muted silencia el audio de forma independiente, sin cambiar el volumen almacenado.

Las propiedades de solo lectura HTMLMediaElement.paused y HTMLMediaElement.ended indican, respectivamente, si está en pausa y si la reproducción ha terminado; no son intercambiables. paused === false no garantiza que haya progreso, por ejemplo, durante el almacenamiento en búfer. HTMLMediaElement.error contiene null o un objeto MediaError. Los eventos play y pause informan de cambios de estado, mientras que los métodos play() y pause() dan órdenes. Gestiona el rechazo de la promesa de play(), por ejemplo, si la política de reproducción automática bloquea la reproducción.

loadedmetadata indica que se han cargado los metadatos, durationchange que ha cambiado la duración y emptied que se ha vaciado el estado del recurso; actualiza también la interfaz en ese caso. Usa timeupdate para actualizar la posición, pero no como reloj de fotogramas: su frecuencia depende de la carga. volumechange corresponde a cambios de volume o muted; ended indica el final de la reproducción. El evento error puede indicar no solo un fallo al cargar el recurso, sino también un error fatal de decodificación una vez iniciada la reproducción. Lee las propiedades actuales en los controladores de eventos.

El ejemplo crea un elemento sin fuente, registra eventos y muestra el estado inicial. No reproduce ningún archivo ni comprueba la decodificación. NaN se representa deliberadamente como texto para que la serialización JSON conserve esa distinción.

Ejemplos

const media = document.createElement("audio");
const events = [
  "timeupdate", "loadedmetadata", "durationchange", "emptied",
  "play", "pause", "volumechange", "ended", "error"
];
function snapshot() {
  return JSON.stringify({
    currentTime: media.currentTime,
    duration: Number.isNaN(media.duration) ? "NaN" : String(media.duration),
    volume: media.volume,
    muted: media.muted,
    paused: media.paused,
    ended: media.ended,
    error: media.error === null ? null : media.error.code
  });
}
for (const type of events) {
  media.addEventListener(type, () => console.log(type, snapshot()));
}
console.log(snapshot());

Resultado

{"currentTime":0,"duration":"NaN","volume":1,"muted":false,"paused":true,"ended":false,"error":null}

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes