Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

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