The <video> Element

Technical Summary

Definition / Categories

Item	Definition
Meaning	Plays a media resource with video data and, optionally, associated audio and text tracks
Categories	Flow, phrasing, embedded, and palpable content; interactive content when the controls attribute is present
Context	Where embedded content is expected
Content model	The order of source, track, and transparent content depends on whether src is present
Tag omission	Neither the start tag nor the end tag is omissible
Content attributes	Global attributes, shared media attributes, poster, playsinline, width, height, and loading
DOM interface	HTMLVideoElement, which inherits from HTMLMediaElement

Content model and resource selection

The permitted order of child content depends on whether the src attribute is present. In either case, transparent content must not contain descendant media elements.

Condition	Child content model
src is present	Zero or more track elements, followed by transparent content. Do not include child source elements.
src is absent	Zero or more source elements, zero or more track elements, then transparent content

<video controls width="640" height="360" poster="/media/lesson.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 user agent does not support the video element.
</video>

A child source in a media element identifies an alternative media resource. When a type is available, a user agent can skip a candidate with an unsupported type before fetching it. Playback is not guaranteed: container, codec, profile, network, CORS, and server behavior can all matter. The selection model for source inside picture is different.

Transparent content inside video is for user agents that do not support the video element. It is not guaranteed to appear when a user agent supports the element but cannot fetch its resource. Provide a separate direct link or transcript if people need an alternative after a loading failure.

Element-specific and shared attributes

Attribute	Normative role	Boundary
src	URL of the media resource	When present, it is the resource-selection entry point instead of child source elements
poster	Representative image to show when video data is unavailable	Not captions, a transcript, or an alternative description
controls	Requests that the user agent show its controls	Appearance, operable controls, and AAM exposure are implementation and platform observations
preload	Author hint about the amount of buffering likely to be needed	none, metadata, and auto do not establish the amount actually fetched
autoplay	Requests automatic playback when the algorithm's conditions are met	User agents are not required to support autoplay and may account for user preferences
muted / loop	Initial muted state / return to the beginning after playback ends	Read the current state separately from the content attribute
playsinline	Encourages video to be shown in the element's playback area	Does not fix fullscreen behavior or UI across all user agents
width / height	Dimension attributes for the playback area	Distinct from the natural dimensions of the video resource
crossorigin / loading	Affect request mode / loading deferral	Record fetch results separately for the resource, poster, and text tracks

poster is used as the image represented by the element while video data is unavailable. videoWidth and videoHeight return the resource's natural dimensions and return zero before that data is available. Do not conflate them with the CSS size of the playback area or the poster image dimensions.

Network state and ready state

networkState describes the stage of resource selection and fetching; readyState describes how much media data is currently available. They describe different state machines and should not be collapsed into one simple loading percentage.

API	What it observes	Values and boundaries
networkState	Resource selection and data fetching	NETWORK_EMPTY, NETWORK_IDLE, NETWORK_LOADING, NETWORK_NO_SOURCE
readyState	Availability of media data for the current position	From HAVE_NOTHING through HAVE_ENOUGH_DATA; values can be skipped
currentTime / duration	Playback position / media resource length on the timeline	Handle seeking, ranges, unknown duration, and end conditions separately. An unbounded live resource can have an infinite duration.
Media events	Changes in fetching, metadata, buffering, playback, and seeking	Examples include loadedmetadata, canplay, waiting, playing, seeking, and seeked; they are not one fixed sequence

preload is a hint; inspect it together with the browser cache, resource, network, and user-agent policy. Events are processed as media element tasks, and the ready state is not required to pass through every intermediate value.

Playback requests and autoplay

HTMLMediaElement.play() returns a Promise. It can reject with NotAllowedError when playback is not allowed or NotSupportedError when the resource is not supported. Do not infer that playback started merely because the method was called; observe the Promise and media events.

const video = document.querySelector('video');

video.play().then(() => {
  console.log('playback started');
}).catch((error) => {
  console.log('playback did not start:', error.name);
});

The HTML Standard does not require user agents to support autoplay. It also encourages authors to let users override autoplay and to consider waiting for an explicit request. Record implementation policy, muted conditions, user activation, and OS settings separately from normative claims.

Text tracks and video accessibility

track associates an external timed text track with a media element. Its kind can be subtitles, captions, descriptions, chapters, or metadata. Cues have start and end times on the media timeline. Examine the meaning of each kind, default, and language selection separately; not every text track is a caption track.

HTML-AAM maps the computed role of video to html-video and defines platform accessibility API mappings. Exposure of the controls when controls is present can differ by platform. The normative mapping, browser accessibility tree, platform API, and assistive-technology output are distinct evidence.

Providing HTML track elements and making the media content meet accessibility requirements are separate questions. WCAG 2.2 time-based media criteria have conditions that depend on whether content is prerecorded or live, what information is conveyed by audio and video, and whether the media is clearly a text alternative.

DOM Interface

API	Summary	Condition or boundary
width / height	Element dimension attributes	Distinct from CSS-computed rendered dimensions
videoWidth / videoHeight	Natural dimensions of the video resource	Zero while media data is unavailable
poster / playsInline	Poster URL / inline-playback IDL surface	Separate reflected attribute values from rendering and playback behavior
play() / pause()	Request playback / pause	play() returns a Promise; handle success and rejection
currentTime / duration / seekable	Timeline, playback position, and seekable ranges	Do not assume finite duration or seeking from the beginning for live and streaming resources
networkState / readyState / error	Resource fetching and current playback readiness	Record these as separate state surfaces
textTracks / addTextTrack()	Associated text tracks and API for adding one	Distinguish child track elements, script-added tracks, and tracks sourced from the resource

Fact / Evidence

Claims from the HTML Standard, HTML-AAM, and WCAG are paired with scope and source locations. Browser observations are kept in the Implementation Evidence section; unrun items are not treated as reviewed.

Evidence

1. HTML Standard: The video element — categories, content model, attributes, poster, and HTMLVideoElement
2. HTML Standard: Media elements — resource selection, network / ready states, playback, seeking, events, and autoplay
3. HTML Standard: The track element and timed text tracks — track kinds, cues, language, default selection, and text track API
4. HTML Accessibility API Mappings: video — computed role and platform control mappings
5. WCAG 2.2 SC 1.2.2 and SC 1.2.3 — prerecorded synchronized-media criteria and their conditions
6. Web Platform Tests: the-video-element and media-elements — test discovery entry points; no results are claimed here

Implementation Evidence

Browser behavior, WPT, and accessibility-tree observations are registered separately from normative claims. Selected measurements and tests have been run; each row records its environment and remaining verification scope.

Measurement fixture: video-v1 was created and used in one Chrome 153 environment to observe video loading, playback, captions, and the Accessibility Tree. Eight selected WPT files were run. See the evidence rows below for details. Cross-browser coverage, the full test suites, and platform accessibility mappings remain incomplete.

Record codec, media file, network, user activation, user preference, browser, OS, native controls, platform APIs, and assistive technology separately. Do not generalize one environment's results to all implementations.

Coverage / Open Issues

• ReviewedMeaning, categories, context, src-dependent content models, major attributes, poster, and HTMLVideoElement
• ReviewedNormative entry points for shared resource selection, network / ready states, playback promises, and event model
• ReviewedText tracks, HTML-AAM, and source locations and scope boundaries for WCAG time-based media criteria
• OpenCross-browser comparison of source fallback, codecs, network / ready state, events, poster, and dimensions in Chrome, Firefox, and Safari
• OpenImplementation comparisons for autoplay policy, user activation, preload, lazy loading, CORS, range requests, media fragments, and live streams
• Opencross-browser measurements, full WPT directories, all HTML-AAM platform mappings, OS accessibility APIs and assistive technology, and caption rendering / selection differences

This is initial coverage. It records normative entry points and sources; it does not claim complete verification of video, playback in every browser, or that every media resource meets accessibility criteria.

Related surface

For a beginner-friendly guide to playback controls, captions, poster images, and descriptions, see video in Yugien. Compare its shared media model with the audio element. Parent-specific candidate selection is covered by the source element; see the track element for timed-text requirements, WebVTT, and its own evidence scope. Compare image-resource selection in picture and img; see iframe for the boundary between media playback and embedding another document.