User guide

Requirements

Before installing, make sure your environment meets the following:

Installation

The plugin is sold on CodeCanyon and installed from its .zip file.

1. Download the plugin .zip from your Envato / CodeCanyon Downloads page (choose Installable WordPress file only).
2. In WordPress go to Plugins → Add New → Upload Plugin and select the file.
3. Click Install Now, then Activate.
4. Make sure WooCommerce is installed and active.

After activation a new Magic PVW item appears in the WordPress admin menu.

License & updates

Open Magic PVW → License and enter your Envato purchase code. Once it is activated for your domain, plugin updates arrive in the WordPress dashboard like any other plugin. The screen links to Envato's guide if you need to find the code.

Installing & configuring FFmpeg

FFmpeg is only needed for the server conversion method. If you can't install it (for example on restricted shared hosting), skip this section and use the in-browser converter instead.

Install on your server

# Debian / Ubuntu
sudo apt update && sudo apt install -y ffmpeg

# RHEL / CentOS / AlmaLinux (EPEL)
sudo dnf install -y epel-release && sudo dnf install -y ffmpeg ffmpeg-devel

# Alpine (many Docker images)
apk add --no-cache ffmpeg

# macOS (Homebrew), local dev
brew install ffmpeg

FFprobe ships together with FFmpeg in all of the above, so a single install covers both conversion and thumbnail generation.

Verify it works

# Should print a version and the install path
ffmpeg -version
which ffmpeg   # e.g. /usr/bin/ffmpeg

Then open Magic PVW → FFmpeg: it shows a green “FFmpeg installed” message with the detected version when everything is wired up correctly.

Make sure PHP can call it

Server conversion launches FFmpeg through PHP's exec(). Some hosts disable it for security. Check your php.ini:

; exec must NOT be listed here
disable_functions = 

Quick start

Three steps to your first product video:

1. Upload & convert

   Open Magic PVW → Media, upload a video and let it convert to MP4 + WebM. A poster thumbnail is created automatically.

2. Attach it to a product

   Edit any product. In the Magic Video box (sidebar) click Select video, pick your video and press Update.

3. Done

   The video now plays inside the product gallery on the storefront, with no theme changes required.

The Magic PVW admin

The plugin ships a dedicated admin app under the Magic PVW menu. Its left sidebar holds Media, WooCommerce, Player, FFmpeg, Settings, License and Info & FAQ (an overview of how videos are converted, how many are ready and whether updates are on).

Magic Media library

The Media screen is your central video library. Here you can:

• Upload a source video (MP4, MOV, AVI, MKV, HEVC, WebM and more).
• Browse all uploaded videos as cards with a poster, status badge and available formats.
• Search and paginate through your library.
• Open a video to manage its converted formats, thumbnail and conversion.
• Delete a video or an individual converted format.

Each video is stored as its own item (a magic_video entry) holding the original file, the converted MP4/WebM and the poster image.

Conversion & queue

Each source video is converted to MP4 and WebM. You choose where that happens: on the server (FFmpeg) or in your browser (WASM). See Conversion methods. Either way:

• Add a format (MP4 or WebM) and watch a live progress indicator.
• Each format uses the preset you choose (see FFmpeg presets).

Server method: runs in the background through a queue, so your editor is never blocked. You can cancel or re-queue a conversion, and a concurrency limit (2 at a time by default) keeps the server from being overloaded. The queue is processed by WP-Cron, so it keeps going even after you close the tab.

Browser method: converts right in the admin tab and uploads the finished file; nothing runs on the server. Jobs run one at a time. Keep the tab open until a conversion finishes: closing it cancels that in-progress browser job (already-saved formats are unaffected).

Thumbnails

A poster image is generated automatically from the first second of the video. Open a video's details to regenerate the thumbnail from a different second if you prefer another frame. If FFmpeg isn't available, the WooCommerce placeholder image is used.

Settings

WooCommerce gallery

On the Magic PVW → WooCommerce screen:

• Use FlexSlider: match how your theme renders the product gallery. Enable it if your theme uses WooCommerce's default FlexSlider gallery; disable it for custom galleries. If a custom theme modifies the product card template, this option may not be relevant.
• Gallery position: show the video as the first item of the gallery (most prominent) or at the end, after the product photos.
• Show video in product list: on shop and category pages, replace the product thumbnail with an autoplaying, muted, looping video for products that have one. Products without a video keep their normal thumbnail. Off by default (video shows only on the single product page).
• Sync WPML languages: share product videos across translations (see WPML).

Enabled post types

By default the Magic Video box appears on products. On Magic PVW → Settings you can enable additional post types (posts, pages, custom post types) so editors can attach a video to them too. Products are always enabled.

When the plugin is deleted

Deactivating or deleting the plugin keeps your videos, product video links, presets and settings, so a reinstall picks up where you left off. To remove everything when you delete the plugin, switch on Delete all plugin data when the plugin is deleted on Magic PVW → Settings and confirm. Deleting the plugin then also removes the Magic Media videos and their converted files, product video links, presets, settings and the conversion queue. This cannot be undone.

FFmpeg presets

A preset on the Magic PVW → FFmpeg screen controls how FFmpeg encodes your videos. You can edit the default preset and create custom ones:

Output formats are MP4 (H.264) and WebM for the widest cross-browser support. WebM uses VP9 on the server method; the in-browser method uses VP8 automatically (VP9 isn't supported by the WASM engine). The same screen also holds the Video processing method switch (Server / Browser).

Player configuration

The Player screen configures the front-end video.js player used on the storefront:

• Autoplay, Muted, Loop, Plays inline, Show controls.
• Open in modal on click: when on, the gallery (and shortcode/PHP embeds) show a poster with a play button; clicking opens a full-screen player. When off, the video plays inline following the Autoplay setting. See Displaying videos.
• Fluid sizing & Aspect ratio (e.g. 16:9).
• Default volume and object-fit (contain/cover).
• Background colour or transparent background.

Conversion methods

The plugin can encode your videos in two places today, and a third is on the roadmap. All of them produce the same MP4 + WebM outputs and feed the same library, so you can switch any time without changing how videos are attached or displayed.

Switching server ↔ browser

Open Magic PVW → FFmpeg and use the Video processing method switch:

1. Pick Server or Browser. The choice is saved instantly.
2. An indicator right below shows the currently active method (and warns if Server is selected but FFmpeg isn't installed, or if your browser can't run the in-browser converter).
3. That's it: the next conversion you start from the Media library uses the selected method.

Speed & file-size guide

Native server FFmpeg is dramatically faster than the in-browser engine, which is single-threaded WebAssembly. Rough relative encoding speed (higher = faster):

Approximate time to convert one format of a typical clip:

Plus a one-time ~30 MB engine download on the first browser conversion. The browser engine keeps the whole job in tab memory, so very large, long or high-resolution files can fail with an out-of-memory error.

Which method should I use?

Rule of thumb: Server is the best default whenever it's available; reach for Browser when you can't run FFmpeg on the host and your clips are reasonably small.

Attaching a video to a product or post

When editing a product (or any enabled post type) you'll see a Magic Video box in the sidebar:

1. Click Select video. A modal video picker opens with the same library as Magic PVW → Media.
2. Choose a ready video (search and paginate as needed) and press Select.
3. The box now shows a small playable preview of the chosen video.
4. Press Update / Publish to save the post. The video is now linked.
5. Use Change video to swap it, or Remove to detach it.

Displaying videos

For products, the video is embedded into the WooCommerce product gallery automatically, no code needed. It uses WooCommerce's standard gallery mechanism, so it works across configurations: the FlexSlider carousel, lightbox/zoom galleries, block (FSE) themes such as Twenty Twenty-Five, and products with or without extra images. If a theme renders a completely custom gallery, the plugin still injects the video into it as a safe fallback.

How it plays follows your Player settings:

• Autoplay on: the video slide plays automatically (muted) when shown in the carousel.
• Autoplay off: the slide shows controls/poster and plays on click, inline.
• Open in modal on click: the gallery shows a poster with a play button; clicking opens a full-screen player.

The Gallery position setting controls whether the video is the first or last gallery item. For any other location (posts, pages, custom layouts) use the shortcodes or PHP helpers below. The player library loads automatically whenever a video is output.

Shortcodes

There are two shortcodes. Pick based on what you want to reference:

// Video attached to the CURRENT post / page / product
[mpvw_video]

// Video attached to a specific post, by POST id
[mpvw_video id="128"]

// Any video directly by its MAGIC VIDEO id
[mpvw_magic_video id="194"]

// With options (both shortcodes accept the same attributes)
[mpvw_magic_video id="194" autoplay="true" muted="true" loop="true" controls="false" class="my-video"]

// Open in a full-screen modal on click
[mpvw_magic_video id="194" modal="true"]

Attributes (both shortcodes)

PHP API

For full control inside theme templates or page builders, these helpers are available. They read the same files and player settings as the gallery.

Get the raw data

<?php
// Returns an array on success, or false when there is no video.
$data = mpvw_get_video_data( $post_id ); // $post_id optional (current post)

// =>
[
  'mp4'            => '…/video.mp4',
  'webm'           => '…/video.webm',
  'thumbnail_id'   => 285,
  'magic_video_id' => 282,
];

Render a ready-made player

<?php
// Returns the player HTML as a string (enqueues the player assets).
$html = mpvw_get_video_html( $post_id, [
  'autoplay' => true,
  'muted'    => true,
  'loop'     => true,
  'controls' => false,
  'modal'    => false, // poster + play → full-screen player
  'class'    => 'my-video',
] );

// Or echo it directly (takes the same optional $args array):
mpvw_the_video( $post_id );

By Magic Video ID

<?php
// The PHP side of [mpvw_magic_video]: no post attachment needed.
$data = mpvw_get_magic_video_data( 194 );          // array or false
$html = mpvw_get_magic_video_html( 194, [ 'modal' => true ] );

WooCommerce gallery data

<?php
// Product-aware getter (honours the WPML fallback). Use in WooCommerce templates.
$video = mpvw_get_product_video_data( $product_id ); // defaults to the global $product

WPML & multilingual

If you run WPML, enable Sync WPML languages on the Magic PVW → WooCommerce screen. With it on, a translated product without its own video falls back to the default-language video, so you set the video once and it shows everywhere. Leave it off to set a different (or no) video per language.

Troubleshooting

Conversion never finishes / stays pending

Check that FFmpeg and FFprobe are installed and that PHP exec() isn't disabled. The Magic PVW → FFmpeg screen shows whether FFmpeg is detected. The queue is processed via WP-Cron, so make sure cron is running.

The video doesn't show on the product page

Confirm the video is attached and the post was saved, the chosen video is ready, and the FlexSlider setting matches your theme's gallery. For heavily customized galleries, render it manually with the PHP API.

The “Magic Video” box doesn't appear on a post type

Enable that post type under Settings → Enabled post types. Products are always enabled.

A video can't be selected in the picker

Only ready videos (with at least one converted format) can be attached. Convert it first on the Media screen.

FAQ

Changelog

1.7.0 16 October 2026

• New: “Delete all plugin data when the plugin is deleted” option in Settings, off by default and confirmed before it turns on. Deleting the plugin now keeps your videos and settings unless you switch it on (see When the plugin is deleted).
• Privacy: nothing is sent to the license server until a purchase code is activated; the License screen explains what activation sends.
• New: the Info & FAQ screen is rebuilt around the real workflow: upload, convert, attach, show.
• Fix: popup (modal) mode in the product gallery: lightbox list, slide height and stray icons.
• Fix: server conversions failing when PHP's working directory is not writable, and a false “ready” status after a failed conversion.
• Fix: saving the WooCommerce settings screen reset the video processing method to Server.
• Fix: admin layout on phones: the menu becomes a scrollable row and the content flows with the page.
• Compatibility: tested with WordPress 7.1 and WooCommerce 11.2; HPOS and the block checkout are declared compatible.

1.6.0

• New: in-browser (WebAssembly) conversion as an alternative to server FFmpeg, with a Server / Browser switch on the FFmpeg screen.
• The browser converter engine is bundled and served from your own site; WebM uses VP8 in the browser and VP9 on the server.
• Browser conversions run one at a time and survive navigation; the server queue keeps running after you close the tab.

1.5.0

• Product gallery video across WooCommerce setups: FlexSlider, lightbox, block (FSE) themes and custom galleries.
• New: “Open in modal on click”, gallery position (start/end) and video in the product list.
• New: [mpvw_video] and [mpvw_magic_video] shortcodes and a video picker for enabled post types.