The video sitemap — Hydrogen SEO

A video sitemap tells Google which of your pages carry a video, and describes each video: its thumbnail, title, description, player URL and duration. Hydrogen SEO builds one for you by scanning your posts for embedded and self-hosted videos, looking up each video's details from its provider in the background, and publishing the result at /video-sitemap.xml. It is off by default; switch it on if video is part of how people find your content.

Turn it on

Open Hydrogen SEO → Sitemap in wp-admin.
In the Sitemap Status card, switch on Video Sitemap.
A panel appears with three parts:
- Include: the post types to scan for videos. Posts and Pages are selected by default.
- Found: scan progress while a scan runs, then "N posts with videos". Use Rescan to scan again.
- Advanced: Custom fields — meta keys, one per line, that hold a video URL or embed code (an ACF oEmbed field, for example) — and an optional YouTube API key.

Turning the video sitemap on starts a background scan of your existing posts, so the sitemap fills in without you opening each post.

Where it lives

The video sitemap is served at /video-sitemap.xml. Larger sites get further pages at /video-sitemap2.xml, /video-sitemap3.xml and so on. This is the same naming Rank Math uses, so a site that moves over keeps the video sitemap URLs it already submitted to Search Console. Each page lists up to 500 posts (fewer if your entries per sitemap setting is lower), since one post can carry several videos.

You do not need to submit it separately: it is listed in your sitemap index automatically, and submitting the index covers it. See submit your sitemap to Google.

Which videos are detected

Providers:

YouTube: watch, youtu.be, embed, shorts, live, youtube-nocookie and mobile URLs
Vimeo, including unlisted and private links that carry a hash
Dailymotion, including dai.ly short links
TED
VideoPress
Wistia
Self-hosted video files (mp4, m4v, webm, ogv, mov and similar)

Where Hydrogen SEO looks:

Post content: iframes (including lazy-loaded ones that use data-src), Gutenberg embed and video blocks, [video] and [embed] shortcodes, video URLs inside Divi and WPBakery shortcodes, and bare video URLs on a line of their own. A plain link to a video in the middle of text is not counted — it is a link, not an embedded video.
Page builder data: Elementor (only the source actually selected in a video widget), Bricks, Beaver Builder, Oxygen, Themify and Cornerstone.
Custom fields: the meta keys you list under Advanced → Custom fields.
VideoObject schema added to the post in the Hydrogen SEO metabox. Its values override the ones detected automatically, so schema is how you correct a title, description or thumbnail for one video.

How video details are filled in

For each video, Hydrogen SEO looks up its details from the provider in the background: oEmbed for YouTube, Vimeo, TED and Wistia, and the Dailymotion and VideoPress APIs. When a YouTube API key is set, the YouTube Data API also supplies the description, duration, upload date and view count.

The results are stored with the post. The sitemap itself never calls a provider while it is being served, so it stays fast however many videos you have. Lookups are cached per video for a week, and a lookup that failed is retried after an hour.

When posts are scanned

On save: every save of a published post in the chosen post types rescans it.
Page builder saves: when builder data is saved, the post is rescanned shortly afterwards.
Background scan: turning the video sitemap on, or changing its post types or custom fields, starts a background scan of existing posts through WP-Cron. While the Sitemap screen is open, the admin screen drives the scan faster.
Imports: posts saved during an import (WP_IMPORTING) are left to the background scan rather than scanned one by one.

What each entry contains

Per video, the sitemap outputs:

Tag	Notes
`thumbnail_loc`	The video's thumbnail
`title`	The video's title
`description`	Up to 2,048 characters
`player_loc` / `content_loc`	The embed URL, the video file URL, or both
`duration`	In seconds, 1 to 28,800
`expiration_date`	When known
`view_count`	When known
`publication_date`	When the video was published
`tag`	The post's tags or the schema's keywords, at most 32
`category`	The post's first category
`family_friendly`
`restriction`	From the schema's `regionsAllowed`
`requires_subscription`
`uploader`	The post author, linked to their author page when it is on the same host
`live`

Where the provider and schema give nothing, Hydrogen SEO falls back to the post title, the excerpt, the featured image and the post date.

Google requires a thumbnail, title, description and a player or content URL for every video. An entry that is still missing one of those after the fallbacks is left out rather than submitted invalid.

What is left out

Posts set to noindex, and post types set to noindex
Password-protected posts
Posts whose canonical URL points to another page
Posts you switch to Exclude from video sitemap in the post's SEO panel (Robots Meta section), stored as the hydrogen_seo_post_meta_video_sitemap_exclude meta key

For developers

Filter	Arguments	Use
`hydrogen_seo_video_sitemap_detected_videos`	`$detected`, `$post`	Change the videos detected in a post
`hydrogen_seo_video_sitemap_builder_meta_keys`	`$keys`	Add page builder meta keys to scan
`hydrogen_seo_video_sitemap_post_videos`	`$videos`, `$post`	Change a post's final video entries
`hydrogen_seo_video_sitemap_exclude_post`	`$excluded`, `$post`	Leave a post out of the video sitemap
`hydrogen_seo_video_sitemap_xml`	`$xml`, `$page`	Change the raw XML of a video sitemap page

Full entries are in the filters reference.

With Hydrogen AI

Hydrogen AI can check and run the scan through the scan-sitemap-videos ability (status, start and step), and change video sitemap settings through the video object of update-sitemap-settings. The YouTube API key is never shown to the agent.

FAQ

Why is a video missing from the video sitemap?

Usually because Google's required fields could not be filled — most often there is no thumbnail and the post has no featured image — or because the post has not been scanned yet. Set a featured image or add VideoObject schema, then click Rescan. Also check that the post type is selected under Include and the post is not noindex, password-protected or canonicalised elsewhere.

Do I need a YouTube API key?

No. Without one, YouTube details come from oEmbed. Add a key if you want the description, duration, upload date and view count filled in from YouTube itself.

Does serving the video sitemap slow my site down?

No. Provider lookups happen in the background and are stored with the post; serving the sitemap only reads what is already stored.

I link to a YouTube video in my text. Why is it not listed?

A plain link is not an embedded video, so it is not counted. Put the URL on a line of its own, or use an embed block, and it will be detected.