EP YouTube
EP YouTube embeds YouTube videos on your PageMotor site without the privacy and performance costs of a plain <iframe>. The visitor sees a lightweight thumbnail. YouTube only loads when they click play.
Published by ElmsPark Studio.
Overview
Section titled “Overview”PageMotor has no YouTube embedding of its own. The nearest thing is the content editor’s Media button, which pastes a plain YouTube <iframe> into the page, and that iframe loads as soon as the page does. That:
- Drops YouTube cookies in the visitor’s browser before they’ve decided to watch anything.
- Ships ~600KB of YouTube player JavaScript per video on the page.
- Tanks Lighthouse scores on any page with more than one video.
- Pings
i.ytimg.com(a Google CDN) for the player poster image.
EP YouTube replaces all of that with a thumbnail placeholder. The heavy iframe is only built when the visitor clicks play, and on that click the iframe loads from youtube-nocookie.com so YouTube does not store tracking cookies unless the visitor actually interacts with the player.
Optional: enable Self-Host Thumbnails to download each video’s thumbnail to your own server on first pageview. After that, no request to Google ever happens until the visitor clicks play.
Requirements
Section titled “Requirements”- PageMotor 0.7 or later
- EP Suite base class (bundled)
Installation
Section titled “Installation”- Download
ep-youtube.zipfrom the EP Suite downloads page. - Upload via Plugins → Manage Plugins. Activate.
- Open Plugin Settings → EP YouTube.
- Defaults are sensible. No-Cookie Mode is on, default aspect ratio is 16:9, default thumbnail resolution is Standard. Most sites need nothing else.
- Insert your first video by adding
[youtube id="dQw4w9WgXcQ"]to any page or post.
The shortcode accepts a bare YouTube ID, a youtu.be/ link, a youtube.com/watch?v= URL, an /embed/ URL, or a /shorts/ URL — paste whichever you have.
[youtube id="dQw4w9WgXcQ"][youtube id="https://youtu.be/dQw4w9WgXcQ"][youtube id="https://www.youtube.com/watch?v=dQw4w9WgXcQ"]All four forms produce the same output.
Optional attributes
Section titled “Optional attributes”| Attribute | Example | Effect |
|---|---|---|
title | title="A Day on the Lake" | Heading overlay on the thumbnail, gradient-down to clear, line-clamped to 2 lines. Matches YouTube’s idle-state title bar so the visitor has context before clicking play. |
aspect | aspect="4:3" | Override the default aspect ratio. Accepts 16:9, 4:3, 1:1, 21:9, 9:16, or any WIDTH:HEIGHT. |
thumb | thumb="https://example.com/poster.jpg" | Use your own thumbnail image instead of YouTube’s. |
alt | alt="Demo of the new feature" | Alt text for the thumbnail image. |
params | params="start=30&end=120" | Extra YouTube player parameters appended to the iframe URL. Use ampersand-separated key=value pairs. |
class | class="extend" | Extra CSS class on the .youtube container, for skin “break out” or other layout hooks. |
wrap | wrap="container" | Wrap the video in an outer <div> with this class. |
Settings
Section titled “Settings”- Default Aspect Ratio. Used when the shortcode does not specify an
aspectattribute. 16:9 by default. The plugin supports 16:9, 4:3, 1:1, 21:9, and 9:16 (vertical / Shorts). - Default Thumbnail Resolution. YouTube serves thumbnails at three tiers. Standard (
sddefault.jpg) is always available and works for every video. High Quality (hqdefault.jpg) is slightly sharper. Maximum (maxresdefault.jpg) is the sharpest but is missing for many older or custom-thumbnail videos — if your thumbnails go blank, drop back to Standard. - No-Cookie Mode (on by default). Loads the player iframe from
youtube-nocookie.cominstead ofyoutube.com. YouTube does not store tracking cookies after the visitor clicks play, unless they interact with the player itself. Recommended. - Self-Host Thumbnails (off by default). Downloads each video’s thumbnail to
user-content/ep-youtube-thumbs/on first pageview, so subsequent visitors only ever see your domain in their network tab until they click play. Adds about 10–50KB of storage per cached video. Best for sites where you want zero Google requests even on the idle pageview state.
How the lazy-load works
Section titled “How the lazy-load works”The shortcode renders a placeholder that is a link to the video on YouTube (<a class="youtube" href="https://www.youtube.com/watch?v=VIDEO_ID" data-embed="VIDEO_ID">), plus a play-button arrow and optionally a title overlay. The plugin’s sitewide JavaScript paints a thumbnail into the placeholder (from YouTube’s CDN, your custom URL, or your self-hosted cache).
When the visitor clicks the placeholder, or presses Enter or Space on it, the JS builds the YouTube iframe with autoplay=1, swaps it in for the placeholder, and the video starts playing immediately. One click, same as a default YouTube embed, but no cookies and no heavy assets until the click happens. The player is named after your title (or alt), so screen readers announce what it is.
Keyboard users reach each video with Tab and see a focus ring around it. If the visitor’s browser runs no JavaScript at all, the placeholder still works as a plain link to the video on YouTube.
Using a video on an HTML document page
Section titled “Using a video on an HTML document page”An HTML document page is sent to the browser exactly as you wrote it, so the shortcode and this plugin’s styles and scripts never reach it. For those pages, open EP Suite → YouTube → Use on an HTML page, paste the video link, add a title if you like, and press Copy for an HTML page. Paste the result into your page.
The snippet is one <script> tag plus the video box, and carries everything it needs. Tick Host the thumbnail on this site and the page makes no request to Google at all until the visitor presses play.
Build each video in the panel. The script tag only needs to be on a page once, so for a second video paste only its box line. But build that box line in the panel too, for every video: building it there is what saves its thumbnail on your site. If you copy a box line and change the video ID, that video has no saved thumbnail and its box starts empty. From version 1.1.1 the site then fetches and saves the missing thumbnail the first time the page is viewed, as long as Self-Host Thumbnails is on, and the box fills in.
AI assistants connected to your site can build the same snippet with the embed-snippet action.
Title overlay vs autoplay
Section titled “Title overlay vs autoplay”YouTube’s own iframe shows a title bar over the poster when the player is idle (before play). EP YouTube uses autoplay=1 on click, which skips that idle state, so YouTube’s title bar never appears. To restore the title context, use the title shortcode attribute:
[youtube id="qIQReeJoAWY" title="A Day on the Lake"]This paints your own heading overlay on the thumbnail with the same gradient-down-to-clear styling YouTube uses, line-clamped to 2 lines so long titles don’t overrun. The overlay is removed when the iframe takes over.
Backwards compatibility
Section titled “Backwards compatibility”If you’ve ported a Thesis/Focus site to PageMotor and the original Thesis YouTube Box markup is still in your content (<div class="youtube" data-embed="...">), EP YouTube’s frontend JavaScript picks those up and lazy-loads them too, with the same keyboard support. No content rewrite required.
This is how a number of ElmsPark migrations have brought across YouTube videos from Thesis without touching the post HTML.
Coordination with EP GDPR
Section titled “Coordination with EP GDPR”EP YouTube is GDPR-compliant on its own. The visitor’s click on the thumbnail is itself an act of explicit consent under GDPR, so no separate cookie-banner gate is required for the iframe.
If EP GDPR is also installed, the two plugins agree on the privacy story. The privacy policy generated by EP GDPR can mention the EP YouTube no-cookie default, and the site’s overall compliance dashboard reflects the embed setup.
Troubleshooting
Section titled “Troubleshooting”“My thumbnail is blank”
Section titled ““My thumbnail is blank””YouTube doesn’t have a maxresdefault.jpg for every video — particularly older uploads or videos with non-default custom thumbnails. If you’ve set Default Thumbnail Resolution to Maximum, try dropping back to Standard. The JS also auto-falls-back from Max to Standard on image-load error.
“The video is playing but there’s no title shown”
Section titled ““The video is playing but there’s no title shown””EP YouTube’s autoplay-on-click flow skips YouTube’s idle-state title overlay. Use the title shortcode attribute to paint your own heading over the thumbnail before click.
“I want the YouTube branding visible”
Section titled ““I want the YouTube branding visible””The params shortcode attribute is passed through to the iframe URL. To re-enable YouTube branding, pass params="modestbranding=0". To show related videos on the end screen, omit the default rel=0 — actually you can’t, but you can override with params if you have a specific need.
“How do I match my old <iframe> embeds for the visual diff?”
Section titled ““How do I match my old <iframe> embeds for the visual diff?””Add the title attribute to match the heading overlay a vanilla YouTube iframe shows in its idle state. The poster image will be the same since both pull from i.ytimg.com. The difference: yours loads YouTube on every pageview, EP YouTube only loads it after the click.
Credit
Section titled “Credit”The lazy-load mechanism is inspired by Chris Pearson’s Thesis YouTube Box (DIYthemes, GPL v3.0, 2019). EP YouTube is a clean-room PageMotor implementation with the same architecture plus two privacy upgrades: the youtube-nocookie.com iframe host by default, and the optional thumbnail self-hosting.
Feedback and corrections
Section titled “Feedback and corrections”For a quick question about this plugin, EP Support inside your admin is the fastest option. The chat widget sits on every EP plugin settings page and knows which one you’re on, with starter questions and links preloaded for that exact screen.
For anything bigger — a bug report, a feature request, or a “how do I…” that needs a real reply — open a ticket at help.elmspark.com. A real person, helped by AI, writes the reply. Usually within a few hours. Tickets don’t disappear into the void.
Changelog
Section titled “Changelog”- The No-Cookie Mode box now shows what your site is really doing, and you can switch it off. Until now the box could show as unticked while every video still loaded from youtube-nocookie.com, and unticking it and saving changed nothing. After this update the box is ticked on every site that was using No-Cookie Mode (which is every site), and unticking it and saving now really does turn it off. Your videos keep loading from youtube-nocookie.com unless you choose otherwise.
- A bigger thumbnail now replaces a smaller one. With Self-Host Thumbnails on, a video’s thumbnail was saved once and then kept, so switching Default Thumbnail Resolution to Maximum, or building a snippet at a bigger size, still showed the first, smaller copy. Now the bigger size replaces it, under the same address, so thumbnails already on your pages pick it up too. When YouTube has no bigger image for a video, the plugin remembers that and stops asking.
- A video box copied from another one fills in its own thumbnail. On an HTML page, if you copied a video’s box line and changed the video ID, that video had no saved thumbnail, so its box showed nothing. Now your site fetches and saves the missing thumbnail the first time the page is viewed (with Self-Host Thumbnails on), and the box fills in. The visitor’s browser still makes no request to Google before they press play. The settings panel and the documentation now also say to build each video in the panel, which is still the best way.
- Protection against misuse of thumbnail saving. Visitors’ browsers can ask your site to save a video’s thumbnail, so that request now has generous limits: per visitor, per day for the whole site, and on the total size of saved thumbnails. Thumbnails that are already saved never count, so a busy page is never held back, and your own builds in the settings panel are never limited.
- Saving settings through an AI assistant no longer clears them. Changing one setting over the API or MCP used to wipe this plugin’s other settings. Now it changes only the one you name.
- Videos now work with the keyboard and with screen readers. Each video box can be reached with Tab and played with Enter or Space, shows a clear focus ring, and is announced as a button that plays the named video. Once playing, the player carries the video’s title, so screen reader users know what it is. Before this release the box could only be clicked with a mouse.
- Still a link when JavaScript is off. The box is now a link to the video on YouTube, so a visitor whose browser blocks scripts can still reach it. With scripts on, nothing changes: the video still plays in place and nothing loads from YouTube until it is pressed.
- New: use a video on an HTML document page. PageMotor sends an HTML document page to the browser exactly as written, so shortcodes and this plugin’s styles never reach it. The new Use on an HTML page section in the settings builds a snippet to paste instead, and copies it for you: one script tag plus the video box, with everything the page needs. Tick the option to host the thumbnail on your own site, and the page makes no request to Google at all until the visitor presses play.
- New for AI assistants: an
embed-snippetaction builds the same snippet over the API or MCP. - Follows YouTube’s embed guidance. The player now asks the browser to send the referrer setting YouTube recommends for embedded videos, instead of relying on whatever the site sets by default.
- Videos you have already added, and boxes pasted into pages by hand, keep working with no changes.
1.0.14
Section titled “1.0.14”- Settings language menu. The language menu in this plugin’s settings now lists only the languages it is actually translated into, plus English, so you can no longer pick a language that changes nothing.
- Danish. Adds a Danish translation.
1.0.13
Section titled “1.0.13”- Fixes a doubled cache-busting tag on its stylesheet. On PageMotor 0.11 and later the page asked for the file with two version tags on the end of its address (
?v=…?v=…), because the core had started adding its own tag and the plugin was still adding one too. The file loaded correctly, so nothing was visibly broken; the address was just malformed and every cache saw a longer key than it needed. The plugin now leaves the tag to the core on 0.11 and later, and still adds its own on older cores, where nothing else would. - No change to what that stylesheet does.
1.0.12
Section titled “1.0.12”- Fixes videos showing a blank click-to-load box with no poster image. YouTube does not generate the standard-definition thumbnail for every upload, and the plugin used it as the default poster with no fallback, so those videos rendered an empty box with only the play button. The poster now steps down one tier at a time when YouTube has no image at that size (maximum, then standard, then high quality, which YouTube generates for every video). Box size and cropping are unchanged.
- The Self-Host Thumbnails download uses the same fallback, so a video whose standard thumbnail is missing now caches locally instead of failing.
- The front-end script is now cache-busted on PageMotor 0.11.2 and earlier, so this fix reaches visitors on their next page load rather than after their browser cache expires. On 0.11.3 and later core already does this.
- The Default Thumbnail Resolution setting labels now say which tier is always available (High Quality) and which can be missing (Standard, Maximum). No settings change or migration required.
1.0.11
Section titled “1.0.11”- Fixes “Your session has expired. Please reload to ensure your security.” on PageMotor 0.11. The message appeared on this plugin’s admin screens even though you were signed in perfectly normally, and whatever you were doing failed to save.
- Nothing was wrong with your session. PageMotor 0.11 started handling part of the security check that this plugin was already handling itself, and the two together made every save look invalid. The plugin now checks whether PageMotor has already done it.
- Visitors who were not signed in were never affected, on any version.
- There is nothing to reconfigure, and nothing else changed.