Video Metadata
Reference video HTML attributes and VideoObject fields, with copyable captions, poster, player, media URL, and chapter examples.
Use a native <video> element or a recognizable embedded player on the watch page. Include a meaningful title, description, and poster outside the player as well as accurate metadata in the initial HTML.
| Field or attribute | Purpose | Best practice |
|---|---|---|
| poster | Selects the image shown before playback. | Use a stable, crawlable, high-quality image that represents this specific video. Keep it consistent with thumbnailUrl and og:video:image when used. |
| preload | Hints how much media to fetch before playback. | Use metadata for most pages or none for data-sensitive experiences. Avoid forcing large downloads with auto. |
| controls | Exposes native playback controls. | Keep controls available unless a custom player provides equivalent accessible behavior. |
| playsinline | Allows inline playback on mobile platforms. | Use for normal inline viewing; do not force unexpected fullscreen playback. |
| width / height | Declares the media's intrinsic dimensions. | Reserve the correct aspect ratio to reduce layout shift and make the player responsive with CSS. |
| <track> | Adds captions, subtitles, chapters, or descriptions. | Provide accurate captions for accessibility. Also publish a readable transcript when the content is substantial. |
| name | VideoObject title; required for Google's video structured data. | Use a unique title for each video and match the visible page title. |
| thumbnailUrl | VideoObject thumbnail; required for Google's video structured data. | Use an absolute, stable thumbnail URL that crawlers can fetch. |
| uploadDate | VideoObject publication time; required for Google's video structured data. | Use ISO 8601 with a timezone. Do not confuse the upload date with the recording date. |
| description | Summarizes the video for machines and viewers. | Write a unique description that reflects the actual spoken and visual content. |
| duration | Declares media duration. | Use ISO 8601 duration syntax, such as PT8M42S. |
| contentUrl | Points to the actual media bytes. | Use a supported media file at a stable URL, not the watch-page URL. Allow authorized crawlers to fetch it when video features are desired. |
| embedUrl | Points to the player for the specific video. | Use the player URL from the iframe src, not the canonical watch page and not the media file. |
| hasPart / Clip | Identifies meaningful chapters with timestamps. | Give each Clip a descriptive name, startOffset, endOffset when useful, and a working timestamp deep link. |
| expires / regionsAllowed | Describes availability constraints. | Include only when true and keep availability rules synchronized with actual playback. |
A native video element can expose the poster, captions, dimensions, and fallback link without making playback a prerequisite for discovering the page:
<video
controls
preload="metadata"
playsinline
width="1280"
height="720"
poster="https://cdn.example.com/guides/brand-video-poster.jpg"
>
<source
src="https://cdn.example.com/guides/brand-video.mp4"
type="video/mp4"
/>
<track
kind="captions"
src="https://cdn.example.com/guides/brand-video-en.vtt"
srclang="en"
label="English"
default
/>
<a href="https://cdn.example.com/guides/brand-video.mp4"
>Download the video</a
>
</video>Add VideoObject JSON-LD to the watch page. This example includes Google's required fields plus common recommended fields and a chapter:
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "How to Build a Brand-Compliant Video Workflow",
"description": "A practical walkthrough of capture, review, rendering, and publishing.",
"thumbnailUrl": ["https://cdn.example.com/guides/brand-video-poster.jpg"],
"uploadDate": "2026-10-14T15:30:00-05:00",
"duration": "PT8M42S",
"contentUrl": "https://cdn.example.com/guides/brand-video.mp4",
"embedUrl": "https://player.example.com/embed/brand-video",
"hasPart": [
{
"@type": "Clip",
"name": "Setting up brand controls",
"startOffset": 95,
"endOffset": 214,
"url": "https://example.com/guides/brand-video?t=95"
}
]
}Keep every value consistent with the visible page and other metadata. Validate the implementation with Google's Rich Results Test and monitor video indexing in Search Console. Continue with Video Sitemaps to expose the same content through a video discovery feed.
Watch page
Player
Media bytes
"contentUrl": "https://cdn.example.com/guides/brand-video.mp4",
"embedUrl": "https://player.example.com/embed/brand-video"