Recommended Free Tools
Choose a WordPress oEmbed hook based on when you need to change the embed: before a provider request, before fetched HTML is cached, when cached markup is rendered, or while WordPress converts provider data into HTML. To add an unsupported service, register its URL pattern and endpoint with wp_oembed_add_provider().
Choose the hook that matches the change
The key difference between the filters is timing. That determines whether your change is stored in the embed cache, applied for each render, or avoids a provider request altogether.
| Hook or function | When it runs | Best fit | Cache and performance effect |
|---|---|---|---|
pre_oembed_result |
Before WordPress makes an oEmbed HTTP request | Return replacement HTML for a known URL without contacting its provider | Short-circuits retrieval; use when you can identify the URL and supply the desired result. WordPress reference |
oembed_result |
After provider HTML is returned, before WordPress caches it | Normalize or transform provider HTML once per fetched response | The transformed result is what WordPress stores in the _oembed_* post-meta cache. WordPress reference |
embed_oembed_html |
When cached embed HTML is rendered | Wrap or adjust output at display time | Runs on every page load for every embed URL, so render-time work can affect performance. WordPress reference |
oembed_dataparse |
As WordPress converts provider data into HTML | Change conversion rules or support another response type | Works at the parsing stage rather than solely editing already-rendered cached markup. WordPress reference |
wp_oembed_add_provider() |
Provider registration | Register a service’s URL pattern and oEmbed endpoint | Adds a provider match; it does not itself transform returned HTML. WordPress reference |
Register an unsupported oEmbed provider
Use wp_oembed_add_provider( $format, $provider, $regex ) to associate a URL pattern with the provider’s oEmbed endpoint. The format can contain wildcards; set the third argument when the format is a regular expression. Keep the pattern narrow so it matches only the URLs your integration supports. See the function reference and the oEmbed handbook.
Register the provider early enough to participate in WordPress’s provider list. If wp_oembed_add_provider() is called before plugins_loaded, WordPress stores the registration early for use by the oEmbed system. Function reference
#1 Best Overall
Transform provider HTML before caching
Use oembed_result when a change should be made to the provider’s returned HTML before WordPress saves it in the _oembed_* post-meta cache. This is generally the appropriate stage for a repeatable normalization of fetched provider output: WordPress stores the transformed result, rather than requiring the same transformation at each render. Filter reference
Change cached markup at render time
Use embed_oembed_html when the desired modification belongs at output time. The filter receives the cached HTML, the URL, shortcode attributes, and the post ID, so a callback can consider the embed’s context. Its cost is that it runs on every page load for every embed URL. Keep this work lightweight, and avoid a universal wrapper that assumes all providers return video or share one aspect ratio; embeds can have different content and dimensions. Filter reference
Replace an embed before WordPress contacts the provider
Use pre_oembed_result to short-circuit retrieval when a known URL should return your own HTML. This is useful when you already know the replacement and do not need a provider response. It changes the retrieval path rather than modifying provider HTML after it arrives. Filter reference
Extend how provider responses become HTML
WordPress’s WP_oEmbed::data2html() parses four core response types: photo, video, rich, and link. Video and rich responses use valid provider-supplied HTML. A photo response requires a URL, width, and height; a link response becomes an anchor using the title. Use oembed_dataparse when you need to alter these conversion rules or add support for another type, rather than merely changing markup after conversion. Parser reference
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Account for provider trust and sanitization
WordPress’s discovery and sanctioned-provider paths have different trust rules. The Advanced Administration Handbook explains that discovery has been supported since WordPress 4.4, but content from non-whitelisted sites is subject to stricter filtering: HTML and video are filtered to links, blockquotes, and iframes, then sanitized and sandboxed with additional security restrictions. Providers on the sanctioned oembed_providers list are trusted to embed richer content, including iframes, video, JavaScript, and arbitrary HTML. WordPress oEmbed handbook · Provider registration reference
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.“As of version 4.4, WordPress supports oEmbed discovery, but has severe limitations on what type of content can be embedded via non-whitelisted sites.” — WordPress Developer Resources, Advanced Administration Handbook
A practical decision sequence
- Need to add a service? Register its URL pattern and endpoint with
wp_oembed_add_provider(). - Need to return your own HTML without a remote request? Use
pre_oembed_result. - Need to normalize what the provider returned before it is stored? Use
oembed_result. - Need to change cached output as it is displayed? Use
embed_oembed_html, keeping its per-render performance cost in mind. - Need to change conversion by response type? Use
oembed_dataparse.
Test against the precise URL patterns and response types you intend to support. A provider-specific match and a response-type-aware transformation are safer than treating every embed as interchangeable.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
