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

CKTIS / JavaScript

HTMLMediaElement.play() — iniciar a reprodução de forma assíncrona

O método play() pede que a reprodução de áudio ou vídeo seja iniciada ou retomada. Devolve uma Promise, pelo que a interface deve ter em conta tanto o início da reprodução como a rejeição do pedido.

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.play() // Promise<undefined>; media is an HTMLAudioElement or HTMLVideoElement

HTMLMediaElement.play() é um método da Web API do browser para elementos audio e video, não uma função ECMAScript. Não aceita argumentos. Devolve uma Promise que é cumprida com o valor undefined quando a reprodução começa — não quando os conteúdos multimédia terminam.

Usa await media.play() dentro de try...catch. Nem o regresso da chamada nem paused === false confirmam que a reprodução começou. A promise pode ficar pendente enquanto os dados são carregados; atualiza a interface quando for resolvida ou rejeitada.

NotAllowedError significa que a reprodução não é permitida, por exemplo, devido à política de reprodução automática. Chama o método diretamente num gestor de cliques, mas trata igualmente a rejeição. NotSupportedError diz respeito a uma origem não suportada. Interromper um pedido pendente com pause() ou ao recarregar pode causar AbortError.

O exemplo fornece intencionalmente texto em vez de uma gravação para demonstrar a gestão de uma rejeição sem um ficheiro externo. Não demonstra uma reprodução bem-sucedida. Esta API pertence ao HTML Living Standard; o Node 24 num repositório não comprova a sua disponibilidade no browser.

Exemplos

const media = document.createElement('audio');
media.src = 'data:text/plain,not-media';
const button = document.createElement('button');
button.textContent = 'Test play()';
const status = document.createElement('pre');
document.body.append(button, status);

button.addEventListener('click', async () => {
  button.disabled = true;
  try {
    await media.play();
    status.textContent = 'Playback started';
  } catch (error) {
    status.textContent = `Rejected: ${error.name}`;
  } finally {
    button.disabled = false;
  }
});

Resultado

Rejected: NotSupportedError

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