<video>

A video is a recording of moving visual images.

Usage information

The <video> element is modeled on the HTML5 <video> element.

A video resource can be referenced by @href, @keyref, and nested <media-source> elements.

Playback behaviors such as auto-playing, looping, and muting are determined by attributes. When not specified, the default behavior is determined by the user agent that is used to present the media.

Rendering expectations

The video resource typically is rendered in the main flow of the content.

Processors SHOULD scale the video resource when values are provided for the @height and @width attributes. The following expectations apply:
  • If a height value is specified and no width value is specified, processors SHOULD scale the width by the same factor as the height.
  • If a width value is specified and no height value is specified, processors SHOULD scale the height by the same factor as the width.
  • If both a height value and width value are specified, implementations MAY ignore one of the two values when they are unable to scale to each direction using different factors.

When a video resource cannot be rendered in a meaningful way, processors SHOULD render the contents of the <fallback> element, if it is present.

Content model

<desc> ?, <longdescref> ?, <fallback> ?, <video-poster> ?, <media-source> *, <media-track> *, <foreign> *

In order
  1. Optional <desc>
  2. Optional <longdescref>
  3. Optional <fallback>
  4. Optional <video-poster>
  5. Zero or more <media-source>
  6. Zero or more <media-track>
  7. Zero or more <foreign>

Attributes

The following attributes are available on this element: universal attributes, @format, @href, @keyref, @scope, and the attributes defined below.

@autoplay
Specifies whether the resource automatically plays when it is presented. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@controls
Specifies whether the presentation of the resource includes user interface controls. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@height
Indicates the vertical dimension for the resulting display. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.
@loop
Specifies whether the resource loops when played. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@muted
Specifies whether the resource is muted. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@tabindex
Specifies whether the video resource can be focused and where it participates in sequential keyboard navigation. See @tabindex in the HTML specification (WHATWG version).
@width
Indicates the horizontal dimension for the resulting display. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.

For this element, the following considerations apply:

  • The @format attribute specifies the MIME type for the resource. This attribute enables processors to avoid loading unsupported resources. If @format is not specified and @keyref is specified, the effective type for the key named by the @keyref attribute is used as the value. If an explicit @format is not specified on either the <video> element or key definition, processors can use other means, such the URI file extension, to determine the effective MIME type of the resource.
  • The @href attribute specifies the absolute or relative URI of the video resource. If @href is specified, also specify @format.

The following attributes are available on this element: universal attributes and the attributes defined below.

@autoplay
Specifies whether the resource automatically plays when it is presented. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@controls
Specifies whether the presentation of the resource includes user interface controls. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@format (link-relationship attributes)
Specifies the format of the resource that is referenced. See The format attribute for detailed information on supported values and processing implications.
@height
Indicates the vertical dimension for the resulting display. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.
@href (link-relationship attributes)
Specifies a reference to a resource. See The href attribute for detailed information on supported values and processing implications.
@keyref
Specifies a key name that acts as a redirectable reference based on a key definition within a map. See The keyref attribute for information on using this attribute.
@loop
Specifies whether the resource loops when played. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@muted
Specifies whether the resource is muted. The following values are recognized: true, false, and -dita-use-conref-target . The default value is true.
@scope (link-relationship attributes)
Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.

See The scope attribute for detailed information on supported values and processing implications.

@tabindex
Specifies whether the video resource can be focused and where it participates in sequential keyboard navigation. See @tabindex in the HTML specification (WHATWG version).
@width
Indicates the horizontal dimension for the resulting display. The value of this attribute is a real number expressed in decimal notation, optionally followed by a unit of measure. The following units of measurement are supported: cm, em, in, mm, pc, pt, and px (centimeters, ems, inches, millimeters, picas, points, and pixels, respectively). The default unit is px (pixels). Possible values include:5, 5in, and 10.5cm.

Examples

This section is non-normative.

This section contains examples of how the <video> element can be used.

Example 1. Example of a <video> element that uses direct addressing

In the following code sample, a video resource is referenced using direct addressing. The @format attribute specifies the MIME type of the video. 

<video href="video.mp4" format="video/mp4"/>
Example 2. Example of a <video> element that uses indirect addressing

In the following code sample, the video resource is addressed using a key reference:

<video keyref="video"/>

The URI and the MIME type do not need to be specified on the <video> element, since they are specified on the key definition:

<keydef keys="video" href="video.mp4" format="video/mp4"/>
Example 3. Example of a <video> element with multiple formats

In the following code sample, <media-source> elements are used to specify the different video formats that are available.

<video>
  <media-source href="video.mp4" format="video/mp4"/>
  <media-source href="video.ogg" format="video/ogg"/>
  <media-source href="video.webm" format="video/webm"/>
</video>
Example 4. Example of a <video> element with multiple formats and multilingual subtitles

The following code sample defines multiple presentational details for a video that is available in multiple formats. The video is referenced using key reference and a fallback image is provided for use when the video cannot be displayed.

<video height="300px"
                loop="false"
                muted="false"
                width="400px">
  <desc>A video illustrating this procedure.</desc>
  <fallback>
    <image href="video-not-available.png">
      <alt>This video cannot be displayed.</alt>
    </image>
  </fallback>
  <video-poster keyref="demo1-video-poster"/>
  <!-- Multiple formats, referenced via key. The key definition 
       specifies both the URI and the MIME type -->
  <media-source keyref="demo1-video-mp4"/>
  <media-source keyref="demo1-video-ogg"/>
  <media-source keyref="demo1-video-webm"/>
  <!-- Subtitle tracks in English, French and German.
       Each key definition provides a URI and sets type="subtitles". -->
  <media-track srclang="en" keyref="demo1-video-subtitles-en"/>
  <media-track srclang="fr" keyref="demo1-video-subtitles-fr"/>
  <media-track srclang="de" keyref="demo1-video-subtitles-de"/>
</video>