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

CKTIS / JavaScript

HTMLMediaElement: `paused` e os eventos `play`, `pause`, `ended` e `error`

Distingue o estado atual do elemento multimédia dos eventos e do resultado de chamar `play()`. Aprende a reconhecer uma pausa, o fim natural e uma falha do recurso.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

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 é a interface da plataforma Web para elementos de áudio e vídeo; não faz parte de ECMAScript. A propriedade booleana media.paused é só de leitura e começa com o valor true. O valor false indica que o elemento não está em pausa, mas não garante que a reprodução esteja a avançar: o elemento pode estar à espera de dados.

play() tenta iniciar ou retomar a reprodução. Devolve uma promessa que é cumprida quando a reprodução começa com êxito ou rejeitada se falhar, por exemplo com NotAllowedError se a política de reprodução automática bloquear o pedido. O evento play é colocado em fila quando paused passa de true para false. É distinto de playing, que assinala o início ou a retoma após a espera por dados. pause() devolve undefined e não provoca outra transição se o elemento já estiver em pausa. O evento pause é emitido após a entrada no estado de pausa.

ended assinala o fim da reprodução, não uma pausa normal. No fim natural da reprodução para a frente, pause pode anteceder ended sem uma chamada a pause(); ended não é emitido quando loop === true e playbackRate não é negativo. O booleano media.ended representa um estado, não um evento.

Escuta estes quatro eventos diretamente no elemento: não sobem na árvore do DOM e não são canceláveis. O evento error assinala uma falha do recurso, por exemplo ao carregar ou descodificar. Consulta media.error: é um MediaError com code, ou null quando não há nenhum erro registado. Trata a rejeição de play() separadamente: o bloqueio da reprodução automática, por si só, não é uma falha do recurso.

Exemplos

<!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 o exemplo como `media-demo.html` e abre-o num navegador. Abre a consola do navegador e clica em `Run media demo`. A sequência esperada pressupõe suporte para WAV PCM, permissão para carregar multimédia com URL `data:` e reprodução sem interrupções. Após um segundo de silêncio, o fim natural produz `pause` antes de `ended`; só depois o código atribui uma fonte deliberadamente inválida. Se `play()` for rejeitada, verifica o nome do erro em vez de esperares a sequência completa.

Lições relacionadas

  • JavaScript · Lição 34 · Avançado · Versão: 4

Fontes