<video>:视频嵌入元素

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

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

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

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

¥Attributes

与所有其他 HTML 元素一样，此元素支持 全局属性。

¥Like all other HTML elements, this element supports the global attributes.

autoplay

布尔属性；如果指定，视频会自动尽快开始播放，而不会停下来完成数据加载。

注意：现代浏览器会阻止音频（或带有未静音音轨的视频）自动播放，因为自动播放音频的网站可能会给用户带来不愉快的体验。有关如何正确使用自动播放的更多信息，请参阅我们的 自动播放指南。

¥Note: Modern browsers block audio (or videos with an unmuted audio track) from autoplaying, as sites that automatically play audio can be an unpleasant experience for users. See our autoplay guide for additional information about how to properly use autoplay.

要禁用视频自动播放，autoplay="false" 将不起作用；如果 <video> 标签中存在该属性，则视频将自动播放。要删除自动播放，需要完全删除该属性。

controls

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

controlslist

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

允许的值为 nodownload、nofullscreen 和 noremoteplayback。

如果要禁用画中画模式（和控件），请使用 disablepictureinpicture 属性。

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 设置属性 了解更多信息。

disablepictureinpicture

在某些情况下，防止浏览器建议画中画上下文菜单或自动请求画中画。

disableremoteplayback

布尔属性，用于禁用使用有线（HDMI、DVI 等）和无线技术（Miracast、Chromecast、DLNA、AirPlay 等）连接的设备中的远程播放功能。

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

height

视频显示区域的高度，以 CSS 像素 为单位（仅限绝对值；无百分比）。

loop

布尔属性；如果指定，浏览器将在到达视频结尾时自动返回到开头。

muted

一个布尔属性，表示视频中包含的默认音频静音设置。如果设置，音频最初将被静音。其默认值为 false，表示播放视频时将播放音频。

playsinline

一个布尔属性，表示视频将在 "inline" 处播放，即在元素的播放区域内播放。请注意，缺少此属性并不意味着视频将始终以全屏播放。

poster

下载视频时显示的图片的 URL。如果未指定此属性，则在第一帧可用之前不会显示任何内容，然后第一帧将显示为海报帧。

preload

此 enumerated 属性旨在向浏览器提供提示，说明作者认为在播放视频之前加载哪些内容会带来最佳用户体验。它可能具有以下值之一：

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

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

注意：

¥Note:

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

src

要嵌入的视频的 URL。这是可选的；你可以使用视频块中的 <source> 元素来指定要嵌入的视频。

width

视频显示区域的宽度，以 CSS 像素 为单位（仅限绝对值；无百分比）。

¥Events

¥Usage notes

浏览器并不都支持相同的视频格式；你可以在嵌套的 <source> 元素内提供多个源，然后浏览器将使用它理解的第一个源。

¥Browsers don't all support the same video formats; you can provide multiple sources inside nested <source> elements, and the browser will then use the first one it understands.

<video controls>
  <source src="myVideo.webm" type="video/webm" />
  <source src="myVideo.mp4" type="video/mp4" />
  <p>
    Your browser doesn't support HTML video. Here is a
    <a href="myVideo.mp4" download="myVideo.mp4">link to the video</a> instead.
  </p>
</video>

我们提供实质性和彻底的 媒体文件类型指南 和 视频支持的编解码器指南。还提供了 可以与它们一起使用的音频编解码器 指南。

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

其他使用注意事项：

¥Other usage notes:

• 如果不指定 controls 属性，视频将不包含浏览器的默认控件；你可以使用 JavaScript 和 HTMLMediaElement API 创建自己的自定义控件。详细信息请参见 创建跨浏览器视频播放器。
• 为了精确控制你的视频（和音频）内容，HTMLMediaElement 触发了许多不同的 events。除了提供可控性之外，这些事件还允许你监视媒体下载和播放的进度以及播放状态和位置。
• 你可以使用 object-position 属性来调整视频在元素框架内的位置，并使用 object-fit 属性来控制如何调整视频大小以适合框架。
• 要与视频一起显示字幕/说明文字，你可以使用一些 JavaScript 以及 <track> 元素和 WebVTT 格式。请参阅 向 HTML 视频添加字幕和副标题 了解更多信息。
• 你可以使用 <video> 元素播放音频文件。例如，如果你需要使用 WebVTT 转录来执行音频，则这会很有用，因为 <audio> 元素不允许使用 WebVTT 的字幕。
• 要在支持该元素的浏览器上测试后备内容，你可以将 <video> 替换为不存在的元素（例如 <notavideo>）。

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

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

¥Styling with CSS

<video> 元素是一个替换元素 — 默认情况下，其 display 值是 inline — 但其在视口中的默认宽度和高度由嵌入的视频定义。

¥The <video> element is a replaced element — its display value is inline by default — but its default width and height in the viewport is defined by the video being embedded.

<video> 的样式没有什么特殊的考虑；一个常见的策略是给它一个 display 值 block，以便更容易定位、大小等，然后根据需要提供样式和布局信息。视频播放器样式基础知识 提供了一些有用的样式技术。

¥There are no special considerations for styling <video>; a common strategy is to give it a display value of block to make it easier to position, size, etc., and then provide styling and layout information as required. Video player styling basics provides some useful styling techniques.

¥Adding subtitles and other timed text tracks

可以通过嵌套 <track> 元素以声明方式添加字幕、隐藏式字幕、章节标题等的定时文本轨道。曲目在 Web 视频文本轨道文件格式 (WebVTT)（.vtt 文件）中指定。

¥Timed text tracks for subtitles, closed captions, chapter headings, and so on, can be added declaratively by nesting the <track> element. The tracks are specified in Web Video Text Tracks File Format (WebVTT) (.vtt files).

例如，下面的 HTML 包含文件 "captions.vtt"，如果用户启用了字幕，该文件将用于在视频上叠加隐藏字幕。

¥For example, the HTML below includes the file "captions.vtt", which will be used to overlay closed captions on the video if captions are enabled by the user.

<video controls src="video.webm">
  <track default kind="captions" src="captions.vtt" />
</video>

也可以使用 WebVTT API 以编程方式添加定时文本轨道。

¥Timed text tracks can also be added programmatically using the WebVTT API.

¥Detecting track addition and removal

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

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

HTMLMediaElement.audioTracks

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

HTMLMediaElement.videoTracks

A VideoTrackList 包含媒体元素的所有音轨。向此对象添加 addtrack 监听器，以便在元素中添加视频轨道时收到通知。

HTMLMediaElement.textTracks

A TextTrackList 包含媒体元素的所有文本轨道（用于字幕、隐藏式字幕等）。向此对象添加 addtrack 监听器，以便在元素中添加文本轨道时收到通知。

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

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

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

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

elem.audioTracks.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.

¥Server support for video

如果服务器上未正确设置视频的 MIME 类型，则视频可能不会显示或显示包含 X 的灰色框（如果启用了 JavaScript）。

¥If the MIME type for the video is not set correctly on the server, the video may not show or show a gray box containing an X (if JavaScript is enabled).

如果你使用 Apache Web Server 提供 WebM 视频，则可以通过将视频文件类型扩展名添加到 video/webm MIME 类型（最常见的 WebM 文件扩展名是 .webm）来解决此问题。为此，请在 /etc/apache 中编辑 mime.types 文件或在 httpd.conf 中使用 AddType 配置指令：

¥If you use Apache Web Server to serve WebM videos, you can fix this problem by adding the video file type extensions to the video/webm MIME type (the most common WebM file extension is .webm). To do this, edit the mime.types file in /etc/apache or use the AddType configuration directive in httpd.conf:

AddType video/webm .webm

你的网络主机可能会为新技术的 MIME 类型配置更改提供简单的界面，直到自然发生全局更新。

¥Your web host may provide an easy interface to MIME type configuration changes for new technologies until a global update naturally occurs.

¥Accessibility

视频应提供准确描述其内容的字幕和文字记录（有关如何实现这些内容的更多信息，请参阅 向 HTML 视频添加字幕和副标题）。字幕可以让听力损失的人在播放视频时理解视频的音频内容，而文字记录可以让需要额外时间的人能够以适合他们的速度和格式查看音频内容。

¥Videos should provide both captions and transcripts that accurately describe their content (see Adding captions and subtitles to HTML video for more information on how to implement these). Captions allow people who are experiencing hearing loss to understand a video's audio content as the video is being played, while transcripts allow people who need additional time to be able to review audio content at a pace and format that is comfortable for them.

值得注意的是，虽然你可以为纯音频媒体添加字幕，但你只能在 <video> 元素中播放音频时这样做，因为元素的视频区域用于呈现字幕。这是在视频元素中播放音频很有用的特殊场景之一。

¥It's worth noting that while you can caption audio-only media, you can only do so when playing audio in a <video> element since the video region of the element is used to present the captions. This is one of the special scenarios in which it's useful to play audio in a video element.

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

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

除了口头对话之外，字幕和文字记录还应该标识传达重要信息的音乐和音效。这包括情绪和语气：

¥In addition to spoken dialog, subtitles and transcripts should also identify music and sound effects that communicate important information. This includes emotion and tone:

14
00:03:14 --> 00:03:18
[Dramatic rock music]

15
00:03:19 --> 00:03:21
[whispering] What's that off in the distance?

16
00:03:22 --> 00:03:24
It's… it's a…

16 00:03:25 --> 00:03:32
[Loud thumping]
[Dishes clattering]

字幕不应遮挡视频的主要主题。可以使用 align VTT 提示设置 来定位它们。

¥Captions should not obstruct the main subject of the video. They can be positioned using the align VTT cue setting.

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

¥Examples

¥Single source

此示例在激活时播放视频，为用户提供浏览器的默认视频控件来控制播放。

¥This example plays a video when activated, providing the user with the browser's default video controls to control playback.

HTML

<!-- Simple video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a href="https://archive.org/details/BigBuckBunny_124">download it</a>
  and watch it with your favorite video player!
</video>

结果

¥Result

在视频开始播放之前，poster 属性中提供的图片将显示在其位置。如果浏览器不支持视频播放，则显示后备文本。

¥Until the video starts playing, the image provided in the poster attribute is displayed in its place. If the browser doesn't support video playback, it displays the fallback text.

¥Multiple sources

此示例建立在上一个示例的基础上，为媒体提供了三种不同的来源；这样，无论浏览器支持哪种视频编解码器，都可以观看视频。

¥This example builds on the last one, offering three different sources for the media; this allows the video to be watched regardless of which video codecs are supported by the browser.

HTML

<!-- Using multiple sources as fallbacks for a video tag -->
<!-- 'Elephants Dream' by Orange Open Movie Project Studio, licensed under CC-3.0, hosted by archive.org -->
<!-- Poster hosted by Wikimedia -->
<video
  width="620"
  controls
  poster="https://upload.wikimedia.org/wikipedia/commons/e/e8/Elephants_Dream_s5_both.jpg">
  <source
    src="https://archive.org/download/ElephantsDream/ed_hd.avi"
    type="video/avi" />
  <source
    src="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    type="video/mp4" />

  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a
    href="https://archive.org/download/ElephantsDream/ed_1024_512kb.mp4"
    download="ed_1024_512kb.mp4">
    download the MP4
  </a>
  and watch it with your favorite video player!
</video>

结果

¥Result

尝试第一个 AVI。如果无法播放，则尝试 MP4。如果不支持视频元素，则会显示一条后备消息，但如果所有源均失败，则不会显示一条后备消息。

¥First AVI is tried. If that can't be played, MP4 is tried. A fallback message is displayed if the video element isn't supported, but not if all sources fail.

某些媒体文件类型允许你使用 codecs 参数作为文件类型字符串的一部分来提供更具体的信息。一个相对简单的例子是 video/webm; codecs="vp8, vorbis"，它表示该文件是 WebM 视频，视频使用 VP8，音频使用 沃尔比斯。

¥Some media file types let you provide more specific information using the codecs parameter as part of the file's type string. A relatively simple example is video/webm; codecs="vp8, vorbis", which says that the file is a WebM video using VP8 for its video and Vorbis for audio.

¥Technical summary

¥See also

• 网络媒体类型和格式指南
  • 媒体容器格式（文件类型）
  • 网络视频编解码器指南
  • 网络音频编解码器指南
• 在框架内定位图片并调整其大小：object-position 和 object-fit
• <audio>
• 使用 HTML 音频和视频
• 使用画布操作视频
• 为 Ogg 媒体配置服务器