Magic Product Video User Guide

Requirements

Before installing, make sure your environment meets the following:

Installation

From the WordPress dashboard

1. Go to Plugins → Add New.
2. Search for “Magic Product Video for WooCommerce”.
3. Click Install Now, then Activate.
4. Make sure WooCommerce is installed and active.

Manual upload

1. Download the .zip from WordPress.org.
2. Go to Plugins → Add New → Upload Plugin and select the file.
3. Click Install Now → Activate.

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

Installing & configuring FFmpeg

FFmpeg is only needed for the server conversion method. If you can't install it (e.g. 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 → Settings → 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:

The Magic PVW admin

The plugin ships a dedicated admin app under the Magic PVW menu, organised into a few areas you can reach from the left sidebar: Dashboard, Media, Settings and Player.

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

General & WooCommerce

• 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 / 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 the plugin 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.

FFmpeg presets

A preset 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 → Settings → 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/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 — 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 shortcode 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, three helpers are available:

Get the raw data

<?php
// Returns 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:
mpvw_the_video( $post_id );

WooCommerce gallery data

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

WPML & multilingual

If you run WPML, enable Sync WPML languages in Settings. 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

FAQ