音频和视频

音频宏语法

块级音频宏允许你将音频流嵌入到你的文档中。你可以嵌入浏览器支持的自托管音频文件。

AsciiDoc支持的音频格式取决于输出格式，例如生成HTML时浏览器支持的格式。虽然这一度是一件棘手的事情，但HTML 5通过增加专用的https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio[<audio>^]元素并引入几种标准音频格式，为浏览器中的音频支持带来了合理性。这些格式现在被广泛支持，横跨各种浏览器和系统。

对于受支持的Web音频格式及其与现代浏览器交互的规范列表，请参阅https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility[Mozilla Developer Supported Media Formats^]文档。

基本音频文件包含

Unresolved directive in audio-and-video.adoc - include::example$audio.adoc[tag=basic]

你可以通过宏上的额外属性来控制音频设置。例如，你可以使用`start`属性来偏移播放的开始时间，使用`autoplay`选项来启用自动播放功能。

为本地音频播放设置属性

Unresolved directive in audio-and-video.adoc - include::example$audio.adoc[tag=attrs]

你可以使用title属性在音频上方添加标题。

给音频添加一个标题

Unresolved directive in audio-and-video.adoc - include::example$audio.adoc[tag=caption]

视频宏语法

块视频宏允许你将视频嵌入到你的文档中。你可以嵌入自托管的视频或者在Vimeo和YouTube等流行的视频托管网站上共享的视频。

AsciiDoc支持的视频格式取决于输出格式，例如在生成HTML时浏览器支持的格式。虽然这曾经是一项不稳定的任务，但HTML 5通过添加专用的https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video[<video>^]元素并引入几种标准视频格式，为浏览器中的视频支持带来了稳定性。这些格式现在被广泛支持，跨越了各种浏览器和系统。

为了获取支持的网络视频格式及其与现代浏览器的互动的权威列表，请参阅https://developer.mozilla.org/en-US/docs/Web/HTML/Supported_media_formats#Browser_compatibility[Mozilla Developer Supported Media Formats^]文档。

为浏览器提供视频推荐的建议

在适当的情况下，我们推荐使用Vimeo或YouTube这样的视频托管服务来在在线文档中提供视频。这些服务专门针对流媒体视频传输至浏览器进行了优化，可以在考虑到观看视频设备的硬件、软件和网络能力的情况下，提供尽可能低的延迟。

Vimeo甚至提供了一种白标模式，因此用户并不会意识到视频是通过其服务提供的。

请参阅Vimeo和YouTube视频了解如何从这些服务中提供视频的详细信息。

基础视频文件包含

Unresolved directive in audio-and-video.adoc - include::example$video.adoc[tag=base]

您可以通过宏的附加属性来控制视频设置。例如，您可以使用`start`属性来偏移播放的起始时间，并使用`autoplay`选项来启用自动播放功能。

为本地视频播放设置属性

Unresolved directive in audio-and-video.adoc - include::example$video.adoc[tag=attr]

你可以使用title属性在视频上添加标题。

给视频添加标题

Unresolved directive in audio-and-video.adoc - include::example$video.adoc[tag=caption]

Vimeo和YouTube视频

视频宏允许嵌入来自像Vimeo和YouTube这样的外部视频托管服务的视频。AsciiDoc处理器，特别是转换器，会自动生成正确的代码以将视频嵌入到HTML输出中。

要使用此功能，请将视频ID放入宏目标中，并将托管服务的名称放入第一个位置属性。

嵌入一个Vimeo视频

Unresolved directive in audio-and-video.adoc - include::example$video.adoc[tag=vimeo]

嵌入一个YouTube视频

Unresolved directive in audio-and-video.adoc - include::example$video.adoc[tag=youtube]

当嵌入一个YouTube视频时，您可以使用`list`属性指定一个与视频关联的播放列表。播放列表必须通过其ID来指定。

嵌入一个带有播放列表的YouTube视频

Unresolved directive in audio-and-video.adoc - include::example$video.adoc[tag=youtube-with-list]

您可以在目标中的视频ID后面指定播放列表的ID，并用斜杠分隔，而不是使用`list`属性。

在目标中嵌入一个带播放列表的YouTube视频

Unresolved directive in audio-and-video.adoc - include::example$video.adoc[tag=youtube-with-list-in-target]

另外，您可以通过在`playlist`属性中列出几个额外的视频ID来创建一个动态的、未命名的播放列表。

嵌入一个带有动态播放列表的YouTube视频

Unresolved directive in audio-and-video.adoc - include::example$video.adoc[tag=youtube-with-playlist]

你可以通过在目标中列出用逗号分隔的多个视频 ID，来创建一个动态的、无需指定名称的播放列表，而不是使用 playlist 属性。

在目标中嵌入一个带有动态播放列表的YouTube视频

Unresolved directive in audio-and-video.adoc - include::example$video.adoc[tag=youtube-with-playlist-in-target]

音频和视频属性及选项

Table 1. 音频属性和值
属性	值	例子	备注
`title`	用户定义的文本	`.Ocean waves`
`start`	用户定义的播放开始时间，以秒为单位。	`start=30`
`end`	用户定义的播放结束时间，以秒为单位。	`end=90`
`options` (`opts`)	`autoplay`, `loop`, `controls`, `nocontrols`	`opts="autoplay,loop"`	默认情况下启用controls值

Table 2. 视频属性和值
属性	值	示例语法	注释
`title`	用户自定义文本	`.An ocean sunset`
`poster`	播放或寻找前展示的图片的URL地址。	`poster=sunset.jpg`	可以作为第一个位置性（未命名）属性进行指定。在提及托管于Vimeo (`vimeo`) 或 YouTube (`youtube`)的视频时，还用于指定服务。
`width`	用户自定义的尺寸，单位为像素。	`width=640`	可以作为第二个位置性（未命名）属性进行指定。
`height`	用户自定义的尺寸，单位为像素。	`height=480`	可以作为第三个位置性（未命名）属性进行指定。
`start`	用户自定义的播放开始时间，单位为秒。	`start=30`
`end`	用户自定义的播放结束时间，单位为秒。	`end=90`
`theme`	YouTube框架使用的主题。	`theme=light`	有效值为`dark`（默认）和`light`。
`lang`	YouTube框架中使用的语言。	`lang=fr`	一个BCP 47语言标签（通常是两个字母的语言代码，如 `en`）。
`list`	与YouTube视频关联的播放列表ID。	`list=PLabc123`	仅适用于YouTube视频。
`playlist`	附加的视频ID，用于创建动态YouTube播放列表。	`playlist="video-abc,video-xyz"`	ID必须以逗号分隔。因此，值必须用双引号括起来。仅适用于YouTube视频。
`options` (`opts`)	`autoplay`, `loop`, `modest`, `nocontrols`, `nofullscreen`, `muted`	`opts="autoplay,loop"`	控件默认启用。 `modest`选项为YouTube视频开启朴素品牌。