The block video macro enables you to embed videos into your documents. You can embed self-hosted videos or videos shared on popular video hosting sites such as Vimeo and YouTube.
30-60 Minutes to read
Asciidoc macro video
The block video macro video::
enables to embed videos into documents. The Macro can be used to embed self-hosted videos or videos shared on popular video hosting sites such as Vimeo and YouTube.
Syntax
The video formats the macro supports is given by the formats supported by the browser. HTML5 has brought sanity to video support in the browser by adding a dedicated video tag element <video>
and by introducing several standard audio formats, widely supported across all modern browsers.
For a canonical list of supported web video formats and their interaction with modern browsers, see the documentation at Mozilla Developer Supported Media Formats.
Recommendations Where appropriate, we recommend using a video hosting service like Vimeo or YouTube 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 Vimeo and YouTube videos for details about how to serve videos from these services.
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.
video::video-file.mp4[width=640,start=60,opts=autoplay]
You can include a caption on the video using the title attribute.
.A walkthrough of the product
video::video-file.mp4[]
Vimeo and YouTube
The video macro supports embedding videos from external video hosting services like Vimeo and YouTube. The AsciiDoc processor, specifically the converter, 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.
video::67480300[vimeo]
video::RvRhUHTV_8k[youtube]
When embedding a YouTube video, you can specify a playlist to associate with the video using the list
attribute. The playlist must be specified by its ID.
video::RvRhUHTV_8k[youtube,list=PLDitloyBcHOm49bxNhvGgg0f9NRZ5lSaP]
Instead of using the list
attribute, you can specify the ID of the playlist after the video ID in the target, separated by a slash.
video::RvRhUHTV_8k/PLDitloyBcHOm49bxNhvGgg0f9NRZ5lSaP[youtube]
Alternatively, you can create a dynamic, unnamed playlist by listing several additional video IDs in the playlist
attribute.
video::RvRhUHTV_8k[youtube,playlist="_SvwdK_HibQ,SGqg_ZzThDU"]
Instead of using the playlist
attribute, you can create a dynamic, unnamed playlist by listing several video IDs in the target separated by a comma.
video::RvRhUHTV_8k,_SvwdK_HibQ,SGqg_ZzThDU[youtube]
Attributes
To control video, following attributes are available.
Attribute | Value|s | Example |
---|---|---|
| User defined text |
|
| A URL to an image to show until the user plays or seeks. |
|
| User-defined size in pixels. |
|
| User-defined size in pixels. |
|
| User-defined playback start time in seconds. |
|
| User-defined playback end time in seconds. |
|
| The YouTube theme to use for the frame. |
|
| The language used in the YouTube frame. |
|
| The ID of a playlist to associate with a YouTube video. |
|
| Additional video IDs to create a dynamic YouTube playlist. |
|
|
|
|
HTML 5 video element
The HTML video element <video>
embeds a media player which supports video playback into the document.
You can use video element |
Examples
The example shows simple usage of the <video> element. In a similar manner to the image element <img>
. 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, whether we want to show the browser’s default video controls, etc.
<video controls
src="/assets/video/gallery/html5/video1.mp4"
poster="/assets/video/gallery/video1-poster.jpg">
Your browser does not support the video tag.
</video>
Attributes
Like all other HTML elements, this element supports the global attributes.
Attribute | Description | ||||
---|---|---|---|---|---|
| Boolean attribute. If specified, the video automatically begins to play back as soon as the browser finished loading the data.
| ||||
| If this attribute is present, the browser will offer controls to allow the user to control video playback, including volume, seeking, and pause or resume playback. | ||||
| The controlslist attribute, when specified, helps the browser select what controls to show for the video element whenever the browser shows its own set of controls (that is, when the controls attribute is specified). The allowed values are nodownload, nofullscreen and noremoteplayback. Use the disablepictureinpicture attribute if you want to disable the Picture-In-Picture mode (and the control). | ||||
| This enumerated attribute indicates whether to use CORS to fetch the related video. CORS-enabled resources can be reused in the canvas element
When not present, the resource is fetched without a CORS request (i.e without sending the Origin: HTTP header), preventing its non-tainted use in canvas elements <canvas>. If invalid, it is handled as if the enumerated keyword anonymous was used. See CORS settings attributes for additional information. | ||||
| Prevents the browser from suggesting a Picture-in-Picture context menu or to request Picture-in-Picture automatically in some cases. | ||||
| The height of the video’s display area, in CSS pixels (absolute values only; no percentages). | ||||
| Boolean attribute. When specified, the browser will automatically seek back to the start upon reaching the end of the video. | ||||
| Boolean attribute. Indicates the default setting of the audio contained in the video. If set, the audio will be initially silenced. Its default value is false, meaning that the audio will be played when the video is played. | ||||
| Boolean attribute. Indicates that the video is to be played inline, that is within the element’s playback area. Note that the absence of this attribute does not imply that the video will always be played in fullscreen. | ||||
| A URL for an image to be shown while the video is downloading. If this attribute isn’t specified, nothing is displayed until the first frame is available, then the first frame is shown as the poster frame. | ||||
| This enumerated attribute is intended to provide a hint to the browser about what the author thinks will lead to the best user experience regarding what content is loaded before the video is played. It may have one of the following values:
| ||||
| The URL of the video to embed. This is optional; you may instead use the source element | ||||
| The width of the video’s display area, in CSS pixels (absolute values only; no percentages). |
Events
Decription is to be added.
Event Name | Fired When |
---|---|
| The input buffer of a |
The browser can play the media, but estimates that not enough data has been loaded to play the media up to its end without having to stop for further buffering of content. | |
The browser estimates it can play the media up to its end without stopping for content buffering. | |
The rendering of an | |
The | |
The media has become empty; for example, this event is sent if the media has already been loaded (or partially loaded), and the | |
Playback has stopped because the end of the media was reached. | |
An error occurred while fetching the media data, or the type of the resource is not a supported media format. | |
The first frame of the media has finished loading. | |
The metadata has been loaded. | |
Fired when the browser has started to load the resource. | |
Playback has been paused. | |
Playback has begun. | |
Playback is ready to start after having been paused or delayed due to lack of data. | |
Fired periodically as the browser loads a resource. | |
The playback rate has changed. | |
A seek operation completed. | |
A seek operation began. | |
The user agent is trying to fetch media data, but data is unexpectedly not forthcoming. | |
Media data loading has been suspended. | |
The time indicated by the | |
The volume has changed. | |
Playback has stopped because of a temporary lack of data. |