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.
<audio controls src="/samples/media/chime.mp3"></audio>
Try it
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.
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>withoutcontrolsisdisplay: 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
HTMLMediaElementAPI gives youplay(),pause(),currentTime,volume,playbackRateand events such asended.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.