audio element

If you don't know what an element is or how you must use it, I recommend you read the "HTML tags and attributes" tutorial that you can find in the HTML tutorials section.

Description

The audio element embeds audio resources in a document. Despite its ease of use, this element can be very adaptable, powerful and compatible.

Authors have two ways to tell browsers which resource is to be loaded. The first, and most direct, is specifying the URI of the resource in the src attribute. The second method increases compatibility among browsers, working toghether with the source element. With the source element you can provide different alternatives of the same resource, and let browsers pick the one that's more suitable for them.

Whatever way you choose to include the audio source, you can always fill the element with alternative content, so browsers not supporting it will have something to display. This becomes very handy for webmasters that need to develop backward compatible websites, as they can provide an alternative flash audio player or a message informing the user about the support issue (and possible ways to resolve it). If the browser supports the audio element, the alternative content will be simply ignored.

One or more track elements can be set inside any media element to provide extra information, such as subtitles, captions or descriptions, that will enhance user's experiece.

Authors must choose one of the two ways to specify an audio resource but never both. If you declare the src attribute you won't be able to provide alternatives with the source element.

Examples

In the next example we'll insert a audio using the src attribute, while we instruct the browser to provide controls for the user to manage its playback. To make controls available, we'll set the boolean attribute controls.

We'll also provide fallback content so users with browsers not supporting the audio element will be informed about the issue and will have a small guidance about how to proceed.

<audio src="../../audio/Jahzzar_The_Flowers_Are_Still_Standing.mp3" controls>
  <p>Your browser doesn't support audio playback natively. You may want to upgrade to a modern browser with more features, in order to listen the audio file.</p>
</audio>

The audio corresponds to the song "The Flowers Are Still Standing" (Jahzzar) / CC BY-SA 4.0.

That may have worked well, but the problem with the previous code is that it only provides one source and, as its format is MP3, it won't play in all browsers. So, lets remove the src attribute and put some source elements, each with a version of the audio in a particular format, to allow browsers to choose the version they are capable of playing.

For browsers supporting the audio element, there's no need to provide more than two formats (MP3 and Ogg) to make our audio cross-browser.

<audio controls>
  <source src="../../audio/Jahzzar_The_Flowers_Are_Still_Standing.ogg" type="audio/ogg">
  <source src="../../audio/Jahzzar_The_Flowers_Are_Still_Standing.mp3" type="audio/mpeg">
</audio>

The audio corresponds to the song "The Flowers Are Still Standing" (Jahzzar) / CC BY-SA 4.0.

Lastly, we're going to try adding captions and subtitles to an audio with the aid of track. The track element has been designed to provide subtitles, captions, descriptions, chapters or metadata for video and audio, but being relatively new, it's not fully supported cross-browser.

Note that captions or subtitles come in a special file format, wich in this case is WebVTT, although there are others.

As of 2014/11/21, no browser provides captions for the audio element. Authors may have to rely on client-side scripts to provide this functionality cross-browser until support grows.

<audio controls>
  <source src="../../audio/Frankenstein_Chapter_5.ogg" type="audio/ogg">
  <source src="../../audio/Frankenstein_Chapter_5.mp3" type="audio/mpeg">
  <track kind="captions" label="Captions" src="../../audio/Frankenstein_Chapter_5_EN.vtt" srclang="en"></track>
</audio>

The audio element has some interesting attributes. You may want to check the next section.

Attributes

Specific attributes

src

The URI (location) of the media resource that will be played.

Authors shouldn't include source inside this element if the src attribute is present. Both methods for declaring media sources aren't meant to work together.

This attribute is mandatory if the itemprop attribute is present in the audio element, as it's used to determine the value of the property.

Be aware that using the src attribute allows only one media source to be declared. If cross-browser compatibility is required, authors should use the source element instead, and define at least the two most supported formats (MP4 and Ogg).

Example

<audio controls src="../../audio/Jahzzar_Ice_Cream.ogg"></audio>

The audio corresponds to the song "Ice cream" (Jahzzar) / CC BY-SA 3.0.

crossorigin

An enumerated value indicating if the request made to the external server should present CORS credentials or not. This attribute is useful when embedding audios, located in other servers that allow cross-origin access, to be used with canvas. The two possible values are (case-insensitive):

  • anonymous: CORS requests for the element will have the "omit credentials" flag set.
  • use-credentials: CORS requests for the element won't have the "omit credentials" flag set.

Example

<audio src="bgmusic.ogg" crossorigin="anonymous"></audio>

preload

A hint for the browser to help it decide if the media resource should be loaded as soon as possible (with the loading of the document). The attribute can define three states which advice the browser to perform the following tasks:

  • none: no data needs to be preloaded for the user and/or server would like to minimize unnecessary traffic.
  • metadata: only the resource's metadata (duration, dimensions, tracks, etc.) and probably the first few chunks of audio data, can be considerer as needed for the user.
  • auto: the complete media resource can be preloaded at browser's discretion.

When the attribute takes the empty string ("") as value or it's just present, the browser behaves as if the value "auto" was passed.

The value in this attribute gives only a hint to the browser about how to handle the preloading of the media resource. The behavior chosen by the browser isn't ruled by the standard, and therefore, can result unpredicible.

Example

<audio controls preload>
  <source src="../../audio/Jahzzar_Change.ogg" type="audio/ogg">
  <source src="../../audio/Jahzzar_Change.mp3" type="audio/mpeg">
</audio>

The audio corresponds to the song "Change" (Jahzzar) / CC BY-SA 3.0.

autoplay

A boolean value indicating if the media playback should start as soon as the browser is capable of doing so without having to stop for loading. If the attribute takes the value "autoplay" or the empty string (""), or if it's just present (with no value) the playback starts automatically.

Example

<audio src="music.mp3" autoplay></audio>

loop

A boolen value indicating if the browser should automatically restart the playback of the media file once it reaches the end. If the attribute takes the value "loop" or the empty string (""), or if it's just present (with no value) the playback will be reapeated endlesly.

Example

<audio controls loop>
  <source src="../../audio/laser.ogg" type="audio/ogg">
  <source src="../../audio/laser.mp3" type="audio/mpeg">
</audio>

The audio belongs to bubaproducer / CC BY 3.0.

muted

A boolen indicating if the media element should be muted (a state equivalent to having no volume). If the attribute takes the value "muted" or the empty string (""), or if it's just present (with no value) the sound output of the element will be muted.

If controls are present, browsers will usually provide a button to mute/unmute the element. This button should be present even when this attribute isn't set.

Example

<audio controls muted>
  <source src="../../audio/Jahzzar_Sketch_Rum_Portrait.ogg" type="audio/ogg">
  <source src="../../audio/Jahzzar_Sketch_Rum_Portrait.mp3" type="audio/mpeg">
</audio>

The audio corresponds to the song "Sketch (rum-portrait)" (Jahzzar) / CC BY-SA 3.0.

controls

A boolen value indicating that the browser should provide an interface to allow the user to control the playback, typically when the author doesn't provide a playback scripted controller. If the attribute takes the value "controls" or the empty string (""), or if it's just present (with no value) the playback controls will be provided.

Example

<audio controls>
  <source src="../../audio/Jahzzar_Please_Listen_Carefully.ogg" type="audio/ogg">
  <source src="../../audio/Jahzzar_Please_Listen_Carefully.mp3" type="audio/mpeg">
</audio>

The audio corresponds to the song "Please Listen Carefully" (Jahzzar) / CC BY-SA 4.0.

meadiagroup

A string value that will link this media element to all other media elements with the same value in their meadiagroup attribute. All grouped media elements will share the same playback position and properties and, therefore, will play altoghether as one.

Authors can take advantage of this attribute to, for example, provide a video with a separate audio element containing multiple sources, one for each language supported. This technique is used in the next example, where a background music is played together with a news report, allowing alternative translations to be provided without changing the background music.

Although possible, there's no need to provide controls for more than one meadia element in a group. The commands executed to a control will affect all media element in the group indistinctly.

This attribute has been recently introduced to the standard and, due to lack of implementation by browsers, deleted. Its use is currently invalid.

Example

<audio mediagroup="radio_report" controls>
  <source src="../../audio/Radio_report_background_music.ogg" type="audio/ogg">
  <source src="../../audio/Radio_report_background_music.mp3" type="audio/mpeg">
</audio>
<audio mediagroup="radio_report">
  <source src="../../audio/Radio_report_voice_english.ogg" type="audio/ogg">
  <source src="../../audio/Radio_report_voice_english.mp3" type="audio/mpeg">
</audio>

The music file belongs to Kevin MacLeod (incompetech.com) / CC BY 3.0 and the voice file to Timbre / CC BY-NC 3.0.

Global attributes

For information about global attributes refer to this list of global attributes in HTML5.

Events

Global events

For information about global events refer to this list of global events in HTML5.