How to Use the video Element

The HTML video element plays video inside a page. Give viewers controls they can use to start and stop playback, and provide captions or descriptions for information carried by the audio or pictures.

The answer first

Minimal example

<video controls width="640" height="360" poster="/media/lesson-poster.jpg">
  <source src="/media/lesson.webm" type="video/webm">
  <source src="/media/lesson.mp4" type="video/mp4">
  <track kind="captions" src="/media/lesson.en.vtt"
         srclang="en" label="English captions" default>
  This browser cannot play the video element.
</video>
<p>If playback fails, <a href="/media/lesson.mp4">open the video file</a>.</p>

The URLs are examples. A real page needs the video and caption files at those locations. The direct link is outside the video element so viewers have another option if playback fails.

Offer video resources

You can set one resource with the src attribute on video, or list candidates in child source elements. When you provide candidates, include their type so the browser can skip a format it does not support when possible.

Supported video formats and audio or video codecs vary across browsers and devices. Multiple candidates do not guarantee playback in every environment. Check the files you serve on the browsers and devices your audience uses.

Text inside video is mainly for older browsers that do not support the video element. It is not guaranteed to appear when a video file fails to load, so provide a separate link or text description when people need one.

Add controls

Adding controls asks the browser to show controls such as play, pause, volume, and playback position. Their appearance and details vary across browsers and devices.

If you omit controls and build your own, check that people can use every control with a keyboard, that assistive technology can identify its name and state, and that focus remains visible. A control that only looks like a button may not be operable.

Set a poster and dimensions

poster gives the URL of a representative image to show before video data is available. It previews the video; it does not replace captions or a description of the video's content.

Set width and height to values with an aspect ratio close to the video. This helps reserve the playback area before the video loads and can reduce layout shifts. Preserve the video's aspect ratio when CSS changes its displayed size.

Provide captions and descriptions

A track element adds timed text such as captions or audio descriptions. Use kind="captions" for text that includes dialogue and meaningful sounds. Use kind="subtitles" for text that lets viewers read dialogue, for example in another language.

Timed text can use a format such as WebVTT, which records cues with their timing. Set srclang for the track's language and label for the name shown to viewers. Captions burned into the picture may not be switchable or searchable.

For the difference between captions and subtitles, plus the conditions for each attribute, see the track element guide.

If important information appears only in the picture, consider audio description or text that describes both the audio and visuals in sequence. Which alternative is required depends on the content, whether it is live or prerecorded, and the accessibility criteria that apply.

Do not rely on autoplay

autoplay asks for playback to start automatically when the page loads. Browsers may block automatic playback based on user settings or other playback conditions. JavaScript's video.play() can also fail when playback is not allowed.

Do not make automatic playback a requirement for using the page; give viewers controls they can use to start playback. preload is also a hint about loading, not a promise that the whole video will be downloaded in advance.

Common mistakes

• Providing neither controls nor usable custom controls.
• Assuming autoplay or muted playback works the same way in every browser.
• Using a poster image as if it were captions or an alternative for the video's content.
• Captioning dialogue but leaving out sounds that matter to understanding the video.
• Expecting fallback text inside video to appear whenever loading fails.

Check it in Atlas

For the video content model, source selection, shared media states, the play() promise, HTML-AAM, and implementation evidence, see video in Yugien Atlas. For parent-specific source candidates and attributes, see the source guide or source in Atlas. For track requirements, WebVTT, and unrun evidence, see track in Atlas. For the related audio element, see audio. For images, see the img element; for choosing images by display conditions or format, see the picture element.