CKTIS / JavaScript
HTMLMediaElement : temps, volume et événements de lecture
HTMLMediaElement fournit l’API commune aux éléments audio et vidéo. Consultez l’état de lecture, modifiez la position et la mise en sourdine, et actualisez l’interface à partir des événements au lieu de supposer qu’une commande de lecture a immédiatement réussi.
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.currentTime = seconds; media.volume = 0.5; media.muted = true; media.addEventListener("timeupdate", render);HTMLMediaElement est l’interface commune aux éléments audio et vidéo. Il s’agit d’une API Web définie par HTML, et non d’une fonctionnalité d’une édition particulière d’ECMAScript. La présence de Node 24 ne prouve pas la prise en charge par un navigateur. L’interface de base est largement disponible, mais volume présente des limites de compatibilité ; vérifiez les navigateurs et appareils visés.
HTMLMediaElement.currentTime indique la position en secondes. Lorsque readyState vaut HAVE_NOTHING, comme pour l’élément sans source de l’exemple, l’affectation mémorise la position de début de lecture par défaut au lieu de lancer un déplacement. Dans les autres états, l’affectation demande un déplacement dans la chronologie disponible. HTMLMediaElement.duration est en lecture seule : une durée en secondes, NaN si aucune donnée n’est disponible, ou Infinity pour une durée indéfinie. Ne calculez le pourcentage de progression que si la durée est finie et positive. HTMLMediaElement.volume accepte les valeurs de 0 à 1. HTMLMediaElement.muted coupe le son indépendamment, sans modifier le volume mémorisé.
Les propriétés en lecture seule HTMLMediaElement.paused et HTMLMediaElement.ended indiquent respectivement la mise en pause et la fin de la lecture ; elles ne sont pas interchangeables. paused === false ne garantit pas que la lecture progresse, par exemple pendant la mise en mémoire tampon. HTMLMediaElement.error contient null ou un objet MediaError. Les événements play et pause signalent des changements d’état, tandis que les méthodes play() et pause() lancent des commandes. Gérez le rejet de la promesse renvoyée par play(), par exemple si la règle d’autoplay bloque la lecture.
loadedmetadata signale le chargement des métadonnées, durationchange un changement de durée et emptied la remise à vide de l’état de la ressource : actualisez alors aussi l’interface. Utilisez timeupdate pour actualiser la position, mais pas comme une horloge de rendu des images : sa fréquence dépend de la charge. volumechange concerne les changements de volume ou de muted ; ended signale la fin de la lecture. L’événement error peut signaler non seulement un échec de chargement de la ressource, mais aussi une erreur fatale de décodage après le début de la lecture. Lisez les propriétés courantes dans les gestionnaires d’événements.
L’exemple crée un élément sans source, enregistre des événements et affiche son état initial. Il ne lit aucun fichier et ne teste pas le décodage. NaN est volontairement représenté sous forme de texte afin que la sérialisation JSON conserve cette distinction.
Exemples
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());Résultat
{"currentTime":0,"duration":"NaN","volume":1,"muted":false,"paused":true,"ended":false,"error":null}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
- HTMLMediaElement - Web APIs | MDN
- HTMLMediaElement: currentTime property - Web APIs | MDN
- HTMLMediaElement: duration property - Web APIs | MDN
- HTMLMediaElement: volume property - Web APIs | MDN
- HTMLMediaElement: timeupdate event - Web APIs | MDN
- HTMLMediaElement: volumechange event - Web APIs | MDN
- HTMLMediaElement: paused property - Web APIs | MDN
- HTMLMediaElement: ended property - Web APIs | MDN
- HTMLMediaElement: error property - Web APIs | MDN
- HTMLMediaElement: play() method - Web APIs | MDN