Docs executáveis de HTML: Tag audio

Q: Como colocar áudio numa página HTML?

Use . O atributo controls mostra o player do navegador com botão de play, linha do tempo e volume. Sem ele, o elemento fica invisível.

Q: Como deixar um áudio em loop no HTML?

Adicione o atributo loop: . Quando o arquivo termina, ele recomeça do início.

Q: Como tocar um som com JavaScript?

Crie ou selecione um elemento de áudio e chame play(), por exemplo new Audio('click.mp3').play() dentro de um manipulador de clique. play() retorna uma promise que é rejeitada se o navegador bloquear a reprodução.

Como colocar áudio

Aponte o elemento <audio> para um arquivo de som e adicione controls:

<audio src="song.mp3" controls></audio>

controls mostra o player do navegador: play e pause, uma linha do tempo, o tempo e um controle de volume. Sem controls o elemento não ocupa espaço nenhum. A prévia não consegue carregar arquivos do seu computador, então este exemplo cria um arquivo WAV curto no navegador com um script e o usa como src. Aperte play:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Audio</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <audio id="player" controls></audio>
  <p>Four notes, 1.8 seconds.</p>
  <script>
    // Builds a tiny WAV file in the browser (stand-in for song.mp3)
    function makeWav(notes) {
      const rate = 8000, samples = [];
      for (const [freq, secs] of notes) {
        const n = secs * rate;
        for (let i = 0; i < n; i++) {
          samples.push(Math.sin(2 * Math.PI * freq * i / rate) * 0.4 * Math.min(1, (n - i) / 400));
        }
      }
      const view = new DataView(new ArrayBuffer(44 + samples.length * 2));
      const text = (at, s) => [...s].forEach((c, i) => view.setUint8(at + i, c.charCodeAt(0)));
      text(0, 'RIFF'); view.setUint32(4, 36 + samples.length * 2, 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 * 2, true);
      view.setUint16(32, 2, true); view.setUint16(34, 16, true);
      text(36, 'data'); view.setUint32(40, samples.length * 2, true);
      samples.forEach((s, i) => view.setInt16(44 + i * 2, s * 32767, true));
      return URL.createObjectURL(new Blob([view], { type: 'audio/wav' }));
    }
    document.getElementById('player').src = makeWav([[523, 0.4], [659, 0.4], [784, 0.4], [1047, 0.6]]);
  </script>
</body>
</html>

O player fica diferente no Chrome, no Firefox e no Safari, porque cada navegador desenha o seu. Apague controls e o player some, mas o áudio continua ali para o JavaScript tocar.

Atributos do áudio

Atributo	O que faz
`controls`	Mostra o player do navegador
`autoplay`	Tenta começar a tocar ao carregar (bloqueado com som, veja abaixo)
`loop`	Recomeça quando o arquivo termina
`muted`	Começa com o volume desligado
`preload`	`none` (não baixa nada até o play), `metadata` (só a duração) ou `auto` (o navegador decide)
`src`	O arquivo a tocar; ou use filhos `<source>` para vários formatos

Use preload="none" ou "metadata" em páginas com muitos players, como uma lista de episódios de podcast, para que a página não baixe todos os arquivos de uma vez.

Formatos e alternativas

Liste vários arquivos com <source> e o navegador toca o primeiro que ele suporta. O texto dentro do elemento só aparece em navegadores sem suporte a <audio>:

<audio controls preload="metadata">
  <source src="episode.opus" type="audio/ogg; codecs=opus">
  <source src="episode.mp3" type="audio/mpeg">
  <p>Your browser cannot play audio. <a href="episode.mp3">Download the episode</a>.</p>
</audio>

Formato	Tipo MIME	Observações
MP3	`audio/mpeg`	Toca em todos os navegadores atuais; a escolha segura para um arquivo só
AAC (`.m4a`)	`audio/mp4`	Amplo suporte, boa qualidade em tamanhos pequenos
Opus ou Vorbis (`.ogg`, `.webm`)	`audio/ogg`, `audio/webm`	Arquivos pequenos; liste MP3 como alternativa, porque o suporte do Safari varia conforme a versão
WAV	`audio/wav`	Sem compressão e grande; serve para efeitos sonoros curtos

Por que o autoplay falha

Os navegadores não deixam uma página começar a fazer som sozinha. autoplay, ou chamar play() antes de o usuário clicar ou tocar na tela, é recusado. Este exemplo tenta tocar ao carregar e mostra o que aconteceu, depois oferece um botão:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Autoplay</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    button { font: inherit; padding: 6px 14px; }
  </style>
</head>
<body>
  <p id="result">Trying to play...</p>
  <button id="play">Play with a click</button>
  <script>
    // Builds a short beep as a WAV file (stand-in for a real sound file)
    function beep(freq, secs) {
      const rate = 8000, n = secs * rate;
      const view = new DataView(new ArrayBuffer(44 + n * 2));
      const text = (at, s) => [...s].forEach((c, i) => view.setUint8(at + i, c.charCodeAt(0)));
      text(0, 'RIFF'); view.setUint32(4, 36 + n * 2, 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 * 2, true);
      view.setUint16(32, 2, true); view.setUint16(34, 16, true);
      text(36, 'data'); view.setUint32(40, n * 2, true);
      for (let i = 0; i < n; i++) view.setInt16(44 + i * 2, Math.sin(2 * Math.PI * freq * i / rate) * 12000, true);
      return URL.createObjectURL(new Blob([view], { type: 'audio/wav' }));
    }
    const sound = new Audio(beep(440, 0.5));
    const result = document.getElementById('result');
    sound.play()
      .then(() => { result.textContent = 'Autoplay worked this time.'; })
      .catch((err) => { result.textContent = 'Autoplay was blocked: ' + err.name; });
    document.getElementById('play').onclick = () => {
      sound.currentTime = 0;
      sound.play()
        .then(() => { result.textContent = 'Playing, because you clicked.'; })
        .catch((err) => { result.textContent = 'Still blocked: ' + err.name; });
    };
  </script>
</body>
</html>

Normalmente você vai ver NotAllowedError, o erro que o navegador dá quando bloqueia a reprodução. O botão funciona porque um clique conta como permissão. Cada navegador tem as suas próprias regras extras (o Chrome, por exemplo, lembra dos sites em que você costuma tocar mídia), então nunca conte com o autoplay: inicie o som a partir de uma ação do usuário e trate sempre a promise que play() retorna.

new Audio(url) cria um elemento de áudio no JavaScript sem adicioná-lo à página, o que é prático para efeitos sonoros.

Crie os seus próprios controles

Esconda o player nativo deixando controls de fora, e controle o elemento pela sua API de JavaScript: play(), pause(), currentTime, duration, volume e eventos como timeupdate e ended:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Custom player</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    .player { display: flex; align-items: center; gap: 10px; max-width: 360px; padding: 10px; border: 2px solid #e5e7eb; border-radius: 10px; }
    .player button { font: inherit; width: 72px; padding: 6px 0; border: 0; border-radius: 6px; background: #2563eb; color: #fff; cursor: pointer; }
    progress { flex: 1; }
    #time { font-variant-numeric: tabular-nums; font-size: 14px; color: #374151; }
  </style>
</head>
<body>
  <div class="player">
    <button id="toggle" aria-label="Play">Play</button>
    <progress id="bar" value="0" max="1"></progress>
    <span id="time">0.0 s</span>
  </div>
  <audio id="audio"></audio>
  <script>
    function makeWav(notes) {
      const rate = 8000, samples = [];
      for (const [freq, secs] of notes) {
        const n = secs * rate;
        for (let i = 0; i < n; i++) {
          samples.push(Math.sin(2 * Math.PI * freq * i / rate) * 0.4 * Math.min(1, (n - i) / 400));
        }
      }
      const view = new DataView(new ArrayBuffer(44 + samples.length * 2));
      const text = (at, s) => [...s].forEach((c, i) => view.setUint8(at + i, c.charCodeAt(0)));
      text(0, 'RIFF'); view.setUint32(4, 36 + samples.length * 2, 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 * 2, true);
      view.setUint16(32, 2, true); view.setUint16(34, 16, true);
      text(36, 'data'); view.setUint32(40, samples.length * 2, true);
      samples.forEach((s, i) => view.setInt16(44 + i * 2, s * 32767, true));
      return URL.createObjectURL(new Blob([view], { type: 'audio/wav' }));
    }
    const audio = document.getElementById('audio');
    const toggle = document.getElementById('toggle');
    audio.src = makeWav([[392, 0.5], [440, 0.5], [494, 0.5], [523, 1]]);
    toggle.onclick = () => {
      if (audio.paused) audio.play().catch((err) => { toggle.textContent = err.name; });
      else audio.pause();
    };
    audio.addEventListener('play', () => { toggle.textContent = 'Pause'; toggle.setAttribute('aria-label', 'Pause'); });
    audio.addEventListener('pause', () => { toggle.textContent = 'Play'; toggle.setAttribute('aria-label', 'Play'); });
    audio.addEventListener('timeupdate', () => {
      document.getElementById('bar').value = audio.currentTime / audio.duration || 0;
      document.getElementById('time').textContent = audio.currentTime.toFixed(1) + ' s';
    });
  </script>
</body>
</html>

O botão é um <button> de verdade, então funciona com o teclado, e o rótulo alterna entre Play e Pause. No fim do arquivo o navegador pausa o elemento e dispara ended, então o botão volta para Play sozinho. Se você cria controles próprios, também assume o que os nativos davam de graça: suporte a teclado, rótulos e controle de volume.

Acessibilidade

Nunca comece um som sozinho. Ele interrompe os leitores de tela e assusta as pessoas. Inicie o áudio a partir de um clique.
Ofereça uma transcrição para podcasts e áudio falado. Um link para uma versão em texto abaixo do player basta, e os buscadores conseguem lê-la.
Mantenha controls, ou crie controles com botões de verdade, para que o áudio possa ser pausado pelo teclado.

Para vídeo com som, legendas e posters, veja a página da tag video; <audio> compartilha a maioria dos atributos e toda a API de JavaScript.

Erros comuns

Esquecer controls. O elemento fica invisível sem ele, e parece que nada aconteceu.
Esperar que o autoplay funcione. Inicie a reprodução com um clique e trate a promise de play().
Um caminho ou tipo de arquivo errado. Abra a URL do arquivo direto para conferir, e faça o type corresponder ao formato real (audio/mpeg para MP3).
Carregar todos os arquivos de uma lista longa. Use preload="none" ou "metadata".
Música de fundo que não pode ser parada. Dê sempre às pessoas um jeito visível de pausar.

Perguntas frequentes

Como colocar áudio numa página HTML?

Use <audio src="song.mp3" controls></audio>. O atributo controls mostra o player do navegador com botão de play, linha do tempo e volume. Sem ele, o elemento fica invisível.

Por que meu áudio não toca automaticamente?

Os navegadores bloqueiam áudio que começa com som antes de o usuário interagir com a página. Inicie a reprodução a partir de um clique com audio.play(). Um elemento mudo pode tocar sozinho, mas para áudio isso raramente é útil.

Qual formato de áudio usar no HTML?

MP3 toca em todos os navegadores atuais, então é a escolha segura para um arquivo só. AAC num arquivo .m4a também tem amplo suporte. Use elementos <source> para oferecer mais de um formato.

Como deixar um áudio em loop no HTML?

Adicione o atributo loop: <audio src="rain.mp3" controls loop>. Quando o arquivo termina, ele recomeça do início.

Como tocar um som com JavaScript?

Crie ou selecione um elemento de áudio e chame play(), por exemplo new Audio('click.mp3').play() dentro de um manipulador de clique. play() retorna uma promise que é rejeitada se o navegador bloquear a reprodução.

Dá para estilizar o player de áudio do HTML?

Só um pouco: você pode definir largura, margem e display, mas os botões de dentro são desenhados pelo navegador e ficam diferentes em cada um. Para uma aparência própria, esconda os controles e crie os seus com botões e a API de áudio do JavaScript.

Conceitos relacionados