How to Use the audio Element

Play a recording on your page, and give people another way to read what it says.

The answer first

A small example

<audio controls preload="metadata">
  <source src="/media/lesson.ogg" type="audio/ogg; codecs=opus">
  <source src="/media/lesson.mp3" type="audio/mpeg">
  This browser cannot play audio here.
  <a href="/media/lesson.mp3">Open the audio file</a>
</audio>
<p><a href="/transcripts/lesson.html">Read the transcript</a></p>

The URLs are examples. For a real page, upload the audio and text files, then use their actual locations.

Show playback controls

With controls, the browser shows controls such as play and pause. Their exact appearance and operation can differ between browsers and devices.

Without controls, people may have no visible way to play the sound. If you build custom controls, make sure they work with a keyboard and that assistive technology can find their names and states.

Offer more than one audio file

Use source elements to list audio files that can be played. The type attribute describes each file's format. A browser may skip a format it knows it cannot play before downloading that candidate.

Browsers and devices support different formats and codecs. Listing several files does not guarantee playback everywhere, so try the actual files in the browsers and devices your visitors use.

You can also put one URL directly in the src attribute on audio. That form is used instead of listing child source candidates. A separate link is useful when people need to open the file themselves.

Loading and autoplay

preload="metadata" hints that the browser should get information such as the recording's length, instead of downloading all of it first. The browser may choose a different amount.

Adding autoplay does not guarantee that the browser will start the sound. User settings and browser rules may block it. Keep a play control that people can use. A JavaScript call to play() can also fail if playback is not allowed.

Provide text for people who cannot listen

When a prerecorded audio-only recording carries information, provide an equivalent text version too. This can help people who cannot hear the sound and people who need to keep their device quiet.

Text inside audio is mainly for older browsers that do not support the element. It is not guaranteed to appear when a supported browser cannot load the file. Put the transcript link outside audio, as in the example.

You can associate a track with the audio, for example for chapters or timed text. But audio has no visual playback area for showing captions over a picture. See the track guide for attributes and caption files. If people need to read what the recording says, provide a separate text version.

Common mistakes

• Leaving out controls and giving people no other way to start playback.
• Assuming preload always downloads the complete recording.
• Assuming autoplay works in every browser.
• Assuming fallback text inside audio will appear when loading fails.
• Providing no text version for information that is only spoken in the recording.

Check it in Atlas

For the audio content model, resource selection, network / ready states, the play() promise, HTML-AAM, and evidence scope, see audio in Yugien Atlas. For parent-specific source selection, see the source guide or source in Atlas. For track requirements, WebVTT, and unrun evidence, see track in Atlas. See the video element for the shared media processing model and the element with a visual playback area.