<audio>:嵌入音频元素

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

¥The above example shows simple usage of the <audio> element. In a similar manner to the <img> element, we include a path to the media we want to embed inside the src attribute; we can include other attributes to specify information such as whether we want it to autoplay and loop, whether we want to show the browser's default audio controls, etc.

开始和结束 <audio></audio> 标记内的内容在不支持该元素的浏览器中显示为后备。

¥The content inside the opening and closing <audio></audio> tags is shown as a fallback in browsers that don't support the element.

¥Attributes

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

¥This element's attributes include the global attributes.

autoplay

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

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

¥Note: 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

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

controlslist

指定 controlslist 属性后，只要浏览器显示自己的控件集（即指定 controls 属性时），就可以帮助浏览器选择为 audio 元素显示哪些控件。

允许的值为 nodownload、nofullscreen 和 noremoteplayback。

crossorigin

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

anonymous

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

use-credentials

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

如果不存在，则在不发送 CORS 请求的情况下获取资源（即不发送 Origin: HTTP 标头），从而防止其在 <canvas> 元素中不受污染地使用。如果无效，则按照使用枚举关键字 anonymous 的方式进行处理。请参阅 CORS 设置属性 了解更多信息。

disableremoteplayback

布尔属性，用于禁用使用有线（HDMI、DVI 等）和无线技术（Miracast、Chromecast、DLNA、AirPlay 等）连接的设备中的远程播放功能。请参阅 本提议的规范 了解更多信息。

在 Safari 中，你可以使用 x-webkit-airplay="deny" 作为后备。

loop

布尔属性：如果指定，音频播放器将在到达音频结尾时自动返回到开头。

muted

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

preload

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

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

每个浏览器的默认值都不同。规范建议将其设置为 metadata。

注意：

¥Note:

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

src

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

¥Events

¥Usage notes

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

¥Browsers don't all support the same file types and audio codecs; you can provide multiple sources inside nested <source> elements, and the browser will then use the first one it understands:

<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>

我们提供实质性和彻底的 媒体文件类型指南 和 可在其中使用的音频编解码器。另外还有 视频支持的编解码器指南。

¥We offer a substantive and thorough guide to media file types and the audio codecs that can be used within them. Also available is a guide to the codecs supported for video.

其他使用注意事项：

¥Other usage notes:

• 如果你不指定 controls 属性，音频播放器将不会包含浏览器的默认控件。但是，你可以使用 JavaScript 和 HTMLMediaElement API 创建自己的自定义控件。
• 为了精确控制音频内容，HTMLMediaElement 会触发许多不同的 events。这还提供了一种监视音频获取过程的方法，以便你可以观察错误或检测何时有足够的可用资源来开始播放或操作它。
• 你还可以使用 Web 音频 API 直接从 JavaScript 代码生成和操作音频流，而不是流式传输预先存在的音频文件。
• <audio> 元素不能像 <video> 元素那样具有与之关联的副标题或标题。请参阅 Ian Devlin 的 WebVTT 和音频，了解一些有用的信息和解决方法。
• 要在支持该元素的浏览器上测试后备内容，你可以将 <audio> 替换为不存在的元素（例如 <notanaudio>）。

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

¥A good general source of information on using HTML <audio> is the Video and audio content beginner's tutorial.

¥Styling with CSS

除非指定了 controls 属性，否则 <audio> 元素没有自己的内在视觉输出，在这种情况下将显示浏览器的默认控件。

¥The <audio> element has no intrinsic visual output of its own unless the controls attribute is specified, in which case the browser's default controls are shown.

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

¥The default controls have a display value of inline by default, and it is often a good idea to set the value to block to improve control over positioning and layout, unless you want it to sit within a text block or similar.

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

¥You can style the default controls with properties that affect the block as a single unit, so for example you can give it a border and border-radius, padding, margin, etc. You can't however style the individual components inside the audio player (e.g. change the button size or icons, change the font, etc.), and the controls are different across the different browsers.

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

¥To get a consistent look and feel across browsers, you'll need to create custom controls; these can be marked up and styled in whatever way you want, and then JavaScript can be used along with the HTMLMediaElement API to wire up their functionality.

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

¥Video player styling basics provides some useful styling techniques — it is written in the context of <video>, but much of it is equally applicable to <audio>.

¥Detecting addition and removal of tracks

你可以使用 addtrack 和 removetrack 事件检测何时向 <audio> 元素添加或删除轨道。但是，这些事件不会直接发送到 <audio> 元素本身。相反，它们被发送到 <audio> 元素的 HTMLMediaElement 内的轨道列表对象，该对象对应于添加到元素的轨道类型：

¥You can detect when tracks are added to and removed from an <audio> element using the addtrack and removetrack events. However, these events aren't sent directly to the <audio> element itself. Instead, they're sent to the track list object within the <audio> element's HTMLMediaElement that corresponds to the type of track that was added to the element:

HTMLMediaElement.audioTracks

包含所有媒体元素的音轨的 AudioTrackList。你可以将 addtrack 的监听器添加到此对象，以便在将新音轨添加到元素时收到警报。

HTMLMediaElement.videoTracks

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

HTMLMediaElement.textTracks

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

注意：尽管它是 <audio> 元素，但它仍然具有视频和文本轨道列表，并且实际上可以用于呈现视频，尽管用户界面的含义可能很奇怪。

¥Note: Even though it's an <audio> element, it still has video and text track lists, and can in fact be used to present video, although the user interface implications can be odd.

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

¥For example, to detect when audio tracks are added to or removed from an <audio> element, you can use code like this:

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

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

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

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

¥This code watches for audio tracks to be added to and removed from the element, and calls a hypothetical function on a track editor to register and remove the track from the editor's list of available tracks.

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

¥You can also use addEventListener() to listen for the addtrack and removetrack events.

¥Accessibility

带有语音对话的音频应提供准确描述其内容的字幕和文字记录。使用 WebVTT 指定的字幕允许听力受损的人在播放录音时理解录音的内容，而文字记录则允许需要额外时间的人能够以适合的速度和格式查看录音内容。 对他们来说很舒服。

¥Audio with spoken dialog should provide both captions and transcripts that accurately describe its content. Captions, which are specified using WebVTT, allow people who are hearing impaired to understand an audio recording's content as the recording is being played, while transcripts allow people who need additional time to be able to review the recording's content at a pace and format that is comfortable for them.

如果使用自动字幕服务，则检查生成的内容以确保其准确代表源音频非常重要。

¥If automatic captioning services are used, it is important to review the generated content to ensure it accurately represents the source audio.

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

¥The <audio> element doesn't directly support WebVTT. You will have to find a library or framework that provides the capability for you, or write the code to display captions yourself. One option is to play your audio using a <video> element, which does support WebVTT.

除了口头对话之外，字幕和文字记录还应该标识传达重要信息的音乐和音效。这包括情绪和语气。例如，在下面的 WebVTT 中，请注意使用方括号向观看者提供语气和情感洞察；这可以帮助建立气氛，否则可以使用音乐、非语言声音和关键音效等来提供。

¥In addition to spoken dialog, subtitles and transcripts should also identify music and sound effects that communicate important information. This includes emotion and tone. For example, in the WebVTT below, note the use of square brackets to provide tone and emotional insight to the viewer; this can help establish the mood otherwise provided using music, nonverbal sounds and crucial sound effects, and so forth.

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> 元素的浏览器的查看者提供一些内容（例如直接下载链接）作为后备也是一个很好的做法：

¥Also it's a good practice to provide some content (such as the direct download link) as a fallback for viewers who use a browser in which the <audio> element is not supported:

<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>

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

¥Examples

¥Basic usage

以下示例显示了使用 <audio> 元素播放 OGG 文件的简单用法。它将由于 autoplay 属性而自动播放（如果页面有权这样做），并且还包含后备内容。

¥The following example shows simple usage of the <audio> element to play an OGG file. It will autoplay due to the autoplay attribute—if the page has permission to do so—and also includes fallback content.

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

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

¥For details on when autoplay works, how to get permission to use autoplay, and how and when it's appropriate to use autoplay, see our autoplay guide.

¥\

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

¥This example specifies which audio track to embed using the src attribute on a nested <source> element rather than directly on the <audio> element. It is always useful to include the file's MIME type inside the type attribute, as the browser is able to instantly tell if it can play that file, and not waste time on it if not.

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

¥\

此示例包含多个 <source> 元素。如果能够播放，浏览器会尝试加载第一个源元素（Opus）；如果不是，则返回到第二个 (Vorbis)，最后返回到 MP3：

¥This example includes multiple <source> elements. The browser tries to load the first source element (Opus) if it is able to play it; if not it falls back to the second (Vorbis) and finally back to 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>

¥Technical summary

¥See also

• 网络媒体技术
  • 媒体容器格式（文件类型）
  • 网络上使用的音频编解码器指南
• Web 音频 API
• HTMLAudioElement
• <source>
• <video>
• 学习字段：视频和音频内容
• 跨浏览器音频基础知识