1 简介

MDN-DOC

audio 元素用于在文档中嵌入音频内容。
audio 元素可以包含一个或多个音频资源，这些音频资源可以使用 src 属性或者 source 元素来进行描述：浏览器将会选择最合适的一个来使用。
也可以使用 MediaStream 将这个元素用于流式媒体。

2 快速尝试

<figure>
  <figcaption>Listrn to the T-Rex:</figcaption>
  <audio controls src="/media/cc0-audio/t-rex-roar.mp3"></audio>
  <a href="/media/cc0-audio/t-rex-roar.mp3">Download audio</a>
</figure>

渲染：

示例展示了 audio 元素的基本用法。与 img 元素类似，可在 src 属性中添加嵌入媒体的路径，也可使用其他属性来规定一些功能，例如是否自动播放、是否循环播放、是否显示浏览器的默认音频控件等等。

占位：在浏览器不支持该元素时，会显示 audio 标签之间的内容作为回退。

3 属性

全局属性

src

嵌入音频的 URL
同时可在 audio 中使用 source 元素来替代该属性指定嵌入的音频。

autoplay

布尔属性
声明该属性，音频会尽快自动播放，不会等待整个音频文件下载完成。
tip: 自动播放不利于用户体验，可加入开关让主动打开自动播放。

controls

添加控件（声音大小、播放进度、播放暂停）控制面板

duration（只读）

双精度浮点数，指明了音频在时间轴中的持续时间（总长度），以秒为单位。
若元素上没有媒体，或媒体不可用，则返回 NaN。
若媒体找不到确切的结尾（如不确定长度的直播流，网络电台，或者是通过 WebRTC 连接的流），那么这个值将返回 +Infinity。

loop

布尔属性
声明该属性，将循环播放音频。

muted

布尔类型值
表示是否静音
值： false (def) 表示有声音

preload

枚举属性
让开发者自行思考来示意浏览器使用何种加载方式以达到最好的用户体验。

值：
none 音频不会被缓存（用户可能不会播放该音频，或服务器希望节省带宽）
metadata 示意即使用户可能不会播放该音频，但获取元数据（例如音频长度）还是有必要的
auto 示意用户可能会播放视频，就是如果有必要，整个音频都将被加载，即使用户不期望使用
‘’ 等效于 auto 属性，不同浏览器有自己的默认值。

规范建议：默认值为 metadata

注意：
autoplay 属性的优先级高于 preload。若 autoplay 被指定，浏览器将显示地开始下载媒体以供播放。
浏览器

---

以下为不常用

crossorigin

枚举属性
展示音频资源是否可以通过 CORS 加载。支持 CORS 的资源可以被 canvas 元素复用而不污染。

值： anonymouse, use-credentials

currentTime

读取 currentTime 属性将返回一个双精度浮点值，可以标明以 秒 为单位的当前音频的播放位置。

4 事件

canplay

浏览器已经可以播放媒体，但是预测已加载的数据不足以在不暂停的情况下顺利将其播放到结尾
（即预测会在播放时暂停 以获取更多的缓冲区内容）

canplaythrough

浏览器预测已经可以在不暂停的前提下降媒体播放到结束。

durationchange

duration 属性发生了变化

emptied

媒体置空
示例：当一个媒体已经加载（或部分加载）的情况下调用 load() 方法，这个事件就将被触发。

ended

播放到媒体的结束位置，播放停止。

loadeddata

媒体第 1 帧加载完成

loadedmetadata

元数据加载完成

pause

播放暂停

play

播放开始

playing

因为缺少数据而暂停或延迟的状态结束，播放准备开始

ratechange

播放速度变化

---

以下为不常用

audioprocess

一个 ScriptProcessorNode 的输入缓冲区已经准备开始处理。

complete

一个 OfflineAudioContext 的渲染已经中止。

seeked

一次获取操作结束

seeking

一次获取操作开始

stalled

用户代理试图获取媒体数据，但数据意外地没有进入。

suspend

媒体加载挂起

timeupdate

由 currentTime 指定的时间更新

volumechange

音量变化

waiting

因为暂时性缺少数据，播放暂停。

5 使用说明

浏览器对 文件类型 和音频编码 的支持各有不同，可使用内嵌的 source 元素提供不同的播放源。

浏览器会使用第 1 个它支持的播放源：

<audio controls>
  <source src="myAudio.mp3" type="audio/mpeg" />
  <source src="myAudio.ogg" type="audio/ogg" />
  <p>
    Your browser doesn't support HTML5 audio. Here is a
    <a href="myAudio.mp4">link to the audio</a>
    instead.
  </p>
</audio>

这里提供了全面细致的 音频文件类型指南 和 这些类型可以使用的音频编码。
此外，还有视频编码支持指南。

其他使用说明：

若没有声明 controls 属性，音频播放器不会包含浏览器的默认控件。但可以使用 JS 和 HTMLMediaElement API 创建自己的自定义控件。

为了更精确地控制你的音频内容， HTMLMediaElement 会触发多种不同的事件。
也提供了一个查看音频获取过程的方式，可查看错误或检测什么时候可开始播放或操作。

还可使用 Web Audio API 以从 JS 代码直接生成和操作音频流，而非流式播放已存在的音频文件。

audio 元素不能像 video 一样附加副标题(subtitle)或标题(caption)。更多有用的信息和解决方法见 Ian Devlin 的 WebVTT and Audio。

CSS 设置样式

audio 元素没有自带的固有视觉样式，除非声明了 controls 属性，则会显示浏览器的默认控件。

默认控件 display 的默认值为 inline。
将该值设为 block 通常会对定位和布局有好处，除非你想讲控件放在文本或类似元素中。

可使用作用于整个控件的属性来为其设置样式。
例如：border, border-radius, padding, margin 等。
但不能设置音频播放器中的单个组件（如改变按钮大小、改变图标或字体等）
控件在不同的浏览器中也有所不同。

自定义控件：若需要在跨浏览器中得到一致的外观和体验，则需要创建自定义控件；自定义控件可以根据需求任意设置样式，还可以使用 JS 和 HTMLMediaElement API 来设置更多功能。

视频播放器样式基础 提供了一些有用的样式技术，文章围绕 video 而写，但大部分都可用于 audio。

检测音轨添加和移除

可通过 addtrack 和 removetrack 事件来检测何时音轨从 audio 元素中添加和移除。

然而，这些事件并不是直接传递给 audio 元素自己的。
相反，它们是发送给 audio 元素的 HTMLMediaElement 中的音轨列表对象的。这些对象与添加进元素的音轨类型一一对应。

HTMLMediaElement.audioTracks
一个 AudioTrackList 包含所有的媒体对象的音轨。能在为 addtrack 事件添加监听，以在新音轨添加进元素时获得通知。

HTMLMediaElement.textTracks
在该 TextTrackList 对象上添加监听，以在文字轨道被添加进元素时获得通知。（也许用于字幕，译者猜测）

备注： 尽管是 元素，但它依然有视频以及文字的轨道列表，并且实际上能够用来展示视频，尽管应用接口的使用可能显得很古怪。

示例：为了侦测何时音轨从一个 audio 元素中添加或者移除，可用如下代码：

var elem = document.querySelector('audio')

elem.audioTrackList.onaddtrack = function (event) {
  trackEditor.addTrack(event.track)
}

elem.audioTrackList.onremovetrack = function (event) {
  trackEditor.removeTrack(event.track)
}

这份代码监听音轨从目标元素中添加删除的事件，并且调用了一个轨道编辑器上的虚拟函数，来从编辑器上的可用音轨列表中注册和移除音轨。

也可使用 addEventListener() 来监听 addtrack 和 removetrack 事件。

6 示例

-1 基本用法

<audio src="AudioTest.ogg" autoplay>
  Your browser does not support the
  <code>audio</code>
  element.
</audio>

若想获得更多信息，包括何时自动播放生效，如何获取自动播放权限，并且通过何种方式，在何时应用自动播放才是合适的，另看

-2 audio, source 元素

下面示例指出了在 嵌套的 source 元素的 src 属性上设置嵌入音轨，而非直接在 audio 元素上设置。
通过这种方法可以同时在 type 属性上包含文件的 MIME 类型，这通常很有用，因为浏览器就能立即决策：自己究竟是能够播放该文件，还是不在不能播放的文件上浪费时间。

<audio controls>
  <source src="foo.wav" type="audio/wav" />
  Your browser does not support the
  <code>audio</code>
  element.
</audio>

-3 audio 与 多个 source 元素

示例中包含了多个 source 元素。
如果能够播放的话，浏览器就会试图去加载第 1 个 source 元素（Opus 后缀名）；
如果不行，就退而求其次去加载第 2 个(Vorbis 后缀名)，最终退到了 MP3 格式：

<audio controls>
  <source src="foo.opus" type="audio/ogg; codecs=opus" />
  <source src="foo.ogg" type="audio/ogg; codecs=vorbis" />
  <source src="foo.mp3" type="audio/mpeg" />
</audio>

7 无障碍考虑

了解

8 技术总结

标签不允许省略，开始标签和结束标签都不能省略。

可嵌入 任何能够作为容器的元素

允许的内容 若元素拥有 src 属性，则允许的内容为 0 个或多个 track 元素，跟随着不包含 audio 或 video 媒体元素的透明内容。
否则，允许的内容为 0 个或多个 source 元素，跟随着 0 个或多个 track 元素，跟随着不包含 audio 或 video 媒体元素的透明内容。

其他

规范
浏览器兼容
—— 见文档