CKTIS / JavaScript
HTMLMediaElement: tempo, volume e eventos de reprodução
HTMLMediaElement disponibiliza a API comum aos elementos de áudio e vídeo. Permite consultar o estado da reprodução, alterar a posição e silenciar, e atualizar a interface com base nos eventos, em vez de presumir que um comando de reprodução teve êxito de imediato.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
media.currentTime = seconds; media.volume = 0.5; media.muted = true; media.addEventListener("timeupdate", render);HTMLMediaElement é a interface comum aos elementos de áudio e vídeo. É uma API Web definida por HTML, não uma funcionalidade de uma edição específica de ECMAScript. A presença do Node 24 não comprova o suporte num navegador. A interface principal está amplamente disponível, mas volume tem limitações de compatibilidade; verifica os navegadores e dispositivos de destino.
HTMLMediaElement.currentTime indica a posição em segundos. Quando readyState tem o valor HAVE_NOTHING, como no elemento sem origem do exemplo, a atribuição guarda a posição predefinida para o início da reprodução, em vez de iniciar uma deslocação. Nos restantes estados, a atribuição solicita uma deslocação dentro da linha temporal disponível. HTMLMediaElement.duration é só de leitura: segundos, NaN quando não há dados disponíveis ou Infinity para uma duração indefinida. Calcula a percentagem de progresso apenas quando a duração for finita e positiva. HTMLMediaElement.volume aceita valores de 0 a 1. HTMLMediaElement.muted silencia o áudio de forma independente, sem alterar o volume guardado.
As propriedades só de leitura HTMLMediaElement.paused e HTMLMediaElement.ended indicam, respetivamente, o estado de pausa e o fim da reprodução; não são permutáveis. paused === false não garante que haja progresso, por exemplo, durante o armazenamento em buffer. HTMLMediaElement.error contém null ou um objeto MediaError. Os eventos play e pause comunicam alterações de estado, enquanto os métodos play() e pause() emitem comandos. Trata a rejeição da promise de play(), por exemplo, se a política de reprodução automática bloquear a reprodução.
loadedmetadata assinala o carregamento dos metadados, durationchange uma alteração da duração e emptied o esvaziamento do estado do recurso; atualiza também a interface nesse caso. Usa timeupdate para atualizar a posição, mas não como relógio de fotogramas: a frequência depende da carga. volumechange diz respeito a alterações de volume ou muted; ended assinala o fim da reprodução. O evento error pode assinalar não só uma falha no carregamento do recurso, mas também um erro fatal de descodificação após o início da reprodução. Lê as propriedades atuais nos processadores de eventos.
O exemplo cria um elemento sem origem, regista eventos e apresenta o estado inicial. Não reproduz qualquer ficheiro nem testa a descodificação. NaN é representado deliberadamente como texto para que a serialização JSON preserve essa distinção.
Exemplos
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}O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.
Fontes
- 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