Skip to content
Tutorials Center
My learning

Topics

HTML Reference ยท Images and Media

The <audio> element

Reference for the HTML <audio> element: every attribute (controls, autoplay, muted, loop, preload, crossorigin), fallback sources, autoplay rules and accessibility.

The <audio> element embeds sound in a page: music, a podcast episode, a pronunciation sample or a notification chime. With the controls attribute the browser draws its own player (play/pause, a timeline, volume); without it, the element is invisible and you control playback from JavaScript.

Give the file with src, or list several formats with <source> children so each browser can pick one it supports.

HTML
<audio controls src="/samples/media/chime.mp3"></audio>

Try it

A player with two formats

The browser walks the <source> list from top to bottom and plays the first file whose type it can handle. The paragraph inside is only shown by browsers that don't know <audio> at all; it is not shown when a file fails to load.

No controls: play from a script

Attributes

Attribute Values Description
src URL The audio file. Leave it out when you use <source> children.
controls Boolean Show the browser's player controls. Without it, the element takes up no space.
autoplay Boolean Start playing as soon as possible. Browsers block autoplay with sound until the user has interacted with the site, so it often does nothing.
muted Boolean Start with the sound muted. (For audio this mostly matters to scripts and to sites allowed to autoplay.)
loop Boolean Jump back to the start when the end is reached.
preload none, metadata, auto A hint about how much to download before the user presses play: nothing, just the duration and other metadata, or as much as the browser likes. An empty value means auto. The default varies by browser; metadata is common.
crossorigin anonymous, use-credentials Fetch the file with CORS. Needed when a script on another origin analyzes the audio (for example with the Web Audio API).
controlslist nodownload, nofullscreen, noplaybackrate, noremoteplayback Non-standard (Chromium browsers only). Hides individual buttons from the built-in controls.
disableremoteplayback Boolean Hides the option to cast the audio to a remote device (AirPlay, Chromecast and similar). Defined by the Remote Playback API, not by HTML; support varies.

It also accepts the global attributes and the media event attributes such as onplay, onpause, onended and ontimeupdate. Unlike <video>, <audio> has no poster, width, height or playsinline.

Usage notes

  • Offer a transcript. People who can't hear the audio need the same information. Put a transcript on the page or link to one, especially for speech.
  • Never autoplay sound. Unexpected sound is startling, it talks over screen readers, and browsers block it anyway. Let the user press play.
  • Formats. MP3 (audio/mpeg) plays everywhere. AAC in MP4 (audio/mp4), Ogg Vorbis or Opus (audio/ogg), WebM Opus and WAV are widely but not universally supported, so list a fallback <source> when you use them.
  • Hidden players. An <audio> without controls is display: none. That is fine for sound effects driven by buttons, as in the second example, but the button must clearly say what it does.
  • Captions for audio. <audio> accepts <track> children, but browsers don't display their text. For visible text, use a transcript or a <video> element.
  • Scripting. The HTMLMediaElement API gives you play(), pause(), currentTime, volume, playbackRate and events such as ended. play() returns a promise that rejects when autoplay is blocked.

Technical summary

Content categories Flow content, phrasing content, embedded content; with controls: interactive content and palpable content
Permitted content With src: zero or more <track> elements, then transparent content with no media elements. Without src: zero or more <source> elements, then zero or more <track> elements, then transparent content with no media elements
Tag omission None; both the start and end tags are required
Permitted parents Any element that accepts embedded content
Implicit ARIA role No corresponding role
DOM interface HTMLAudioElement
Default display inline with controls; none without it

Browser support

Supported in every browser; the available file formats and the look of the built-in controls differ between browsers.