WP Manifestindependent plugin directory
manifest / media / bg-video-overlay

Video Background + Overlay

WordPress Plugin - Uses a full-screen background video with an optional overlay (smoke) video and fallback image behind all site content.

by Piotr Kijowski [piotr.kijowski@gmail.com] · github.com/piotr-kijowski/bg-video-overlay

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/piotr-kijowski/bg-video-overlay/archive/refs/heads/main.zip
No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.
Readme github.com/piotr-kijowski/bg-video-overlay ↗

Add a full-screen background video with an optional transparent overlay (smoke) behind all site content - with solid admin controls.

Description

Video Background + Overlay adds a fixed, full-viewport media layer behind your entire WordPress site.

You can run up to 3 layers:

  • Background video (MP4/WebM)
  • Overlay “smoke” video (best as WebM with alpha)
  • Fallback background image (used when video is disabled / missing, and recommended for mobile)

Everything is configured in wp-admin (no code edits):

Settings -> Video Background + Overlay

The output is injected using wp_body_open, with a safe fallback to wp_footer for themes that don’t support wp_body_open.

Features

  • Enable / disable toggle (keep your URLs saved)

Media Library pickers for:

  • Background video
  • Overlay video
  • Fallback image

Visual controls:

  • Background opacity
  • Overlay opacity
  • Overlay blend mode
  • Z-index control (for “my theme is weird” situations)

Mobile controls:

  • Disable background video on mobile
  • Disable overlay video on mobile

Scope controls:

  • Site-wide
  • Only selected post types
  • Only specific page IDs
  • Per-page override in the editor (inherit / force enable / force disable)

Performance controls:

  • Video preload mode (auto / metadata / none) per layer

Creative controls:

  • Playback speed (0.25x - 2x)
  • Optional parallax multiplier (subtle scroll depth effect)

Installation

  1. Upload the plugin folder to:

/wp-content/plugins/video-background-overlay/

  1. Activate the plugin through the Plugins menu in WordPress.
  2. Go to:

Settings -> Video Background + Overlay

and configure your media.

Usage

Open:

Settings -> Video Background + Overlay

Configure:

  • Enable: master on/off
  • Background video: base layer
  • Overlay video: optional smoke layer
  • Fallback image: shows when video is disabled / missing and recommended for mobile

Notes

  • If background + overlay + fallback are all empty, the plugin outputs nothing.
  • Overlay transparency works best with WebM alpha.

Scope

You can control where the effect runs:

  • Site-wide: everywhere on the front end
  • Selected post types: only on chosen post types
  • Specific page IDs: only on selected pages

Per-page override:

In the page/post editor you get a “Video Background + Overlay” box:

  • Inherit global settings
  • Force enable on this page
  • Force disable on this page

Performance tips

  • Keep videos short and optimized (loop-friendly).
  • Prefer modern codecs (WebM, H.264).
  • Use preload=metadata or none if you care about page speed scores.
  • Consider disabling video on mobile and using a fallback image instead.

FAQ

Does this work in wp-admin?

No. The background output is front-end only. wp-admin only contains the settings UI.

Will it block clicking or scrolling?

No. The container uses pointer-events: none.

Why is the overlay opacity usually low?

Because smoke overlays get obnoxious fast. Start around 0.03 and creep up.

My theme shows the video above content. Help.

Set Z-index to a negative value (default -1). If your theme forces weird stacking contexts, try 0 and adjust as needed.

Does Safari/iOS autoplay work?

Usually, if the video is muted and uses playsinline. Still, mobile browsers can be unpredictable - that’s why the “disable on mobile + fallback image” options exist.

Changelog

1.2.0

Added full Settings page controls:

  • enable toggle
  • opacity sliders
  • z-index control
  • blend mode selector
  • mobile toggles
  • fallback image picker
  • scope rules + per-page override meta box
  • preload controls
  • playback speed + optional parallax

1.1.0

Added:

Settings -> Video Background + Overlay

page with Media Library pickers for background and overlay videos.

1.0.0

Initial release.

Full-screen background video output via wp_body_open with wp_footer fallback.
Optional smoke overlay layer with blend mode.

Upgrade Notice

1.2.0

Adds full admin controls (scope, mobile toggles, opacity, fallback image, performance + creative controls).

License

This plugin is licensed under the GPL v3 or later.