HTML 5 Video · Playback Video files

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.

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.

Set attributes for local video playback

video::video-file.mp4[width=640,start=60,opts=autoplay]

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

Add a caption to a video

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

Embed a Vimeo video

video::67480300[vimeo]

Embed a YouTube video

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.

Embed a YouTube video with a playlist

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.

Embed a YouTube video with a playlist in the target

video::RvRhUHTV_8k/PLDitloyBcHOm49bxNhvGgg0f9NRZ5lSaP[youtube]

Alternatively, you can create a dynamic, unnamed playlist by listing several additional video IDs in the playlist attribute.

Embed a YouTube video with a dynamic playlist

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.

Embed a YouTube video with a dynamic playlist in the target

video::RvRhUHTV_8k,_SvwdK_HibQ,SGqg_ZzThDU[youtube]

Attributes

To control video, following attributes are available.

Table 1. Attributes for the Asciidoc audio macro
Attribute	Value\|s	Example
`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 Vimeo (`vimeo`) or YouTube (`youtube`).
`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.
`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 BCP 47 language tag (typically a two-letter language code, like `en`).
`list`	The ID of a playlist to associate with a YouTube video.	`list=PLabc123`. Only applies to YouTube videos.
`playlist`	Additional video IDs to create a dynamic YouTube playlist.	`playlist="video-abc,video-xyz"`. IDs must be separated by commas. Therefore, the value must be enclosed in double quotes. Only applies to YouTube videos.
`options` (`opts`)	`autoplay`, `loop`, `modest`, `nocontrols`, `nofullscreen`, `muted`	`opts="autoplay,loop"`. The controls are enabled by default. The `modest` option enables modest branding for a YouTube video.

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 <video> for audio content as well, but the audio element <audio> may provide a more appropriate user experience.

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.

MP4 video

<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

autoplay

Boolean attribute. If specified, the video automatically begins to play back as soon as the browser finished loading the data.

For most browsers, autoplay can not be used in combination with controls. The attribute controls take precedence.

Sites that automatically play audio or video 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 the guide autoplay for additional information about how to properly use autoplay.

controls

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.

controlslist

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

crossorigin

This enumerated attribute indicates whether to use CORS to fetch the related video. CORS-enabled resources can be reused in the canvas element <canvas> without being tainted. The allowed values are:

anonymous: Sends a cross-origin request without a credential. In other words, it sends the Origin: HTTP header without a cookie, X.509 certificate, or performing HTTP Basic authentication. If the server does not give credentials to the origin site (by not setting the Access-Control-Allow-Origin: HTTP header), the resource will be tainted, and its usage restricted.
use-credentials: Sends a cross-origin request with a credential. In other words, it sends the Origin: HTTP header with a cookie, a certificate, or performing HTTP Basic authentication. If the server does not give credentials to the origin site (through Access-Control-Allow-Credentials: HTTP header), the resource will be tainted and its usage restricted.

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.

disablepictureinpicture

Prevents the browser from suggesting a Picture-in-Picture context menu or to request Picture-in-Picture automatically in some cases.

height

The height of the video’s display area, in CSS pixels (absolute values only; no percentages).

loop

Boolean attribute. When specified, the browser will automatically seek back to the start upon reaching the end of the video.

muted

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.

playsinline

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.

poster

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.

preload

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:

none: Indicates that the video should not be preloaded.
metadata: Indicates that only video metadata (e.g. length) is fetched.
auto: Indicates that the whole video file can be downloaded, even if the user is not expected to use it. empty string: Synonym of the auto value.

The default value is different for each browser. The spec advises it to be set to metadata.

The autoplay attribute has precedence over preload. If autoplay is specified, the browser would obviously need to start downloading the video for playback.
The specification does not force the browser to follow the value of this attribute; it is a mere hint.

src

The URL of the video to embed. This is optional; you may instead use the source element <source> within the video block to specify the video to embed.

width

The width of the video’s display area, in CSS pixels (absolute values only; no percentages).

Events

Decription is to be added.

Table 3. Supported events for the HTML 5 video
Event Name	Fired When
`audioprocess` Deprecated	The input buffer of a `ScriptProcessorNode` is ready to be processed.
`canplay`	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.
`canplaythrough`	The browser estimates it can play the media up to its end without stopping for content buffering.
`complete`	The rendering of an `OfflineAudioContext` is terminated.
`durationchange`	The `duration` attribute has been updated.
`emptied`	The media has become empty; for example, this event is sent if the media has already been loaded (or partially loaded), and the `load()` method is called to reload it.
`ended`	Playback has stopped because the end of the media was reached.
`error`	An error occurred while fetching the media data, or the type of the resource is not a supported media format.
`loadeddata`	The first frame of the media has finished loading.
`loadedmetadata`	The metadata has been loaded.
`loadstart`	Fired when the browser has started to load the resource.
`pause`	Playback has been paused.
`play`	Playback has begun.
`playing `	Playback is ready to start after having been paused or delayed due to lack of data.
`progress`	Fired periodically as the browser loads a resource.
`ratechange`	The playback rate has changed.
`seeked`	A seek operation completed.
`seeking`	A seek operation began.
`stalled`	The user agent is trying to fetch media data, but data is unexpectedly not forthcoming.
`suspend`	Media data loading has been suspended.
`timeupdate`	The time indicated by the `currentTime` attribute has been updated.
`volumechange`	The volume has changed.
`waiting`	Playback has stopped because of a temporary lack of data.