Why WPMediaVerse

WPMediaVerse is a purpose-built media platform for WordPress. Unlike plugins that bolt media features onto WordPress posts or attachments, WPMediaVerse uses its own high-performance database architecture designed from the ground up for media-heavy communities.

The Problem with WordPress Attachments

Most WordPress media plugins store user uploads as wp_posts with post_type = 'attachment'. This creates serious problems at scale:

• wp_posts table bloat - A community with 50,000 photos adds 50,000 rows to the same table that holds your pages, blog posts, menu items, and revisions. Every WP_Query on your site slows down.
• wp_postmeta overhead - Each media item needs 10-20 meta rows for stats, privacy, tags, and file paths. At 50K media, that is 500K-1M rows in wp_postmeta - the single biggest performance bottleneck in WordPress.
• No native stats - WordPress attachments have no built-in view counting, reaction tracking, or engagement metrics. Plugins that add these use postmeta, compounding the bloat.
• Mixed concerns - Admin queries for pages and posts compete with media queries. There is no way to independently optimize media storage.

How WPMediaVerse Is Different

WPMediaVerse stores all media in dedicated custom tables, completely separate from wp_posts:

Table	Purpose
mvs_media_index	Core media record - title, author, file URL, privacy, status, timestamps
mvs_media_meta	Sparse key-value metadata (thumbnails, EXIF, groups)
mvs_media_stats	Views, reactions, comments, favorites - one row per media
mvs_reactions	Individual emoji reactions with user attribution
mvs_favorites	User favorites / saved items
mvs_follows	User follow relationships
mvs_conversations	Direct message conversations
mvs_messages	Individual chat messages

What This Means for You

• Zero wp_posts bloat - 100,000 media items add zero rows to wp_posts. Your pages, menus, and blog posts are unaffected.
• Indexed queries - Every table has purpose-built indexes. Fetching "latest 12 public photos by user X" is a single indexed query, not a WP_Query with meta joins.
• Independent scaling - You can optimize, partition, or replicate media tables without touching the rest of WordPress.
• No postmeta bottleneck - Stats, privacy, and metadata live in dedicated columns or a sparse meta table. No serialized arrays, no autoload bloat.
• Real-time stats - Views, reactions, and comments are atomic counters in mvs_media_stats, not meta values that need cache invalidation.

Performance at Scale

Metric	Attachment-based plugins	WPMediaVerse
10K media: wp_posts rows added	10,000	0
10K media: wp_postmeta rows added	100,000-200,000	0
Query: latest 12 photos	WP_Query + 3 meta joins	Single indexed SELECT
Query: user's photo count	COUNT on wp_posts + meta	COUNT on mvs_media_index (indexed)
Stats update (view count)	update_post_meta (cache bust)	UPDATE mvs_media_stats SET views = views + 1

Files Are Still in wp-content

WPMediaVerse stores database records in custom tables. The actual files (images, videos, audio) are stored in the standard WordPress uploads directory:

wp-content/uploads/wpmediaverse/2026/03/photo-name.jpg
wp-content/uploads/wpmediaverse/2026/03/photo-name-300x200.jpg  (thumbnail)
wp-content/uploads/wpmediaverse/2026/03/photo-name-1024x768.jpg (large)
wp-content/uploads/wpmediaverse/2026/03/photo-name-150x150.jpg  (square)

With Pro's cloud storage, files can also be stored on Amazon S3 or BunnyCDN while database records remain local.

How It Compares

Feature	rtMedia	BuddyBoss Media	MediaPress	WPMediaVerse
Storage	wp_posts + postmeta	wp_posts + postmeta	wp_posts + postmeta	Custom tables
Requires BuddyPress	Yes	Yes (BuddyBoss)	Yes	No (optional)
Standalone mode	No	No	No	Yes
Custom privacy levels	Basic	Basic	Basic	6 levels (Pro)
Direct messaging	No	Separate plugin	No	Built-in
Gamification	No	No	No	Challenges, battles, tournaments (Pro)
Video transcoding	No	No	No	Multi-quality + HLS (Pro)
Cloud storage	No	No	No	S3 + BunnyCDN (Pro)
AI moderation	No	No	No	OpenAI + Vision + Rekognition
Upload quotas	No	No	No	Per-user packages (Pro)
Layout modes	1	1	1	5 (grid + 4 Pro layouts)

Use Cases

Photography Community

A social network for photographers to share, discover, and compete. Users upload photos, follow each other, enter weekly challenges, and battle head-to-head. The Pinterest or Instagram layout creates a visual-first experience.

Portfolio Showcase

Designers, artists, and photographers use WPMediaVerse as their portfolio. The Dribbble layout presents work in a professional shot grid. Clients can view galleries, leave comments, and message directly.

School or University

Students submit media projects through the upload system. Teachers use collections to curate work. Privacy controls ensure only enrolled members see content. Quotas limit storage per student.

Company Intranet

Employees share photos from events, marketing assets, and training videos. Group media tabs organize content by department. AI moderation flags inappropriate uploads automatically.

BuddyPress Community

Add a rich media layer to any BuddyPress social network. Members get media tabs on profiles and groups, uploads appear in the activity stream, and followers see new content in their feed. Everything works out of the box - activate BuddyPress and the integration is automatic.

Frequently Asked Questions

Will my media appear in the WordPress Media Library?

No. WPMediaVerse media is managed through its own admin pages (Media > All Media) and frontend dashboard (My Media). This is intentional - it keeps the WordPress Media Library clean for your theme images, post attachments, and other site assets.

Can I use WPMediaVerse without BuddyPress?

Yes. WPMediaVerse is a standalone plugin. It creates its own pages (/explore-media/, /my-media/, /upload-media/) and works on any WordPress site. BuddyPress integration activates automatically when BuddyPress is installed but is completely optional.

What happens to my data if I deactivate the plugin?

Deactivation stops all plugin functionality but your data stays intact in the database. Reactivating restores everything. Deleting the plugin (uninstall) removes all custom tables and data permanently.

Can I migrate from rtMedia / MediaPress / BuddyBoss?

Yes. WPMediaVerse Pro includes WP-CLI migration tools that import media records, preserving original upload dates, author attribution, and file URLs. See Migration Tools.

How does search work?

WPMediaVerse has its own search system that queries the mvs_media_index table directly. It searches titles and descriptions. Tags and categories use WordPress taxonomies for filtering.

Does it work with page builders?

Yes. WPMediaVerse provides Gutenberg blocks (Media Grid, Explore Feed, Album Viewer) and shortcodes for Elementor, Beaver Builder, and other builders. The blocks use the WordPress Interactivity API for dynamic behavior.

Installation

Get WPMediaVerse running on your WordPress site in under five minutes - install, activate, and your community is ready to start uploading.

Requirements

• WordPress 6.5+
• PHP 7.4+
• MySQL 5.7+ or MariaDB 10.4+
• BuddyPress 12.0+ (optional, for social integration)

Installing via WordPress Admin

1. Go to Plugins > Add New Plugin in your WordPress dashboard.
2. Search for WPMediaVerse.
3. Click Install Now, then Activate.

Installing via ZIP Upload

1. Download the wpmediaverse.zip file from wbcomdesigns.com.
2. Go to Plugins > Add New Plugin > Upload Plugin.
3. Choose the ZIP file and click Install Now.
4. Click Activate Plugin.

Installing via FTP

1. Unzip the downloaded archive.
2. Upload the wpmediaverse folder to /wp-content/plugins/.
3. Go to Plugins in your dashboard and activate WPMediaVerse.

What Happens on Activation

When you activate WPMediaVerse, the plugin automatically:

• Creates custom database tables for media index, stats, reactions, comments, favorites, follows, conversations, messages, collections, access grants, and webhooks - all separate from wp_posts for maximum performance.
• Registers the mvs_album and mvs_collection custom post types (media itself uses the custom mvs_media_index table, not wp_posts).
• Registers the mvs_tag and mvs_category taxonomies.
• Adds default capabilities to the Administrator, Editor, Author, Contributor, and Subscriber roles.
• Redirects you to the Setup Wizard for initial configuration.

Deactivation and Uninstall

Deactivation stops all plugin functionality but keeps your data intact.

Uninstall (deleting the plugin) removes all plugin data including:

• All mvs_album and mvs_collection posts
• All custom database tables (including the mvs_media_index media records)
• All plugin options and transients

To preserve data after uninstalling, export your media library first.

Setup Wizard

After you activate WPMediaVerse, a short wizard guides you through the only settings you need to make your first upload possible. The whole thing takes about two minutes.

Step 1: Welcome

A quick overview of what WPMediaVerse does - uploads and albums, the social layer (reactions, comments, favorites, follows), AI moderation and privacy controls, and optional BuddyPress integration. Click Let's Get Started to continue, or Skip setup to jump straight to the dashboard.

Step 2: Pages

The wizard confirms the three frontend pages that were created automatically on activation:

Page	Default slug	Purpose
Explore Media	/explore-media/	Public gallery where visitors browse all media
My Media	/my-media/	Personal dashboard for users to manage their uploads
Upload Media	/upload-media/	Frontend upload form, linked from the Explore page header

If any page is missing, the wizard flags it and asks you to reactivate the plugin. Click Continue when the pages are in place.

Step 3: Display

Configure how media appears on your site.

Option	Choices	Default
Grid Columns	2, 3, 4	3
Items Per Page	12, 24, 48	24
Thumbnail Style	Square (cropped), Original proportions	Square

You can change these any time later under Media > Settings.

Step 4: Done

The wizard marks setup as complete (the mvs_setup_complete option) and redirects you to the Media Overview dashboard.

From here you can:

• Upload your first media file
• Configure AI moderation settings
• Set up BuddyPress integration (if BuddyPress is active)

Role Capabilities

The wizard itself does not configure roles. On activation, WPMediaVerse adds default media capabilities to the Administrator, Editor, Author, Contributor, and Subscriber roles. You can review and change these at any time in Media > Settings.

Skipping the Wizard

You can skip the wizard at any step using the Skip setup link, which takes you to the dashboard. Once setup is marked complete, the wizard no longer runs automatically on subsequent visits.

Your First Upload

Upload your first photo in two minutes - drag, drop, set privacy, done. Here is exactly how it works.

Option 1: Use the Upload Block or Shortcode

Add the upload form to any page using either the Gutenberg block or shortcode.

In the Block Editor: Add the WPMediaVerse: Media Upload block to your page.

In the Classic Editor or any text area:

[mvs_upload]

Option 2: Upload via REST API

Use the REST endpoint directly (for custom integrations):

curl -X POST https://yoursite.com/wp-json/mvs/v1/media \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -F "file=@/path/to/image.jpg" \
  -F "title=My First Upload" \
  -F "privacy=public"

The Upload Process

When you upload a file, WPMediaVerse:

1. Validates the MIME type against your allowed file types list.
2. Checks the file size against your configured maximum (default: 100 MB).
3. Scans for duplicate files using SHA-256 hash comparison.
4. Strips EXIF GPS data from images (if enabled - on by default).
5. Stores the file using your configured storage driver (local by default).
6. Creates a record in the mvs_media_index table with the title, privacy level, and file metadata (media is not stored as a WordPress post).
7. Runs AI analysis if auto-analyze is enabled (requires OpenAI API key).
8. Runs AI moderation if auto-moderate is enabled.
9. Records BuddyPress activity if BuddyPress is active.

Supported File Types

By default, WPMediaVerse accepts:

Type	Formats
Images	JPEG, PNG, GIF, WebP
Video	MP4, WebM
Audio	MP3 (MPEG), OGG

You can customize allowed file types in Media > Settings > General.

Setting Privacy on Upload

Each file can have one of 6 privacy levels:

Level	Who Can See It
Public	Everyone, including logged-out visitors
Members Only	Any logged-in WordPress user
Friends	BuddyPress friends of the uploader (requires BuddyPress)
Group	Members of a specific BuddyPress group (requires BuddyPress)
Private	Only the uploader and administrators
Custom	A specific list of user IDs (managed via API or access rules)

The default privacy level is set in Media > Settings > General > Default Privacy Level.

After Uploading

Your uploaded media appears:

• On the media archive page (/wp-json/mvs/v1/media in the API)
• In the Media > All Media list in your admin dashboard
• In the Media tab on your BuddyPress profile (if BuddyPress is active)
• In your media dashboard (use [mvs_dashboard] shortcode)

Free vs Pro Comparison

WPMediaVerse Free is a full-featured media platform. WPMediaVerse Pro unlocks advanced tools for professional communities, monetization, and engagement.

Free and Pro release in lockstep and share the same version number. See the changelog for what shipped in each release, or Pro feature overview for the current Pro feature set.

Quick Comparison

Feature	Free	Pro
Media Upload & Management
Drag & drop upload (photo, video, audio)	Yes	Yes
Bulk upload	Yes	Yes
Title, description, tags, categories	Yes	Yes
EXIF stripping & duplicate detection	Yes	Yes
Thumbnail generation (3 sizes)	Yes	Yes
Custom storage path	Yes	Yes
Amazon S3 cloud storage	--	Yes
BunnyCDN cloud storage	--	Yes
Feed Layouts
Default grid layout	Yes	Yes
Instagram layout (square grid + stories)	--	Yes
Pinterest layout (masonry cards)	--	Yes
Flickr layout (justified gallery)	--	Yes
Dribbble layout (portfolio shots)	--	Yes
Social Features
Follow / unfollow users	Yes	Yes
Emoji reactions on media	Yes	Yes
Threaded comments	Yes	Yes
Favorites (save for later)	Yes	Yes
@Mentions in comments	Yes	Yes
Share to social media	Yes	Yes
Direct messages (1-on-1 chat)	Yes	Yes
Voice messages in DMs	Yes	Yes
Media sharing in DMs	Yes	Yes
Message requests & privacy controls	Yes	Yes
Content Organization
Albums with cover photos	Yes	Yes
Collections (curated boards)	Yes	Yes
Stories (24-hour ephemeral posts, seen-by receipts)	--	Yes
Gallery groups (multi-photo posts)	Yes	Yes
Privacy & Moderation
Public / Members Only / Private	Yes	Yes
Friends Only privacy level	Yes (needs BuddyPress Friends)	Yes
Group Members Only privacy level	Yes (enforced)	Yes (picker UI)
Custom privacy (specific users)	Yes (enforced)	Yes (picker UI)
Album-level privacy inheritance	Yes	Yes
Privacy presets	--	Yes
Bulk privacy updates	--	Yes
AI content moderation (OpenAI)	Yes	Yes
Google Cloud Vision moderation	--	Yes
AWS Rekognition moderation	--	Yes
Claude (Anthropic) moderation	--	Yes
User reporting	Yes	Yes
User blocking	Yes	Yes
GDPR data export & erasure	Yes	Yes
Video
Video upload & playback	Yes	Yes
Multi-quality transcoding (720p/480p/360p)	--	Yes
HLS adaptive streaming	--	Yes
Video chapter markers	--	Yes
Resume playback (pick up where you left off)	--	Yes
Auto-captions via OpenAI Whisper	--	Yes
Video analytics & heatmaps	--	Yes
Image Processing
Basic text watermarking	Yes	Yes
Logo watermarking with positioning	--	Yes
Watermark opacity & font control	--	Yes
Gamification
Photo Challenges (themed competitions)	--	Yes
1v1 Photo Battles	--	Yes
Single-elimination Tournaments	--	Yes
Media Boosts (spend points for visibility)	--	Yes
Upload Streaks with milestones	--	Yes
Weekly Autopilot (auto-create challenges)	--	Yes
XP integration with wb-gamification	--	Yes
Quotas & Monetization
Per-user upload quotas (count + storage)	--	Yes
Quota packages (Free, Premium, etc.)	--	Yes
MemberPress integration	--	Yes
Paid Memberships Pro integration	--	Yes
WooCommerce integration	--	Yes
Credit transaction log	--	Yes
User Profiles
Public profile page (/media/@username/)	Yes	Yes
Follow / Message buttons	Yes	Yes
Custom avatar upload	Yes	Yes
Inline profile editing	--	Yes
Admin Tools
Media overview dashboard	Yes	Yes
Media list with bulk actions	Yes	Yes
Settings (general, display, social, AI)	Yes	Yes
Competitions dashboard	--	Yes
Challenge manager with theme library	--	Yes
Tournament bracket manager	--	Yes
Battle monitor	--	Yes
Video analytics dashboard	--	Yes
Quota & credits management	--	Yes
Media stats & insights	--	Yes
BuddyPress Integration
Profile media tab	Yes	Yes
Group media tab	Yes	Yes
Activity stream media	Yes	Yes
Notifications (likes, comments, follows)	Yes	Yes
Gutenberg Blocks
Core blocks (Media Grid, Player, Album, Upload, Stats, Explore Feed, Lock Overlay, Member Photos, PDF Viewer)	Yes (9)	Yes (inherited)
Pro feature blocks (Tournament, Challenge, Battle, Leaderboard, Compete Hub)	--	Yes (5)
Pro feed-layout blocks (Instagram, Flickr, Pinterest, Dribbble)	--	Yes (4)
Pro list blocks (Tournaments List, Challenges List, Battles Active)	--	Yes (3)
Mix layouts per-page	--	Yes
Developer
REST API (100+ endpoints, mvs/v1 namespace)	Yes	Yes
Pro REST API (37 additional endpoints, mvs-pro/v1 namespace)	--	Yes
Lightbox download + share REST endpoints	Yes	Yes
150+ action and filter hooks	Yes	Yes
Template override system	Yes	Yes
Custom storage driver API	Yes	Yes
WP-CLI commands (18 commands, wp mvs namespace)	Yes	Yes
wp mvs generate-video-thumbnails (poster backfill)	Yes	Yes
Migration tools (rtMedia, MediaPress, BuddyBoss)	--	Yes
MigrationPage admin (per-platform cards)	--	Yes
Accessibility
WCAG 2.1 AA pass on customer-facing UI	Yes	Yes
aria-label on icon buttons + aria-pressed on toggles	Yes	Yes
:focus-visible outlines + keyboard navigation	Yes	Yes
Theme dark-mode support (BuddyX Pro / generic class-based)	Yes	Yes
Integrations
BuddyPress 12+	Yes	Yes
wb-gamification	--	Yes
MemberPress	--	Yes
Paid Memberships Pro	--	Yes
WooCommerce	--	Yes
OpenAI (moderation + captions)	Yes	Yes
Google Cloud Vision	--	Yes
AWS Rekognition	--	Yes
Amazon S3	--	Yes
BunnyCDN	--	Yes

A note on the privacy rows

Privacy is the one area where "Free vs Pro" is not a clean on/off split, so it is worth stating precisely:

• Free enforces all six privacy levels. PrivacyService gates viewing for public, members, friends, group, private and custom. If a media item carries one of those levels - set by an import, the REST API, an album inheriting its privacy, or Pro before a licence lapsed - Free honours it. Your members' private media does not become visible because Pro is inactive.
• Free's upload form exposes three of them, plus Friends Only when the BuddyPress Friends component is active: Public, Members, Friends (conditional) and Only Me. Group and Custom are enforced but have no picker in the stock Free upload form.
• Pro adds the interface, not the enforcement: a picker for all six levels with plain-language descriptions, saved presets, and bulk privacy updates across many items at once.
• Album-level privacy inheritance is Free. When media is added to an album, AlbumService clamps each item to the more restrictive of the two, filterable via mvs_album_inherit_privacy.

There is no "Followers Only" media privacy level in either plugin. followers appears only as a direct-message access setting (mvs_dm_access), which controls who may open a conversation with you - not who can see your media.

What You Get Free

WPMediaVerse Free is not a stripped-down trial. It is a complete media platform with:

• Full upload system with drag & drop, bulk upload, and duplicate detection
• Albums, collections, and gallery groups
• Complete social layer: follows, reactions, comments, favorites, mentions, sharing
• Built-in direct messaging with voice messages, file sharing, and read receipts
• User profiles with follow/message buttons and media grids
• AI content moderation via OpenAI
• BuddyPress integration (profiles, groups, activity, notifications)
• Full REST API with 100+ endpoints
• GDPR compliance (data export + erasure)
• User blocking and reporting

What Pro Adds

WPMediaVerse Pro is for sites that need professional-grade features:

• Visual identity - Choose from Instagram, Pinterest, Flickr, or Dribbble layouts to match your community's style
• Scale - Offload media to S3 or BunnyCDN for global CDN delivery and unlimited storage
• Video intelligence - Multi-quality transcoding, adaptive streaming, chapters, auto-captions, and engagement analytics
• Engagement - Gamification system with challenges, battles, tournaments, boosts, and streaks that keep users coming back
• Monetization - Quota packages with MemberPress/WooCommerce integration let you sell tiered upload plans
• Privacy - A picker UI for all six privacy levels, plus saved presets and bulk privacy management
• AI - Google Vision, AWS Rekognition, and Claude (Anthropic) for auto-tagging and advanced content moderation
• Migration - Import from rtMedia, MediaPress, or BuddyBoss with one WP-CLI command

Upgrading

1. Purchase a Pro license at wbcomdesigns.com
2. Upload and activate the wpmediaverse-pro.zip plugin
3. Enter your license key at Media > License
4. Pro features activate immediately - no data migration needed, no settings lost

Integrations

WPMediaVerse connects with 12+ third-party services and plugins out of the box. No custom code, no middleware - configure credentials in settings and the integration activates.

Integrations Admin Page (1.8.0)

Go to WPMediaVerse > Integrations for a visual view of the Wbcom plugin family - the products designed to work alongside WPMediaVerse. Each card shows the product logo, a short "why you'd want this" description, and a status badge (Connected, Installed, activate, or Not installed).

• Install free - installs and activates the companion plugin's free version in one click, without leaving the page.
• Learn more - links out to the product's page on the Wbcom store.
• Every companion plugin works standalone - installing one from this page does not tie it to WPMediaVerse, and WPMediaVerse simply lights up the matching integration when it detects the companion is active.

This page lists the family (WB Gamification, BuddyX/BuddyNext, and other Wbcom products); it's separate from the third-party service integrations (AI providers, cloud storage) documented below, which are configured under Settings.

Integration Map

Integration	Plugin	What It Does	Free	Pro
BuddyPress	Free	Profile media tabs, group media, activity stream, notifications	Yes	Yes
BuddyNext	Free	Enhanced member directory and profile blocks	Yes	Yes
WB Gamification	Free (separate plugin)	XP points, badges, leaderboards for competitions (optional - competitions run without it, only points need it)	--	Yes
Amazon S3	Pro	Store all media files on S3 with CDN delivery	--	Yes
BunnyCDN	Pro	Store and deliver media via BunnyCDN edge network	--	Yes
OpenAI	Free	AI content moderation, auto-tagging, description generation	Yes	Yes
Google Cloud Vision	Pro	Advanced image labeling, object detection, safe search	--	Yes
AWS Rekognition	Pro	Face detection, content moderation, celebrity recognition	--	Yes
OpenAI Whisper	Pro	Automatic video/audio transcription to WebVTT captions	--	Yes
MemberPress	Pro	Auto-assign quota packages based on membership level	--	Yes
Paid Memberships Pro	Pro	Auto-assign quota packages based on PMPro level	--	Yes
WooCommerce	Pro	Sell upload quota packages as WooCommerce products	--	Yes
WordPress Webhooks	Free	Send real-time HTTP notifications on media events	Yes	Yes

Community & Social

BuddyPress

WPMediaVerse is the most complete media solution for BuddyPress communities. The integration activates automatically when BuddyPress is detected - no configuration needed.

What users get:

• A Media tab on every member profile showing their uploads in a grid
• A Media tab in every group where members upload and share within the group
• Media uploads appear as activity items in the BuddyPress activity stream with thumbnails
• Notifications when someone likes, comments on, or shares your media
• One-click media sharing from the lightbox directly into BuddyPress activity

What admins get:

• Zero configuration - activate BuddyPress and the integration works
• Media tab visibility follows BuddyPress privacy settings
• Activity items follow BuddyPress moderation rules
• Compatible with BuddyPress 12.0+

See BuddyPress Integration for full details.

BuddyNext

If you use the BuddyNext theme, WPMediaVerse detects it automatically and enhances the member directory with media counts and the profile layout with media grid blocks. As of 2.0.0, BuddyNext also changes how individual media links behave - see Activity Stream Media for details.

wb-gamification (Pro)

This integration requires the separate, free WB Gamification plugin. Points (XP) are only earned or spent when WB Gamification is installed and active. Without it, the competition features still run fully - members can create and enter Challenges, Battles, and Tournaments, vote, and see winners - but no points are awarded for wins or streaks, and the point-spending controls (such as Media Boosts) stay hidden. Every MediaVerse award/spend path is guarded, so Pro works correctly whether or not WB Gamification is present.

When WB Gamification is active, WPMediaVerse Pro feeds it points for these competition outcomes via the wb_gam_points_for_action filter:

Action	When	Default XP
Win a challenge (1st)	First place in a challenge	200
Win a challenge (2nd)	Second place	100
Win a challenge (3rd)	Third place	50
Enter a challenge	Submit an entry that meets the rules	10
Win a tournament round	Advance one bracket round	configurable
Win a tournament	Tournament champion	configurable
Reach a streak milestone	Hit a daily-upload streak threshold	configurable

Challenge XP values are configured per competition when you create a Challenge (1st / 2nd / 3rd / participation), not as a single global table. WB Gamification handles the points ledger, badges, leaderboards, and leveling - WPMediaVerse Pro only tells it which competition outcome occurred.

Get the free plugin: WB Gamification.

Cloud Storage

Amazon S3 (Pro)

Offload every upload to an S3 bucket. Files are served from S3 directly (or via CloudFront if configured).

What you get:

• Unlimited storage (pay-as-you-go with AWS)
• Global CDN delivery when paired with CloudFront
• Signed URLs for private/members-only media
• Automatic retry (3 attempts) on upload failure
• Connection test button in admin to verify credentials

Setup: Paste your bucket name, region, access key, and secret key into Media > Settings > Storage > Amazon S3. Click "Test Connection" to verify. New uploads go to S3 immediately.

Security: Store credentials in wp-config.php instead of the database:

define( 'MVS_PRO_AWS_ACCESS_KEY', 'AKIA...' );
define( 'MVS_PRO_AWS_SECRET_KEY', '...' );

See Cloud Storage for IAM policy and full setup guide.

BunnyCDN (Pro)

Store and deliver media through BunnyCDN's global edge network.

What you get:

• 114 edge locations worldwide
• Automatic image optimization
• Per-request pricing (no minimum commitment)
• Simpler setup than AWS (one API key)

Setup: Enter your storage zone name, API key, and CDN hostname into Media > Settings > Storage > BunnyCDN.

Custom Storage Drivers

WPMediaVerse uses a StorageDriverInterface that any developer can implement. Build drivers for Google Cloud Storage, DigitalOcean Spaces, Wasabi, Backblaze B2, or any S3-compatible service.

See Custom Storage Drivers for the interface spec.

AI & Machine Learning

OpenAI (GPT + Vision)

Built into the free plugin. Uses the OpenAI API for:

• Content moderation - Automatically flag inappropriate uploads before they appear on the site
• Auto-tagging - AI suggests relevant tags based on image content
• Description generation - Generate alt text and descriptions for accessibility
• Monthly budget cap - Set a dollar limit to prevent unexpected API costs

Setup: Paste your OpenAI API key into Media > Settings > AI & Moderation.

Google Cloud Vision (Pro)

Adds Google's image analysis capabilities:

• Label detection - Identify objects, locations, activities in photos
• Safe search - Detect explicit, violent, or medical content
• Text detection - Extract text from images (OCR)
• Circuit breaker pattern prevents API hammering on failures

Setup: Paste your Google Cloud API key into Media > Settings > AI & Moderation > Google Vision.

AWS Rekognition (Pro)

Adds Amazon's image and video analysis:

• Object and scene detection - Identify objects with confidence scores
• Face detection - Detect faces with attributes (smile, glasses, age range)
• Content moderation - Flag suggestive, violent, or explicit content
• Circuit breaker pattern with automatic recovery

Setup: Uses the same AWS credentials as S3 storage, or set separate credentials in Media > Settings > AI & Moderation > AWS Rekognition.

OpenAI Whisper (Pro)

Automatic speech-to-text transcription for video and audio uploads:

• Generates WebVTT caption files
• Captions are searchable and displayed as subtitles in the video player
• Process runs asynchronously via Action Scheduler
• Supports 50+ languages

Setup: Enable at Media > Settings > Video > Auto-Captions (uses the same OpenAI API key).

Monetization

MemberPress (Pro)

Automatically assign upload quota packages based on MemberPress membership levels.

How it works:

1. Create quota packages in Media > Quotas (e.g., "Free: 50 photos", "Premium: unlimited")
2. Map each MemberPress membership to a quota package
3. When a user purchases or is assigned a membership, their quota updates automatically
4. When a membership expires, the user reverts to the default package

Paid Memberships Pro (Pro)

Same automatic package assignment, but using PMPro membership levels instead of MemberPress.

WooCommerce (Pro)

Sell upload quota packages as WooCommerce products:

How it works:

1. Create quota packages in Media > Quotas
2. Create a WooCommerce product and map it to a quota package
3. When a customer completes checkout, their quota package activates
4. If the order is refunded or cancelled, the package reverts to default

This lets you sell storage tiers directly from your WooCommerce store.

Webhooks

WPMediaVerse can send real-time HTTP POST notifications to external services when events occur:

Event	Payload
Media uploaded	Media ID, file URL, author, type, privacy
Media deleted	Media ID
Comment posted	Comment ID, media ID, author, content
Reaction added	Media ID, user ID, reaction type
Report submitted	Media ID, reporter ID, reason
Moderation changed	Media ID, old status, new status

Use cases:

• Notify a Slack channel when new media is uploaded
• Trigger a Zapier workflow on media events
• Sync media metadata to an external CMS or DAM
• Log moderation actions to an audit system

Setup: Add webhook URLs at Media > Settings > Webhooks. Each webhook can filter by event type.

See Webhooks for payload formats and authentication.

WordPress Core

Site Health

WPMediaVerse registers 3 custom tests in Tools > Site Health:

• Database tables - Verifies all custom tables exist and have the expected schema
• Upload directory - Checks that the wpmediaverse upload directory is writable
• Required pages - Confirms Dashboard, Explore, and Upload pages are assigned

GDPR / Privacy Tools

• Export Personal Data - Exports all user media, comments, reactions, favorites, DMs, and follow relationships
• Erase Personal Data - Removes all of the above when processing an erasure request
• Privacy Policy - Suggests privacy policy text via WordPress's built-in privacy policy tool

See GDPR & Privacy Compliance.

REST API

WPMediaVerse exposes 50+ REST endpoints in the free plugin and 30+ additional endpoints in Pro, all under the mvs/v1 and mvs-pro/v1 namespaces. Any external application, mobile app, or headless frontend can consume the full API.

See REST API Reference and Pro REST API Reference.

WP-CLI

CLI commands for automation, migration, and maintenance:

wp mvs stats              # Show media stats
wp mvs migrate            # Run database migrations
wp mvs reindex            # Rebuild media index
wp mvs cache-flush        # Flush all caches
wp mvs prune-views        # Clean old view records
wp mvs cleanup-expired    # Remove expired stories/tokens
wp mvs moderation-stats   # Show moderation queue stats
wp mvs optimize           # Losslessly optimize an image
wp mvs migrate-storage    # Migrate files between storage drivers

See WP-CLI Commands.

Gutenberg Blocks

5 blocks for the block editor:

Block	Description
Media Grid	Display a filtered grid of media items
Explore Feed	Full explore page with search, tags, and pagination
Album Viewer	Display an album's contents
Lock Overlay	Restrict content visibility with a paywall-style overlay
Profile Edit	Inline profile editing block

See Gutenberg Blocks.

Shortcodes

For classic editor and page builders:

Shortcode	Description
[mvs_gallery]	Media grid with filtering
[mvs_upload]	Upload form
[mvs_dashboard]	User's media dashboard
[mvs_profile_edit]	Inline profile editing form

See Shortcodes.

What's New in 2.3.0

WPMediaVerse 2.3.0 is a correctness release. Photos taken on a phone stop landing sideways, media added to a private album stops being publicly visible, the archived-conversations tab arrives in chat, and members can sign in to the mobile app with the password they already have.

Included in Free. Every item on this page applies to the free version unless marked Pro. Paired with WPMediaVerse Pro 2.3.0 - install and test both together.

Phone photos keep their orientation

Images uploaded from a phone are rotated to match their EXIF Orientation tag before they are stored, so portrait shots no longer appear sideways in the grid, the lightbox, or an activity post. This runs on the normal upload path and on Replace file, and the stored width and height are re-recorded after rotation so grid layouts reserve the right space.

Sites that already normalise orientation upstream - some CDNs and phone-upload apps do - can skip the extra re-encode with the new mvs_apply_exif_orientation filter.

Media added to a private album inherits its album's privacy

A member who creates a Private album and uploads into it expects the contents to be private. Adding media to an album now clamps each item to the more restrictive of the two privacy levels, so a public photo added to a private album becomes private, and a private photo added to a public album stays private.

Nothing is ever made more public by this: the clamp only tightens. Album privacy inheritance is controllable with mvs_album_inherit_privacy, and each clamp fires mvs_media_privacy_clamped_by_album for auditing.

Album-level privacy inheritance is a Free feature. See Free vs Pro for exactly which parts of privacy are Free and which parts Pro adds.

Archived conversations

Chat gains a proper Archived tab. Archiving a conversation moves it out of your main list without deleting it, and it comes back on its own when the other person writes to you again - controllable via mvs_dm_unarchive_on_activity.

Alongside it, two long-standing chat annoyances are fixed:

• Tab counts are honest. The message-requests badge counts actual pending requests. Previously requests were counted from the main list, so the badge could read 0 while requests were waiting.
• Day separators and message times are grouped by day with Today / Yesterday headings.

Sign in to the app with your existing password

Members can now sign in to a native WPMediaVerse client with their normal WordPress password, and the site issues an Application Password behind the scenes - no more copying a generated credential by hand.

The exchange endpoint is public by necessity (there is nothing to authenticate with before you have a credential) and is guarded accordingly: a site-owner switch, a TLS requirement, uniform failure responses, the suspension gate, rate limiting applied before any credential is read, and a 409 rather than a silent two-factor bypass. See POST /auth/app-password.

Fixes you will notice

• Tall portraits are no longer clipped in the lightbox - they scale to fit instead of being cropped.
• The activity feed no longer distorts single images. Aspect ratios are preserved rather than force-cropped to a fixed height.
• Double-clicking Post no longer publishes the same comment twice. Duplicate comments within a short window are rejected; the window is filterable via mvs_comment_duplicate_window.
• Album counts ignore trashed media, so an album no longer advertises photos that are in the trash.
• No more phantom "sent you a message" notification when a conversation is merely opened.
• Demo data can be removed and re-imported. Previously the importer refused to run once demo data had been deleted, and reported that refusal as a success.
• Album dropzones are visible outside BuddyPress, and album assets load correctly under client-side navigation.

Pro 2.3.0

• Competition transitions no longer fire twice on sites upgraded from an earlier version, so challenges and tournaments do not double-advance.
• Turning Boosts off unschedules its expiry job instead of leaving a cron entry behind.
• Quota widget polish - the dashboard quota widget is spaced properly, and it no longer appears at all for members who have no quota package and no limits, where it previously showed a "No Package" heading above three "Unlimited" rows and an offer to contact an administrator for more storage. Site owners who use it to advertise upgrades still get it, and mvs_pro_quota_widget_visible forces it back on.
• Autopilot "Run Now" sits in a proper action row on the Competitions dashboard.

For developers

• The complete option list now lives in Settings Reference.
• New filters: mvs_apply_exif_orientation, mvs_album_inherit_privacy, mvs_comment_duplicate_window, mvs_dm_unarchive_on_activity, mvs_pro_quota_widget_visible (Pro).
• New action: mvs_media_privacy_clamped_by_album.
• The moderation queue route is GET /moderation. Earlier revisions of the REST reference showed /moderation/queue, which returns 404.
• Four watermark hooks that appeared in older revisions of the hooks reference (mvs_watermark_config, mvs_generate_watermark, mvs_watermark_invalidated, mvs_watermarks_invalidated_all) do not exist in the code and have been removed from the docs. The real extension points are mvs_watermark_enabled, mvs_watermark_stamp_file and, in Pro, mvs_watermark_font_path.

Compatibility

Free and Pro release in lockstep. Install WPMediaVerse 2.3.0 and WPMediaVerse Pro 2.3.0 together - Pro 2.3.0 expects the Free 2.3.0 service surface.

No database migration is required beyond the automatic Migrator run on activation, and no settings are lost on upgrade.

What's New in 2.2.0

WPMediaVerse 2.2.0 is a polish and privacy release: the whole REST surface can now follow your community's privacy setting, chat gets live reactions and a cleaner attachment experience, and a batch of visible UX fixes across profiles, the lightbox, Explore layouts, and admin settings.

Included in Free. Every item on this page applies to the free version unless marked Pro. Paired with WPMediaVerse Pro 2.2.0 - install and test both together.

Private-community REST gate

When the host community is private (for example a BuddyNext site in private mode), the entire REST surface now requires a logged-in user - including public reads, and including the Pro mvs-pro/v1 namespace (tournament brackets and other public Pro reads) - so nothing leaks to logged-out visitors through the API. Unauthenticated requests get 401 mvs_community_private. The gate is off by default and developer-controllable via the mvs_rest_require_auth and mvs_rest_can_access filters. See REST API: Authentication.

Messaging improvements

• Live reactions - a reaction added to a message you already received now appears for you in real time, without a page reload.
• Media-only attachments - chat attachments now accept images, video, and audio only. Documents (PDF, DOC, ZIP) are rejected with a clear message, client- and server-side. Site owners who need documents back can extend the mvs_dm_allowed_file_types filter. See Direct Messages.
• Upload feedback - attaching a video or audio file shows an "Uploading..." chip with a spinner, and Send waits until the upload finishes - a message can no longer go out without its file.

Profile and lightbox fixes

• Live follower counts - the follower and following numbers on a member profile update the moment you press Follow or Unfollow, on the default layout and on every Pro layout.
• Favorite heart - the lightbox Favorite button now fills and turns red when favorited (the state saved correctly before, but the color was stuck).

Explore empty states (Pro layouts)

The Flickr, Pinterest, and Dribbble Explore layouts now show a proper empty state when a search has no results or a tag does not exist - a heading naming the term, a "Browse all media" button, and popular-tag chips - instead of a generic message or, for unknown tags, a silently unfiltered feed. Matches the behavior the default layout has always had.

Admin polish

• The "Settings saved." notice can be dismissed, fades out on its own after a few seconds, and no longer follows you across settings sections.

Compatibility

• BuddyBoss and older BuddyPress - fixed a fatal error where bp_get_group_url() does not exist.
• Requires and pairs with WPMediaVerse Pro 2.2.0 (Pro is a lockstep release: shared competition-media formatting internals, no Pro-only feature changes).

What's New in 2.0.0

WPMediaVerse 2.0.0 is a major release: upload watermarking, a full pass to make the entire frontend translation-ready, privacy hardening across albums, collections, and protected media, and a batch of activity, moderation, and image-pipeline fixes.

Included in Free. Every item on this page applies to the free version. Paired with WPMediaVerse Pro 2.0.0 - install and test both together.

Upload watermarking engine

Every upload now flows through a single, consistent watermark stamp point - at upload time and at file-replace time, so there's no way to bypass it by replacing a file after the fact. WPMediaVerse Free ships the engine and the option schema; WPMediaVerse Pro adds the Settings UI (Watermark Type, Logo, Position, Opacity) and the renderer that actually draws the mark. See Watermarking: Free vs Pro. Watermark stamping now fails closed - if the renderer can't draw the mark, the upload is logged as an error instead of silently serving an un-watermarked original.

Full frontend translation readiness

Every Interactivity API store, the shared-UI store, classic scripts, and the messaging module now ship translatable strings through a standard i18n delivery pipeline. Previously, roughly 165 JavaScript strings inside Interactivity modules were English-locked regardless of the site's language setting - the entire customer-facing frontend is translation-ready now.

Privacy hardening: albums, collections, protected media

• Album and collection privacy is enforced at the database level, so visitor pagination counts stay correct and private items never leak into a count or a listing.
• Protected media shows a proper login gate in the media slot instead of a 404, while still returning the correct 403 status to unauthorized requests.
• Private collection single views and their REST responses are gated - previously they could leak the collection's title and structure to unauthorized viewers.
• Album and collection privacy-stub rows no longer show up as broken tiles on Explore, the media grid, or the media feed, and their index row is purged on delete.

Explore feed scope filters

The media listing endpoint gains scope=followers and scope=self, working across every layout (grid and every Pro feed layout) - not just the default. See Explore Feed Scope Filters.

Album creation from the upload modal

You can create a new album directly from the upload modal instead of navigating away to create one first. See Media Upload.

Activity, lightbox, and notification fixes

• Favorite, Save, Share, and Download buttons work in the media lightbox inside the BuddyPress activity stream.
• Batch uploads to an album now show a "View all photos" link in the activity entry.
• BuddyPress notifications are cleaned up when media is deleted, and commenting on activity media no longer sends a duplicate notification. See BuddyPress Notifications.
• Direct-message reactions can be removed and are correctly attributed.
• Moderation actions no longer corrupt unrelated posts.

Lossless GPS/EXIF strip

GPS location data is stripped from photos without a lossy re-encode, preserving image quality and the colour profile.

Moderation default changed to Flag

The When AI Flags Content default changed from Delete permanently to Flag for review, so a fresh install can never auto-delete uploads before an admin has chosen otherwise. See AI & Moderation Settings.

Admin menu rename: "Media Moderation"

The admin sidebar label Moderation is now Media Moderation, to avoid ambiguity with WordPress's general moderation terminology. See AI & Moderation Settings.

App pages use the theme's no-sidebar template

App pages (Dashboard, Explore, Upload, and similar plugin-owned pages) now use the active theme's no-sidebar page template for a cleaner full-width layout, when the theme provides one.

BuddyNext: media links open their activity post

When BuddyNext is active, media links and /media/{slug}/ URLs redirect to the BuddyPress activity entry the media was posted in, instead of rendering as a separate public page. A BuddyNext-side settings toggle switches back to dedicated media pages if you want a standalone page per item. See Activity Stream Media.

Under the hood

New filter mvs_suppress_bp_comment_notification controls the BuddyPress comment-notification bridge (#bp-notifications-mvs)). MediaRepositoryInterface now declares get_url_for_viewer() for viewer-aware URLs to the full original file. Filterable avatar (mvs_user_avatar_url) and profile-link (mvs_user_profile_url) seams were added for BuddyNext integration. The dead watermark preview/serve system and the 1.9.0 admin access-rules UI were both removed - access-rule enforcement continues in the backend via the REST API.

Upgrade notes

• Pairs with WPMediaVerse Pro 2.0.0 - install and test both together.
• No manual action needed for the privacy or watermark changes - they apply automatically on update.
• If you relied on the 1.9.0 access-rules admin screen, switch to managing access rules via the Privacy & Access Control REST API.
• If your site prefers standalone media pages under BuddyNext, use BuddyNext's settings toggle after updating (the new default sends media links to the activity feed).

What's New in 1.9.0

WPMediaVerse 1.9.0 adds interests-based onboarding, a big native-app readiness push across the REST API, and several messaging and profile improvements, alongside a batch of QA-driven fixes.

Included in Free. Every item on this page applies to the free version. Pro picks up these improvements automatically because Pro builds on top of free.

Interests & personalized onboarding

New members can choose interests, get a ranked list of suggested people to follow, and request an interest-aware feed. See Interests & Personalized Onboarding for the full REST API.

Native-app readiness

A broad pass across mvs/v1 makes the API fully drivable without a browser session: the /app/config endpoint, the interest endpoints, and viewer-aware fields on media responses. This is the foundation the official MediaVerse app and any headless client build on.

Direct messages: search and moderation

• Per-conversation message search - search message content within a single conversation via GET /conversations/{id}/messages/search.
• Content moderation on DMs - messages now pass through the same mvs_message_content_check filter seam that guards other content types, so a host running a word-blocklist for posts and comments can apply it to DMs too.

See Direct Messages.

Followers/following modal + profile overflow menu

Follower and following counts on a profile now open a modal listing the users, instead of requiring a separate page. Member profiles also gain an overflow menu with Report.

Manage blocked members from Edit Profile

Blocked members can now be reviewed and unblocked from the Edit Profile screen, in addition to the REST API. See User Blocking & Reporting.

"Also share as a story" on upload

The upload flow gains an option to also share the upload as a story at the same time, instead of uploading and then separately posting to Stories.

Access-rules admin screen (retired in 2.0.0)

1.9.0 added an admin screen for managing per-media access rules, with the watermark display wired to the site's configured logo. This screen was retired in 2.0.0 - access-rule enforcement stays in the backend (REST API and AccessRulesService), and rules are managed via the Privacy & Access Control REST API rather than a dedicated admin UI. If you're running 1.9.0, this page still exists; update to 2.0.0 and use the REST API going forward.

AI moderation controls (carried from 1.8.0)

The Anthropic (Claude) provider, owner-configurable AI Flag Criteria, and Custom Flag Terms shipped in 1.8.0 - see What's New in 1.8.0 and AI & Moderation Settings.

Masonry default (carried from 1.8.0)

The Original-proportions masonry grid became the default Thumbnail Style in 1.8.0; 1.9.0 confirms this as the default Explore grid style with the same escape hatch back to the fixed square grid (Settings > Display, or the mvs_default_thumbnail_style filter).

Theme templates and child themes

Child themes can now override MediaVerse templates - member partials, messages, and layout pages resolve theme-first before falling back to the plugin's own templates. See Template Overrides.

BuddyNext: media links open in the activity feed

When BuddyNext is active, media links open the activity they were posted in by default instead of a standalone media page. See Activity Stream Media (documented in full under the 2.0.0 lockstep behavior, since the filter this relies on is unchanged across both releases).

Smaller fixes

• Media comments no longer leak onto unrelated posts or pages (existing comments repaired automatically on update).
• Competition pages (Compete, Battles, Challenges, Tournaments) keep their MediaVerse styling when BuddyNext is active.
• Smart collections report their real item count in the list.
• AI moderation now runs when only Auto-Moderate is enabled (it was being skipped before).
• Theme-defense fixes for BuddyX and Reign (tab text, lightbox open); Instagram action buttons hardened against theme button styles.
• Cloud storage display and migration are more robust across admin operations.

Under the hood

New wp mvs cert functional certification engine - a boot smoke test across every REST route plus dead-toggle oracles, gated at 100% coverage in CI. All WordPress.org Plugin Check errors resolved (30 to 0).

Upgrade notes

• Pairs with WPMediaVerse Pro 1.9.0 - install both updates together.
• If you use the 1.9.0 access-rules admin screen, plan to move to the REST API workflow before or during your 2.0.0 update.

What's New in 1.8.0

WPMediaVerse 1.8.0 adds configurable AI moderation with a new Claude provider, working image and text watermarks, a masonry media grid as the new default, member blocking from the frontend, an Integrations page for the Wbcom plugin family, and a long list of QA-driven fixes across storage, video, and theme compatibility. No database schema change.

Included in Free. Every item on this page applies to the free version unless marked Pro. Pro picks up these improvements automatically because Pro builds on top of free.

Integrations page

A new WPMediaVerse > Integrations admin page lists the Wbcom plugin family with product logos, short descriptions, and store links, plus a one-click companion installer that installs and activates a companion plugin without leaving the page. See Integrations.

Member blocking from the frontend

Members can block or unblock another member directly from their profile - a Block toggle next to Follow and Message. Blocking already hid a blocked member's media and refused their follows and DMs; this release adds the missing frontend control to actually do it. See User Blocking & Reporting.

Configurable AI moderation + Claude provider

• AI Flag Criteria checkboxes let you choose which categories the AI flags (nudity, violence, hate, self-harm, drugs, spam), plus a Custom Flag Terms field for your own terms (e.g. weapons, gambling, political content). All categories are on by default.
• Claude (Anthropic) joins OpenAI, Google Vision, and AWS Rekognition as a selectable AI provider.
• Delete permanently is now an option for When AI Flags Content - removes the media and its files from local and cloud storage.
• The AI settings tab shows only the selected provider's credentials, and the per-call cost is plugin-managed instead of a manual field.

See AI & Moderation Settings.

Masonry grid is now the default

The Explore and media-grid feed now shows every image at its native aspect ratio by default (masonry, no cropping or gaps). Grid tiles also serve a larger thumbnail so they stay sharp on HiDPI/retina screens. Sites that prefer the uniform square crop can restore it in Settings > Display, or site-wide with the mvs_default_thumbnail_style filter. See Display Settings.

Watermark fixes

Selecting Watermark Type "Image" now applies the configured logo (it was being dropped before). Restricted (gated) images show the watermarked preview to visitors without access, instead of a plain blurred thumbnail - watermarking applies to images only, never video or audio.

Video posters everywhere

Video tiles now show the video's real first frame - instead of a generic placeholder - on My Media, the explore-feed block, and the Pinterest/Flickr/Dribbble/Instagram layout grids, including Load More, matching the Explore grid. All client-side thumbnail renderers now follow the same video-first contract as the server.

Storage display and migration fixes

• Media uploaded before a cloud service was connected now displays from where it actually lives, instead of a fabricated CDN URL that 404'd.
• Migrating storage moves a media's thumbnails and other variants alongside the original, and only flips the media to the new service once the full set has transferred.
• "Free up server space" never deletes a local file whose cloud copy can't be verified.
• Storage paths left inconsistent by earlier versions are repaired automatically in the background after update - small batches, only affected media. Disable with the mvs_storage_repair_enabled filter or run manually with wp mvs repair-storage.

Theme and UI fixes

• The Explore lightbox now opens in place instead of stacking over the previous screen.
• Explore and the dashboard share one REST client with document-level event delegation, so Load More and other actions keep working after client-side navigation.
• Dark mode follows the active BuddyX/Reign theme toggle.
• Like, comment, bookmark, share, and other action buttons on the Instagram layout run their action instead of opening the lightbox.
• The dashboard, create-modal, chat tabs, and lightbox action buttons keep their flat, readable styling under themes that restyle plain buttons (BuddyX, Reign).
• Lightbox Share now works on non-HTTPS sites via a fallback copy method.
• Paginated Explore and member profile pages (page 2+) return HTTP 200 instead of a soft 404, so search engines keep them indexed.

Smaller fixes

• Smart collections with more than one rule of the same type now match with OR instead of AND (e.g. tag Image OR tag Video), so they return items instead of resolving to zero.
• "Followers only" online-status visibility now actually hides presence from non-followers.
• The story viewer plays video and audio stories correctly instead of showing a broken image.
• Direct-message attachments are scoped to their conversation so only participants can view them.
• REST POST /conversations accepts an as_request flag so a message can open as a pending request instead of landing directly in the inbox.

Under the hood

New filters: mvs_ai_moderation_terms, mvs_ai_cost_per_call, mvs_storage_repair_enabled, mvs_default_thumbnail_style, mvs_strip_dead_bp_links, mvs_dead_bp_link_patterns, mvs_dm_denial_message, mvs_dm_denial_reason, mvs_collections_enabled. New UploadService::sideload_external_file() for bringing outside files into the library. The frontend was refactored onto a shared window.mvsRest client plus a router store for client-side navigation. All WordPress.org Plugin Check errors resolved (30 to 0, continued into 1.9.0).

Upgrade notes

• Pairs with WPMediaVerse Pro 1.8.0 - install both updates together.
• No database migration runs for this release.
• If your site relies on the square-crop grid, set Thumbnail Style back to Square in Settings > Display after updating (the default flipped to Original proportions).

What's New in 1.5.0

WPMediaVerse 1.5.0 closes two privacy and access bugs around non-public media, heals video posters that were stored with the wrong path before this version, and unifies the upload-and-serve pipeline so the underlying bug pattern cannot recur. There are no new customer-facing features; this is a correctness and robustness release.

Included in Free. Every item on this page applies to the free version. Pro picks up these fixes automatically because Pro builds on top of free - Pro 1.5.0 itself ships no code changes, it is a lockstep version bump. Install both updates together when running Pro.

Non-public uploads render their own thumbnails

Members, Friends, Only Me, Group, and Custom-access media no longer return a 403 for their own thumbnails after upload. The owner, and any viewer who has been granted access, now sees the thumbnail correctly - on local storage and on every cloud driver (BunnyCDN, S3, R2, Spaces).

Private uploads leave zero public footprint

Private media is now fully invisible to everyone except its owner:

• No BuddyPress activity entry is created for a private upload.
• The profile activity tab no longer surfaces broken thumbnail cards for private items.
• The profile media tab badge no longer counts private items when someone else is viewing.
• The Explore grid stays clean of private media.

Other non-public levels (Members, Friends, Group, Custom) keep their normal audience-discovery behavior - this change is specifically about media marked Private.

Legacy video posters heal automatically

Videos and audio uploaded before 1.5.0 could store a poster path pointing at the wrong subdirectory, which showed up as a broken still frame on cards, in the lightbox, and in feed previews. Database migration v15 runs once on the first page load after updating and re-derives the correct poster path from the on-disk file location. It is idempotent and safe to let run.

For cloud-storage sites, the migration is cloud-aware: it respects CDN-authoritative paths so existing cloud video posters keep resolving. If a poster still looks broken after the update, run wp mvs cloud-thumbs-backfill to push any local-only poster variants to the active cloud driver.

One unified read path for media URLs

Theme overrides and shortcode users can now call the same Core\MediaUrl helper that the plugin's own templates use, so custom integrations no longer have to know anything about the signed-URL plumbing. See Template Overrides for how to use it from a theme.

One unified upload pipeline

Image variants, video posters, audio cover art, and WebP/AVIF siblings now all flow through a single writer, so the file layout is identical for every media type. WebP and AVIF generation in particular was collapsed into one shared publisher, removing a duplicate-write footgun where the two paths could disagree about the destination directory. Adding a new output format in the future is now one extension point instead of five.

Shorter-lived thumbnail links, now filterable

Thumbnails embedded in long-lived surfaces (notification emails, RSS) are minted with a one-hour access TTL. Sites that cache those surfaces at the CDN for longer can widen the window with the new mvs_broadcast_thumbnail_ttl filter.

Under the hood

The upload and read pipeline is now backed by five focused services - MediaUrl, VariantSpec, StorageRouter, MediaVariantWriter, and PosterService. Existing methods are kept as shims for at least two releases per the deprecation policy, so custom code calling the old paths keeps working.

Upgrade notes

• Update Free to 1.5.0 first, then Pro to 1.5.0 if you run it.
• Migrator v15 runs automatically on the first request after the update. No manual action is needed.
• Cloud-storage sites with pre-1.5.0 video uploads: if any poster still appears broken after the update, run wp mvs cloud-thumbs-backfill.

What's New in 1.4.0

WPMediaVerse 1.4.0 is a robustness release that hardens cloud storage, gives site owners precise control over AI spend, and finishes a full mobile and translation pass. This page also folds in the headline additions from 1.3.0 (the image optimization pipeline) so you have a single place to catch up.

Included in Free. Every item on this page applies to the free version unless marked Pro. Pro picks up these improvements automatically because Pro builds on top of free.

Storage that follows the media, not a toggle

Each media item is now served from where it is actually stored, combined with its privacy. Switching the active storage driver, or turning a cloud service on, no longer breaks media you uploaded earlier. Public media stored on cloud serves directly from the CDN. Local media serves through the plugin's own delivery route. There is nothing to toggle: the old "Serve public cloud media directly" checkbox has been retired because direct CDN serving for public media is now automatic. See Cloud Storage for the full behavior.

Private media stays on local disk (Pro)

Only public media is eligible for the cloud. Private and restricted uploads, including their thumbnails and generated variants, never leave your local disk. Each item is effectively "cloud or local" based on its own privacy, so a private photo is never copied to a CDN.

Tighter access checks on private media

The delivery route re-verifies the viewer's permission on every request for non-public media, so a shared link cannot be used to leak a private item. If a Cloudflare R2 bucket has no public domain configured, WPMediaVerse will not emit a raw bucket URL (those are never public) and falls back to serving locally.

Per-feature control over AI

AI is opt-in and off by default, and you now choose exactly which AI features run and what they cost:

• Generate Descriptions and Generate Tags are independent toggles under Auto-Analyze, so you can run one without the other.
• The AI Provider dropdown correctly switches between OpenAI, Google Vision, and AWS Rekognition (Pro). Earlier builds could silently fall back to OpenAI.
• The Monthly AI Budget now caps moderation calls too, not just analysis and tagging. A fresh install ships with a conservative $10 cap so AI never runs against an unbounded bill before you set a budget.

See AI & Moderation Settings for the full matrix.

Image optimization pipeline (added in 1.3.0)

Uploads are now optimized losslessly: file sizes shrink with no visible quality loss, and an original is never made larger (if there is no gain, the original is kept). Animated GIFs are detected and left untouched. WebP copies are generated by default and AVIF copies are available as an opt-in, and browsers that support those formats receive the smaller file automatically across the explore grid, BuddyPress activity, dashboard, single media, and the lightbox. The All Media admin screen gains an Optimization column with savings badges and per-row Optimize and Details actions. See Image Optimization.

Reliable moderation queue actions

The per-row Approve and Reject buttons in the Moderation Queue work correctly again. They were previously dead because of nested forms in the markup.

100% mobile ready

Every customer-facing surface was verified at a 390px viewport. Explore tag chips, the upload privacy selector, and the lightbox close and gallery navigation controls were all raised to the 44px touch target floor, and the layouts produce zero horizontal overflow on a phone.

100% translation ready

Every user-facing string across the chat and messaging templates is wrapped for translation, the BuddyPress activity media script is bridged for JavaScript translations, and the translation template files were regenerated. The plugin is ready for full localization out of the box.

What's New in 1.2.0

WPMediaVerse 1.2.0 is a UX completeness release focused on filling gaps surfaced by real-world use. Twelve customer-visible improvements ship together, plus a full WCAG 2.1 AA accessibility pass.

Included in Free - Every item on this page applies to the free version. Pro picks up these improvements automatically because Pro builds on top of free.

Member Photos block + shortcode

A new mvs/member-photos Gutenberg block and matching [mvs_member_photos] shortcode render any member's media grid. The block auto-detects the right user - explicit userId attribute first, then the BuddyPress displayed user, then the post author, then the current user - so the same block can be dropped into a profile template, a member-specific page, or an author archive without any wiring.

PDF Viewer block + shortcode

A new mvs/pdf-viewer block and [mvs_pdf_viewer] shortcode embed PDFs using the browser-native viewer (the #view=FitH URL fragment). Configurable height, optional toolbar, five distinct empty states (no media, wrong type, missing file, access denied, generic). No third-party JS, no plugins to install, no licensing fuss.

Sort options on Media Grid

The Media Grid block and [mvs_gallery] shortcode now support four new sort orders - Most Popular, Most Viewed, Most Reactions, and Random - alongside the existing Date and Title sorts. A new direction toggle (ascending / descending) and a per-author filter (userId) make the grid usable as a "Top media by this member" surface.

Search autocomplete on Explore

The Explore page (and [mvs_explore_feed] shortcode) now shows a type-ahead dropdown as you type in the search box - top eight title matches, debounced, with full keyboard navigation (Arrow keys, Enter, Escape) and ARIA combobox semantics for screen reader users.

Lightbox: Download, Fullscreen, and F shortcut

The lightbox toolbar gains two new buttons - Download (writes to media stats; gated by the new global Allow Downloads toggle) and Fullscreen (also bound to the F keyboard shortcut). The Share button's third-popup window.prompt() fallback is gone; it's now navigator.share → clipboard copy → toast on failure.

Per-media Edit modal

The settings cog on dashboard cards opens a prefilled edit modal - change title, description, privacy level, and per-media Allow Downloads in place. No more clicking through to a separate edit screen for a quick rename.

Open Graph + Twitter Card meta

/media/{slug}/ URLs now emit og:* and twitter:card=summary_large_image meta tags. Paste a media URL into Slack, Twitter, LinkedIn, or Discord and it unfurls with title, description, and the cover image - no extra plugin, no SEO setup.

Upload modal polish

Preview tiles in the upload modal now show the filename (truncated tastefully) and a per-tile remove (×) button. Audio files get a proper audio-fallback icon instead of a broken thumbnail. The tags input gains a row of eight popular tag pills below it - click to append, no duplicates.

Bulk Actions in admin All Media

The Media > All Media admin screen now supports multi-select. Tick the rows you want, pick Move to Trash / Restore / Delete permanently from the bulk-actions dropdown, and confirm. Context-aware - the available actions change based on whether you're viewing trashed or live media.

Chat panel visibility setting

A new Chat Panel Visibility dropdown under Media > Settings > Social lets you scope where the floating chat panel renders: Everywhere (default), WPMediaVerse pages only, BuddyPress pages only, or Disabled. For code-level overrides there's the mvs_should_render_chat_panel filter.

Global Allow Downloads toggle

A single switch under Media > Settings > Display hides the lightbox Download button site-wide and refuses the download REST endpoint. Pair with the per-media Allow Downloads checkbox in the Edit modal for fine-grained control.

WCAG 2.1 AA pass

Every interactive surface added or touched in 1.2.0 was audited against WCAG 2.1 AA - aria-label (sentence-form) on icon buttons, aria-pressed on toggles, :focus-visible outlines on every focusable element, role="tablist" + role="tab" on segmented toggles, decorative emoji marked aria-hidden. Keyboard navigation works everywhere mouse navigation works.

General Settings

Access these settings at WPMediaVerse > Settings > General.

General Section

Option	Default	Description
Max Upload Size	100 MB	Maximum file size per upload. Enter value in MB. The plugin reads this setting server-side - WordPress's upload_max_filesize PHP ini value also applies.
Allowed File Types	image/jpeg, image/png, image/gif, image/webp, video/mp4, video/webm, audio/mpeg, audio/ogg	Comma-separated list of allowed MIME types.
Default Privacy Level	Public	The privacy level assigned to new uploads when the user does not choose one. Options: Public, Members Only, Private.
Duplicate Detection	Warn (allow upload)	What to do when a user uploads a file with a SHA-256 hash matching an existing media item. Options: Warn (allow upload), Skip (reject duplicate), Allow (no check).
Strip EXIF Data	Enabled	When enabled, removes GPS coordinates and device information from uploaded JPEG images before storing them.

Storage Section

Option	Default	Description
Storage Driver	Local (WordPress uploads)	Where uploaded files are stored. Local stores files in wp-content/uploads/wpmediaverse/YYYY/MM/. Amazon S3 and BunnyCDN require WPMediaVerse Pro.
Signed URL Expiry	3600 (1 hour)	How long temporary signed URLs remain valid for private media files. Set in seconds.

Changing the storage driver only affects new uploads. Existing files remain in their original storage location. A notice appears after saving if the driver is changed.

Pages Section

Assign existing WordPress pages to WPMediaVerse page roles. WPMediaVerse uses these assignments to generate links in the navigation, chat panel, and notification emails.

Option	Option Key	Description
Dashboard Page	mvs_page_dashboard	The main logged-in user dashboard. Displays the follow feed, quick upload, and activity summary.
Explore Page	mvs_page_explore	The public media browse archive. Used as the landing page for non-logged-in visitors.
Upload Page	mvs_page_upload	The dedicated upload form page. Linked from the dashboard and the navigation bar.

Create a standard WordPress page for each role, then select it from the corresponding dropdown. Each page should contain only the matching WPMediaVerse shortcode ([mvs_dashboard], [mvs_explore], [mvs_upload]) with no other content.

If a page assignment is empty, WPMediaVerse falls back to the site home URL for that link. Set all three pages to avoid broken navigation.

Display Settings

Access these settings at WPMediaVerse > Settings > Display.

Media Display Section

Option	Default	Description
Grid Columns	3	Number of columns in the media grid. Applies to [mvs_gallery], the Media Grid block, and the explore archive. Options: 2, 3, 4, 5 columns.
Items Per Page	12	Number of media items loaded per page. Options: 12, 24, 48.
Thumbnail Style	Original proportions (masonry)	Controls the aspect ratio of grid thumbnails. Square crops images to a 1:1 ratio. Original proportions preserves the file's native aspect ratio, packed into a masonry layout. The default flipped from Square to Original proportions in 1.8.0; restore the old square-crop default site-wide with the mvs_default_thumbnail_style filter.
Allow Downloads	On	Master toggle for the lightbox Download button. When off, the button is hidden site-wide and the /mvs/v1/media/{id}/download REST endpoint refuses requests. Per-media Allow Downloads (set in the per-media Edit modal) is still honoured when this master toggle is on.

Lightbox Toolbar

The full-screen lightbox includes a toolbar with three quick-action buttons.

Button	Behaviour
Download	Streams the original file to the user and increments the mvs_media_stats.downloads counter. Hidden when Allow Downloads is off (either site-wide or per-media). Rate-limited to 30 requests per minute per user.
Fullscreen	Expands the lightbox to fill the viewport using the browser Fullscreen API. Also bound to the F keyboard shortcut.
Share	Uses navigator.share where supported, falls back to copying the URL to the clipboard, falls back to a toast error. No window.prompt() fallback.

All three buttons carry aria-label text and :focus-visible outlines for keyboard users.

How Display Settings Interact with Shortcodes

The [mvs_gallery] shortcode deliberately uses the backend settings for Grid Columns and Items Per Page rather than letting shortcode attributes override them. This ensures consistent display across your site.

The [mvs_album] shortcode allows you to override the column count directly:

[mvs_album id="123" columns="4"]

Thumbnail Generation

WPMediaVerse generates thumbnails for uploaded images using WordPress's built-in image editor. Thumbnails are stored alongside the original file in the wpmediaverse/YYYY/MM/ upload directory.

For video files, a poster is extracted from the first frame (ffmpeg, with a getID3 cover-atom fallback). As of 1.8.0, every grid, feed, and layout (My Media, Explore, the explore-feed block, and the Pinterest/Flickr/Dribbble/Instagram layouts, including Load More) shows this real first-frame poster instead of a generic video placeholder icon.

Watermarking: Free vs Pro

WPMediaVerse Free ships the watermark engine: WatermarkService resolves whether an upload should be stamped and fires the mvs_watermark_stamp_file filter at upload time and at file-replace time (so there's no bypass via the replace endpoint), before any thumbnail or WebP/AVIF variant is cut. The underlying option schema (watermark type, text, logo, position, opacity) also ships in Free with safe defaults, all off by default.

What Free does not include is the Settings UI to configure those options, or the GD code that actually draws the mark into the image. WPMediaVerse Pro adds both: the Watermark section on Media > Settings > Display, where you pick Enable Watermark, Apply to (all uploads or specific roles), Watermark Type (Text or Image), Watermark Text/Image, Position, Opacity, and Text Size/Color - and the renderer that hooks mvs_watermark_stamp_file to draw it. Without Pro active, the engine has nothing registered to draw with, so uploads are never watermarked.

Permissions

Access these settings at WPMediaVerse > Settings > Permissions.

Custom Capabilities

WPMediaVerse registers the following custom WordPress capabilities:

Capability	Description
upload_mvs_media	Upload new media files
edit_mvs_media	Edit own media posts
edit_others_mvs_media	Edit media posts created by other users
delete_mvs_media	Delete own media posts
delete_others_mvs_media	Delete media posts created by other users
moderate_mvs_media	Access the moderation queue and approve/reject media
manage_mvs_settings	Manage WPMediaVerse settings (finer-grained grant checked by settings actions; the admin menu itself gates on core manage_options)
manage_mvs_access	Manage custom access grants for private media
read_mvs_media	View media (used for private media visibility checks)
publish_mvs_media	Publish media posts immediately (without pending review)

Default Role Assignments

Role	upload	edit own	delete own	moderate	manage settings
Administrator	Yes	Yes	Yes	Yes	Yes
Editor	Yes	Yes	Yes	Yes	No
Author	Yes	Yes	Yes	No	No
Contributor	Yes	Yes	Yes	No	No
Subscriber	Yes	No	No	No	No

Changing Permissions

1. Go to Media > Settings > Permissions.
2. Check or uncheck capabilities for each role.
3. Click Save Permissions.

The page shows how many roles were updated. If no changes were needed, it shows "No changes were needed."

Granting Capabilities Programmatically

You can grant or revoke capabilities in your theme's functions.php or a custom plugin:

// Grant moderation capability to a custom role.
$role = get_role( 'shop_manager' );
if ( $role ) {
    $role->add_cap( 'moderate_mvs_media' );
    $role->add_cap( 'manage_mvs_access' );
}

Important Notes

• The moderate_mvs_media capability grants access to the moderation queue and the ability to see all media regardless of privacy level.
• The WPMediaVerse admin menu pages (Settings, Moderation, Logs, etc.) are registered against the core manage_options capability. The manage_mvs_settings capability is a finer-grained grant some settings actions and dashboard links check, so it can be assigned to non-administrator roles that should manage WPMediaVerse without full manage_options access.
• Capabilities are stored in the WordPress wp_user_roles option and persist after plugin deactivation.

AI & Moderation Settings

Access these settings at WPMediaVerse > Settings > AI & Moderation.

AI Features Section

AI is opt-in and off by default. Nothing calls an AI provider until you (1) supply an API key and (2) turn on at least one of the toggles below. There is no separate "enable AI" master switch because a missing key already disables every AI feature - you stay in full control of what runs and what it costs.

Option	Default	Description
AI Provider	OpenAI (GPT-4 Vision)	The AI service used for image analysis, tagging, and moderation. Free version: OpenAI only. Pro adds Google Vision, AWS Rekognition, and Claude (Anthropic) (added in 1.8.0, selectable from this dropdown).
OpenAI API Key	(empty)	Your OpenAI API key. You can also define MVS_OPENAI_API_KEY in wp-config.php instead.
OpenAI Model	GPT-4o Mini	Model used for analysis calls. GPT-4o Mini is cheaper; GPT-4o provides higher quality results.
Auto-Analyze Uploads	Off	Master switch for the two per-feature toggles below. When off, neither descriptions nor tags are generated on upload.
Generate Descriptions	On	When Auto-Analyze is on, use AI to generate a description / alt text for each upload. Turn off to skip description calls and only generate tags.
Generate Tags	On	When Auto-Analyze is on, use AI to suggest tags for each upload. Turn off to skip tag-suggestion calls.
Auto-Apply Tags	Off	When enabled, AI-suggested tags are automatically assigned to the mvs_tag taxonomy. Requires Generate Tags to be on.
Auto-Moderate Uploads	Off	When enabled, each new upload is checked for policy violations. The action taken depends on the When AI Flags Content setting below.
Monthly AI Budget ($)	$10	Hard cap on AI spend per calendar month, covering analysis, tagging and moderation calls. When the cap is reached, all AI calls stop until the next month. Set to 0 for unlimited spend - recommended only after you configure a billing alert on the provider account itself.

Estimated cost per call is not a settings-page field - it is a developer-only default ($0.01) used for budget tracking, overridable via the mvs_ai_cost_per_call filter.

AI Flag Criteria and Custom Flag Terms (New in 1.8.0)

Option	Default	Description
AI Flag Criteria	All 6 categories on	Checkbox group controlling which content categories the AI flags: Nudity / sexual content, Violence / gore, Hate / harassment, Self-harm, Drugs, Spam. Unchecking all categories restores every category (the rule can never go blank).
Custom Flag Terms	(empty)	Optional comma-separated terms the AI should also flag beyond the built-in categories - e.g. weapons, gambling, political content, competitor logos. Narrated to the AI alongside the categories above.

Choosing exactly which AI features run

Each toggle is independent so a site owner enables only what they want to pay for:

• Descriptions only - Auto-Analyze on, Generate Descriptions on, Generate Tags off.
• Tags only - Auto-Analyze on, Generate Descriptions off, Generate Tags on (add Auto-Apply Tags to write them to the taxonomy automatically).
• Moderation only - leave Auto-Analyze off and turn on Auto-Moderate; uploads are scanned for policy violations without generating descriptions or tags.

The budget cap applies to all of the above, so moderation calls also stop once the monthly cap is hit.

Setting the API Key via wp-config.php

// wp-config.php
define( 'MVS_OPENAI_API_KEY', 'sk-your-key-here' );

When this constant is defined, the settings page field is disabled and shows a notice.

Moderation Section

Option	Default	Description
When AI Flags Content	Flag for review	What happens when AI detects a policy violation. Options: Flag for review (keeps media visible but adds it to the moderation queue), Hide (sets media to private), Reject (moves media to draft), Delete permanently (removes the media and its files from local and cloud storage - cannot be undone). The default changed from Delete permanently to Flag for review in 2.0.0, so a fresh install can never auto-delete uploads before an admin has chosen otherwise.
Auto-Hide Threshold	3	Number of user reports required to automatically hide a media item. The media is set to private and added to the moderation queue. Set to 0 to disable automatic hiding.

Moderation Queue

Administrators with the moderate_mvs_media capability can review flagged media at WPMediaVerse > Media Moderation (renamed from "Moderation" in 2.0.0 to avoid ambiguity with the general WordPress term).

The queue shows:

• Media flagged by AI
• Media that reached the auto-hide threshold from user reports
• Media manually flagged by moderators

Log Viewer

The AI & moderation activity log is available at WPMediaVerse > Logs. It shows each AI call, the result, estimated cost, and any action taken.

Budget Alerts

When monthly AI spend reaches 80% of your budget, WPMediaVerse adds an admin notice. When the budget is fully consumed, all AI calls - analysis, tagging, and moderation - are suspended and a warning appears on the settings page. Because a fresh install ships with a conservative $10 default cap, AI never silently runs against an unbounded bill before you have chosen a budget.

Webhooks

Access these settings at WPMediaVerse > Settings > Webhooks.

Webhooks allow WPMediaVerse to send signed HTTP POST notifications to external services when media events occur.

Supported Events

Event	Triggered When
media.uploaded	A new media file is successfully uploaded
media.updated	An existing media post is saved/updated
media.deleted	A media post is permanently deleted
media.moderated	A media item's moderation status changes (approved, flagged, rejected)
media.reaction	A user adds a reaction to a media item
media.comment	A user posts a comment on a media item

Adding a Webhook

1. Go to WPMediaVerse > Settings > Webhooks.
2. Click Add Webhook.
3. Enter the URL that should receive the POST request.
4. Select which events should trigger this webhook.
5. Optionally enter a secret key for signature verification.
6. Click Save Webhooks.

Payload Format

All webhook payloads are sent as JSON via HTTP POST with these headers:

Content-Type: application/json
X-MVS-Event: media.uploaded
X-MVS-Delivery: <uuid>
X-MVS-Signature: sha256=HMAC_SIGNATURE

The X-MVS-Signature header is only sent when a secret key is configured for the webhook.

Example: media.uploaded Payload

{
  "event": "media.uploaded",
  "timestamp": "2025-03-27T12:00:00Z",
  "site_url": "https://yoursite.com",
  "data": {
    "media_id": 123,
    "title": "My Photo",
    "author": 1,
    "url": "https://yoursite.com/media/my-photo/",
    "file_url": "https://yoursite.com/wp-content/uploads/wpmediaverse/2025/03/photo.jpg",
    "file_type": "image",
    "privacy": "public",
    "status": "publish"
  }
}

Verifying Webhook Signatures

Use the secret key you configured to verify that requests are from WPMediaVerse:

$payload   = file_get_contents( 'php://input' );
$signature = $_SERVER['HTTP_X_MVS_SIGNATURE'] ?? '';
$secret    = 'your-webhook-secret';

$expected = 'sha256=' . hash_hmac( 'sha256', $payload, $secret );

if ( ! hash_equals( $expected, $signature ) ) {
    http_response_code( 401 );
    exit( 'Invalid signature' );
}

Retry Behavior

Failed webhook deliveries (5xx HTTP response or connection error) are retried up to 2 times via Action Scheduler, after 5 minutes and then 10 minutes. 4xx client-error responses are not retried. After the final attempt the failure is recorded in the mvs_webhook_failures option.

Social & Messaging Settings

Access these settings at WPMediaVerse > Settings > Social.

These settings control who can send direct messages and online presence visibility.

---

Direct Messages

Option	Key	Default	Description
Who Can Send DMs	mvs_dm_access	everyone	Controls who is allowed to send direct messages to other users on the site. Options: everyone, followers (people who follow the recipient; others go to Requests), mutual (only mutual followers), nobody (DMs disabled).
Minimum Account Age (days)	mvs_dm_min_age	0	Number of days a user account must exist before that user can initiate new conversations. Set to 0 to disable the restriction.
Online Status Visibility	mvs_show_online_status	everyone	Who can see when a user is currently online in the messaging interface. Options: everyone, followers, nobody.
Chat Panel Visibility	mvs_chat_panel_visibility	everywhere	Where the floating chat panel renders. Options: everywhere, mvs_pages (WPMediaVerse pages only - Explore, Dashboard, Albums, Member Profiles), bp_pages (BuddyPress member + group pages only), disabled. For code-level overrides, hook into the mvs_should_render_chat_panel filter - return false to suppress the panel on a specific request.

Setting Who Can Send DMs here applies site-wide. Users cannot override this individually at this time.

---

Defining Options via wp-config.php

You can lock any Social setting as a constant to prevent admin changes:

// wp-config.php
define( 'MVS_DM_ACCESS', 'followers' );        // Lock DM access to followers only.
define( 'MVS_DM_MIN_AGE', 7 );                 // Require 7-day-old accounts to send DMs.
define( 'MVS_SHOW_ONLINE_STATUS', false );      // Disable online status site-wide.

When a constant is detected, the corresponding field on the settings page is shown as read-only.

Settings Reference

Every option WPMediaVerse and WPMediaVerse Pro register, with its option key, type and default.

The other pages in this section explain settings in the order you meet them in the admin screens. This page is the complete index: use it when you need to set an option in code, seed a site with WP-CLI, or check what a value defaults to before you change it.

Option keys are stored as normal WordPress options, so anything here can be read or written with get_option() / update_option() or the WP-CLI equivalents:

wp option get mvs_default_privacy
wp option update mvs_items_per_page 24

Defaults apply only when the option row is absent. Saving a settings screen writes every field on that screen, including the ones you did not touch. After the first save an option holds a real stored value, and changing the default in a later release will not move it.

Free options

Registered by Admin\Settings\SettingsRegistrar and Admin\Settings\AiSettingsRegistrar.

Uploads and storage

Option key	Setting label	Type	Default
mvs_max_upload_size	Max Upload Size	integer	104857600 (100 MB, in bytes)
mvs_allowed_file_types	Allowed File Types	string	image/jpeg,image/png,image/gif,image/webp,video/mp4,video/webm,audio/mpeg,audio/ogg
mvs_duplicate_action	Duplicate Detection	string	warn
mvs_strip_exif	Strip EXIF Data	boolean	true
mvs_storage_driver	Storage Driver	string	local
mvs_signed_url_ttl	Signed URL Expiry (seconds)	integer	3600
mvs_cloud_direct_public_urls	(no settings field - set in code)	boolean	false

mvs_duplicate_action accepts warn (allow the upload and warn), skip (reject the duplicate) or allow (skip the hash check entirely). mvs_strip_exif removes GPS and device data from JPEGs at upload time; it does not rewrite files already stored.

Privacy and permissions

Option key	Setting label	Type	Default
mvs_default_privacy	Default Privacy Level	string	public
mvs_allow_user_privacy	Allow Users to Set Privacy	boolean	true
mvs_allow_downloads	Allow Downloads	boolean	true
mvs_app_password_login	App Sign-In	boolean	true

mvs_app_password_login controls whether members may exchange their WordPress password for an Application Password to sign in to a mobile app. Turn it off when you require everyone through the interactive login - for example when you enforce two-factor authentication. Also filterable at runtime via mvs_app_password_login_enabled.

mvs_default_privacy is the level applied when the uploader makes no choice. When mvs_allow_user_privacy is off, the privacy select is removed from the upload form and every upload takes the default.

Display

Option key	Setting label	Type	Default
mvs_grid_columns	Grid Columns	integer	3
mvs_items_per_page	Items Per Page	integer	12
mvs_thumbnail_size	Thumbnail Quality	string	medium
mvs_thumbnail_style	Thumbnail Style	string	original
mvs_large_image_size	Large Image Size	integer	1024
mvs_lightbox_image_source	Lightbox Image Size	string	original

mvs_large_image_size is the long-edge pixel width of the generated large variant. mvs_lightbox_image_source chooses which file the lightbox opens: original for full quality, or the large variant to save bandwidth on image-heavy pages.

Social and messaging

Option key	Setting label	Type	Default
mvs_dm_access	Who Can Send DMs	string	everyone
mvs_dm_min_age	Minimum Account Age (days)	integer	0
mvs_chat_panel_visibility	Chat Panel Visibility	string	everywhere
mvs_show_online_status	Online Status Visibility	string	everyone
mvs_comment_edit_window	(no settings field - filterable)	integer	900 (15 minutes)

mvs_dm_access accepts everyone, followers, mutual or nobody. This is the only place the word "followers" appears as a setting value - it controls who may open a conversation with a member, and has nothing to do with media privacy.

mvs_comment_edit_window is the number of seconds after posting during which a member may still edit their own comment.

Moderation and reporting

Option key	Setting label	Type	Default
mvs_enable_reports	Member Reporting	boolean	true
mvs_report_auto_hide_threshold	Auto-Hide Threshold	integer	3
mvs_abuse_contact_email	Abuse Contact Email	string	(empty)
mvs_moderation_auto_action	When AI Flags Content	string	(empty)

mvs_report_auto_hide_threshold is the number of distinct reports after which a media item is hidden automatically pending review. Set mvs_abuse_contact_email if you want abuse notifications sent somewhere other than the site admin address.

AI

Option key	Setting label	Type	Default
mvs_ai_provider	AI Provider	string	openai
mvs_openai_api_key	OpenAI API Key	string	(empty)
mvs_openai_model	OpenAI Model	string	gpt-4o-mini
mvs_ai_auto_analyze	Auto-Analyze Uploads	boolean	false
mvs_ai_auto_tag	Generate Tags	boolean	true
mvs_ai_auto_apply_tags	Auto-Apply Tags	boolean	false
mvs_ai_auto_describe	Generate Descriptions	boolean	true
mvs_ai_auto_moderate	Auto-Moderate Uploads	boolean	false
mvs_ai_moderation_categories	AI Flag Criteria	array	nudity, violence, hate, self-harm, drugs, spam
mvs_ai_moderation_custom_terms	Custom Flag Terms	string	(empty)
mvs_ai_monthly_budget	Monthly AI Budget ($)	string	(empty)
mvs_ai_cost_per_call	(no settings field - filterable)	number	0.01

Note the pairing: mvs_ai_auto_tag decides whether tags are generated, and mvs_ai_auto_apply_tags decides whether they are attached to the media item automatically rather than suggested for review. Generating without applying is the safe starting configuration.

mvs_ai_moderation_categories falls back to the full category list when stored empty, so an empty value never silently disables flagging. mvs_ai_monthly_budget combined with mvs_ai_cost_per_call drives the spend estimate and the budget cutoff.

Webhooks

Option key	Setting label	Type	Default
mvs_webhooks	Webhook Configuration	array	(empty array)

See Webhooks for the payload format and the event list.

Pro options

Registered by Admin\ProSettings and Admin\GamificationSettings. All Pro options are inert unless WPMediaVerse Pro is active.

Feature toggles

Option key	Setting label	Type	Default
mvs_stories_enabled	Stories	string	0
mvs_connectors_enabled	Enable Connectors	string	0
mvs_streaks_enabled	Enable Streaks	string	0
mvs_watermark_enabled	Enable Watermark	boolean	false
mvs_pro_transcode_enabled	Enable Transcoding	boolean	false
mvs_autopilot_enabled	Enable Autopilot	string	0

Toggles stored as strings compare against '1'. When a feature is off its service is never constructed, so its REST routes are not registered and its scheduled actions do not run - which is why a disabled feature's endpoints return 404 rather than 403.

The gamification toggles mvs_battles_enabled, mvs_challenges_enabled, mvs_tournaments_enabled and mvs_boosts_enabled follow the same pattern and are covered in Gamification.

Video

Option key	Setting label	Type	Default
mvs_pro_transcode_auto	Auto-Transcode on Upload	boolean	true
mvs_pro_transcode_presets	Quality Presets	array	720p, 480p
mvs_pro_transcode_hls	Generate HLS Stream	boolean	false
mvs_pro_transcode_thumbnail	Generate Video Thumbnail	boolean	true
mvs_pro_ffmpeg_path	FFmpeg Binary Path	string	(empty)

mvs_pro_transcode_auto only takes effect while mvs_pro_transcode_enabled is on. Leave mvs_pro_ffmpeg_path empty to use the binary on the system PATH.

AI providers

Option key	Setting label	Type	Default
mvs_pro_google_vision_key	Google Cloud API Key	string	(empty)
mvs_pro_anthropic_key	Anthropic API Key	string	(empty)
mvs_pro_anthropic_model	Claude Model	string	claude-haiku-4-5-20251001

Gamification

Option key	Setting label	Type	Default
mvs_pro_battle_win_xp	Battle Win Reward (XP)	integer	100
mvs_pro_boost_cost_per_100	Points per 100 Impressions	integer	50
mvs_pro_boost_max_impressions	Max Impressions per Boost	integer	5000
mvs_pro_boost_expiry_days	Boost Expiry (Days)	integer	7
mvs_streak_freezes_enabled	Allow Streak Freezes	string	0
mvs_pro_streak_freeze_cost	Freeze Cost (Points)	integer	100

Challenge autopilot

Option key	Setting label	Type	Default
mvs_autopilot_day	Day of Week	string	monday
mvs_autopilot_hour	Time	integer	9
mvs_autopilot_entry_days	Entry Period (Days)	integer	7
mvs_autopilot_voting_days	Voting Period (Days)	integer	3
mvs_autopilot_max_entries	Max Entries per User	integer	1

Autopilot creates the next themed challenge from the Theme Library on the configured day and hour. mvs_autopilot_entry_days and mvs_autopilot_voting_days set the length of each phase, so a challenge's full cycle is the sum of the two.

Connectors and layout

Option key	Setting label	Type	Default
mvs_pro_connector_flickr_app_key	Flickr Plugin API Key	string	(empty)
mvs_pro_connector_flickr_app_secret	Flickr Plugin API Secret	string	(empty)
mvs_pro_feed_layout	Explore Page Layout	string	grid

Other

Option key	Setting label	Type	Default
mvs_pro_webhook_secret	Webhook Secret	string	(empty)
mvs_pro_settings	(container option)	array	(empty array)

mvs_pro_settings is a single array option holding assorted Pro values that have no dedicated key. Read it with get_option( 'mvs_pro_settings', array() ) rather than assuming a shape.

Storing credentials in wp-config.php

API keys and cloud credentials can be defined as constants instead of being stored in the database. When a constant is defined, the matching settings field renders locked and shows "Defined in wp-config.php", and the stored option is ignored.

This keeps secrets out of database dumps and out of staging copies. See Cloud Storage for the Cloudflare R2, S3 and DigitalOcean Spaces constant names.

Related

• General Settings - the General tab, explained in context
• Display Settings
• Permissions
• AI & Moderation
• Social & Messaging Settings
• Webhooks
• Hooks & Filters Reference - filters that override these values at runtime

Media Upload

Free + Pro - Core functionality is included free. Features marked with (Pro) require WPMediaVerse Pro.

Share photos, videos, and audio with your community - no admin access needed, straight from any page on your site.

What You Can Do

• Drag and drop files directly onto the upload zone
• Paste an image from your clipboard to upload instantly
• Select multiple files at once for bulk upload
• Set a title, description, and tags for each file before submitting
• Choose who can see each file: public, members only, friends, or private
• Upload JPEG, PNG, GIF, WebP images; MP4 and WebM videos; MP3 and OGG audio

How It Works (for Users)

1. Go to the upload page your site administrator set up (often /upload/ or /media/upload/)
2. Drag your files onto the upload zone, or click Browse to pick files from your device
3. To paste a screenshot or copied image, click inside the upload zone and press Ctrl+V (Cmd+V on Mac)
4. For each file, enter a title and optional tags. Select a privacy level from the dropdown
5. Click Upload - a progress bar shows each file uploading
6. When finished, your files appear in your media dashboard and your profile page
7. Find all your uploads anytime under My Media or your profile's Media tab

For Site Owners

1. Go to Media > Settings > General and confirm the allowed file types match what your community needs
2. Add the upload form to any page: in the block editor, insert the WPMediaVerse: Media Upload block; in the classic editor, add [mvs_upload]
3. Set the default privacy level and maximum file size for your site
4. Enable Strip EXIF Data (on by default) to automatically remove GPS coordinates from photos before storage
5. Users see the upload form immediately on that page when logged in

Supported File Formats

Type	Formats
Images	JPEG, PNG, GIF, WebP
Video	MP4, WebM
Audio	MP3 (MPEG), OGG

Customize allowed types in Media > Settings > General.

Upload Modal (1.9.0, 2.0.0)

The upload modal no longer asks you to pick a media type tab first - drop in an image, video, or audio file and WPMediaVerse auto-detects the type (1.9.0).

When uploading into an album, you can create a brand-new album right from the upload modal instead of leaving to create one first, then switching back to upload into it (2.0.0).

Bulk Album Upload (1.2.0)

When uploading multiple files at once into an album, WPMediaVerse now creates one activity entry for the whole batch ("Varun uploaded 3 photos to album Portrait Series") with a thumbnail grid, instead of one separate activity per file. Single-file uploads and ad-hoc photo posts retain their existing per-post behaviour.

Per-Media Edit Modal (1.2.0)

The settings cog on dashboard cards now opens a prefilled edit modal - change title, description, privacy level, and per-media Allow Downloads in place. Save updates the row live without a page reload. The matching PUT /mvs/v1/media/{id} REST endpoint accepts an allow_download boolean.

When you change the title, the URL slug stays stable by default. Tick the new Update URL slug checkbox if you want the slug regenerated from the new title - the page redirects to the new URL automatically so existing tabs and bookmarks don't 404.

What Happens After Upload

• Thumbnails are generated automatically for images and videos (videos: ffmpeg poster extraction; run wp mvs generate-video-thumbnails to backfill any uploaded before 1.2.0)
• EXIF GPS data is stripped from JPEG files (other metadata like camera model is kept)
• A SHA-256 hash is computed to detect duplicate files
• If AI moderation is enabled, the file is queued for automatic review
• BuddyPress activity is recorded if BuddyPress is active on your site

Adding the Upload Form

Gutenberg Block: Add the WPMediaVerse: Media Upload block to any page or post.

Shortcode:

[mvs_upload]
[mvs_upload max_files="5" show_privacy="true"]

Attribute	Default	Description
max_files	10	Maximum number of files the user can upload at once
show_privacy	true	Whether to show the privacy level selector

Upload Validation

Every upload goes through these checks in order:

1. MIME type check - file content is inspected (not just the extension) against your allowed types list.
2. File size check - measured server-side against mvs_max_upload_size (default 100 MB).
3. Extension block list - blocks PHP, shell, and other executable extensions even if the MIME passes.
4. Double extension block - rejects filenames like photo.php.jpg.
5. Duplicate detection - computes a SHA-256 hash and compares against existing uploads. Behavior depends on your Duplicate Detection setting (warn, skip, or allow).

EXIF Stripping

When Strip EXIF Data is enabled (default), GPS coordinates and device metadata are removed from JPEG images before storage. Non-GPS EXIF data (camera model, focal length) is retained.

Storage Path

Files are stored at:

wp-content/uploads/wpmediaverse/YYYY/MM/filename.ext

WordPress's wp_unique_filename() prevents filename collisions.

Programmatic Upload

Use the UploadService to upload files from code:

$upload_service = WPMediaVerse\Core\Plugin::container()->get( 'upload' );

$result = $upload_service->handle(
    $_FILES['my_file'],
    get_current_user_id(),
    array(
        'title'       => 'My File',
        'privacy'     => 'public',
        'description' => 'Optional description',
    )
);

if ( is_wp_error( $result ) ) {
    // Handle error.
} else {
    $media_id = $result; // int - new mvs_media post ID.
}

Actions Fired During Upload

• mvs_before_media_insert - fires before the mvs_media post is created.
• mvs_before_upload_form - fires before the upload form HTML is rendered (used by Pro for quota display).
• mvs_media_uploaded - fires after the post is created and indexed. Passes $media_id (int), an array of file metadata (file_url, file_path, file_size, file_type, file_hash, media_type, privacy, etc.), $user_id (int), and $media_type (string).

Media Metadata

Media metadata is stored in WPMediaVerse's own mvs_media_meta table (keyed by media ID), not in WordPress post meta. Access it through the MediaRepository (->get( $media_id, $key )). Common keys:

Meta Key	Type	Description
file_url	string	Public URL of the stored file
file_path	string	Relative storage path
media_type	string	image, video, audio, or document
file_type	string	Full MIME type (e.g., image/jpeg)
file_size	int	File size in bytes
privacy	string	Privacy level (see Privacy & Access Control)
file_hash	string	SHA-256 hash for duplicate detection
group_id	int	BuddyPress group ID (for group privacy)

Albums

Included in Free - This feature is available in the free version of WPMediaVerse.

Group your photos into beautiful collections - tell a story, document a trip, or organize your portfolio with a single shareable album.

What You Can Do

• Create albums to organize related photos and videos together
• Add photos from your existing media library to any album
• Set a cover photo that represents the album
• Control album privacy independently from individual photo privacy
• Share albums with friends or keep them private
• Embed any album on a page using a block or shortcode

How It Works (for Users)

1. Go to your media dashboard and click Create Album
2. Give your album a title and optional description
3. Choose a privacy level: public, members only, friends, or private
4. Click Add Media to pick photos from your uploads - select as many as you like
5. Drag photos in the album to reorder them. Click the star on any photo to set it as the cover
6. Click Save Album - your album is live and appears on your profile
7. To share your album, copy the album link from the album page and send it to anyone

For Site Owners

1. Albums are enabled by default once WPMediaVerse is activated
2. To embed a specific album on a page, use the WPMediaVerse: Album Viewer block in the block editor - select the album from the block sidebar
3. Or use the shortcode [mvs_album id="123"] where 123 is the album's post ID
4. Users manage their own albums from their media dashboard
5. Admins can view and delete any album from Media > Albums in wp-admin

Album Privacy

Albums have their own privacy level, and media added to a non-public album inherits it.

When you add a media item to an album, its privacy is clamped to the more restrictive of the two. Adding a public photo to a Private album makes that photo private, so it stops appearing in Explore and in other members' feeds. The clamp only ever tightens: an item that is already more restrictive than its album keeps its own setting, and a public album never changes anything.

Two things this does not do:

• Changing an album's privacy later does not re-apply to items already inside it. Only the moment of adding clamps.
• Removing an item from an album does not restore its previous privacy.

Site owners who want album and item privacy to stay fully independent (the behaviour before 2.3.0) can return false from the mvs_album_inherit_privacy filter.

If a user can see the album but not a specific media item (because the item's privacy is more restrictive still), that item is hidden from the album view.

Displaying an Album

Gutenberg Block: Add the WPMediaVerse: Album Viewer block, then select an album from the block settings.

Shortcode:

[mvs_album id="123"]
[mvs_album id="123" columns="4" show_title="true" show_description="true"]

Attribute	Default	Description
id	(required)	Album post ID
columns	3	Grid columns to display
show_title	true	Show the album title above the grid
show_description	true	Show the album description

REST API Endpoints for Albums

Method	Endpoint	Description
GET	/mvs/v1/albums	List albums
POST	/mvs/v1/albums	Create album
GET	/mvs/v1/albums/{id}	Get album
PUT	/mvs/v1/albums/{id}	Update album
DELETE	/mvs/v1/albums/{id}	Delete album
GET	/mvs/v1/albums/{id}/items	List album media
POST	/mvs/v1/albums/{id}/items	Add media to album
DELETE	/mvs/v1/albums/{id}/items/{media_id}	Remove media from album

Creating an Album via API

curl -X POST https://yoursite.com/wp-json/mvs/v1/albums \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Summer 2025",
    "description": "Photos from our trip",
    "privacy": "public"
  }'

Adding Media to Albums via API

curl -X POST https://yoursite.com/wp-json/mvs/v1/albums/ALBUM_ID/items \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -H "Content-Type: application/json" \
  -d '{"media_ids": [101, 102, 103]}'

This fires the mvs_album_items_added action, which triggers BuddyPress activity updates if BuddyPress is active.

BuddyPress Activity

When media is added to an album and BuddyPress is active, the mvs_album_items_added action updates the upload activity item to reference the album. This replaces the generic "uploaded media" activity with "uploaded media to [Album Name]".

Collections

Included in Free - This feature is available in the free version of WPMediaVerse.

Save and curate media from anyone on your site into personal boards - like Pinterest boards, but for your community's photos and videos.

What You Can Do

• Save any public media item to a personal collection with one click
• Create multiple collections for different themes or moods (e.g., "Travel Inspiration", "Black and White")
• Curate manually by hand-picking individual photos, or let smart rules auto-fill a collection
• Smart collections stay fresh automatically - tag a rule once and the collection updates itself
• Share collections publicly or keep them private
• Browse your saved collections from your media dashboard

How It Works (for Users)

1. When you find a photo you love, click the Save button (bookmark icon) below it
2. Choose an existing collection from the dropdown, or click New Collection to create one
3. Give your new collection a name and choose a privacy level, then click Create
4. The photo is added instantly - you'll see the bookmark icon turn solid to confirm
5. Find all your collections under My Media > Collections in your dashboard
6. To manage a collection, open it and click Edit to rename it, reorder items, or remove ones you no longer want
7. To share a collection, copy the link from the collection page

For Site Owners

1. Collections are available to all users with upload access once WPMediaVerse is activated
2. To embed a collection on any page, use [mvs_collection id="456"] or the WPMediaVerse: Collection Viewer block
3. Smart collections are especially useful for curated showcase pages - create a smart collection filtered by a tag and embed it on your homepage
4. Manage all collections from Media > Collections in wp-admin
5. Use the Collection Settings meta box on any collection post to switch between manual and smart mode and configure smart rules

Collection Types

Type	Description
Manual	You add specific media items by hand. Items are stored in the wp_mvs_favorites table with the collection ID.
Smart	Rules-based. The collection resolves its item list dynamically at request time based on criteria like tag, category, media type, or date range.

Displaying a Collection

Shortcode:

[mvs_collection id="456"]
[mvs_collection id="456" columns="3" per_page="20"]

Attribute	Default	Description
id	(required)	Collection post ID
columns	3	Grid columns to display
per_page	20	Maximum number of media items to show

If no id is provided, the shortcode outputs an error message. If the collection post is not published, the shortcode shows "Collection not found."

REST API Endpoints for Collections

Method	Endpoint	Description
GET	/mvs/v1/collections	List collections
POST	/mvs/v1/collections	Create collection
GET	/mvs/v1/collections/{id}	Get collection with resolved items
PUT	/mvs/v1/collections/{id}	Update collection
DELETE	/mvs/v1/collections/{id}	Delete collection

Creating a Smart Collection via API

curl -X POST https://yoursite.com/wp-json/mvs/v1/collections \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Nature Photos",
    "type": "smart",
    "rules": {
      "tags": ["nature", "landscape"],
      "media_type": "image"
    },
    "privacy": "public"
  }'

Collection Meta Box

In the WordPress admin, each mvs_collection post has a Collection Settings meta box that lets you set the collection type and define smart rules without using the API.

Stories

Pro feature. Stories (time-limited, ephemeral posts) ship in WPMediaVerse Pro. The free plugin provides the upload-flow entry point described below, but story creation, the viewer, and view receipts all require Pro.

What's in Free

The Media Upload block includes an "Also share as a story" checkbox next to the tag input, but only when the mvs_stories_enabled option is on:

$mvs_stories_on = ( '1' === get_option( 'mvs_stories_enabled', '0' ) );

mvs_stories_enabled defaults to off and is set by Pro when it registers the Stories feature - so on a free-only install this toggle stays hidden and no story code runs. Free no longer ships a StoryService; the class was relocated to Pro in 1.9.0 (it was built ahead of the create-flow and viewer UI, then moved wholesale once those shipped).

What Pro Adds

See Stories (Pro) for the full feature: 24-hour default expiry (1-168h configurable per story), a tap-to-advance viewer, "seen by" receipts, and the mvs-pro/v1 REST routes that drive it (GET /stories, POST /media/{id}/story, DELETE /media/{id}/story, POST /stories/{id}/view, GET /stories/{id}/viewers).

Hooks

mvs_story_created and mvs_story_expired are Pro hooks (fired from WPMediaVersePro\Stories\StoryService). See Hooks & Filters - Access & Privacy.

Social Features

Included in Free - This feature is available in the free version of WPMediaVerse.

React, comment, follow, and share - WPMediaVerse turns your media site into a living community where every photo starts a conversation.

What You Can Do

• React to any photo or video with emoji reactions (like, love, wow, and more)
• Comment on media and edit your comment within 15 minutes of posting
• Follow photographers you love - their new uploads appear in your feed
• Save media to your favorites for quick access later
• @mention other members in comments to notify them directly
• Share any public media item to social networks or copy a direct link
• Report inappropriate content directly from the media page

How It Works (for Users)

Following Someone

1. Visit any member's profile page
2. Click Follow - their public uploads now appear in your feed
3. To stop following, click Unfollow on their profile
4. See everyone you follow under My Media > Following

Reacting to Media

1. Open any media item
2. Click the reaction bar below the photo
3. Choose your reaction - like, love, wow, haha, sad, or angry
4. Your reaction is shown instantly. Click the same reaction to remove it
5. Click a different reaction to change yours

Commenting

1. Scroll to the comments section below any media item
2. Type your comment in the text box and press Enter or click Post
3. To @mention someone, type @ followed by their username - they receive a notification
4. To edit your comment, click the pencil icon next to it (available within 15 minutes of posting)
5. To delete your comment, click the trash icon

Saving to Favorites

1. Click the heart icon on any media item
2. The item is added to your favorites list
3. Find all your favorites under My Media > Favorites in your dashboard
4. To save to a named collection instead, click the bookmark icon and choose or create a collection

Sharing Media

1. Open any public media item
2. Click Share to see options: copy the direct link, or share to social networks
3. The share link respects the media's privacy - private media returns an error for unauthorized viewers

For Site Owners

1. All social features are enabled by default
2. Configure reaction types and moderation in Media > Settings > Social
3. Set the comment edit window (default: 15 minutes) in Media > Settings > Social
4. Set the auto-hide threshold: when a media item receives a certain number of reports, it is automatically hidden and sent to the moderation queue
5. BuddyPress notifications fire automatically for reactions, comments, and mentions when BuddyPress is active

Explore Feed Scope Filters (2.0.0)

The media listing REST endpoint accepts a scope parameter that narrows results to a viewer's own network, available across every layout (default grid and every Pro feed layout):

Value	Shows
public	Public media only
followers	Media from people the current viewer follows
self	Only the current viewer's own uploads

followers and self require a logged-in viewer and fall back to the public-only privacy gate for anonymous requests.

Reactions

WPMediaVerse uses a custom reactions system stored in a dedicated database table, separate from WordPress post meta.

REST API

Method	Endpoint	Description
GET	/mvs/v1/media/{id}/reactions	Get reaction counts for a media item
POST	/mvs/v1/media/{id}/reactions	Add or change your reaction
DELETE	/mvs/v1/media/{id}/reactions	Remove your reaction

Action: mvs_reaction_added

Fires when a reaction is added. BuddyPress integration uses this to send notifications.

do_action( 'mvs_reaction_added', $media_id, $user_id, $reaction_type );

Comments

WPMediaVerse uses a custom comments system stored in a dedicated table, separate from WordPress's wp_comments.

REST API

Method	Endpoint	Description
GET	/mvs/v1/media/{id}/comments	List comments on a media item
POST	/mvs/v1/media/{id}/comments	Post a new comment
PUT	/mvs/v1/media/{id}/comments/{comment_id}	Edit a comment
DELETE	/mvs/v1/media/{id}/comments/{comment_id}	Delete a comment

Action: mvs_comment_created

do_action( 'mvs_comment_created', $media_id, $user_id, $comment_id, $content, $source );

BuddyPress integration uses this to record activity and send notifications.

Favorites

Users can save media items to their favorites or to a named collection.

REST API

Method	Endpoint	Description
POST	/mvs/v1/media/{id}/favorite	Add to favorites
DELETE	/mvs/v1/media/{id}/favorite	Remove from favorites
GET	/mvs/v1/me/favorites	List the current user's favorites

Follows

Users can follow other users to see their public media in a feed.

REST API

Method	Endpoint	Description
POST	/mvs/v1/users/{id}/follow	Follow a user
DELETE	/mvs/v1/users/{id}/follow	Unfollow a user
GET	/mvs/v1/users/{id}/followers	List a user's followers
GET	/mvs/v1/users/{id}/following	List who a user follows

Mentions

Users can @mention each other in comments. Mentioned users receive a notification.

Action: mvs_mentions_created

do_action( 'mvs_mentions_created', $media_id, $mentioned_user_ids, $context, $comment_id );

Sharing

The ShareService provides share URL generation for media items. Shareable links respect the media's privacy level - private media returns a 403 when accessed via a share link by an unauthorized user.

Reports

Users can report inappropriate media content.

REST API

Method	Endpoint	Description
POST	/mvs/v1/media/{id}/report	Submit a content report

When the number of reports for a single media item reaches the Auto-Hide Threshold (set in AI & Moderation settings), the media is automatically hidden and added to the moderation queue.

Interests & Personalized Onboarding

Included in Free - This feature is available in the free version of WPMediaVerse.

New members pick a handful of interests, get a ranked list of creators to follow, and see a feed that leans toward what they picked - instead of landing on an empty explore page with nobody to follow and nothing personalized to see.

What You Can Do

• Choose interests from the site's existing media categories (mvs_category taxonomy) during first-session activation
• See a ranked "people you may know" list, boosted toward creators who post in your chosen interests
• Request an interest-aware media feed that favors your picks over a plain chronological/popular feed
• Skip the picker entirely and mark onboarding done without choosing anything

How It Works

1. On first login, a client shows the available interest chips - up to 40 of the site's most-used categories, each with a cover photo and post count
2. The member taps the interests they care about and saves
3. The site immediately has a ranked follow-suggestion list ready, weighted toward creators active in those interests
4. Requesting the feed with the interest-aware flag on returns media favoring the member's saved interests first

Today this ships as a REST API surface (built for the official MediaVerse app and for headless/custom frontends) rather than a bundled on-page picker screen in the default web templates - any client that speaks REST can build the picker UI on top of it.

For Site Owners

Nothing to configure - interests reuse the categories you already use for tagging media (mvs_category), so there's no separate taxonomy to maintain. The candidate pool for follow suggestions and the public interest list are both cached (default 1 hour) so this stays cheap on busy sites.

REST API

Base URL: /wp-json/mvs/v1/

GET /app/interests

Public (no authentication). Returns the available interest chips, ranked by post count.

Response:

[
  { "id": 12, "name": "Landscape", "slug": "landscape", "count": 340, "cover_url": "https://yoursite.com/..." }
]

Up to 40 categories. Cache TTL is filterable via mvs_app_interests_cache_ttl (default 1 hour, seconds; 0 disables caching).

---

GET /me/interests

Requires a logged-in user. Returns the current user's saved interest IDs.

Response:

{ "interest_ids": [12, 45] }

---

POST /me/interests

Requires a logged-in user. Save the member's interest picks.

Body:

{ "interest_ids": [12, 45] }

Only real mvs_category term IDs are kept; anything else is silently dropped. Saving also marks the member as onboarded (see below).

---

POST /me/onboarding/complete

Requires a logged-in user. Flags the viewer as onboarded without requiring them to pick any interests - the "skip" path.

Response:

{ "onboarded": true }

The onboarded flag is also surfaced on the member's own profile response so a client only shows the activation flow once.

---

GET /users/suggested

Requires a logged-in user (anonymous requests fall back to pure popularity ranking). Returns "people you may know" - creators ranked by follower count, boosted toward creators posting in the viewer's saved interests, excluding the viewer, anyone already followed, and anyone blocked.

Parameters:

Parameter	Type	Default	Description
limit	int	20	Maximum suggestions (1-50)

Candidate pool cache TTL is filterable via mvs_suggestions_cache_ttl (default 1 hour, seconds; 0 disables caching).

---

Interest-aware media feed

Pass interests=auto on the media listing endpoint (GET /mvs/v1/media) to narrow results toward the logged-in viewer's saved interest categories. Requires a logged-in user with at least one saved interest; anonymous viewers and members with no saved interests are unaffected (the feed never comes back empty because of this parameter).

Related

• Social Features - follow/unfollow and the explore feed's scope parameter
• Native App Readiness - interests shipped as part of the 1.9.0 native-app-readiness push

Direct Messages

Included in Free - This feature is available in the free version of WPMediaVerse.

Send private messages, share photos, record voice notes, and have real conversations - all without leaving your media community.

What You Can Do

• Send a private message to any member directly from their profile
• Attach photos, videos, or audio, or share a media item from the gallery straight into chat
• Record and send short voice messages
• React to individual messages with any emoji
• See typing indicators and read receipts in real time
• Mute noisy conversations, pin important ones, or archive old chats
• Search across all your messages to find anything instantly
• Control who can message you: everyone, followers only, mutual followers only, or nobody

How It Works (for Users)

Starting a Conversation

1. Visit any member's profile page
2. Click Message - the chat panel opens in the bottom-right corner with that conversation ready
3. Type your message and press Enter to send

To start a conversation without visiting a profile:

1. Click the chat icon at the bottom of any page
2. Click the compose icon inside the chat panel
3. Search for the member by name or username and select them

Sending a Voice Message

1. Open a conversation
2. Click the microphone icon in the message bar
3. Hold to record your message, then release to send
4. The recipient sees a playable audio clip in the conversation

Sharing a Photo in Chat

1. Open a conversation
2. Click the media icon (photo frame) in the message bar
3. Browse your uploaded media and click any item to share it directly into the chat

Managing Conversations

Action	How to do it
Mute	Open the conversation menu and click Mute - notifications are suppressed
Pin	Click Pin to keep the conversation at the top of your list
Archive	Click Archive to hide it from the main list. Find archived chats under the Archive tab
Search	Click the search icon in the panel header and type any word or phrase

Message Requests

If a member has restricted who can message them to followers only, your message goes to their Requests tab rather than their main inbox. They can accept or decline the request.

• Accept - Your conversation moves to their main inbox and messaging continues normally
• Decline - The request is removed. You are not notified of the decline

For Site Owners

1. Go to Media > Settings > Social to configure site-wide DM defaults
2. Set who can send DMs by default: everyone, followers, mutual followers, or nobody
3. Set a minimum account age (in days) to prevent new accounts from sending DMs
4. Users can override their own DM access setting from their account settings
5. The chat panel appears automatically at the bottom of every page for logged-in users - no shortcode needed
6. To adjust how often the chat checks for new messages, set the polling interval (default: 3 seconds)

Database Tables

Table	Purpose
mvs_conversations	One row per conversation, stores metadata (muted, pinned, archived state per participant)
mvs_conversation_participants	Maps users to conversations (supports future group chat expansion)
mvs_messages	Individual messages with content, type, read status, and soft-delete flag
mvs_message_reactions	Emoji reactions attached to individual messages

Opening a Conversation

There are three ways to start or open a conversation:

• From a profile page - Click the Message button on any user's profile. The chat panel opens with that conversation pre-loaded. No searching required.
• From the chat panel - Click the compose icon inside the chat panel and search by username or display name.
• Deep links - Link directly to a conversation or user using a URL fragment:

Fragment	Opens
#mvs-chat/{conversationId}	A specific conversation by ID
#mvs-chat/user/{userId}	The conversation with a specific user (creates one if none exists)

Chat Panel Features

Feature	Description
Text messages	Plain text with @mention support
Media attachments	Attach images, video, or audio. MediaVerse is a media platform, so documents (PDF, DOC, ZIP) are not accepted in chat as of 2.2.0 - a developer can extend the list with the mvs_dm_allowed_file_types filter. While a file uploads, the composer shows an "Uploading..." chip and Send waits for the upload to finish
Media sharing	Share a WPMediaVerse media item directly into a conversation
Voice messages	Record and send short audio clips
Emoji reactions	React to individual messages with any emoji
Typing indicators	Shows a live indicator when the other user is typing
Read receipts	Delivered and read timestamps shown per message
Message deletion	Delete your own messages (content replaced with "This message was deleted")

Conversation Management

Action	How
Mute	Suppress notifications for a conversation without leaving it
Pin	Keep a conversation at the top of the conversation list
Archive	Hide a conversation from the main list; accessible via the Archive tab
Search	Full-text search across all your messages via the search icon in the panel header

Privacy Settings

Each user controls their DM privacy from their account settings. Admins set the site-wide defaults at Media > Settings > Social.

Option	Key	Values
Who can message me	mvs_dm_access	everyone, followers, mutual, nobody
Minimum account age	mvs_dm_min_age	Integer (days). Prevents newly registered accounts from sending DMs.
Show online status	mvs_show_online_status	everyone, followers, or nobody

When mvs_dm_access is set to nobody, the Message button is hidden on that user's profile.

Content Moderation (1.9.0)

Every outgoing DM passes through the mvs_message_content_check filter before it is stored, the same seam other content types on the site already use to reject disallowed words. On its own, WPMediaVerse Free doesn't ship a word-blocklist for messages - the filter is what lets a host (a full community stack like BuddyNext, or your own mu-plugin) block a message the moment it's sent, so a member can't route banned words through a DM that would otherwise be caught in a comment or activity post. A blocked send returns an error instead of saving the message.

add_filter( 'mvs_message_content_check', function( $result, $content, $sender_id, $conversation_id ) {
    if ( str_contains( strtolower( $content ), 'bannedword' ) ) {
        return new WP_Error( 'content_blocked', 'That word is not allowed.' );
    }
    return $result; // true lets the message through.
}, 10, 4 );

Transport

The chat panel polls the REST API to fetch new messages. There are three intervals (in milliseconds), chosen by context: an open conversation polls fastest, the conversation list slower, and a closed panel slowest. The defaults are active 3000, list 10000, and background 30000.

Filter the intervals with mvs_messaging_poll_intervals:

add_filter( 'mvs_messaging_poll_intervals', function( $intervals ) {
    $intervals['active'] = 2000; // Poll the open conversation every 2 seconds.
    return $intervals;
} );

REST API

Base URL: /wp-json/mvs/v1/

All endpoints require a logged-in user. Pass the X-WP-Nonce header with a nonce from wp_create_nonce( 'wp_rest' ).

POST /conversations

Start a new conversation.

Body:

{ "recipient_id": 42 }

Response: 201 Created with the new conversation object, or 200 OK with the existing conversation if one already exists between the two users.

---

GET /me/conversations

List all conversations for the current user. Excludes archived conversations unless ?include_archived=1 is passed.

Parameters:

Parameter	Type	Default	Description
include_archived	int	0	Set to 1 to include archived conversations
per_page	int	20	Conversations per page
page	int	1	Page number

---

GET /conversations/{id}/messages

List messages in a conversation. The current user must be a participant.

Parameters:

Parameter	Type	Default	Description
per_page	int	30	Messages per page
before	int	0	Return messages with ID lower than this value (for pagination). 0 means no cursor.

---

POST /conversations/{id}/messages

Send a message. The current user must be a participant and must satisfy the recipient's mvs_dm_access setting.

Body (JSON or multipart/form-data for file attachments):

Field	Required	Description
content	No	Text content. Defaults to empty string.
message_type	No	Message type: text (default), media_share, image, video, audio, voice, file, system. Unknown values fall back to text.
media_id	No	WPMediaVerse media ID when message_type=media_share
attachment_id	No	WordPress attachment ID from a prior POST /messages/upload, used for image/video/audio/voice/file messages
parent_id	No	Message ID to reply to. Creates a threaded reply visible under the parent message.
metadata	No	Object of extra data (e.g. { "duration": 12 } for voice messages).

Response: 201 Created with the new message object.

---

GET /conversations/{id}/messages/search

Search message content within a single conversation (1.9.0). The current user must be a participant.

Parameters:

Parameter	Type	Default	Description
q	string	(required)	Search term matched against message content
per_page	int	50	Matching messages per page

Response: Array of matching message objects, same shape as GET /conversations/{id}/messages.

---

POST /messages/upload

Upload a file to use as a DM attachment. Returns the WordPress attachment ID to pass as attachment_id in a subsequent POST /conversations/{id}/messages call.

Body: multipart/form-data with a file field.

Allowed types (2.2.0): media only - image/jpeg, image/png, image/gif, image/webp, audio/webm, audio/mp4, audio/mpeg, audio/ogg, video/mp4, video/webm. The real MIME is sniffed server-side (finfo), so renaming a file does not bypass the check; anything else returns 400 File type not allowed. Extend the list with the mvs_dm_allowed_file_types filter. (The file message type remains for messages sent before 2.2.0.)

Response: 200 OK

{ "id": 123, "source_url": "https://yoursite.com/...", "thumbnail": "https://yoursite.com/..." }

---

PATCH /conversations/{id}

Update conversation state for the current user.

Body:

Field	Type	Description
is_muted	bool	Set to true to mute, false to unmute
is_pinned	bool	Set to true to pin, false to unpin
is_archived	bool	Set to true to archive, false to restore

Response: 200 OK with the updated conversation object.

---

DELETE /conversations/{id}

Delete a conversation for the current user. The conversation remains visible to the other participant.

Response: 204 No Content

---

DELETE /messages/{id}

Soft-delete a message. Requires ownership of the message. The message record is kept but its content is replaced and is_deleted is set to 1.

---

DELETE /messages/{id}/unsend

Hard-delete a message. Only available within the edit window (default: 5 minutes after sending). Requires ownership of the message. The message record is permanently removed.

Response: 204 No Content

---

GET /me/messages/unread-count

Return the total number of unread messages across all conversations for the current user. Used to update the chat panel badge.

Response:

{ "unread": 4 }

---

POST /messages/{id}/reactions

Add or change a reaction on a message.

{ "emoji": "❤️" }

To remove a reaction, call DELETE /messages/{id}/reactions.

---

Actions and Filters

mvs_message_sent

Fires after a message is successfully saved.

add_action( 'mvs_message_sent', function( $message_id, $conversation_id, $sender_id, $recipient_ids ) {
    // React to the new message.
}, 10, 4 );

mvs_message_types

Filter the list of allowed message types accepted by the send endpoint.

add_filter( 'mvs_message_types', function( $types ) {
    return $types; // Default: text, media_share, image, video, audio, voice, file, system.
} );

mvs_messaging_poll_intervals

Filter the client-side polling intervals (in milliseconds) delivered to the front end. See the Transport section above.

mvs_message_content_check

Filter fired before a message is stored. Return a WP_Error to block the send; return the passed-in true (or anything not a WP_Error) to let it through. See the Content Moderation section above.

Privacy & Access Control

Free + Pro - Core functionality is included free. Features marked with (Pro) require WPMediaVerse Pro.

WPMediaVerse provides 6 privacy levels for media items, albums, and collections. Access checks run on every REST API call and on the explore archive query.

Privacy Levels

Level	Value	Who Can View
Public	public	Everyone, including logged-out visitors
Members Only	members	Any logged-in WordPress user
Friends	friends	BuddyPress friends of the media owner (requires BuddyPress active)
Group	group	Members of a specific BuddyPress group (requires BuddyPress active)
Private	private	Only the media owner and users with moderate_mvs_media
Custom	custom	A specific list of user IDs defined via access grants

Owners and Moderators Always Have Access

Media owners (the post_author) and users with the moderate_mvs_media capability bypass all privacy checks. They can view all media regardless of its privacy level.

Setting Privacy on Upload

Set the privacy field when creating media via REST API:

curl -X POST https://yoursite.com/wp-json/mvs/v1/media \
  -H "X-WP-Nonce: NONCE" \
  -F "file=@photo.jpg" \
  -F "privacy=friends"

For group privacy, also include group_id:

  -F "privacy=group" \
  -F "group_id=42"

Changing Privacy After Upload

curl -X PUT https://yoursite.com/wp-json/mvs/v1/media/123 \
  -H "X-WP-Nonce: NONCE" \
  -H "Content-Type: application/json" \
  -d '{"privacy": "private"}'

Custom Access Grants

For custom privacy, grant access to specific users:

curl -X POST https://yoursite.com/wp-json/mvs/v1/media/123/grant \
  -H "X-WP-Nonce: NONCE" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 55,
    "expires_at": "2026-01-01T00:00:00Z"
  }'

Access grants can have optional expiry dates. Expired grants are cleaned up via wp mvs cleanup-expired or via cron.

Signed URLs for Private Files

For media stored with a non-public privacy level, WPMediaVerse can generate time-limited signed URLs:

curl https://yoursite.com/wp-json/mvs/v1/media/123/signed-url \
  -H "X-WP-Nonce: NONCE"

Response:

{
  "url": "https://yoursite.com/wp-content/uploads/wpmediaverse/2025/03/photo.jpg?token=abc123&expires=1743000000",
  "expires_at": "2025-03-27T13:00:00Z"
}

The signed URL TTL defaults to 3600 seconds (1 hour) and is configurable in Media > Settings > Storage > Signed URL Expiry (seconds).

Filtering Privacy Access in Code

Use the mvs_privacy_can_view filter to extend or override access logic:

add_filter( 'mvs_privacy_can_view', function( $result, $media_id, $user_id, $privacy ) {
    // Grant access to premium subscribers regardless of privacy level.
    if ( null === $result && wcs_user_has_subscription( $user_id, '', 'active' ) ) {
        return true;
    }
    return $result;
}, 10, 4 );

Return null to let the built-in logic run. Return true or false to override it.

Explore Archive Privacy Filtering

On the explore archive (/media/), WPMediaVerse applies automatic privacy filtering through a SQL clause on its own mvs_media_index table (a privacy IN (...) OR post_author = current gate shared by every explore surface), not a WordPress posts_where filter:

• Logged-out users see only public media.
• Logged-in non-moderators see public, members media, and their own media (any privacy level).
• Moderators (moderate_mvs_media capability) see all media.

AI Moderation

Free + Pro - Core functionality is included free. Features marked with (Pro) require WPMediaVerse Pro.

WPMediaVerse integrates with OpenAI Vision (GPT-4o or GPT-4o Mini) to automatically analyze and moderate uploaded media. WPMediaVerse Pro adds support for Google Vision, AWS Rekognition, and Claude (Anthropic).

How AI Analysis Works

When Auto-Analyze Uploads is enabled, WPMediaVerse sends each uploaded image to OpenAI immediately after storage. The analysis returns:

• A natural-language description of the image
• Suggested tags (comma-separated keywords)
• Safety categories with confidence scores (adult content, violence, etc.)

The description is saved to the ai_description media metadata key. If Auto-Apply Tags is enabled, the suggested tags are assigned to the mvs_tag taxonomy.

How AI Moderation Works

When Auto-Moderate Uploads is enabled, WPMediaVerse checks the AI safety scores against configurable thresholds. If a policy violation is detected, the action defined in When AI Flags Content is applied:

Action	What Happens
Flag for review	Media stays published but appears in the moderation queue
Hide	Media's privacy is set to private
Reject	Media's post_status is set to draft
Delete permanently	Media and its files are removed from local and cloud storage. Cannot be undone.

Moderation status changes fire the mvs_moderation_changed action hook ($media_id, $status, $old_status, $user_id).

Triggering Analysis Manually

Site administrators can re-analyze any media item from the moderation queue or via the REST API:

curl -X POST https://yoursite.com/wp-json/mvs/v1/moderation/123/analyze \
  -H "X-WP-Nonce: NONCE"

Approving or Rejecting from the Moderation Queue

1. Go to Media > Media Moderation (renamed from "Moderation" in 2.0.0).
2. Review the flagged item and its AI analysis result.
3. Click Approve to publish or Reject to move to draft.

Budget Control

Set a monthly spending cap at Media > Settings > AI & Moderation > Monthly AI Budget ($). WPMediaVerse tracks estimated spending per call and stops making AI calls when the budget is reached.

To check current spending:

wp mvs stats

Registering a Custom AI Provider (Developer)

Implement the AIProviderInterface and register your provider:

use WPMediaVerse\Services\AIProviderInterface;

class MyCustomProvider implements AIProviderInterface {

    public function get_id(): string {
        return 'my_provider';
    }

    public function is_available(): bool {
        return (bool) get_option( 'my_provider_api_key' );
    }

    public function analyze( int $media_id ): array|WP_Error {
        // Return array with 'description', 'tags', 'flags'.
    }
}

add_action( 'mvs_ai_providers', function( $ai_service ) {
    $ai_service->register_provider( new MyCustomProvider() );
} );

Moderation & AI Metadata

These keys live in WPMediaVerse's mvs_media_meta table (accessed via the MediaRepository), not in WordPress post meta. moderation_status is also a column on the mvs_media_index table.

Meta Key	Values	Description
moderation_status	approved, pending, flagged, rejected	Current moderation status
ai_description	string	AI-generated description
ai_tags	string[]	AI-suggested tags
ai_confidence	float	Confidence score for the AI analysis

Shortcodes

Included in Free - This feature is available in the free version of WPMediaVerse.

WPMediaVerse provides 12 shortcodes for embedding media features in pages, posts, and classic editor content.

[mvs_gallery]

Displays a filterable media grid. Columns and items-per-page come from Media > Settings > Display and cannot be overridden by shortcode attributes.

[mvs_gallery]
[mvs_gallery type="image" category="nature" tag="summer" orderby="date"]

Attribute	Default	Description
type	(all types)	Filter by media type: image, video, or audio
category	(all)	Filter by mvs_category slug
tag	(all)	Filter by mvs_tag slug
user_id	(all authors)	Filter to a single author. Pair with orderby="popular" for a "Top media by this member" embed.
orderby	date	Sort order: date, title, views, popular, reactions, or random.
order	desc	Sort direction: asc or desc.

[mvs_upload]

Displays the frontend file upload form. The form is only functional for logged-in users.

[mvs_upload]
[mvs_upload max_files="5" show_privacy="true"]

Attribute	Default	Description
max_files	10	Maximum number of files selectable at once
show_privacy	true	Show privacy level selector on the form

This shortcode fires the mvs_before_upload_form action before rendering.

[mvs_album]

Displays a single album by ID.

[mvs_album id="123"]
[mvs_album id="123" columns="4" show_title="true" show_description="false"]

Attribute	Default	Description
id	(required)	Album post ID
columns	3	Grid columns
show_title	true	Show album title
show_description	true	Show album description

[mvs_player]

Embeds a single media item in an interactive player.

[mvs_player id="456"]
[mvs_player id="456" autoplay="false" loop="false" download="false"]

Attribute	Default	Description
id	(required)	Media post ID
autoplay	false	Start playback automatically (audio/video)
loop	false	Loop the media after it finishes
download	false	Show a download button

[mvs_stats]

Displays site-wide media statistics.

[mvs_stats]
[mvs_stats views="true" downloads="true" reactions="true" top="true" top_count="5"]

Attribute	Default	Description
views	true	Show total view count
downloads	true	Show total download count
reactions	true	Show total reaction count
top	true	Show the top media list
top_count	5	Number of items in the top media list

[mvs_dashboard]

Displays a personal media dashboard for the logged-in user. Shows the user's own uploads, albums, and stats. Redirects to login if the user is not logged in.

[mvs_dashboard]

No configurable attributes. The dashboard uses the dashboard-view Interactivity API block store.

[mvs_collection]

Displays a collection by ID. Works for both manual and smart collections.

[mvs_collection id="789"]
[mvs_collection id="789" columns="3" per_page="20"]

Attribute	Default	Description
id	(required)	Collection post ID
columns	3	Grid columns
per_page	20	Maximum items to show

[mvs_profile_edit]

Displays a profile edit form for the logged-in user, allowing them to update their first name, last name, display name, bio, and avatar. Redirects to login if not logged in.

[mvs_profile_edit]

No configurable attributes. The form is powered by the mvs/profile-edit Interactivity API store and saves to /mvs/v1/profile.

[mvs_explore_feed]

Embeds the explore archive - infinite-scroll public media feed with filter chips and the new search autocomplete dropdown. Use this when you want the explore experience on a custom page rather than the dedicated archive route.

[mvs_explore_feed]
[mvs_explore_feed layout="grid" columns="3" per_page="12" filters="true" search="true"]

Attribute	Default	Description
layout	grid	Feed layout.
columns	3	Grid columns.
per_page	12	Items per page.
filters	true	Show the filter chips.
search	true	Show the search input with autocomplete.

[mvs_lock_overlay]

Renders a privacy lock overlay for a single media item. If the current user has access, the overlay falls through and renders the player or image inline. If they do not, the overlay shows the configured restriction message.

[mvs_lock_overlay id="456"]
[mvs_lock_overlay id="456" blur="20" overlay_opacity="60" unlock_label="Restricted Content"]

Attribute	Default	Description
id	(required)	Media post ID to evaluate access against.
blur	20	Blur amount applied to the locked preview.
overlay_opacity	60	Overlay opacity (0-100).
unlock_label	(empty)	Custom restriction label.

[mvs_member_photos]

Renders a member's media grid. Auto-resolves the user - explicit user_id attribute first, then the BuddyPress displayed user, then the post author, then the current user - so the same shortcode works on profile pages, member-specific landing pages, and author archives.

Added in 1.2.0.

[mvs_member_photos]
[mvs_member_photos user_id="42" columns="3" per_page="12" type="image" show_header="true" actions="true"]

Attribute	Default	Description
user_id	(auto-detect)	Force a specific user. Leave empty to use the four-step resolution chain.
columns	3	Grid columns.
per_page	12	Items per page.
type	(all types)	Filter by media type: image, video, or audio.
show_header	true	Show the member header above the grid.
actions	true	Show per-item action controls.

[mvs_pdf_viewer]

Embeds a PDF using the browser-native viewer (the #view=FitH URL fragment). No third-party JS, no licensing concerns.

Added in 1.2.0.

[mvs_pdf_viewer id="123"]
[mvs_pdf_viewer id="123" height="800" toolbar="false"]

Attribute	Default	Description
id	(required)	Media ID of the PDF.
height	600	Viewer height in pixels. Range: 200-1400.
toolbar	true	Show or hide the browser PDF toolbar. true to show, false to hide.

Usage History

Free. Requires a logged-in visitor - renders nothing for guests.

Shows the current member's own upload usage ledger. Useful on an account page beside the quota widget when you sell upload packages with Pro.

[mvs_usage_history]
[mvs_usage_history limit="50"]

Attribute	Default	Description
limit	20	Number of ledger rows to show, most recent first.

Pro: Compete shortcodes

These require WPMediaVerse Pro, and each one needs its feature toggle enabled. With the toggle off the shortcode renders nothing rather than an error.

Every block in the Compete set has a matching shortcode, so you can place competitions on a classic-editor page or inside a page builder.

Shortcode	Feature toggle	Purpose
[mvs_pro_compete_hub]	any Compete feature	The combined hub - challenges, battles, tournaments and leaderboard in one tabbed surface.
[mvs_pro_challenge id="12"]	mvs_challenges_enabled	One challenge, with its entry or voting interface.
[mvs_pro_challenges_list]	mvs_challenges_enabled	All challenges, grouped by state.
[mvs_pro_battle id="8"]	mvs_battles_enabled	One head-to-head battle with its voting UI.
[mvs_pro_battles_active]	mvs_battles_enabled	Every battle currently open for voting.
[mvs_pro_tournament id="3"]	mvs_tournaments_enabled	One tournament bracket.
[mvs_pro_tournaments_list]	mvs_tournaments_enabled	All tournaments, grouped by state.
[mvs_pro_leaderboard]	-	Top creators ranking.

The single-item shortcodes (mvs_pro_challenge, mvs_pro_battle, mvs_pro_tournament) take a required id attribute and render nothing when it is missing or zero.

Leaderboard attributes

[mvs_pro_leaderboard source="reactions" window="month" per-page="25"]

Attribute	Default	Description
source	reactions	What to rank by.
window	all	Time window for the ranking. all counts everything.
per-page	10	Number of creators listed.

Presentation attributes

All eight Compete shortcodes accept the same optional presentation attributes, which map to the equivalent block settings. Leave them empty to inherit your theme's styling.

Attribute	Description
padding-desktop, padding-tablet, padding-mobile	Per-breakpoint padding.
margin-desktop, margin-tablet, margin-mobile	Per-breakpoint margin.
border-width, border-color, border-radius	Border styling.
shadow-enabled, shadow-offset-x, shadow-offset-y, shadow-blur	Drop shadow.

Use hyphens in shortcode attributes (padding-desktop); they are converted to the camelCase block attributes internally.

Pro: Layout feed shortcodes

Require WPMediaVerse Pro. See Layout Modes for what each layout looks like.

Shortcode	Layout
[mvs_pro_instagram_feed]	Instagram-style square grid
[mvs_pro_flickr_feed]	Flickr-style justified rows
[mvs_pro_pinterest_feed]	Pinterest-style masonry columns
[mvs_pro_dribbble_feed]	Dribbble-style cards with stats

These accept the same presentation attributes as the Compete shortcodes.

Gutenberg Blocks

Included in Free - This feature is available in the free version of WPMediaVerse.

WPMediaVerse registers 9 Gutenberg blocks under the WPMediaVerse block category. All blocks use the WordPress Interactivity API for reactive front-end behavior without a separate JavaScript framework.

Block List

Block Name	Handle	Description
Media Upload	mvs/media-upload	Frontend file upload form with drag-and-drop
Media Grid	mvs/media-grid	Filterable, paginated media gallery grid
Media Player	mvs/media-player	Single-item audio/video player with controls
Album Viewer	mvs/album-viewer	Displays a single album's media in a grid
Member Photos	mvs/member-photos	Auto-detects the user (explicit userId → BuddyPress displayed user → post author → current user) and renders their media grid
PDF Viewer	mvs/pdf-viewer	Browser-native PDF embed using the #view=FitH URL fragment. Configurable height, optional toolbar, five distinct empty states
Media Stats	mvs/media-stats	Site-wide or per-user media statistics
Explore Feed	mvs/explore-feed	Infinite-scroll explore feed (all public media) with search autocomplete
Lock Overlay	mvs/lock-overlay	Paywall/restriction overlay for any block

Story Viewer is not in this list of 9. The block source and the server-side StoryService that used to ship here were relocated to Pro in 1.9.0 along with a complete Stories feature (create-flow toggle, viewer, REST API, view receipts). See Stories (Pro).

Interactivity API Architecture

Each block ships with a view.js module registered via wp_enqueue_script_module(). Blocks communicate through shared state in the mvs interactivity store. The shared-ui module provides common utilities (REST fetching, nonce management) shared by all blocks.

Using Blocks in Templates

All registered blocks can be used in Full Site Editing (FSE) templates, template parts, and block patterns. They are fully compatible with query blocks and block themes.

Media Upload Block

Block Settings:

• Max Files per Upload (default: 10)
• Show Privacy Selector (default: on)

Upload modal polish (1.2.0):

• Preview tiles show the filename (truncated tastefully) and a per-tile remove (×) button.
• Audio files render with a dedicated audio fallback icon instead of a broken thumbnail.
• A row of eight popular tag pills appears below the tags input - click to append, no duplicates.

Media Grid Block

Block Settings:

• Media Type Filter (image/video/audio/all)
• Category Filter
• Tag Filter
• Sort Order - date, title, popular, views, reactions, random
• Sort Direction - asc / desc
• User ID filter (userId) - restrict the grid to a single author
• Lightbox (default: on)
• Show Reactions (default: on)

Grid columns and pagination inherit from Media > Settings > Display.

Sorting (1.2.0): Most Popular and Most Reactions sorts join the mvs_media_stats table to rank by aggregate engagement. Random sort reshuffles each page load.

Media Player Block

Block Settings:

• Media ID (required - use the picker to select)
• Autoplay (default: off)
• Loop (default: off)
• Show Download Button (default: off)

Album Viewer Block

Block Settings:

• Album (select from a dropdown of your albums)
• Columns override
• Show Title / Show Description

Story Viewer (Pro)

Stories moved to Pro in 1.9.0 as a complete feature: the mvs/pro-stories block (stories bar + fullscreen viewer), a create-from-the-bar upload tile, mvs-pro/v1 REST routes, and view receipts. It is a Pro-registered block, not one of the 9 free blocks above. See Stories (Pro) for the full reference.

Member Photos Block

The Member Photos block renders a single member's media grid. The block resolves the user automatically using a four-step fallback chain so the same block works in profile templates, member-specific pages, author archives, and BuddyPress profile tabs without per-page wiring.

Resolution order:

1. Explicit userId attribute on the block
2. BuddyPress displayed user (when on a BP profile)
3. Post author (when in a single-post context)
4. Current logged-in user

Block Settings:

• User ID (optional - leave empty to auto-detect)
• Items Per Page
• Sort Order - same options as Media Grid

PDF Viewer Block

The PDF Viewer block embeds a PDF using the browser's native viewer via the #view=FitH URL fragment - no third-party JS, no licensing concerns.

Block Settings:

• Media ID (required - pick a PDF media item)
• Height (200-1400 px, default 600)
• Show Toolbar (default: on)

Empty states: the block emits five distinct empty states - no media selected, wrong media type, missing file, access denied, and a generic fallback.

Media Stats Block

Block Settings:

• Show Views (default: on)
• Show Downloads (default: on)
• Show Reactions (default: on)
• Show Top Media (default: on)
• Top Media Count (default: 5)

Explore Feed Block

The Explore Feed block provides an infinite-scroll feed of all public media. It supports URL-based filtering via ?mvs_tag=slug and ?s=search-term query parameters.

Search autocomplete (1.2.0): the search input now shows a type-ahead dropdown - top eight title matches, debounced 250 ms, full keyboard navigation (Arrow keys, Enter, Escape) and ARIA combobox semantics for screen reader users.

Lock Overlay Block

The Lock Overlay block wraps any other block content and shows a restriction message to users who do not meet access criteria. Configure access rules via the Access Control REST API.

Internal blocks (not in the inserter)

Four registered blocks are deliberately hidden from the block inserter. They carry no markup of their own - each one registers an Interactivity API store that the plugin's templates bind to, which is how a page rendered by a shortcode still gets a fully reactive interface.

Block	Purpose
mvs/dashboard-view	Dashboard store for the My Media, Albums and Favorites tabs
mvs/explore-view	Explore page tag-cloud store
mvs/media-social	Social interactions store for single media and album pages
mvs/shared-ui	Shared UI store - toasts, confirm dialogs, tag autocomplete

Each declares "supports": { "inserter": false } in its block.json, so it never appears in the editor. You do not add these to a page and there is nothing to configure. They are listed here so that a block audit of the site does not report them as stray registrations.

Do not remove these from a custom build. The dashboard, explore and single-media templates bind to these stores by name. Dropping one leaves the matching interface inert - buttons render but nothing responds.

GDPR & Privacy Compliance

Included in Free - This feature is available in the free version of WPMediaVerse.

WPMediaVerse integrates with the WordPress privacy tools built into Tools > Export Personal Data and Tools > Erase Personal Data. No configuration is required. The integration is active whenever the plugin is active.

The privacy functionality lives in GDPRService.php.

What Gets Exported

When an administrator runs a personal data export for a user, WPMediaVerse adds the following data groups to the export ZIP:

Data Group	What Is Included
Media uploads	File URLs, titles, descriptions, privacy level, upload date
Comments	All comments the user posted on media items
Reactions	Each reaction (emoji, media item, timestamp)
Favorites	Each media item the user saved as a favorite
Direct messages	All conversation participants and message content
Follow relationships	List of users the subject follows and users following the subject

The export respects the WordPress standard format. Each group appears as a named section in the downloadable HTML and JSON files.

What Gets Erased

When an administrator runs a personal data erasure for a user, WPMediaVerse removes:

• All media items uploaded by that user (files and database records)
• All comments posted by that user on media items
• All reactions and favorites
• All direct message conversations and messages where the user is a participant
• All follow relationships (both directions)

Erasure is permanent and cannot be undone. Media items that belong to BuddyPress groups are also removed.

Before erasing, WordPress asks the user to confirm the request via email. WPMediaVerse erasure only runs after that confirmation is received.

Privacy Policy Text

WPMediaVerse registers suggested privacy policy text via wp_add_privacy_policy_content(). The suggestion appears in the Privacy Policy Guide at Settings > Privacy > Privacy Policy Guide.

The suggested text describes:

• What media metadata is collected and stored
• How direct messages are stored and for how long
• What follow data is retained
• How to request export or erasure

You are not required to use the suggested text verbatim. Review it and incorporate the relevant parts into your site's privacy policy.

Developer Notes

WPMediaVerse registers its exporters and erasers through the standard WordPress privacy hooks. It does not add its own wrapper filters - extend the export/erase flow with the WordPress-core filters directly.

Adding Custom Data to the Export

Register your own exporter via WordPress core's wp_privacy_personal_data_exporters filter:

add_filter( 'wp_privacy_personal_data_exporters', function( $exporters ) {
    $exporters['my-extension'] = [
        'exporter_friendly_name' => __( 'My Extension Data', 'my-extension' ),
        'callback'               => 'my_extension_export_callback',
    ];
    return $exporters;
} );

Hooking into Erasure

Register your own eraser via WordPress core's wp_privacy_personal_data_erasers filter:

add_filter( 'wp_privacy_personal_data_erasers', function( $erasers ) {
    $erasers['my-extension'] = [
        'eraser_friendly_name' => __( 'My Extension Data', 'my-extension' ),
        'callback'             => 'my_extension_erase_callback',
    ];
    return $erasers;
} );

User Blocking & Reporting

Included in Free - This feature is available in the free version of WPMediaVerse.

WPMediaVerse includes a blocking system that prevents specific users from interacting with you and a reporting system that lets users flag abusive content or accounts for moderator review.

Blocking a User

You can block a user from two places:

• From their profile page - Open the action menu on the user's profile card and select Block User.
• From the report flow - After submitting a report against a user, you are offered the option to also block them.

What Blocking Does

When you block a user, they cannot:

• View your media items (media items are hidden from them on all browse pages and their direct URLs return a 403)
• Send you direct messages (your profile shows no Message button for them; any existing conversation is locked)
• Follow you (the Follow button is removed for them)
• Comment on your media
• React to your media

Blocking is one-directional. You can still view the blocked user's public media unless you also choose to hide it.

Blocks are stored per-user and do not require any admin action.

Unblocking a User

Go to Account Settings > Blocked Users to see your full block list and remove individual blocks. You can also unblock via the REST API.

User Reporting

Reporting a user notifies the site moderators. It does not automatically take any action on the reported account.

To report a user, open the action menu on their profile card and select Report User. Choose a reason from the dropdown and optionally add details.

Report Reasons

The same reason whitelist applies to both user and media reports:

Value
spam
harassment
nudity
violence
copyright
misinformation
other

Reports appear in Media > Media Moderation under the Users tab. Moderators with the moderate_mvs_media capability can review, dismiss, or act on reports.

Media Reporting

Any logged-in user can report a media item from the media card or the media detail page using the flag icon.

Report Reasons

Media reports use the same whitelist as user reports: spam, harassment, nudity, violence, copyright, misinformation, other.

When a media item accumulates reports equal to the Auto-Hide Threshold set in Media > Settings > AI & Moderation, it is automatically hidden and added to the moderation queue.

REST API

Base URL: /wp-json/mvs/v1/

All endpoints require a logged-in user. Pass the X-WP-Nonce header with a nonce from wp_create_nonce( 'wp_rest' ).

POST /users/{id}/block

Block a user.

Response: 200 OK

{ "blocked": true }

---

DELETE /users/{id}/block

Unblock a user.

Response: 200 OK

{ "blocked": false }

---

GET /me/blocked

List users blocked by the current user.

Parameters:

Parameter	Type	Default	Description
per_page	int	20	Blocked users per page
page	int	1	Page number

Response: Array of user objects with id, name, and avatar_url.

---

POST /users/{id}/report

Report a user account.

Body:

Field	Required	Description
reason	Yes	One of: spam, harassment, nudity, violence, copyright, misinformation, other
details	No	Optional free-text note visible to moderators

Response: 200 OK

{ "reported": true }

---

POST /media/{id}/report

Report a media item.

Body:

Field	Required	Description
reason	Yes	One of: spam, harassment, nudity, violence, copyright, misinformation, other
details	No	Optional free-text note

Response: 200 OK

{ "reported": true }

---

Actions and Filters

mvs_user_blocked

Fires after a user is blocked.

add_action( 'mvs_user_blocked', function( $blocker_id, $blocked_id ) {
    // Perform additional cleanup or logging.
}, 10, 2 );

mvs_report_submitted

Fires after a report (user or media) is submitted. The $target_type is user or media.

add_action( 'mvs_report_submitted', function( $report_id, $reporter_id, $target_type, $target_id, $reason ) {
    // Notify a Slack channel, send to an external moderation service, etc.
}, 10, 5 );

Image Optimization

Included in Free - This feature is available in the free version of WPMediaVerse.

WPMediaVerse automatically reduces image file sizes at upload time. No extra plugin is required. Originals are never made larger: if re-encoding produces no gain, the original file is kept untouched.

What It Does

When a JPEG, PNG, or GIF is uploaded:

1. The file is re-encoded at high quality with embedded camera metadata stripped.
2. The result is compared to the original. If it is smaller, the smaller file is committed. If not, the original is kept.
3. A WebP copy is generated alongside the original and every thumbnail size (on by default).
4. An AVIF copy can optionally be generated for even smaller file sizes (off by default; slower to encode).

Animated GIFs are detected and skipped from the lossless re-encode step. Their frames are preserved.

How Browsers Receive Images

WPMediaVerse uses a <picture> element with progressive fallback. Browsers receive the most efficient format they support:

1. AVIF (if enabled and available)
2. WebP (if enabled and available)
3. Original JPEG/PNG/GIF (always served as a fallback)

This format negotiation applies across the explore grid, BuddyPress activity stream, the media dashboard, single media pages, and the lightbox. No JavaScript is required; it is handled by native browser behavior.

Settings

Access these settings at Media > Settings > Storage.

Setting	Default	Description
Compress uploaded images	On	Re-encodes JPEG, PNG, and GIF originals to remove camera metadata and reduce file size. Works alongside EWWW, Imagify, Smush, and ShortPixel.
Create WebP copies for faster loading	On	Saves a WebP copy next to every original and thumbnail. WebP files are typically 25 to 35 percent smaller than JPEG.
Create AVIF copies for the smallest possible files	Off	Saves an AVIF copy next to every original and thumbnail. AVIF is around 30 to 50 percent smaller than WebP. Encoding is much slower than WebP. Requires Imagick with libheif, or GD on PHP 8.1+ with libavif.

Toggling any setting takes effect on the next upload. Settings do not retroactively process existing media.

Admin: Optimization Column

The Optimization column on the Media > All Media list shows the result for each image:

Badge	Meaning
-23% (green)	The original was re-encoded and reduced by that percentage.
WebP ready (green)	No lossless gain on the original, but a WebP copy was generated.
No lossless gain (grey)	Re-encoding did not reduce the file and WebP was not generated.
Not optimized	The image has not been through the optimization pipeline yet.

Each image row also has two row actions: Optimize (re-runs the optimization pipeline for that image) and Details (opens a detail page at ?page=mvs-media&view=details&media_id=N showing file sizes, savings percentage, and variant URLs).

Bulk Optimization and WP-CLI

To optimize images uploaded before 1.3.0, use WP-CLI:

wp mvs optimize <id>
wp mvs optimize-bulk

Both commands are resume-safe. See the WP-CLI reference for all available options.

For Developers

To replace the built-in optimizer with an external service (EWWW, Imagify, Smush, ShortPixel, or a custom compressor), hook into the mvs_optimize_image filter. See the Hooks and Filters reference for the full signature and examples.

BuddyPress Integration Overview

Included in Free - WPMediaVerse is the most complete media solution for BuddyPress communities. Integration is optional - the plugin works standalone on any WordPress site, but when BuddyPress is active, it unlocks profile tabs, group media, activity stream, and notifications automatically.

WPMediaVerse integrates with BuddyPress to add media features directly into the BuddyPress social layer. The integration is automatic - no configuration needed. It activates when BuddyPress is active and gracefully skips all BP-specific code when BuddyPress is not installed.

Requirements

• BuddyPress 12.0+
• WPMediaVerse 1.0.0+

What the Integration Adds

BuddyPress Component	Feature Added
Activity	Records activity on media upload, comment, and album additions
Member Profiles	Adds a Media tab showing the member's uploads
Groups	Adds a Media tab in group navigation
Notifications	Sends notifications for reactions, comments, and @mentions
Activity Post Form	Adds a media attach button to the activity update form

Activation Check

The integration loads via BuddyPressManager::init(), which is called on plugins_loaded. Every feature check begins with:

if ( ! function_exists( 'buddypress' ) ) {
    return;
}

Individual features additionally check bp_is_active( 'activity' ), bp_is_active( 'groups' ), and bp_is_active( 'notifications' ) before hooking.

Multisite Compatibility

The BuddyPress integration works on WordPress Multisite networks. Activity and notifications are scoped to the site where BuddyPress is installed. Media uploaded on a subsite is recorded in that subsite's activity stream.

Profile Media Tab

Included in Free - WPMediaVerse is the most complete media solution for BuddyPress communities. Integration is optional - the plugin works standalone on any WordPress site, but when BuddyPress is active, it unlocks profile tabs, group media, activity stream, and notifications automatically.

When BuddyPress is active, WPMediaVerse adds a Media tab to every user's BuddyPress profile page.

Tab Location

The tab appears in the main BuddyPress profile navigation at:

/members/{username}/media/

It is added via bp_setup_nav at priority 100.

What the Tab Shows

The Media tab displays the profile owner's published media items in a paginated grid. Privacy filtering applies:

• Visitors see only the profile owner's public media.
• Logged-in users see public and members-only media.
• BuddyPress friends see public, members-only, and friends media.
• The profile owner sees all their own media.
• Moderators (moderate_mvs_media) see all media.

Profile URL Pattern

WPMediaVerse also registers a standalone media profile URL:

/media/@{username}/
/media/@{username}/page/2/

These URLs are handled by the TemplateLoader and use the explore.php template, filtered to the specific user.

User Profile Edit Page

Logged-in users can edit their avatar and profile details at:

/media/edit-profile/

Or use the [mvs_profile_edit] shortcode on any page.

Disabling the Profile Tab

To remove the profile tab without disabling the entire integration:

remove_action( 'bp_setup_nav', array( $integration, 'add_profile_tab' ), 100 );

Since $integration is not easily accessible externally, the cleaner approach is to use the tab's existence to skip rendering:

add_action( 'bp_setup_nav', function() {
    // Remove the WPMediaVerse media nav item from BP.
    bp_core_remove_nav_item( 'media' );
}, 200 );

Group Media Tab

Included in Free - WPMediaVerse is the most complete media solution for BuddyPress communities. Integration is optional - the plugin works standalone on any WordPress site, but when BuddyPress is active, it unlocks profile tabs, group media, activity stream, and notifications automatically.

When BuddyPress Groups is active, WPMediaVerse adds a Media tab to every BuddyPress group.

Tab Location

The tab appears in the group navigation at:

/groups/{group-slug}/media/

It is registered via bp_setup_nav at priority 100, conditional on bp_is_active( 'groups' ).

What the Tab Shows

The group media tab displays media that was:

• Uploaded with privacy=group and group_id={this-group-id}.
• Reassigned to the group via the mvs_media_group_assigned action.

Privacy applies within the group: only group members can view the tab content.

Assigning Media to a Group

When uploading, set the privacy to group and provide the group_id:

curl -X POST https://yoursite.com/wp-json/mvs/v1/media \
  -H "X-WP-Nonce: NONCE" \
  -F "file=@photo.jpg" \
  -F "privacy=group" \
  -F "group_id=42"

This sets the media row's privacy to group (a column in mvs_media_index) and stores group_id=42 (in mvs_media_meta). Media is tracked in WPMediaVerse's custom tables, not as a WordPress post.

Group Activity Integration

Media uploaded to a group fires the mvs_media_group_assigned action:

do_action( 'mvs_media_group_assigned', $media_id, $group_id );

The BuddyPress integration listens to this action and re-scopes the upload's activity item from the member component to the groups component, so it appears in the group's activity stream rather than the member's personal stream.

Group Activity in the Activity Post Form

When a group member uses the BP activity post form inside a group, the Attach Media button (added by WPMediaVerse) automatically assigns uploaded media to that group.

Activity Stream Media

Included in Free - WPMediaVerse is the most complete media solution for BuddyPress communities. Integration is optional - the plugin works standalone on any WordPress site, but when BuddyPress is active, it unlocks profile tabs, group media, activity stream, and notifications automatically.

WPMediaVerse records media events as BuddyPress activity items and enhances existing activity with media thumbnails and inline video players.

Activity Types Registered

WPMediaVerse registers two custom activity action types:

Action Type	Component	Label
mvs_media_upload	wpmediaverse	Media Uploads
mvs_media_upload	groups	Group Media Uploads
mvs_comment	wpmediaverse	Media Comments

These appear in the BuddyPress activity filter dropdown.

When Activity Is Recorded

Event	Action Hook	Activity Recorded
Media uploaded via UploadService	mvs_media_uploaded	"Username uploaded a new [type]" with thumbnail
Comment posted on media	mvs_comment_created	"Username commented on [media title]" (synced as an activity comment)
Media added to an album	mvs_album_items_added	Updates existing upload activity to reference the album
Media assigned to a group	mvs_media_group_assigned	Reassigns activity to the group component
Bulk album upload	mvs_album_items_added	One grouped activity for all files in the same upload action - see below

Bulk album upload activity grouping (1.2.0)

When a user uploads multiple files at once via the album upload modal, WPMediaVerse emits one grouped activity entry for the whole batch instead of one entry per file:

Username uploaded 3 photos to album Portrait Series - with a 3-thumbnail grid

The mechanism: the upload modal sends ?album_upload=1 with each per-file POST /media request. The mvs_media_uploaded listener records a skip flag on the activity row, suppressing per-media activity creation. After the JS link call finishes, mvs_album_items_added fires once with the bundled media IDs and the listener emits a single grouped bp_activity_add with the thumbnail grid as content. Single-file album uploads still produce a per-photo activity (no bundling needed); ad-hoc photo posts via the activity composer keep their existing one-row-per-post behaviour.

Activity Format

Upload activities use the format:

Username uploaded a new [type]

When the media belongs to an album:

Username uploaded a new [type] to album [Album Name]

For group uploads:

Username uploaded a new [type] in the group [Group Name]

Thumbnail Injection

WPMediaVerse injects media thumbnails into activity items in two ways:

1. bp_get_activity_content_body filter (priority 0) - transforms activity content to include an image tag.
2. bp_activity_entry_content action - injects thumbnails for activities with empty content (common for imported media).

Inline video players are injected for video media via inject_video_player_in_activity.

Attaching Media via the Activity Post Form

The Attach Media button appears in the BuddyPress activity post form for members and inside groups.

Users select previously uploaded media or upload new files inline. The media IDs are attached to the activity via bp_activity_posted_update / bp_groups_posted_update.

BuddyNext: Media Links Open Their Activity Post (2.0.0)

When the BuddyNext theme is active, WPMediaVerse media stops behaving like a separate public page by default. Clicking a media item, or visiting its /media/{slug}/ URL directly, redirects (HTTP 301) to the BuddyPress activity entry the media was originally posted in - so a photo lives in the community feed, not as a standalone URL alongside it.

This is implemented through a single filter WPMediaVerse exposes for any host to use:

apply_filters( 'mvs_single_media_redirect', '', $media_id, $slug );

Return a URL to redirect /media/{slug}/ there instead of rendering the native single-media page; return '' (the default) to render the native page. Standalone WPMediaVerse installs (no BuddyNext) always return '', so this only changes behavior when BuddyNext is active and hooks the filter.

If you prefer a dedicated, standalone page per media item even with BuddyNext active, BuddyNext ships its own settings toggle to switch back to that mode - check BuddyNext's own settings screen for the exact option, since it lives in the theme, not in WPMediaVerse.

WPMediaVerse also exposes filterable seams so BuddyNext (or any profile system) can point member links and avatars at its own profile/avatar URLs instead of WPMediaVerse's standalone /media/@handle/ profile:

• mvs_user_profile_url ($url, $user_id) - overrides the profile link used across grids, cards, notifications, and share text.
• mvs_user_avatar_url ($url, $user_id, $size) - overrides the avatar image URL.

Allowed HTML Tags in Activity

WPMediaVerse extends the bp_activity_allowed_tags filter to allow its custom HTML attributes (data-mvs-*, data-wp-*) to pass through BP's kses filter without being stripped.

BuddyPress Notifications

Included in Free - WPMediaVerse is the most complete media solution for BuddyPress communities. Integration is optional - the plugin works standalone on any WordPress site, but when BuddyPress is active, it unlocks profile tabs, group media, activity stream, and notifications automatically.

When BuddyPress Notifications is active, WPMediaVerse sends in-app notifications for media social events.

Notification Types

Event	NotificationService Type	BP Component Action	Who Gets Notified
Someone reacts to your media	media_reaction	mvs_new_reaction	Media owner
Someone comments on your media	media_comment	mvs_new_comment	Media owner
Someone @mentions you in a comment	media_mention	mvs_new_mention	Each mentioned user

NotificationIntegration subscribes to the single mvs_notification_created signal emitted by NotificationService::create() and mirrors these three types into BuddyPress via bp_notifications_add_notification(). It does not listen on raw plugin hooks (which previously caused duplicate notifications).

Notification Registration

WPMediaVerse registers wpmediaverse as a BuddyPress notification component via the bp_notifications_get_registered_components filter.

Notification format strings are registered via:

add_filter( 'bp_notifications_get_notifications_for_user', ... );

Notification Format

Notifications appear in the BuddyPress notification bell with these formats:

Type	Format
Reaction	Username reacted to your media
Comment	Username commented on your media
Mention	Username mentioned you

Notification Filters (BP Nouveau)

In BuddyPress Nouveau, notification filter links are registered via bp_nouveau_notifications_init_filters to allow users to filter their notification list by WPMediaVerse notifications.

Reading Notifications via REST API

curl https://yoursite.com/wp-json/mvs/v1/me/notifications \
  -H "X-WP-Nonce: NONCE"

This returns WPMediaVerse-specific notifications. For the full BuddyPress notification list, use the BP REST API.

Marking Notifications as Read

curl -X POST https://yoursite.com/wp-json/mvs/v1/me/notifications/read \
  -H "X-WP-Nonce: NONCE" \
  -H "Content-Type: application/json" \
  -d '{"ids": [123]}'

Notification Count

The frontend reads the unread count from GET /mvs/v1/me/notifications/count, which returns {"count": N} for the current user, without requiring WebSockets.

2.0.0 update - no double-notify on activity comments

When a media comment is posted from inside a linked BuddyPress activity (an upload shared to the activity stream), BuddyPress already fires its own native "replied to your update" notification. Before 2.0.0, WPMediaVerse also mirrored its own media_comment notification for the same comment, so the media owner saw two bell entries for one comment.

NotificationIntegration now detects this case (a comment whose media has a linked bp_activity_id that BuddyPress itself will notify on) and skips the BP-mirrored media_comment notification. The native MVS in-app notification is unaffected - GET /mvs/v1/me/notifications and any REST/app client still see it; only the duplicate BuddyPress bell entry is suppressed.

Restore the old double-notify behavior with a filter, if a site wants both:

add_filter( 'mvs_suppress_bp_comment_notification', '__return_false' );

See mvs_suppress_bp_comment_notification in the hooks reference.

1.2.0 update - single notification surface

When BuddyPress is active, every WPMediaVerse notification is mirrored to BuddyPress via bp_notifications_add_notification, and the standalone dashboard .mvs-notification-bell markup is suppressed. This means BP-active sites see one bell - the BP nav bell - instead of two competing bells rendering the same notifications.

This is automatic. No setting to flip, no filter to add. If BuddyPress is deactivated, the standalone WPMediaVerse bell returns automatically.

WPMediaVerse Pro

Requires WPMediaVerse Pro - This feature is available exclusively in the Pro version.

WPMediaVerse Pro extends the free plugin with advanced layout modes, cloud storage, video processing, AI providers, quota management, and granular privacy controls.

Requirements

• WPMediaVerse (free) 2.0.0 or higher installed and activated (Pro halts with an admin notice on older Free)
• WordPress 6.5+
• PHP 7.4+
• MySQL 5.7+ or MariaDB 10.4+

Installation

1. Install and activate the free WPMediaVerse plugin first.
2. Go to Plugins > Add New Plugin > Upload Plugin.
3. Upload the wpmediaverse-pro.zip file and click Install Now.
4. Click Activate Plugin.
5. Go to Media > License and enter your license key.
6. Click Activate License.

All Pro features run as soon as the plugin is activated. The license key is used only to unlock automatic updates - it does not gate any feature, so every Pro capability works regardless of license state.

Updating Pro

When an update is available, WordPress shows it in the standard Plugins screen. The updater requires a valid active license. If your license has expired, your installed Pro features keep working - only automatic updates are paused. Download the latest ZIP from your account at wbcomdesigns.com and upload it manually.

1.2.0: All Pro features now Gutenberg blocks

Every Pro feature now ships as a first-class Gutenberg block - drop-in, configurable in the editor, no shortcodes-as-the-only-option. Each block has a matching [mvs_pro_*] shortcode for classic editor and template-tag use.

Block	Handle	Notes
Tournament	mvs/pro-tournament	Configurable tournamentId attribute.
Tournaments List	mvs/pro-tournaments-list	Lists active tournaments.
Challenge	mvs/pro-challenge	Configurable challengeId attribute.
Challenges List	mvs/pro-challenges-list	Lists active and upcoming challenges.
Battle	mvs/pro-battle	Configurable battleId attribute.
Battles Active	mvs/pro-battles-active	Currently running battles.
Instagram Feed	mvs/pro-instagram-feed	Instagram-style square grid layout.
Flickr Feed	mvs/pro-flickr-feed	Flickr-style justified rows layout.
Pinterest Feed	mvs/pro-pinterest-feed	Pinterest-style masonry layout.
Dribbble Feed	mvs/pro-dribbble-feed	Dribbble-style card grid layout.
Leaderboard	mvs/pro-leaderboard	Top performers across competitions.
Compete Hub	mvs/pro-compete-hub	Combined challenges + battles + tournaments dashboard.
Stories	mvs/pro-stories	24-hour ephemeral stories bar + fullscreen viewer, with a same-screen "Your story" upload tile. Added in 1.9.0.

Layout flexibility: because each layout (Instagram, Flickr, Pinterest, Dribbble) is its own block, admins can mix layouts on different pages - e.g. a Pinterest feed on the home page and an Instagram feed on a member directory - instead of being locked to one site-wide layout setting.

MigrationPage admin restructure

The migration tool admin page is now a generic shell that hosts per-platform cards (rtMedia, MediaPress, BuddyBoss). Two pre-existing detection bugs were fixed in the same pass: the Imported count was always 0 regardless of actual progress, and the MediaPress dedup query was running against an undefined $wpdb. Migrations now report accurate counts and skip already-imported items correctly.

Pro Feature Categories

Category	Page	What It Adds
Layout Modes	layout-modes.md	Instagram, Pinterest, Flickr, and Dribbble feed layouts
Cloud Storage	cloud-storage.md	Amazon S3 and BunnyCDN storage drivers
Video Transcoding	video-transcoding.md	Async FFmpeg transcoding to 720p/480p/360p and HLS
Video Chapters	video-chapters.md	Chapter markers and resume playback
Auto-Captions	auto-captions.md	OpenAI Whisper transcription and WebVTT captions
Watermarking	watermarking.md	GD-based text and logo watermarks on media
Video Analytics	video-analytics.md	Play event tracking, heatmaps, and retention reports
AI Providers	ai-providers.md	Google Cloud Vision, AWS Rekognition, and Claude (Anthropic) support
Quotas	quotas.md	Per-user storage and count limits with membership integration
Advanced Privacy	advanced-privacy.md	Multi-level privacy, presets, album inheritance, and bulk updates
Connected Accounts	connected-accounts.md	Connect Flickr to import/export photos and auto-push new uploads
Stories	stories.md	24-hour ephemeral stories with a tap-to-advance viewer and "seen by" receipts
Save to Collections	collections.md	A dedicated Save control for adding media to any number of named collections, separate from favoriting
Mobile App	mobile-app.md	White-label branding, feed layout, push notifications, and a leaderboard endpoint for the native app

User Reports (Pro Moderation)

Pro adds a Reports view that surfaces user-submitted abuse reports on media and members - the complaints your community files, as opposed to the free Moderation Queue, which is about AI/auto-flagged content awaiting an approve/reject decision.

• Where: MediaVerse > Moderation, in the User Reports tab. (It is also reachable directly at admin.php?page=mvs-reports.)
• Who: any user with the moderate_mvs_media capability.
• What it lists: every report row - date, reporter, target type (media or user), the target, the reason code, and a details excerpt. A status filter switches between Pending, Resolved, and Dismissed, each with a live count.
• Actions: on a pending report you can Resolve (mark handled) or Dismiss (no action needed). Both are nonce-protected and capability-checked.

Note for the parent agent: this section documents the Pro Reports admin page inline. If the docs site wants it discoverable on its own, it could later be split into a dedicated pro-features/reports.md page - the content above is self-contained and ready to lift out.

License Management

Setting	Location	Description
License Key	Media > License	Your product license key from wbcomdesigns.com
Activation Status	Media > License	Shows active, inactive, or expired
Deactivate License	Media > License	Release the activation to use on another site

A single license activates one site. Purchase additional activations from your account dashboard if you need to run Pro on multiple sites.

Layout Modes

Requires WPMediaVerse Pro - This feature is available exclusively in the Pro version.

Transform your media community's look with one click - choose the visual style that fits your audience, from Instagram-style grids to Pinterest masonry boards.

What You Can Do

• Switch between four distinct visual layouts without touching code
• Match your community's purpose: photo sharing, discovery, portfolios, or design showcases
• Drop a specific layout on any page with its dedicated block or shortcode (Instagram, Flickr, Pinterest, Dribbble feed)
• Conditionally switch the active layout by page context using the mvs_active_layout filter

The Four Layouts at a Glance

Mode	Best For
Instagram	Photo-sharing communities, daily uploads, stories
Pinterest	Inspiration boards, discovery-focused sites
Flickr	Photography portfolios, camera clubs
Dribbble	Design showcases, creative portfolios

How to Switch Layouts (for Site Owners)

1. Go to Media > Settings > Display
2. Find the Feed Layout option and select your preferred mode
3. Click Save Settings - the explore page and all profile media tabs update immediately

The setting is stored in the mvs_pro_feed_layout option.

What Changes for Users When You Switch Layouts

• The explore/browse page re-renders in the new layout style
• All user profile media tabs switch to the new layout automatically
• The lightbox updates: Flickr mode shows EXIF camera data in the sidebar; Instagram shows the swipe carousel
• Stories appear above the grid in Instagram mode only
• Search and tag filtering behave identically to the default layout, including the empty states (2.2.0): a zero-result search shows "No results for ..." with a Browse-all button and popular-tag chips, and an unknown tag shows "Tag not found" instead of an unfiltered feed

---

Choosing a Layout Mode

The selected mode applies to the explore archive and the user profile media tab. For a specific layout on a specific page, use that layout's own block (e.g. Instagram Feed) or shortcode (e.g. [mvs_pro_instagram_feed]) instead of relying on the global setting.

---

Instagram Mode

Perfect for photo-sharing communities and daily uploads.

The Instagram layout renders a vertical card feed. Each post shows the author avatar, full-width photo, reaction/comment/share buttons, like count, caption, and inline comment box - identical to the Instagram experience.

• Recent uploaders appear as circular avatars above the feed (links to their profiles)
• Each card has heart, comment, share, and bookmark buttons
• Clicking "Expand" opens the lightbox with the full media detail view
• Other users' posts show a "Following" button in the card header

Feed template: templates/layouts/instagram/feed.php Profile template: templates/layouts/instagram/profile.php

---

Pinterest Mode

Ideal for inspiration boards, discovery-focused sites, and mixed-format content.

The Pinterest layout uses a masonry algorithm that preserves each image's original proportions. Cards include the media title and a truncated description below the image.

• Column count is controlled by the Grid Columns display setting (2-4)
• Hovering a card reveals a save-to-collection button
• Infinite scroll loads the next page of results automatically

Feed template: templates/layouts/pinterest/feed.php Profile template: templates/layouts/pinterest/profile.php

---

Flickr Mode

Best for photography portfolios, camera clubs, and image-quality-focused communities.

The Flickr layout uses a justified gallery algorithm: images in each row are resized to fill the full container width while maintaining a consistent row height.

• Clicking an image opens the lightbox with EXIF data displayed in the sidebar
• Profile page shows a filmstrip-style contact sheet view

Feed template: templates/layouts/flickr/feed.php Profile template: templates/layouts/flickr/profile.php

Drop the Flickr layout on a specific page with the Flickr Feed block or the [mvs_pro_flickr_feed] shortcode.

---

Dribbble Mode

Great for design showcases, creative portfolios, and high-resolution work.

The Dribbble layout presents media as large portfolio shots in a 2-column grid. Each card shows the title, view count, and reaction count on hover. This layout is optimised for high-resolution PNG and GIF files.

• Animated GIFs play on hover
• Profile page shows featured work prominently at the top before the full grid

Feed template: templates/layouts/dribbble/feed.php Profile template: templates/layouts/dribbble/profile.php

---

Putting a Specific Layout on a Specific Page

Each layout ships as its own block and shortcode, so you can mix layouts across pages without changing the global setting:

Layout	Block	Shortcode
Instagram	Instagram Feed	[mvs_pro_instagram_feed]
Flickr	Flickr Feed	[mvs_pro_flickr_feed]
Pinterest	Pinterest Feed	[mvs_pro_pinterest_feed]
Dribbble	Dribbble Feed	[mvs_pro_dribbble_feed]

Overriding the Active Layout in Code

The global active-layout slug (read from the mvs_pro_feed_layout option) passes through the mvs_active_layout filter, so you can switch it by context:

add_filter( 'mvs_active_layout', function( $layout ) {
    // Force the Flickr layout on archive pages.
    if ( is_post_type_archive( 'mvs_media' ) ) {
        return 'flickr';
    }
    return $layout;
} );

Cloud Storage

Requires WPMediaVerse Pro - This feature is available exclusively in the Pro version.

Stop storing media on your web server - offload every photo and video to Amazon S3 or BunnyCDN for faster delivery, lower server load, and global CDN performance.

Pluggable Storage Architecture

WPMediaVerse separates where media records live (always in your WordPress database) from where files are stored (local, S3, or BunnyCDN). Every upload goes through a StorageDriverInterface - a clean abstraction that means:

• Switch drivers anytime - Change from local to S3 in one setting. Existing files continue to serve from their original location; new uploads go to the new driver.
• Build your own driver - Developers can register custom drivers (Google Cloud Storage, DigitalOcean Spaces, Wasabi) by implementing the StorageDriverInterface. See Custom Storage Drivers.
• Signed URLs for private media - Cloud drivers generate time-limited signed URLs so private and members-only media stays protected even when served from a public CDN.
• No lock-in - Media metadata stays in your WordPress database regardless of storage driver. Switch providers without losing any data.

Why Use Cloud Storage

• Your WordPress server no longer stores or serves media files - reducing disk usage and bandwidth costs
• Files are served from edge locations closest to each visitor, so images load faster worldwide
• S3 and BunnyCDN both scale to millions of files without any WordPress configuration changes
• Private media gets signed URLs so only authorized users can access the actual file - even with cloud storage

---

How Media Serving Works in 1.4.0

Location-based serving

Each media item is served from where it is actually stored, based on its storage location and privacy setting at the time of the request. The active storage driver setting only controls where new uploads go - it does not affect files that were uploaded previously.

This means:

• Switching the active driver (for example, from local to S3) does not break any existing media. Files already on S3 keep serving from S3. Files on local disk keep serving through the plugin's /serve route.
• Enabling a cloud integration for the first time does not affect older uploads - they continue working as before.
• Public media stored on cloud serves directly from the CDN (no WordPress request involved). Local media serves through the plugin's /serve proxy route.

Private media stays local

Only public media is eligible for cloud storage. Media with any other privacy setting (members-only, friends-only, private, or group) is always stored on the local server disk. This applies to the original file, all thumbnails, and all generated image variants (WebP, AVIF).

There is effectively one storage location per media item at any time: either cloud (for public media) or local (for everything else).

Per-request access check for private media

Every request to the /serve route for non-public media re-verifies the requesting user's view permission (can_view). A signed URL does not act as a transferable bearer token for private media. If the viewer no longer has access, the request returns 403 - even with a valid, unexpired signed URL. Public media uses bearer-style URLs (cacheable and shareable) because they carry no access restriction.

Cloudflare R2 requires a public domain

If you use Cloudflare R2 and have not configured a public domain (r2.dev subdomain or custom domain) on your bucket, WPMediaVerse will not emit the raw *.r2.cloudflarestorage.com API URL. That endpoint is never publicly readable. Instead, the plugin falls back to serving the file from the local copy via /serve.

To enable true CDN serving from R2, configure a public domain for your bucket in the Cloudflare R2 dashboard (either the r2.dev subdomain or your own custom domain), then enter that hostname in the CDN Domain field in Storage settings.

"Serve public cloud media directly" setting retired

The Serve public cloud media directly checkbox (mvs_cloud_direct_public_urls) has been removed from the settings UI in 1.4.0. Direct CDN serving for public cloud media is now automatic. You do not need to enable any toggle. The underlying option is retained in the database for back-compatibility, but it has no effect on serving behavior.

If you had this checkbox enabled before upgrading, no action is needed - behavior is the same or better.

---

Setting Up Amazon S3

1. Log into your AWS Console and create an S3 bucket
2. Create an IAM user with the required permissions (see IAM Policy below) and save the access key and secret key
3. In WordPress, go to Media > Settings > Storage
4. Set Storage Driver to Amazon S3
5. Enter your bucket name, region, access key ID, and secret access key
6. If you use CloudFront or a custom domain, enter the hostname in the CDN Domain field
7. Click Test Connection - WPMediaVerse Pro uploads a small test file and reads it back to confirm everything works
8. Click Save Settings - all new uploads now go directly to S3

Setting Up BunnyCDN

1. Log into your BunnyCDN dashboard and create a Storage Zone
2. Note your storage zone name, API key, region, and pull zone hostname
3. In WordPress, go to Media > Settings > Storage
4. Set Storage Driver to BunnyCDN
5. Enter your storage zone name, API key, region, and CDN hostname
6. Click Test Connection to verify
7. Click Save Settings - all new uploads now go to BunnyCDN

Choosing a Storage Driver

Go to Media > Settings > Storage and set the Storage Driver option. The value is stored in the mvs_storage_driver option.

Value	Driver
local	Default WordPress uploads directory (no Pro required)
s3	Amazon S3
bunnycdn	BunnyCDN
r2	Cloudflare R2
dospaces	DigitalOcean Spaces

Only one driver is active at a time. Switching drivers does not migrate existing files - previously uploaded files remain at their original URLs and continue to serve from their original location.

---

Amazon S3

Settings

Option	Option Key	Description
S3 Bucket	mvs_pro_s3_bucket	The name of your S3 bucket
S3 Region	mvs_pro_s3_region	AWS region code, e.g. us-east-1
Access Key ID	mvs_pro_s3_access_key	Your AWS IAM access key ID
Secret Access Key	mvs_pro_s3_secret_key	Your AWS IAM secret access key
CDN Domain	mvs_pro_s3_cdn_domain	Optional CloudFront or custom domain for file URLs

Storing Credentials in wp-config.php

Instead of saving credentials to the database, define them as constants in wp-config.php:

define( 'MVS_PRO_AWS_ACCESS_KEY', 'AKIAIOSFODNN7EXAMPLE' );
define( 'MVS_PRO_AWS_SECRET_KEY', 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY' );

When these constants are defined, WPMediaVerse Pro uses them instead of the database values. The admin fields show a placeholder indicating constants are in use.

Required IAM Policy

Your IAM user needs at minimum:

{
  "Effect": "Allow",
  "Action": [
    "s3:PutObject",
    "s3:GetObject",
    "s3:DeleteObject",
    "s3:ListBucket"
  ],
  "Resource": [
    "arn:aws:s3:::your-bucket-name",
    "arn:aws:s3:::your-bucket-name/*"
  ]
}

CDN Domain

If you serve your bucket through CloudFront or a custom domain, enter the hostname (without trailing slash) in the CDN Domain field. WPMediaVerse Pro replaces the default S3 URL with this domain for all generated file URLs.

---

BunnyCDN

Settings

Option	Option Key	Description
Storage Zone	mvs_pro_bunny_zone	Your BunnyCDN storage zone name
API Key	mvs_pro_bunny_api_key	Your BunnyCDN API key
Region	mvs_pro_bunny_region	Storage region: de, ny, la, sg, syd
CDN Hostname	mvs_pro_bunny_cdn_hostname	Your pull zone hostname, e.g. media.yoursite.b-cdn.net

Regions

Value	Location
de	Falkenstein, Germany (default)
ny	New York, USA
la	Los Angeles, USA
sg	Singapore
syd	Sydney, Australia

---

Testing the Connection

After saving settings, click Test Connection in the Storage settings panel. WPMediaVerse Pro uploads a small test file, reads it back, then deletes it. The result (success or error message) appears inline without a page reload.

If the test fails, verify your credentials, bucket name, and that the IAM or API key has sufficient permissions.

---

File Path Structure

Files are stored under the same path structure used for local uploads:

wpmediaverse/YYYY/MM/filename.ext

For S3 this becomes s3://your-bucket/wpmediaverse/YYYY/MM/filename.ext. For BunnyCDN it becomes a path within your storage zone.

Signed URLs with Cloud Storage

When media privacy is not public, WPMediaVerse Pro generates signed URLs through the /serve proxy route. The proxy re-verifies view permission on every request - signed URLs for non-public media do not grant transferable access. S3 presigned URLs and BunnyCDN token authentication are used for migration and admin operations, not for end-user delivery of private media.

---

Developer: Filtering Public Cloud URLs

The public-cloud serving behavior can be adjusted using three filters. Full parameter details are in the Developer Guide: Hooks and Filters.

Filter	What it controls
mvs_serve_public_cloud_direct	Return false to force all media back through the /serve proxy instead of emitting direct CDN URLs
mvs_public_cloud_thumbnail_url	Rewrite or replace the direct CDN URL for a public cloud-hosted thumbnail
mvs_public_cloud_file_url	Rewrite or replace the direct CDN URL for a public cloud-hosted original file

Video Transcoding

Requires WPMediaVerse Pro - This feature is available exclusively in the Pro version.

Give your community professional-quality video playback with automatic quality selection - viewers on fast connections get 720p, mobile users on slower connections get 360p, automatically.

What Users See

When a user plays a video, they see a quality selector in the player corner showing available options: 720p, 480p, and 360p. The player automatically selects the best quality for their connection and lets them override it manually. Playback starts faster because the video streams progressively rather than requiring a full download.

While transcoding is in progress after upload, the video plays at its original uploaded resolution. Once transcoding completes (typically within a few minutes), the quality selector appears.

What Admins Need

• FFmpeg installed on the server and accessible from PHP. Verify this by running which ffmpeg via SSH.
• Action Scheduler 3.0+ (bundled with WooCommerce, or install as a standalone plugin from wordpress.org)

Shared hosting plans often do not have FFmpeg. VPS and dedicated servers typically do. Contact your host if you are unsure.

Enabling Transcoding

1. Confirm FFmpeg is installed on your server: run which ffmpeg via SSH and note the path
2. Go to Media > Settings > Video
3. Enable Transcode Uploaded Videos
4. If your FFmpeg path differs from /usr/bin/ffmpeg, update the FFmpeg Path field
5. Click Save Settings
6. All new video uploads will now be queued for transcoding automatically

Requirements

• FFmpeg installed on the server and accessible from PHP (verify with which ffmpeg via SSH)
• Action Scheduler 3.0+ (bundled with WooCommerce or installable as a standalone plugin)

Enabling Transcoding

Go to Media > Settings > Video and enable Transcode Uploaded Videos. The setting is stored in the mvs_pro_transcode_enabled option.

Option	Option Key	Default	Description
Transcode Uploaded Videos	mvs_pro_transcode_enabled	0	Enable async FFmpeg transcoding on upload
FFmpeg Path	mvs_pro_ffmpeg_path	/usr/bin/ffmpeg	Absolute path to the FFmpeg binary

Output Formats

Each uploaded video is transcoded to:

Resolution	Bitrate	Format
720p	~2500 kbps	MP4 (H.264 + AAC)
480p	~1000 kbps	MP4 (H.264 + AAC)
360p	~500 kbps	MP4 (H.264 + AAC)

An HLS playlist (master.m3u8) is also generated, referencing all three resolutions. The player loads the HLS stream by default and falls back to direct MP4 at the highest available resolution for browsers without HLS support.

File Storage

Transcoded files are stored at:

/wp-content/uploads/mvs-transcodes/{media_id}/
  720p.mp4
  480p.mp4
  360p.mp4
  master.m3u8
  720p/
  480p/
  360p/

If cloud storage is configured, the transcoded files are uploaded to the same bucket or storage zone using the same path structure.

Post Meta

Meta Key	Values	Description
_mvs_transcode_status	queued, processing, complete, failed	Current transcoding job status
_mvs_transcodes	serialized array	URLs to each transcoded file and the HLS playlist

REST API

Base URL: /wp-json/mvs-pro/v1/

GET /media/{id}/transcodes

Get the transcoding status and file URLs for a media item.

Response:

{
  "status": "complete",
  "transcodes": {
    "720p": "https://example.com/wp-content/uploads/mvs-transcodes/123/720p.mp4",
    "480p": "https://example.com/wp-content/uploads/mvs-transcodes/123/480p.mp4",
    "360p": "https://example.com/wp-content/uploads/mvs-transcodes/123/360p.mp4",
    "hls": "https://example.com/wp-content/uploads/mvs-transcodes/123/master.m3u8"
  }
}

DELETE /media/{id}/transcodes

Delete all transcoded files for a media item. Requires ownership or admin (manage_mvs_settings).

Response: 200 OK.

POST /media/{id}/transcode

Trigger transcoding manually (note the singular transcode). Requires ownership or admin (manage_mvs_settings). Use this to re-transcode a file after correcting the FFmpeg path.

Response: 202 Accepted with the current status object.

There are also two admin-only diagnostic routes: GET /transcode/status (overview of pending/processing jobs) and GET /transcode/config (FFmpeg availability and configured presets). Both require manage_mvs_settings.

Transcoding Queue

Action Scheduler processes the transcoding queue in the background. You can monitor jobs at Tools > Scheduled Actions (if WooCommerce is active) or at the Action Scheduler standalone admin page. Filter by the mvs_pro_transcode_video hook to see only transcoding jobs.

Troubleshooting

If transcoding fails, check:

1. FFmpeg is installed: run ffmpeg -version via SSH.
2. The path in Media > Settings > Video > FFmpeg Path matches the which ffmpeg output.
3. The PHP process has permission to invoke the binary (disable_functions in php.ini does not block it).
4. The mvs-transcodes directory inside wp-content/uploads is writable by the web server user.

Failed jobs set _mvs_transcode_status to failed. Re-trigger via the REST API endpoint above or by editing the media item in WP Admin and clicking Re-Transcode.

Video Chapters

Requires WPMediaVerse Pro - This feature is available exclusively in the Pro version.

WPMediaVerse Pro lets you add chapter markers to video files and tracks each viewer's resume position so they can pick up where they left off.

How Chapters Work

Chapter markers appear on the video player's progress bar as clickable tick marks. A chapter list panel opens alongside the player, showing each chapter title and its timestamp. Clicking a chapter jumps the video to that position.

Chapter data is stored per media item via the REST API and rendered into the player on page load.

---

REST API

Base URL: /wp-json/mvs-pro/v1/

GET /media/{id}/chapters

Retrieve the chapter list for a media item.

Response:

{
  "chapters": [
    { "time": 0, "title": "Introduction" },
    { "time": 145, "title": "Main Topic" },
    { "time": 312, "title": "Conclusion" }
  ]
}

time is in seconds from the start of the video.

PUT /media/{id}/chapters

Replace the chapter list for a media item. Requires ownership or the edit_mvs_media capability.

Body:

{
  "chapters": [
    { "time": 0, "title": "Introduction" },
    { "time": 145, "title": "Main Topic" },
    { "time": 312, "title": "Conclusion" }
  ]
}

Sending an empty array ("chapters": []) removes all chapters from the media item.

Response: 200 OK with the updated chapter list.

---

Resume Playback

WPMediaVerse Pro tracks the furthest playback position reached by each authenticated user. When a user returns to a video they have partially watched, the player offers a Resume from X:XX prompt.

Resume positions are stored server-side, not in browser storage, so they persist across devices.

REST API

GET /media/{id}/resume

Get the resume position for the current authenticated user.

Response:

{
  "position": 187,
  "updated_at": "2025-03-28T09:14:00Z"
}

Returns 404 if no resume position exists for this user and media item.

POST /media/{id}/resume

Save or update the resume position. The player calls this endpoint as the video plays.

Body:

{ "position": 187 }

position is in seconds. The endpoint accepts updates only when the new position is greater than the stored one, preventing backwards seeks from overwriting progress.

Response: 200 OK.

DELETE /media/{id}/resume

Clear the resume position for the current user. This is called when the user watches to the end of the video or manually dismisses resume tracking.

Response: 204 No Content.

---

How Chapters Are Stored

Chapters are managed through the REST API (PUT /media/{id}/chapters) and stored per media item as JSON in the _mvs_chapters post meta. They are returned with the media REST response and rendered into the player on page load. Each entry is an object with a time (seconds from the start) and a title.

Auto-Captions

Requires WPMediaVerse Pro - This feature is available exclusively in the Pro version.

WPMediaVerse Pro transcribes video and audio files using the OpenAI Whisper API and attaches the result as a WebVTT caption file. Captions are served with the media player and can be edited via the REST API.

Requirements

• An OpenAI API key with access to the Whisper transcription endpoint
• The media file must be a supported audio or video format (MP3, MP4, M4A, WAV, WEBM, OGG)

Enabling Auto-Captions

Go to Media > Settings > Video and configure the following options.

Option	Option Key	Default	Description
Auto-Generate Captions	mvs_pro_captions_auto	0	Automatically transcribe each uploaded video or audio file
Caption Language	mvs_pro_captions_language	(auto)	Optional source-language hint passed to the provider
Caption Provider	mvs_pro_captions_provider	whisper	Transcription provider

The OpenAI API key is read from the free plugin's existing OpenAI API Key setting (the mvs_openai_api_key option, configured under Media > Settings > AI & Moderation). There is no separate Pro Whisper key field - captions reuse the same key as the rest of the AI features.

When Auto-Generate Captions is on, WPMediaVerse Pro queues a transcription job via Action Scheduler immediately after a file is stored. The caption file is saved once the Whisper API responds.

Caption File Storage

WebVTT files are stored at:

/wp-content/uploads/mvs-captions/{media_id}.vtt

If cloud storage is active, the VTT file is also uploaded alongside the media file.

REST API

Base URL: /wp-json/mvs-pro/v1/

GET /media/{id}/captions

Retrieve the caption file content and metadata for a media item.

Response:

{
  "status": "complete",
  "language": "en",
  "vtt_url": "https://example.com/wp-content/uploads/mvs-captions/123.vtt",
  "generated_at": "2025-03-28T10:00:00Z"
}

status can be none, pending, complete, or failed.

POST /media/{id}/captions/generate

Queue Whisper transcription for the media item. Requires ownership or admin (manage_mvs_settings). No body is required.

curl -X POST https://yoursite.com/wp-json/mvs-pro/v1/media/123/captions/generate \
  -H "X-WP-Nonce: NONCE"

Response: 202 Accepted with the current status object.

GET /media/{id}/captions/status

Poll the transcription job status for a media item.

Response: 200 OK with { "status": "pending" | "complete" | "failed" | "none" }.

PUT /media/{id}/captions

Replace the caption content with edited VTT text. Use this to correct transcription errors.

Body (JSON):

{
  "content": "WEBVTT\n\n00:00:00.000 --> 00:00:04.000\nHello and welcome.\n\n00:00:04.500 --> 00:00:09.000\nToday we are covering...",
  "language": "en"
}

Response: 200 OK with the updated caption metadata.

DELETE /media/{id}/captions

Remove the caption file and reset the caption status to none.

Response: 204 No Content.

WebVTT Format

WPMediaVerse Pro always stores captions in WebVTT format. Caption content you submit through the API must begin with the WEBVTT header - content that does not start with that header is rejected. There is no automatic SRT-to-VTT conversion; convert SRT to WebVTT before uploading.

Example VTT file:

WEBVTT

00:00:00.000 --> 00:00:04.000
Hello and welcome to this video.

00:00:04.500 --> 00:00:09.000
Today we are covering the main topic.

Editing Captions

To correct a transcription, replace the stored VTT through the REST API with PUT /media/{id}/captions, passing the edited WebVTT content in the content field (see the REST API section above). The content must begin with the WEBVTT header.

Watermarking

Requires WPMediaVerse Pro - This feature is available exclusively in the Pro version.

WPMediaVerse Pro stamps a text or logo watermark onto uploaded images using PHP's GD library, so your brand or credit travels with every photo members share.

How it works (read this first)

The watermark is baked into the image at upload time - it is composited directly onto the stored file, so everyone who views the image sees it, on the page, in the feed, and in any download.

Because of that, three things are important to understand before you turn it on:

• It is permanent. The watermark alters the stored image. There is no separate "clean" copy kept, and no un-watermark step. Turning the setting off later does not remove the watermark from images that were already uploaded.
• It applies to new uploads only. Existing media is not re-stamped, and changing the text, logo, position, or opacity later only affects images uploaded after the change.
• Images only. Video and audio are never watermarked.

If you need the original files kept pristine, do not enable watermarking - keep your own unwatermarked copies before uploading.

Requirements

• PHP GD extension enabled (verify with phpinfo() - look for the gd section). If GD is unavailable the watermark is not applied and the failure is recorded on Media > Logs.
• For logo watermarks: a PNG file with a transparent background is recommended.

Enabling watermarks

Go to Media > Settings > Display > Image Watermarking and configure the options below.

Option	Option Key	Default	Description
Enable Watermark	mvs_watermark_enabled	0	Stamp a watermark onto uploaded images
Apply to	mvs_watermark_apply	all	all = every uploaded image; roles = only images uploaded by the roles selected below
Watermark uploads from	mvs_watermark_roles	(none)	The uploader roles to watermark. Only used when Apply to is roles; with none selected, nothing is watermarked
Watermark Type	mvs_watermark_type	text	text to overlay a text string, image to overlay a logo
Watermark Text	mvs_watermark_text	site title	The text to overlay (used when type is text); defaults to your site name. Supports the {site} and {username} tokens
Watermark Image	mvs_watermark_image_id	0	WordPress attachment ID of the logo image (used when type is image)
Position	mvs_watermark_position	bottom-right	Where on the image to place the watermark
Opacity	mvs_watermark_opacity	40	Watermark opacity, 0 (transparent) to 100 (opaque)
Text Size	mvs_watermark_font_size	24	Base font size for text watermarks (px); scales with the image
Text Colour	mvs_watermark_color	#ffffff	Hex colour for text watermarks

Who gets watermarked

Watermarking is controlled by Apply to, not by a photo's privacy level:

• All uploads (all, the default) - every image any member uploads is watermarked.
• Uploads from selected roles (roles) - only images uploaded by the roles you tick under Watermark uploads from are watermarked. If you choose this and tick no roles, nothing is watermarked (the settings screen warns you when that happens).

Watermark positions

Value	Location
top-left	Top-left corner with padding
top-right	Top-right corner with padding
center	Centred on the image
bottom-left	Bottom-left corner with padding
bottom-right	Bottom-right corner with padding (default)
tile	Repeated across the whole image

Text watermarks

When Watermark Type is text, WPMediaVerse Pro renders the string in Watermark Text. Two tokens are supported:

• {site} - your site name.
• {username} - the uploader's public handle (their user_nicename, e.g. @jane). It never uses the WordPress login name.

The text size comes from Text Size and scales with the image so it stays proportional on any photo. When a TrueType font is available it is measured for accurate placement; otherwise the built-in GD bitmap font is used. Supply your own TTF with the mvs_watermark_font_path filter:

add_filter( 'mvs_watermark_font_path', function ( $path, $config ) {
    return '/path/to/your-font.ttf';
}, 10, 2 );

Logo watermarks

When Watermark Type is image, select an image from your WordPress Media Library using the Watermark Image field (its attachment ID is stored in mvs_watermark_image_id). WPMediaVerse Pro scales the logo to roughly 20% of the base image width before compositing. A PNG with a transparent background is recommended.

For developers

The stamp is applied by Pro's Watermarker through the mvs_watermark_stamp_file filter, fired by the free plugin's upload pipeline on each new image before its thumbnails and WebP/AVIF variants are generated - so every derived size inherits the mark from a single draw.

To disable watermarking programmatically (for example on a staging site) without changing the stored setting, filter mvs_watermark_enabled:

add_filter( 'mvs_watermark_enabled', '__return_false' );

Video Analytics

Requires WPMediaVerse Pro - This feature is available exclusively in the Pro version.

WPMediaVerse Pro records play events for every video, builds per-video heatmaps, and provides a dashboard showing retention and engagement metrics.

How Event Tracking Works

The player fires events to the REST API as viewers interact with a video. Events are rate-limited to one event per second per session to prevent flooding. Anonymous viewers are tracked by session ID; authenticated users are tracked by user ID.

Tracked Events

Event	Fired When
play	Playback starts or resumes
pause	Playback is paused
seek	User jumps to a new position
complete	Playback reaches the end of the video
buffer	Player enters a buffering state

Events are written to the mvs_play_events database table.

Database Table: mvs_play_events

Column	Type	Description
id	bigint	Auto-increment primary key
media_id	bigint	The mvs_media post ID
user_id	bigint	WordPress user ID, or NULL for anonymous
session_id	varchar(64)	Unique session identifier
event_type	varchar(20)	Event type: play, pause, seek, complete, buffer
position_seconds	float	Playback position in seconds when the event fired
duration_seconds	float	Total video duration in seconds (nullable)
created_at	datetime	UTC timestamp

Data Retention

A daily WP-Cron job (mvs_pro_prune_play_events) prunes raw event rows; the default retention window is 90 days. There is no dedicated retention-days setting option.

REST API

Base URL: /wp-json/mvs-pro/v1/

POST /media/{id}/events

Record a single play event. Authentication is not required - anonymous events are accepted.

Body:

{
  "event_type": "play",
  "position": 0,
  "duration": 360,
  "session_id": "abc123xyz"
}

event_type must be one of play, pause, seek, complete, buffer. session_id should be a stable string generated client-side per browser session (e.g. a UUID stored in sessionStorage). Events are rate-limited per session inside the service.

Response: 204 No Content.

GET /media/{id}/analytics

Get the full analytics bundle for a single media item in one request: heatmap, retention curve, completion rate, average watch duration, engagement score, and drop-off points. Requires ownership or admin (manage_mvs_settings).

Response:

{
  "media_id": 123,
  "heatmap": [42, 41, 40, 39, 38, 12, 12, 11],
  "retention_curve": [100, 98, 97, 95, 60, 58],
  "completion_rate": 0.42,
  "avg_duration": 148,
  "engagement_score": 0.61,
  "drop_offs": [45, 120, 240]
}

avg_duration is in seconds. completion_rate is a decimal between 0 and 1. The retention_curve and heatmap are normalised arrays; pass an optional bucket_count query argument to control the heatmap resolution.

Admin-only aggregate routes

Two site-wide routes require the manage_mvs_settings capability:

• GET /analytics/top - top media items by play activity.
• GET /analytics/overview - aggregate analytics across all media.

Viewing Analytics in WP Admin

Pro adds a Video Analytics tab to the Media > Stats page (the AnalyticsDashboard, injected via the mvs_stats_tabs filter). It includes a per-media detail view with the full heatmap, retention curve, and drop-off table.

AI Providers

Requires WPMediaVerse Pro - This feature is available exclusively in the Pro version.

WPMediaVerse Pro adds Google Cloud Vision, AWS Rekognition, and Claude (Anthropic) as AI analysis providers alongside the built-in OpenAI Vision option. All four providers support auto-tagging and content moderation.

Supported Providers

Provider	Auto-Tag	Content Moderation	Configuration Location
OpenAI Vision (free + Pro)	Yes	Yes	Media > Settings > AI & Moderation
Google Cloud Vision	Yes	Yes	Media > Settings > AI & Moderation > Google Vision
AWS Rekognition	Yes	Yes	Media > Settings > AI & Moderation > AWS Rekognition
Claude (Anthropic)	Yes	Yes	Media > Settings > AI & Moderation > Claude

Only one provider is active at a time. Select it under Media > Settings > AI & Moderation > Provider.

---

Google Cloud Vision

Requirements

• A Google Cloud project with the Cloud Vision API enabled
• An API key or service account with roles/cloudvision.user

Settings

Option	Option Key	Description
Vision API Key	mvs_pro_google_vision_key	Google Cloud API key

What Google Vision Returns

• Labels: Object and scene descriptions, mapped to mvs_tag terms when Auto-Apply Tags is on
• Safe Search: Likelihood scores for adult, violence, racy, medical, and spoof categories
• Web Detection: Public web entities that match the image (used as supplemental tags)

---

AWS Rekognition

Requirements

• AWS account with the Rekognition service enabled in your chosen region
• IAM user or role with rekognition:DetectLabels and rekognition:DetectModerationLabels permissions

Settings

Option	Option Key	Description
Access Key ID	mvs_pro_aws_access_key	AWS IAM access key ID
Secret Access Key	mvs_pro_aws_secret_key	AWS IAM secret access key
Region	mvs_pro_aws_region	AWS region, e.g. us-east-1

What Rekognition Returns

• Labels: Hierarchical object and scene labels with confidence scores, mapped to mvs_tag terms
• Moderation Labels: Content categories (nudity, violence, drugs, etc.) with confidence scores used by the moderation threshold settings

---

Claude (Anthropic) (New in 1.8.0)

Requirements

• An Anthropic account and API key with billing enabled

Settings

Option	Option Key	Description
Anthropic API Key	mvs_pro_anthropic_key	Your Anthropic API key
Claude Model	mvs_pro_anthropic_model	Vision-capable model used for analysis, tagging, and moderation. Choices: Claude Haiku 4.5 (fast & low cost, recommended, default), Claude Sonnet 4.6 (stronger judgment), Claude Opus 4.8 (most capable)

What Claude Returns

• Description + tags: same natural-language description and comma-separated tag suggestions as the OpenAI path, mapped to mvs_tag terms when Auto-Apply Tags is on
• Moderation: flags content against the site's configured AI Flag Criteria and Custom Flag Terms - the same category checkboxes and custom-terms field the free plugin's OpenAI path uses

---

Circuit Breaker

WPMediaVerse Pro implements a circuit breaker for all AI providers. If a provider records 5 consecutive failures (network timeout, invalid API key, rate limit), the circuit opens and no further API calls are made to that provider for a cooldown period of 1 hour. This prevents quota exhaustion during outages.

While the circuit is open, calls to that provider are skipped. The failure counter is stored in a transient that expires after the cooldown, and a successful call resets the counter immediately. There is no separate half-open/retry phase or manual reset command.

---

Auto-Tagging Behaviour

All providers map their returned labels to mvs_tag taxonomy terms. Terms are created if they do not exist. Auto-tagging and the confidence/threshold controls that govern it are configured through the free plugin's AI settings (Auto-Apply Tags and the moderation thresholds under Media > Settings > AI & Moderation) - the Pro providers feed into that same pipeline rather than adding their own tag-confidence option keys.

---

Content Moderation Thresholds

Each safety category has an independent threshold. When a category's confidence score meets or exceeds the threshold, the moderation action configured in When AI Flags Content is applied.

Configure thresholds at Media > Settings > AI & Moderation > Moderation Thresholds.