`<audio>`

Audio is sound that the human ear is capable of hearing.

Usage information

The <audio> element is modeled on the HTML5 <audio> element.

An audio resource can be referenced by @href, @keyref, and nested <media-source> elements.

Playback behaviors such as auto-playing, looping, and muting are determined by attributes. When not specified, the default behavior is determined by the user agent that is used to present the media.

Rendering expectations

When an audio resource cannot be rendered in a meaningful way, processors SHOULD present the contents of the <fallback> element, if it is present.

Content model

<desc> ?, <longdescref> ?, <fallback> ?, <media-source> *, <media-track> *, <foreign> *

In order

Optional <desc>
Optional <longdescref>
Optional <fallback>
Zero or more <media-source>
Zero or more <media-track>
Zero or more <foreign>

Attributes

The following attributes are available on this element: universal attributes, @format, @href, @keyref, @scope, and the attributes defined below.

For this element, the following considerations apply:

The @format attribute specifies the MIME type for the resource. This attribute enables processors to avoid loading unsupported resources. If @format is not specified and @keyref is specified, the effective type for the key named by the @keyref attribute is used as the value. If an explicit @format is not specified on either the <audio> element or key definition, processors can use other means, such as the URI file extension, to determine the effective MIME type of the resource.
The @href attribute specifies the absolute or relative URI of the audio resource. If @href is specified, also specify @format.

@autoplay: Specifies whether the resource automatically plays when it is presented. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@controls: Specifies whether the presentation of the resource includes user interface controls. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@loop: Specifies whether the resource loops when played. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@muted: Specifies whether the resource is muted. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@tabindex: Specifies whether the audio resource can be focused and where it participates in sequential keyboard navigation. See @tabindex in the HTML specification (WHATWG version).

The following attributes are available on this element: universal attributes and the attributes defined below.

@autoplay: Specifies whether the resource automatically plays when it is presented. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@controls: Specifies whether the presentation of the resource includes user interface controls. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@format (link-relationship attributes): Specifies the format of the resource that is referenced. See The format attribute for detailed information on supported values and processing implications.; The @format attribute specifies the MIME type for the resource. This attribute enables processors to avoid loading unsupported resources. If @format is not specified and @keyref is specified, the effective type for the key named by the @keyref attribute is used as the value. If an explicit @format is not specified on either the <audio> element or key definition, processors can use other means, such as the URI file extension, to determine the effective MIME type of the resource.
@href (link-relationship attributes): Specifies a reference to a resource. See The href attribute for detailed information on supported values and processing implications.; The @href attribute specifies the absolute or relative URI of the audio resource. If @href is specified, also specify @format.
@keyref: Specifies a key name that acts as a redirectable reference based on a key definition within a map. See The keyref attribute for information on using this attribute.
For HDITA, the equivalent of @keyref is @data-keyref
@loop: Specifies whether the resource loops when played. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@muted: Specifies whether the resource is muted. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@scope (link-relationship attributes): Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.
See The scope attribute for detailed information on supported values and processing implications.
@tabindex: Specifies whether the audio resource can be focused and where it participates in sequential keyboard navigation. See @tabindex in the HTML specification (WHATWG version).

Examples

This section is non-normative.

Example 1. An <audio> element that uses direct addressing

In the following code sample, an audio resource is referenced using direct addressing. The @type attribute specifies the MIME type of the audio resource.

<audio href="message.mp3" format="audio/mp3"/>

Example 2. An <audio> element that uses indirect addressing

In the following code sample, the audio resource is addressed using a key reference:

<audio keyref="message"/>

Both the URI and the MIME type are specified on the key definition:

<keydef keys="message" href="message.mp3" format="audio/mp3"/>

Example 3. An <audio> element with multiple formats

In the following code sample, <media-source> elements are used to specify the different audio formats that are available.

<audio>
  <media-source href="message.mp3" format="audio/mp3"/>
  <media-source href="message.wav" format="audio/wav"/>
</audio>

Example 4. Example of a complex <audio> element

The following code sample specifies an audio resource and defines multiple presentational details. It also provides fallback behavior for when the audio resource cannot be rendered.

<audio autoplay="true"
                controls="true"
                loop="false"
                muted="false">
  <desc>A sound file narrating the performance of this procedure.</desc>
  <fallback>The audio track walking through this procedure is not available.</fallback>
  <!-- Multiple formats, with URI and MIME type referenced using a key -->
  <media-source keyref="walkthrough-mp3"/>
  <media-source keyref="walkthrough-wav"/>
</audio>