HTML 5 Audio · Playback Audio files

The block audio macro enables you to embed audio streams into your documents. Using the macro, embed self-hosted audio files or audio sources from the Internet are supported.

5-10 Minutes to read

Asciidoc macro audio

The Asciidoc block audio macro audio:: enables you to embed audio streams into your documents. Using the macro, embed self-hosted audio files or audio sources from the Internet are supported.

Syntax

The audio formats the macro supports is given by the formats supported by the browser. HTML 5 has brought sanity to audio support in the browser by adding a dedicated audio tag element <audio> and by introducing several standard audio formats, widely supported across all modern browsers.

For a canonical list of supported web audio formats and their interaction with modern browsers, see the documentation at Mozilla Developer Supported Media Formats.

Basic audio file include

audio::ocean-waves.wav[]

You can control the audio settings using additional attributes on the macro. For instance, you can offset the start time of playback using the start attribute start and enable autoplay using the autoplay option autoplay.

Set attributes for local audio playback

audio::ocean-waves.wav[start=60,opts=autoplay]

You can include a caption above the audio using the title attribute.

Add a caption to the audio

.Take a zen moment
audio::ocean-waves.wav[]

Attributes

To control the audio, following attributes are available.

Attribute Value|s Example

title

User defined text

.Ocean waves

start

User-defined playback start time in seconds.

start=30

end

User-defined playback end time in seconds.

end=90

options (opts)

autoplay, loop, controls, nocontrols

opts="autoplay,loop"

The controls value is enabled by default.

HTML audio

The HTML audio tag <audio> embeds a media player which supports audio playback into the document.

HTML Markup for basic audio playback

<audio src="ambient-piano.mp3" controls="">
  Your browser does not support the audio tag.
</audio>

Attributes

The above example shows simple usage of the audio element <audio>. Fimd available attributes in alphabetical order below.

Attribute Description

autoplay

A Boolean attribute: if specified, the audio will automatically begin playback as soon as it can do so, without waiting for the entire audio file to finish downloading.

Sites that automatically play audio (or videos with an audio track) can be an unpleasant experience for users, so should be avoided when possible. If you must offer autoplay functionality, you should make it opt-in (requiring a user to specifically enable it). However, this can be useful when creating media elements whose source will be set at a later time, under user control. See our autoplay guide for additional information about how to properly use autoplay.

controls

If this attribute is present, the browser will offer controls to allow the user to control audio playback, including volume, seeking, and pause/resume playback.

controlslist

The controlslist attribute, when specified, helps the browser select what controls to show for the audio element whenever the browser shows its own set of controls (that is, when the controls attribute is specified).

The allowed values are nodownload, nofullscreen and noremoteplayback.

crossorigin

This enumerated attribute indicates whether to use CORS to fetch the related audio file. CORS-enabled resources can be reused in the <canvas> element without being tainted.

The allowed values are:

anonymous: Sends a cross-origin request without a credential. In other words, it sends the Origin: HTTP header without a cookie, X.509 certificate, or performing HTTP Basic authentication. If the server does not give credentials to the origin site (by not setting the Access-Control-Allow-Origin: HTTP header), the resource will be tainted, and its usage restricted.
use-credentials: Sends a cross-origin request with a credential. In other words, it sends the Origin: HTTP header with a cookie, a certificate, or performing HTTP Basic authentication. If the server does not give credentials to the origin site (through Access-Control-Allow-Credentials: HTTP header), the resource will be tainted and its usage restricted.

When not present, the resource is fetched without a CORS request (i.e. without sending the Origin: HTTP header, preventing its non-tainted use in <canvas> elements.

If invalid, it is handled as if the enumerated keyword anonymous was used. See CORS settings attributes for additional information.

disableremoteplayback

A Boolean attribute used to disable the capability of remote playback in devices that are attached using wired (HDMI, DVI, etc.) and wireless technologies (Miracast, Chromecast, DLNA, AirPlay, etc.). See this proposed specification for more information. In Safari, you can use //developer.apple.com/library/archive/documentation/AudioVideo/Conceptual/AirPlayGuide/OptingInorOutofAirPlay/OptingInorOutofAirPlay.html as a fallback.

loop

A Boolean attribute: if specified, the audio player will automatically seek back to the start upon reaching the end of the audio.

muted

A Boolean attribute that indicates whether the audio will be initially silenced. Its default value is false.

preload

This enumerated attribute is intended to provide a hint to the browser about what the author thinks will lead to the best user experience. It may have one of the following values:

none: Indicates that the audio should not be preloaded.
metadata: Indicates that only audio metadata (e.g. length) is fetched.
auto: Indicates that the whole audio file can be downloaded, even if the user is not expected to use it.
empty string: A synonym of the auto value.

The default value is different for each browser. The spec advises it to be set to metadata.

The autoplay attribute autoplay has precedence over the preload attribute preload. If autoplay is specified, the browser would obviously need to start downloading the audio for playback.

The browser is not forced by the specification to follow the value of this attribute; it is a mere hint.

Events

Table 3. Supported events for the HTML 5 audio
Event Name	Fired When
`audioprocess`	The input buffer of a `ScriptProcessorNode` is ready to be processed.
`canplay`	The browser can play the media, but estimates that not enough data has been loaded to play the media up to its end without having to stop for further buffering of content.
`canplaythrough`	The browser estimates it can play the media up to its end without stopping for content buffering.
`complete`	The rendering of an `OfflineAudioContext` is terminated.
`durationchange`	The `duration` attribute has been updated.
`emptied`	The media has become empty; for example, this event is sent if the media has already been loaded (or partially loaded), and the `HTMLMediaElement.load` method is called to reload it.
`ended`	Playback has stopped because the end of the media was reached.
`loadeddata`	The first frame of the media has finished loading.
`loadedmetadata`	The metadata has been loaded.
`loadstart`	Fired when the browser has started to load the resource.
`pause`	Playback has been paused.
`play`	Playback has begun.
`playing`	Playback is ready to start after having been paused or delayed due to lack of data.
`ratechange`	The playback rate has changed.
`seeked`	A seek operation completed.
`seeking`	A seek operation began.
`stalled`	The user agent is trying to fetch media data, but data is unexpectedly not forthcoming.
`suspend`	Media data loading has been suspended.
`timeupdate`	The time indicated by the `currentTime` attribute has been updated.
`volumechange`	The volume has changed.
`waiting`	Playback has stopped because of a temporary lack of data

Codecs

The list below denotes the codecs most commonly used on the web and which file types support them. If you only need to know which codecs are possible, this is for you.

Individual browsers may or may not choose to support all of these codecs, and their support for which container types can use them may also vary. In addition, browsers may support additional codecs not included on this list.

Table 4. Most commonly codecs used on the web
Codec name	Full name	Container support
AAC	Advanced Audio Coding	MP4, ADTS, 3GP
ALAC	Apple Lossless Audio Codec	MP4, QuickTime (MOV)
AMR	Adaptive Multi-Rate	3GP
FLAC	Free Lossless Audio Codec	MP4, Ogg, FLAC
G.711	Pulse Code Modulation (PCM) of Voice Frequencies	RTP, WebRTC
G.722	7 kHz Audio Coding Within 64 kbps (VoIP)	RTP, WebRTC
MP3	MPEG-1 Audio Layer III	MP4, ADTS, MPEG, 3GP When MPEG-1 Audio Layer III codec data is stored in an MPEG file, and there is no video track on the file, the file is typically referred to as an MP3 file, even though it’s still an MPEG format file.
Opus	Opus	WebM, MP4, Ogg
Vorbis	Vorbis	WebM, Ogg