Audio and Video

Video macro syntax

The block video macro enables you to embed videos into your documentation. You can embed self-hosted videos or videos shared on popular video hosting sites such as YouTube and Vimeo.

The video formats Asciidoctor supports is dictated by the formats supported by the browser (and, in turn, the user’s system). While this was once a precarious ordeal, HTML5 has brought sanity to video support in the browser by adding a dedicated <video> element and by introducing several standard video formats. Those formats are now widely supported across browsers and systems.

For a canonical list of supported web video formats and their interaction with modern browsers, see the Mozilla Developer Supported Media Formats documentation.

A recommendation for serving video to browsers

Where appropriate, we recommend using a video hosting service like YouTube or Vimeo to serve videos in online documentation. These services specialize in streaming optimized video to the browser, with the lowest latency possible given hardware, software, and network capabilities of the device viewing the video.

Vimeo even offers a white label mode so users aren’t made aware that the video is being served through its service.

See YouTube and Vimeo videos for details about how to serve videos from these services.

Example 1. Basic video file include

video::video_file.mp4[]

You can control the video settings using additional attributes on the macro. For instance, you can offset the start time of playback using the start attribute and enable autoplay using the autoplay option.

Example 2. Set attributes for local video playback

video::video_file.mp4[width=640,start=60,end=140,opts=autoplay]

You can include a caption on the video using the title attribute.

Example 3. Add a caption to a video

.A walkthrough of the product
video::video_file.mp4[]

YouTube and Vimeo videos

The video macro supports embedding videos from external video hosting services like YouTube and Vimeo. Asciidoctor automatically generates the correct code to embed the video in the HTML output.

To use this feature, put the video ID in the macro target and the name of the hosting service in the first positional attribute.

Example 4. Embed a YouTube video

video::rPQoq7ThGAU[youtube]

Example 5. Embed a Vimeo video

video::67480300[vimeo]

Audio and video attributes and options

Audio attributes and values
Attribute	Value(s)	Example Syntax	Notes
`options`	`autoplay`, `loop`, `controls`, `nocontrols`	`audio::ocean_waves.mp3[options="autoplay,loop"]`	The controls value is enabled by default

Video attributes and values
Attribute	Value(s)	Example Syntax	Notes
`title`	User defined text	`.An ocean sunset`
`poster`	A URL to an image to show until the user plays or seeks.	`poster=sunset.jpg`	Can be specified as the first positional (unnamed) attribute. Also used to specify the service when referring to a video hosted on YouTube (`youtube`) or Vimeo (`vimeo`).
`width`	User-defined size in pixels.	`width=640`	Can be specified as the second positional (unnamed) attribute.
`height`	User-defined size in pixels.	`height=480`	Can be specified as the third positional (unnamed) attribute.
`options`	`autoplay`, `loop`, `modest`, `nocontrols`, `nofullscreen`	`opts="autoplay,loop"`	The controls are enabled by default. The `modest` option enables modest branding for a YouTube video.
`start`	User-defined playback start time in seconds.	`start=30`
`end`	User-defined playback end time in seconds.	`end=90`
`theme`	The YouTube theme to use for the frame.	`theme=light`	Valid values are `dark` (the default) and `light`.
`lang`	The language used in the YouTube frame.	`lang=fr`	A two-letter language code or fully specified locale.