The essentials

Quick reference

One focused task per row. Jump to the related section for complete, working examples.

UseSyntaxExamples
Embed controlled video<video controls width="960" height="540" src="demo.mp4"> </video>View examples
Embed controlled audio<audio controls src="episode.mp3"></audio>View examples
Show a poster image<video controls poster="poster.jpg" src="demo.mp4"> </video>View examples
Offer alternate formats<source src="demo.webm" type="video/webm">View examples
Provide legacy fallback content<video controls> <a href="demo.mp4">Download the video</a> </video>View examples
Add captions<track kind="captions" src="captions-en.vtt" srclang="en" label="English" default>View examples
Add translated subtitles<track kind="subtitles" src="subtitles-pt.vtt" srclang="pt-BR" label="Português">View examples
Link a transcript<a href="transcript.html">Read the transcript</a>View examples
Hint metadata loading<video controls preload="metadata" src="demo.mp4"> </video>View examples
Defer media loading<audio controls preload="none" src="episode.mp3"> </audio>View examples
Request inline playback<video controls playsinline src="demo.mp4"></video>View examples
Request muted autoplay<video autoplay muted playsinline src="ambient.mp4"> </video>View examples
Size video responsivelyvideo { max-inline-size: 100%; block-size: auto; }View examples
Reserve media spacevideo { aspect-ratio: 16 / 9; inline-size: 100%; }View examples
Pause with JavaScriptdocument.querySelector('video').pause();View examples
Request playbackawait video.play();View examples
Seek to a timevideo.currentTime = 30;View examples

Native media elements provide keyboard-aware controls and format negotiation without a custom player. Supply controls, dimensions, text alternatives, and honest loading hints; treat autoplay as an exceptional enhancement and never make essential information available only through sound or moving images.

Step by step

Detailed examples

01

Start with native, user-controlled playback

controls exposes the browser's playback UI and should be the default unless an equally accessible custom interface is fully implemented. Width and height attributes reserve the video's intrinsic ratio before loading; CSS can then scale it. A poster should represent the content and must not contain essential text unavailable elsewhere.

Native video and audio players
<video controls width="960" height="540" poster="poster.jpg" src="demo.mp4">
  <a href="demo.mp4">Download the demonstration video</a>
</video>

<audio controls src="episode.mp3">
  <a href="episode.mp3">Download the episode audio</a>
</audio>
Back to quick reference ↑
02

Offer sources in preference order

When src is absent on the media element, source children provide candidates in document order. A correct type lets the browser skip formats it knows it cannot decode without fetching them, though codec support can vary within a container. Put source elements before track elements. Child fallback content serves user agents without video-element support; place a normal link outside the element when modern users also need a dependable download option.

Two video candidates and an adjacent download
<video controls width="960" height="540" poster="poster.jpg">
  <source src="demo.webm" type="video/webm">
  <source src="demo.mp4" type="video/mp4">
  <a href="demo.mp4">Download the MP4 video</a>
</video>
<p><a href="demo.mp4" download>Download the video</a></p>
Back to quick reference ↑
03

Provide captions, subtitles, and transcripts

Captions include dialogue plus meaningful sounds for people who cannot hear the audio; subtitles primarily translate dialogue. A subtitles track requires srclang, and labels help users choose among tracks. WebVTT text tracks do not replace a well-structured transcript, which supports reading at another pace and can include descriptions of important visual information.

Captioned video with a transcript
<figure>
  <video controls width="960" height="540">
    <source src="interview.webm" type="video/webm">
    <track kind="captions" src="captions-en.vtt" srclang="en" label="English" default>
    <track kind="subtitles" src="subtitles-pt.vtt" srclang="pt-BR" label="Português">
  </video>
  <figcaption><a href="interview-transcript.html">Read the interview transcript</a></figcaption>
</figure>
Back to quick reference ↑
04

Treat loading and autoplay as hints, not guarantees

preload is a browser hint: metadata is a balanced default for many videos, while none helps large media lists avoid eager fetching. Autoplay is commonly blocked and can be disruptive even when muted; never depend on it for essential content. If motion starts automatically, provide an obvious way to pause it and respect reduced-motion preferences in the surrounding experience.

Conservative foreground media
<video controls playsinline preload="metadata" width="960" height="540" src="lesson.mp4"></video>
<audio controls preload="none" src="episode.mp3"></audio>
Decorative muted loop with a static fallback
<video autoplay muted loop playsinline preload="metadata" poster="ambient.jpg" aria-hidden="true">
  <source src="ambient.webm" type="video/webm">
</video>

Note: Do not use aria-hidden when the media communicates information.

Back to quick reference ↑
05

Reserve space and scale without distortion

HTML dimensions communicate the resource's intended aspect ratio and reduce layout movement. CSS max-inline-size and block-size:auto let a video shrink proportionally, while aspect-ratio can reserve space for a known ratio. Avoid forcing unrelated width and height values that stretch the picture, and ensure native controls remain large enough to operate.

A responsive media frame
.media-frame {
  max-inline-size: 60rem;
  margin-inline: auto;
}

.media-frame video {
  display: block;
  inline-size: 100%;
  block-size: auto;
  aspect-ratio: 16 / 9;
  background: #000;
}
Back to quick reference ↑
06

Enhance playback through the media API

HTMLMediaElement exposes play, pause, currentTime, duration, volume, and events. play returns a promise because playback can be rejected by policy or fail during loading; handle that result instead of assuming success. Custom controls must retain names, focus order, keyboard operation, state communication, and caption access, so native controls are usually safer.

A separate replay button
<video id="lesson" controls preload="metadata" src="lesson.mp4"></video>
<button type="button" id="replay">Replay from the start</button>
<script>
  const video = document.querySelector('#lesson');
  document.querySelector('#replay').addEventListener('click', async () => {
    video.currentTime = 0;
    try {
      await video.play();
    } catch (error) {
      console.warn('Playback was not started', error);
    }
  });
</script>
Back to quick reference ↑

Local code tester

Try HTML media markup

Edit a native media figure with fallback text and a transcript link; substitute local media URLs to test playback.

Runs in your browser
Preview

Keep exploring

More HTML cheat sheets

HTML · Media and Embedding15 quick references

HTML iframes Cheat Sheet

Embed external documents with accessible iframe titles, responsive sizing, lazy loading, sandbox restrictions, permissions policy, and safe cross-window messaging.

Open cheat sheet

Sources and further reading

References

Authoritative documentation used to verify and expand this cheat sheet.

  1. WHATWGHTML Standard: Video, audio, track, and media elementshtml.spec.whatwg.org
  2. MDN Web DocsHTML video and audiodeveloper.mozilla.org
  3. MDN Web DocsAccessible multimediadeveloper.mozilla.org
  4. World Wide Web ConsortiumWebVTT: The Web Video Text Tracks Formatw3.org

Help us improve

Found a typo or missing example?

Tell us what would make this cheat sheet clearer, more complete, or more useful.

Share feedback