=== MisticEase – Video Thumbnails & Draggable Popups ===
Contributors: misticuantum
Tags: video popup, youtube, vimeo, lightbox, lazy load
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.3.3
License: GPLv2
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Pasted YouTube or Vimeo URLs become thumbnails on publish to keep pages fast. A click opens a popup visitors can drag anywhere and watch as they read.

== Description ==

Paste a YouTube, YouTube Shorts, Vimeo, or Dailymotion URL into a post or page and publish. That is all it takes: instead of a heavy embedded player, the page shows a lightweight, clickable thumbnail, and the video opens in a popup. There are no shortcodes and no embed code to write.

* **Paste and it is done** — MisticEase fetches and saves the thumbnail, builds the HTML, and creates the player and the popup.
* **Pages stay fast** — The video player is not loaded until a visitor clicks. Only a lightweight thumbnail image is on the page.
* **Watch while reading** — Visitors can drag the popup and leave it anywhere on the page. The video keeps playing while they read on.
* **Control each item** — Add a short prefix such as `t300/` before a URL to set the width, the corner radius, or a text link for that item only.
* **Works for images too** — Images linked to their media file open in a popup and can be viewed one after another.

See it in action in the [MisticEase live demo](https://mitum.me/misticease/).

MisticEase is built to give editors back the time they used to spend every time they added a video. MisticEase takes on the tedious work. All the editor does is paste a URL.

= How to use it: paste and publish =

1. Paste a video URL into a post or page.
2. Publish.
3. On the published page, the URL becomes a clickable thumbnail. Clicking it opens the video in a popup.

It works the same in the Block Editor and the Classic Editor. If WordPress shows an embedded video player in the editor, MisticEase still converts it to a thumbnail on the published page. A caption added to the embed block is kept.

If you do not want a thumbnail, add `n/` before the URL. The video title becomes a text link, and clicking it opens the popup.

The appearance follows the defaults you choose in the settings. To change a single item, use Slash Markup, described below.

= Floating mode: watch the video while reading the page =

A popup first opens in the center of the screen as a normal popup. Dragging it switches it to floating mode, where it can be moved to any place on the page and left there. It stays afloat while the visitor reads on.

* Read the text while watching a how-to video.
* Compare a video with an image. One video and one image can be open at the same time.
* Pin a popup so that it is not closed by accident or replaced by other media. A pinned popup can still be moved.
* While a popup is floating, scrolling the page and clicking links work as usual (except when two popups are both pinned).

Floating mode is available on desktops and tablets with a window wider than 640 px. At 640 px or narrower, media opens in a normal popup. When floating mode is turned off in the settings, only normal popups are used.

= Keeping pages fast =

The video player is not loaded until a visitor clicks. Only a lightweight thumbnail image is on the page.

* When a page is first opened, MisticEase fetches a high-quality thumbnail (1280×720 for YouTube when available) and saves it as an image file in the uploads directory. This is finished when the editor opens the page after publishing, so visitors normally receive the saved thumbnail from the site's own server from the start.
* Thumbnails have an explicit width and height, so the layout does not shift while they load.
* It does not use jQuery.
* With lazy loading on (the default), thumbnails are not loaded until they enter the viewport.
* You can set a cap on the thumbnail cache. When the cap is reached, thumbnails are deleted starting with those displayed least recently. In addition, regardless of the cap, thumbnails that have not been displayed for 90 days or more are deleted every 30 days.

= Showing items side by side =

Paste one URL into each cell of a Table block or each column of a Columns block. That alone lines the thumbnails up evenly.

When the space they are given is small, thumbnails and popups fit that width, so there is no need to set sizes. Add `n/` only to the cells you want as text links. To line up many media items, the Table block is recommended.

= Slash Markup: change the display one item at a time =

When a page holds many media items, the same display is not always right for all of them. For example, if a video URL mentioned in the middle of a sentence also becomes a thumbnail, the layout breaks.

For those cases, add a short prefix before the URL to set the display for that item. Just join initials and numbers with slashes, as in `t200/p500/`. It is not a shortcode that you write out for each item, so it is intuitive and easy to remember. Because the notation is separated only by slashes, it is called Slash Markup.

Slash Markup is a notation unique to MisticEase. Think of it as a brush that turns a WordPress page into a free canvas. MisticEase builds the HTML as specified, so the item appears in the visitor's browser as the editor intended. Without a prefix, the item follows the settings.

* `t300/` — thumbnail width (100–4096 px)
* `p980/` — popup width (200–8192 px)
* `r30/` — corner radius (1–9999 px)
* `n/` — show the video title as a text link instead of a thumbnail
* `/Your text/` — show a text link with text of your choice (place it before any other prefix)
* `ttl Caption/` — caption shown below the popup. Type one space after `ttl`, then the text. It is mainly for images, where it is also used as the alternative text
* `np/` — show a same-site image URL as an inline image that does not open in a popup

The numbers are examples. Any value within the range can be used. As long as `/Your text/` comes first, the other prefixes can be in any order.

Prefixes can be combined. Examples:

* `t300/r30/p980/https://youtu.be/XXXXXXXXXXX` — a 300 px wide thumbnail with a 30 px corner radius that opens a 980 px wide popup.
* `n/https://youtu.be/XXXXXXXXXXX` — the video title becomes a text link.
* `/Watch the demo/p980/https://youtu.be/XXXXXXXXXXX` — a text link reading “Watch the demo” that opens a 980 px wide popup.
* `t300/p500/r30/ttl Night view/https://example.com/wp-content/uploads/2026/09/sample.jpg` — a same-site image shown 300 px wide with a 30 px corner radius. Clicking it opens a 500 px wide popup with “Night view” shown below the image.

A width you set is a maximum. When the available space is smaller, the item shrinks to fit. When prefixes conflict, the one with priority is used. For example, a text link combined with a corner radius becomes a text link.

= Writing rules =

**When a URL sits inside a sentence**

* When text that is displayed on the page comes directly before or after a URL, put a space on each side. This keeps the surrounding text from being taken into the URL. It is needed whether or not you use Slash Markup.
* When the URL is next to an HTML tag (`<`, `>`, and so on), no space is needed. The same applies inside a Table block: no space is needed there.
* When punctuation or text follows a URL with no space, type three slashes, `///`. MisticEase treats that point as the end of the URL. The `///` is not shown on the published page.
* Without `///` or a space, the text that follows is treated as part of the URL, and no thumbnail is made (a video URL becomes a plain link).
* Example: `See n/https://youtu.be/XXXXXXXXXXX///, then read on.`
* The same rules apply when you paste a same-site image URL.

**When you use Slash Markup**

* No space, line break, or HTML tag can come between the prefix and the URL.
* When text comes before the prefix, put a space before the prefix.
* A `/Your text/` label must start at the beginning of the text or immediately after whitespace.
* The text in `/Your text/` and `ttl` cannot contain `/`, `<`, `>`, or quotation marks (`"`, `'`).

= Images open in a popup (lightbox) too =

An image linked to its media file opens in a popup when clicked. Just set an Image block to link to its media file, or add a text link to an image file. When a page has several, visitors can view them one after another inside the popup. Supported formats are JPEG, PNG, GIF, and WebP.

To show a same-site image URL as a thumbnail or an inline image, add Slash Markup. `t300/` plus the image URL makes a 300 px wide thumbnail that opens in a popup when clicked. `np/` plus the image URL makes an inline image that does not open in a popup. `/Your text/` plus the image URL makes a text link that opens the image. An image URL with no prefix is not converted.

* It works even if the uploads directory has been moved, as long as it is under `wp-content`.
* Images served from a CDN are supported. Add the CDN hostname in the settings.
* If you already use another gallery plugin, turn off image popups in the settings and the two can coexist.

= Settings and Multisite =

What you can set in the settings panel:

* Thumbnail width (default 640 px; 200 px or more)
* Popup width (default 854 px; 200 px or more)
* Thumbnail cache cap (default 0 = unlimited)
* Lazy loading (thumbnails are not loaded until they enter the viewport; on by default)
* Image popups on or off
* Floating mode on or off (shown as “Floating UX mode” in the settings panel)
* CDN hostnames

On Multisite, the network admin panel can enforce the thumbnail cache cap and the CDN hostname allowlist across all sites. It also lists the cache usage of each site, and one button recalculates the usage for all sites.

Detailed guidance is available after installation in the “Readme” tab of the settings panel.

= Other details =

* It can be operated from the keyboard. Enter or Space opens a thumbnail, Esc closes a popup, and the Left and Right arrow keys switch images.
* YouTube videos play through youtube-nocookie.com (privacy-enhanced mode).
* Uninstalling removes the settings and the saved thumbnails.

== External services ==

MisticEase connects to the supported video services (YouTube, Vimeo, and Dailymotion) in the following cases.

* When a thumbnail has not been saved yet. The site's server fetches the image and related information and saves it in the site's uploads directory. After that, the saved image is used.
* When a page whose thumbnails have not been saved is opened. To prevent a delay in display, the browser of the person who opens the page loads a low-quality temporary thumbnail directly from the video service (YouTube and Dailymotion). For Vimeo, a placeholder image bundled with the plugin is shown, and the video title is fetched and shown with it. Saving is normally finished when the editor opens the page after publishing, so this rarely happens in a visitor's browser.
* When an `n/` title link is displayed. The video title is fetched. The title is not stored in the database or in a cache.
* When a visitor plays a video. The visitor's browser connects directly to the video service. YouTube videos play through youtube-nocookie.com.

Terms and privacy policies:

* YouTube Terms: https://www.youtube.com/t/terms
* Google Privacy Policy: https://policies.google.com/privacy
* Vimeo legal terms: https://vimeo.com/legal
* Vimeo API terms: https://vimeo.com/legal/service-terms/api
* Vimeo Privacy Policy: https://vimeo.com/privacy
* Dailymotion Terms: https://legal.dailymotion.com/en/terms-of-use/
* Dailymotion Privacy Policy: https://legal.dailymotion.com/en/privacy-policy

== Freemius ==

MisticEase includes the Freemius SDK. It is used for notices, for information about and licensing of MisticEase Arc (the paid version), and for support. MisticEase and MisticEase Arc share some functions. To avoid processing the same content twice, the Freemius SDK prevents both from being active at the same time.

Opting in to Freemius is optional. All MisticEase features work without opting in. If you do not opt in, no data is sent to Freemius.

If you opt in, the following information is sent to Freemius and managed by Freemius.

* Your WordPress username and email address
* The site URL
* The MisticEase version, and whether the plugin is active or has been deleted
* The WordPress and PHP versions, the site language, and basic environment information

This information is used for compatibility checks, updates, licensing, and support. It also helps the developer decide which versions and languages to prioritize.

In its Privacy Policy, Freemius states that it does not sell data and that it keeps data secure using industry-standard methods. It states that it grants GDPR rights to users outside the EU as well, and that it complies with Brazil's LGPD. It also states that it makes an effort to comply with California's CCPA as far as possible and gives the rights under that law to non-residents as well.

For details:

* Privacy Policy: https://freemius.com/privacy/
* Data Practices: https://freemius.com/privacy/data-practices/

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/`, or install the plugin from the WordPress Plugins screen.
2. Activate it on the “Plugins” screen.
3. Paste a video URL into a post or page and publish.

== Frequently Asked Questions ==

= Do I need to write HTML or embed code? =

No. Just paste a video URL and publish. It works the same in the Block Editor and the Classic Editor.

= Which video URLs are supported? =

URLs of single videos on YouTube (regular videos, Shorts, live streams, and `youtu.be` short URLs), Vimeo (in the form `vimeo.com/` followed by numbers), and Dailymotion (including `dai.ly` short URLs). URLs that cannot be made into thumbnails, such as playlists and channels, are converted to external links.

= Why did my URL become a plain link instead of a thumbnail? =

When text or punctuation follows a URL with no space, everything up to that point is treated as the URL. Put a space or `///` directly after the URL. Unsupported URLs, such as playlists and channels, also become plain links.

= Why is the thumbnail low quality or a placeholder on the first view? =

Because it is the first view, before the thumbnail has been saved. To prevent a delay in display, MisticEase first shows a low-quality temporary thumbnail and, in the meantime, fetches and saves the high-quality one. From the next view on, the saved image is used. Saving is finished once the editor opens the page after publishing, so visitors almost never see the temporary thumbnail.

= Can I keep a link to a video as a plain link? =

Yes. A link placed on text (where the link text is not the URL itself) is not converted. URLs inside code blocks are not converted either.

= Will it slow down my pages? =

No. The player is not loaded until it is clicked. Only a lightweight thumbnail image is on the page, and once saved it is served from the site's own server.

= Can visitors move the popup on a smartphone? =

No. At a window width of 640 px or less, floating mode is off and media opens in a normal popup. Floating mode is available on desktops and tablets with a window wider than 640 px.

= Can I change the display for individual items? =

Yes. Add a short prefix such as `t200/` or `n/` directly before the URL. Without one, the item is displayed according to the settings.

= Can I use it together with another gallery plugin? =

Yes. Turn off image popups in the settings to leave images to the other plugin and use MisticEase for videos only.

= Does it work with images served from a CDN? =

Yes. Add the CDN hostname in the settings.

= Does it work with Multisite? =

Yes. Network administrators can enforce the thumbnail cache cap and the CDN hostname allowlist across all sites. When the cap is enforced, the same cap applies to each site.

= Where are thumbnails stored? =

In the WordPress uploads directory. A single site uses `/wp-content/uploads/misticease/`; Multisite subsites use folders such as `/wp-content/uploads/sites/2/misticease/`.

= Will saved thumbnails keep piling up? =

You can set a cap on the thumbnail cache (the default is 0 = unlimited). When the cap is reached, thumbnails are deleted starting with those displayed least recently. Even with no cap set, thumbnails that have not been displayed for 90 days or more are deleted every 30 days.

= What happens when I uninstall the plugin? =

The settings and the saved thumbnails are removed. URLs and Slash Markup inside your posts are left untouched.

= What happens when JavaScript is disabled? =

Popups, floating mode, and switching between images do not work. MisticEase requires JavaScript.

= Does it collect personal data? =

MisticEase itself does not collect, store, or analyze personal information. Opting in to Freemius is optional and is described in the “Freemius” section.

== Screenshots ==

1. Paste a supported video URL and save the page.
2. On the published page, the video URL becomes a clickable thumbnail.
3. Click a thumbnail to play the video in a popup.
4. Slash Markup lets you set the thumbnail width and more for each URL.
5. In floating mode, one video popup and one Media Library image popup can stay open at the same time.
6. The settings panel includes guidance you can read on the spot.

== Upgrade Notice ==

= 1.3.3 =
Fixes Slash Markup label detection to prevent slashes in ordinary text or URLs from breaking video and image markup.

== Changelog ==

= 1.3.3 =

* Fixed Slash Markup label detection so slashes in ordinary text or other URLs no longer disrupt video and image markup.

Older changelog entries are in `changelog-misticease.txt`.
