Vexal Media User Guide
Vexal Media is the media intelligence and optimization layer for WordPress. It compresses images, generates metadata, converts WebP, optimizes video, scores site media readiness, and integrates with SmartBlocks and Portfolio through shared taxonomy and processing bridges.
What Vexal Media does
- Image compress, resize, and EXIF stripping
- AI-assisted alt text and caption generation (via Vexal/SearchAsist Engine when configured)
- Site Media Readiness scoring with Apply Fix batches
- WebP conversion with rollback-safe URL sync
- Video optimization (remote API or local FFmpeg fallback)
[vexal_video]shortcode with layout and style controls- Media Library columns: Vexal Category, Vexal Gallery, Vexal Project
- Portfolio uploader processing bridge
- SmartBlocks Visibility Ledger snapshot integration (optional)
Media Library optimization
Vexal Media enriches attachments with optimized variants, metadata, and Vexal linkage fields. The queue workflow supports incoming folder scans, bulk upload, approvals, and processing logs.
Default image targets: max edge ~1920px, target file size ~200 KB with quality/dimension step-down.
Site Media Readiness
The dashboard shows readiness signals from vexal_media_get_site_readiness_signals():
- Total images
- Missing alt text count
- Oversized images
- Weak filenames
- Optimized images / WebP availability
- Readiness score (0–100)
When SmartBlocks is active, readiness can trigger ledger snapshot updates and post-fix events.
Apply Fix buttons
Batch fixes process up to 50 items per run with risk tiers and rollback safety:
- Missing alt — AI or rule-based alt generation
- Oversized images — compress and resize
- Weak filenames — rename with URL-sync repair
- WebP convert — when
imagewebpis available
High-risk batches may require confirmation. Failed URL sync rolls back safely.
WebP conversion
WebP output is available when the server supports imagewebp. Quality is configurable (45–95). The readiness panel shows webp_available status. If unavailable, the fix button is disabled—this is a server capability issue, not a plugin bug.
Video optimization
Upload a master video in Vexal Media → Videos. Optimization uses the remote Vexal API (api.vexalai.com) when configured, or local FFmpeg as fallback. Outputs include responsive MP4/WebM per breakpoint and poster extraction.
Video Style Controls
Per-video defaults for feather, shadow, radius, and bevel can be set in the Videos admin. Shortcode attributes override defaults. Presets include ambient loop, tap-for-sound, and hero layouts.
[vexal_video] shortcode
Embed optimized videos anywhere with theme-safe, container-bound output:
[vexal_video id="my-video-id" layout="hero"]Attributes
| Attribute | Values / notes |
|---|---|
id | Required. Video registry ID (lowercase, numbers, hyphens) |
layout | hero, inline, background |
autoplay | yes / no |
loop | yes / no |
muted | yes / no |
controls | yes / no |
poster | auto or custom URL |
preload | Standard preload values |
class | Additional CSS class |
feather | Edge feather: light, medium, etc. |
shadow | soft, medium, strong |
radius | Border radius preset |
bevel | Bevel style preset |
interactive | Tap-for-sound behavior |
expand | Expand-to-modal behavior |
Use the Shortcode generator in the Videos admin to copy ready-made snippets.
SmartBlocks Visibility Ledger
When SmartBlocks is active:
- Ledger snapshots include
metadata.media_readiness - Apply fix events log as
media_readiness_fix_applied - Engine credentials can inherit from SmartBlocks Integrations
Vexal Media works fully standalone without SmartBlocks.
Vexal Portfolio integration
- Shared taxonomy
vexal_portfolio_category(admin: Vexal Category) - Media Library columns and filters for gallery/project linkage
- Project uploader files staged via
NADMP_Intake_Upload::stage_and_queue_files() - Workspace batch processing via
process_workspace_batch()
Media Library columns
| Column | Meaning |
|---|---|
| Vexal Gallery | Linked project (vxp_portfolio) — the gallery/job record |
| Vexal Project | Linked showcase (vxp_project) when assigned |
| Vexal Category | Taxonomy term — preserved across plugins |
Filter gallery media: upload.php?vexal_gallery={portfolio_id}
API / credential rule
Do not manually assign external APIs in Portfolio Project Workspace. Vexal Media is the processing configuration home. Configure API keys and engine credentials in Vexal Media → Settings / Integrations (or inherit from SmartBlocks Integrations). Portfolio Workspace consumes internal bridge APIs only.
Recommended media cleanup workflow
- Review Site Media Readiness dashboard for baseline score
- Run Missing alt fix batch on highest-traffic pages first
- Run Oversized images fix to reduce payload
- Address weak filenames for crawl clarity
- Convert to WebP where server supports it
- Optimize key videos and embed with
[vexal_video] - Assign Vexal Category / Gallery / Project columns for Portfolio-linked assets
- If SmartBlocks is active, verify ledger snapshot reflects improved media readiness
Not yet production-ready
- Asset Usage scanner — documented in readme unreleased section
- Pre-flight preview for weak filename/WebP batches
- Gutenberg video blocks — shortcode is production; native blocks are future