<audio>: 嵌入式音频元素

试一试

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

figure {
  margin: 0;
}

上面的示例展示了 <audio> 元素的基本用法。与 <img> 元素类似，我们在 src 属性中包含要嵌入的媒体的路径；我们可以包含其他属性来指定信息，例如我们是否希望它自动播放和循环，是否希望显示浏览器的默认音频控件等。

在开闭 <audio></audio> 标签内的内容将作为不支持该元素的浏览器的备用内容显示。

属性

此元素的属性包括全局属性。

autoplay

一个布尔属性：如果指定，音频将尽快自动开始播放，无需等待整个音频文件下载完成。

注意：自动播放音频（或带有音轨的视频）的网站可能会给用户带来不愉快的体验，因此应尽可能避免。如果您必须提供自动播放功能，则应使其成为可选加入（要求用户明确启用）。但是，这在创建源将在以后由用户控制设置的媒体元素时非常有用。有关如何正确使用自动播放的更多信息，请参阅我们的自动播放指南。

controls

如果存在此属性，浏览器将提供控件，允许用户控制音频播放，包括音量、快进/快退以及暂停/恢复播放。

controlslist

当指定 controlslist 属性时，它有助于浏览器选择在浏览器显示其自身控件集（即当指定了 controls 属性时）时，为 audio 元素显示哪些控件。

允许的值为 nodownload、nofullscreen 和 noremoteplayback。

crossorigin

此枚举属性指示是否使用 CORS 来获取相关的音频文件。启用 CORS 的资源可以在 <canvas> 元素中重复使用而不会被污染。允许的值是：

anonymous

发送不带凭据的跨域请求。换句话说，它发送 Origin: HTTP 头，但不带 cookie、X.509 证书或执行 HTTP 基本认证。如果服务器不向源站点提供凭据（通过不设置 Access-Control-Allow-Origin: HTTP 头），资源将被污染，其使用将受到限制。

use-credentials

发送带凭据的跨域请求。换句话说，它发送 Origin: HTTP 头，并带有一个 cookie、一个证书或执行 HTTP 基本认证。如果服务器不向源站点提供凭据（通过 Access-Control-Allow-Credentials: HTTP 头），资源将被污染，其使用将受到限制。

如果不存在，则在不进行 CORS 请求的情况下获取资源（即，不发送 Origin: HTTP 头），从而阻止其在 <canvas> 元素中进行未污染的使用。如果无效，则将其视为使用了枚举关键字 anonymous。有关更多信息，请参阅 CORS 设置属性。

disableremoteplayback

一个布尔属性，用于禁用通过有线（HDMI、DVI 等）和无线技术（Miracast、Chromecast、DLNA、AirPlay 等）连接的设备中的远程播放功能。有关更多信息，请参阅拟议的 远程播放 API 规范。

在 Safari 中，您可以使用 x-webkit-airplay="deny" 作为备用方案。

loop

一个布尔属性：如果指定，音频播放器在到达音频末尾时会自动跳回开始处。

muted

一个布尔属性，指示音频是否在初始时静音。其默认值为 false。

preload

此枚举属性旨在向浏览器提供关于作者认为将带来最佳用户体验的提示。它可能具有以下值之一：

• none：表示不应预加载音频。
• metadata：表示仅获取音频元数据（例如，长度）。
• auto：表示可以下载整个音频文件，即使预计用户不会使用它。
• 空字符串：auto 值的同义词。

默认值因浏览器而异。规范建议将其设置为 metadata。

备注

• autoplay 属性优先于 preload。如果指定了 autoplay，浏览器显然需要开始下载音频进行播放。
• 规范并未强制浏览器遵循此属性的值；它只是一个提示。

src

要嵌入的音频的 URL。这受 HTTP 访问控制的约束。这是可选的；您可以改为在音频块内使用 <source> 元素来指定要嵌入的音频。

事件

audioprocess 已弃用

ScriptProcessorNode 的输入缓冲区已准备好进行处理。

canplay

浏览器可以播放媒体，但估计加载的数据不足以播放到媒体结束而无需停止以进一步缓冲内容。

canplaythrough

浏览器估计它可以在不停止内容缓冲的情况下播放媒体直到结束。

完成

OfflineAudioContext 的渲染已终止。

durationchange

duration 属性已更新。

emptied

媒体已变为空；例如，如果媒体已加载（或部分加载），并且调用 HTMLMediaElement.load 方法以重新加载它，则会发送此事件。

ended

播放已停止，因为已达到媒体的末尾。

loadeddata

媒体的第一帧已完成加载。

loadedmetadata

元数据已加载。

loadstart

当浏览器开始加载资源时触发。

pause

播放已暂停。

play

播放已开始。

playing

在因数据不足而暂停或延迟后，播放已准备好开始。

ratechange

播放速率已更改。

seeked

查找操作完成。

seeking

查找操作开始。

stalled

用户代理正在尝试获取媒体数据，但数据意外地未能提供。

suspend

媒体数据加载已暂停。

timeupdate

currentTime 属性指示的时间已更新。

volumechange

音量已更改。

waiting

由于暂时缺少数据，播放已停止。

用法说明

浏览器并非都支持相同的文件类型和音频编解码器；您可以在嵌套的<source>元素中提供多个源，然后浏览器将使用它能理解的第一个源

<audio controls>
  <source src="myAudio.mp3" type="audio/mpeg" />
  <source src="myAudio.ogg" type="audio/ogg" />
  <p>
    Download <a href="myAudio.mp3" download="myAudio.mp3">MP3</a> or
    <a href="myAudio.ogg" download="myAudio.ogg">OGG</a> audio.
  </p>
</audio>

音频源可以设置为任何有效的 URL，包括 HTTP(S) URL 和 数据 URL。使用 HTTP(S) URL 时，请注意浏览器的缓存行为会影响文件从服务器请求的频率。数据 URL 将音频数据直接嵌入到 HTML 中，这对于小型音频文件很有用，但对于大型文件不建议使用，因为它会增加 HTML 文件的大小。

使用 <source> 元素时，浏览器会尝试按顺序加载每个源。如果某个源失败（例如，由于无效 URL 或不支持的格式），则会尝试下一个源，依此类推。在所有源都失败后，会在 <audio> 元素上触发 error 事件；不会在每个单独的 <source> 元素上触发 error 事件。

您还可以使用 Web Audio API 直接从 JavaScript 代码生成和操作音频流，而不是流式传输预先存在的音频文件。您可以将 JavaScript 中的 srcObject 设置为 MediaStream 对象。这通常用于实时音频流或实时音频处理。

const audioElement = document.querySelector("audio");
navigator.mediaDevices
  .getUserMedia({ audio: true })
  .then((stream) => {
    audioElement.srcObject = stream;
  })
  .catch((error) => {
    console.error("Error accessing the microphone", error);
  });

请注意，MediaStream 源有局限性：它们不可查找，并且仅支持有限的编解码器集。

我们提供了一份内容丰富且全面的媒体文件类型指南以及可在其中使用的音频编解码器。还提供视频支持的编解码器指南。

其他使用注意事项

• 如果您未指定 controls 属性，则音频播放器将不包含浏览器的默认控件。但是，您可以使用 JavaScript 和 HTMLMediaElement API 创建自己的自定义控件。
• 为了精确控制您的音频内容，HTMLMediaElement 会触发许多不同的事件。这还提供了一种监控音频获取过程的方法，以便您可以查找错误或检测何时有足够的内容可用以开始播放或操作它。
• <audio> 元素不能像 <video> 元素那样关联字幕或说明。有关一些有用信息和变通方法，请参阅 Ian Devlin 的WebVTT 和音频。
• 要在支持该元素的浏览器上测试备用内容，您可以将 <audio> 替换为不存在的元素，例如 <notanaudio>。

有关使用 HTML <audio> 的一个很好的通用信息来源是 HTML 视频和音频初学者教程。

使用 CSS 样式

<audio> 元素本身没有固有的视觉输出，除非指定了 controls 属性，在这种情况下会显示浏览器的默认控件。

默认情况下，默认控件的 display 值为 inline，通常最好将值设置为 block 以改善对定位和布局的控制，除非您希望它位于文本块或类似内容中。

您可以使用影响块作为一个整体的属性来样式化默认控件，例如，您可以为其指定 border 和 border-radius、padding、margin 等。但是，您无法样式化音频播放器中的各个组件（例如，更改按钮大小或图标、更改字体等），并且不同浏览器中的控件也不同。

为了在不同浏览器中获得一致的外观和感觉，您需要创建自定义控件；这些控件可以按您希望的任何方式进行标记和样式设置，然后可以使用 JavaScript 和 HTMLMediaElement API 来连接其功能。

视频播放器样式基础提供了一些有用的样式技术——它是在 <video> 的背景下编写的，但其中大部分同样适用于 <audio>。

检测轨道的添加和移除

您可以使用 addtrack 和 removetrack 事件来检测何时将轨道添加到 <audio> 元素或从 <audio> 元素中移除轨道。但是，这些事件不会直接发送到 <audio> 元素本身。相反，它们会发送到 <audio> 元素的 HTMLMediaElement 中与添加到元素的轨道类型对应的轨道列表对象

HTMLMediaElement.audioTracks

一个 AudioTrackList，包含所有媒体元素的音轨。您可以向此对象添加 addtrack 监听器，以便在新音轨添加到元素时收到通知。

HTMLMediaElement.videoTracks

向此 VideoTrackList 对象添加 addtrack 监听器，以便在视频轨道添加到元素时收到通知。

HTMLMediaElement.textTracks

向此 TextTrackList 添加 addtrack 事件监听器，以便在新文本轨道添加到元素时收到通知。

例如，要检测何时向 <audio> 元素添加或从中移除音轨，您可以使用以下代码：

const elem = document.querySelector("audio");

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

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

此代码监视音轨添加到元素和从元素中移除的情况，并调用音轨编辑器上的假想函数，以在编辑器的可用音轨列表中注册和移除音轨。

您还可以使用 addEventListener() 来监听 addtrack 和 removetrack 事件。

无障碍

带有语音对话的音频应提供准确描述其内容的字幕和文字记录。字幕（使用 WebVTT 指定）允许听力受损的人在录音播放时理解其内容，而文字记录则允许需要额外时间的人以适合自己的节奏和格式回顾录音内容。

如果使用自动字幕服务，务必审核生成的内容，以确保其准确地代表了源音频。

<audio> 元素不直接支持 WebVTT。您必须找到提供该功能的库或框架，或者自己编写代码来显示字幕。一种选择是使用支持 WebVTT 的 <video> 元素播放音频。

除了语音对话之外，字幕和文字记录还应识别传达重要信息的音乐和音效。这包括情感和语调。例如，在下面的 WebVTT 中，请注意使用方括号为观看者提供语调和情感洞察力；这有助于营造否则通过音乐、非语言声音和关键音效等提供的氛围。

1
00:00:00 --> 00:00:45
[Energetic techno music]

2
00:00:46 --> 00:00:51
Welcome to the Time Keeper's podcast! In this episode we're discussing which Swisswatch is a wrist switchwatch?

16
00:00:52 --> 00:01:02
[Laughing] Sorry! I mean, which wristwatch is a Swiss wristwatch?

此外，提供一些内容（例如直接下载链接）作为不支持 <audio> 元素的浏览器的备用是一种很好的做法

<audio controls>
  <source src="myAudio.mp3" type="audio/mpeg" />
  <source src="myAudio.ogg" type="audio/ogg" />
  <p>
    Download <a href="myAudio.mp3">MP3</a> or
    <a href="myAudio.ogg" download="myAudio.ogg">OGG</a> audio.
  </p>
</audio>

• Web 视频文本轨道格式 (WebVTT)
• WebAIM：字幕、文字记录和音频描述
• MDN 理解 WCAG，指南 1.2 解释
• 理解成功标准 1.2.1 | W3C 理解 WCAG 2.0
• 理解成功标准 1.2.2 | W3C 理解 WCAG 2.0

示例

基本用法

以下示例显示了 <audio> 元素播放 OGG 文件的基本用法。如果页面有权限，它将由于 autoplay 属性而自动播放，并且还包含备用内容。

<!-- Basic audio playback -->
<audio src="AudioTest.ogg" autoplay>
  <a href="AudioTest.ogg" download="AudioTest.ogg">Download OGG audio</a>.
</audio>

有关自动播放何时工作、如何获得自动播放权限以及何时适合使用自动播放的详细信息，请参阅我们的自动播放指南。

带有 <source> 元素的 <audio> 元素

此示例使用嵌套 <source> 元素上的 src 属性，而不是直接在 <audio> 元素上，来指定要嵌入的音轨。在 type 属性中包含文件的 MIME 类型总是很有用的，因为浏览器能够立即判断它是否可以播放该文件，如果不能，就不会浪费时间。

<audio controls>
  <source src="foo.wav" type="audio/wav" />
  <a href="foo.wav" download="foo.wav">Download WAV audio</a>.
</audio>

带有多个 <source> 元素的 <audio>

此示例包含多个 <source> 元素。如果浏览器能够播放第一个源元素（Opus），它会尝试加载它；否则它会回退到第二个（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>

技术摘要

规范

浏览器兼容性

另见

• Web 媒体技术

  • 媒体容器格式（文件类型）
  • 网络上使用的音频编解码器指南

• Web Audio API

• HTMLAudioElement
• <source>
• <video>

• 学习区：HTML 视频和音频

• 跨浏览器音频基础