Welcome to the EmbedPress developer documentation. This is the free plugin — for the Pro extension, see the corresponding docs/ folder in the embedpress-pro repo.

EmbedPress is a WordPress plugin that turns 250+ external sources (videos, audio, PDFs, calendars, social feeds, maps, documents…) into clean, configurable embeds available as Gutenberg blocks, Elementor widgets, and the classic [embed] / [embedpress] shortcode.

This documentation explains how the plugin is built, why it's designed the way it is, and how to extend it safely.

• Architecture Overview — the 30,000-ft view of the codebase
• Data Flow — how a URL becomes a rendered embed
• WordPress Integration — hooks, lifecycle, autoloading
• Free + Pro Coupling — how Pro extends the free plugin

• Folder Reference — what every top-level folder does

• Gutenberg Architecture
• Elementor Architecture
• Classic Shortcode

• Provider System — adapter pattern, URL routing, embed generation
• Adding a New Provider — step-by-step
• Provider Catalog — every shipped provider, what it does

The core feature is the embed itself. EmbedPress ships 250+ sources — YouTube, Vimeo, Wistia, Twitch, Spotify, SoundCloud, PDFs, Google Docs/Sheets/Slides/Maps/Forms/Calendar, Instagram, X (Twitter), LinkedIn, GitHub, Calendly, Canva, AirTable, OpenSea, Gumroad, and many more — usable as Gutenberg blocks, Elementor widgets, the classic [embedpress] shortcode, or auto-embed (URL on a line). Anything not in the catalog falls back to the Universal Wrapper. See:

• Provider System — how URL → embed routing works
• Provider Catalog — every shipped provider
• Adding a New Provider

Layered on top of the embed, these features decorate or extend it:

Content blocks

• PDF Embedder + 3D Flipbook
• PDF Gallery
• Document Block (DOC/PPT/XLS)
• Custom Video Player — Plyr-based branded player (free + Pro tiers)

Engagement & tracking

• Social Share — Facebook / X / Pinterest / LinkedIn buttons around any embed
• Analytics — view / click / impression tracking + dashboard

Infrastructure & admin

• Universal Wrapper / Auto-embed — the catch-all fallback for unknown URLs
• Onboarding Wizard — first-run admin setup
• Feature Enhancer — the cross-provider decoration pipeline (embedpress:onAfterEmbed)

Many have free-side scaffolding (filter slots, upsell UI, Elementor traits) covered in the feature pages above. Full Pro implementation is in the embedpress-pro repo's docs/features/ tree.

• Cinematic Preview — Netflix / Prime Video / Disney+ / Apple TV+ style hero overlay with 6 presets
• Custom Branding — per-provider logo + clickable CTA overlay on YouTube, Vimeo, Wistia, Twitch, Dailymotion, PDF, and Document embeds
• Lazy Load — native loading="lazy" on every iframe / image, per-block or global
• Content Protection — password gate (AES-128-CBC, 1-hour cookie unlock) or user-role gate, per embed
• Showcase Ads — image / video pre-roll overlay on top of any embed, with skip timing
• Broken Embeds Detector — daily scanner flags dead embed URLs (404 / 410 only — bot-hostile statuses → "inconclusive")
• Analytics Pro tier — per-embed breakdown, geo / device / browser / referrer + UTM, advanced charts, email reports (weekly / monthly), PDF + Excel export, unlimited retention
• Custom Player engagement sub-features — 12 modules layered over the free Plyr player:
  • Email Capture — pause at time → modal email form → resume
  • Action Lock — full-cover overlay (share / form / link / login) before unlock
  • Timed CTA — call-to-action overlays at chosen seconds, multi-stack
  • Chapters — clickable timeline segments (manual or YouTube auto-detect)
  • Auto Resume — localStorage seek persistence + Resume prompt
  • End Screen — replay / next / countdown-redirect on ended
  • Drop-Off Heatmap — anonymous 5s-bucket retention chart per video
  • Adaptive Streaming — auto-loads hls.js / dash.js for .m3u8 / .mpd
  • Country Restriction — server-side GeoIP gate (with IP-API fallback)
  • Privacy Mode — static thumb + click-to-load; youtube-nocookie.com
  • LMS Completion — fires on threshold-cross to LearnDash / TutorLMS / LifterLMS, with anti-skip guard
  • CDN Offloading — BunnyCDN / Cloudflare Stream URL rewrite at upload

• REST API
• oEmbed Integration
• Provider HTTP calls

• Coding Standards
• Hooks & Filters Reference
• Extending EmbedPress
• Debugging & Troubleshooting
• Build & Asset Pipeline
• Testing

• Local Development Setup
• Pull Request Guidelines
• Release Process

If you have 15 minutes and want to grok the plugin:

1. Read Architecture Overview — explains the four entry points (shortcode, block, widget, auto-embed) and how they all funnel into the same renderer.
2. Skim Data Flow — follow a YouTube URL from paste to rendered iframe.
3. Open Provider System — the heart of the plugin. Almost every customer-facing feature lives in or hooks into a Provider.

If you're adding a feature, start with Extending EmbedPress. If you're fixing a bug, start with Debugging.

• File paths are relative to the plugin root (/Applications/Workspace/GitHub/embedpress/).
• Code snippets are illustrative — always cross-check against the actual file before relying on signatures.
• "Pro" in italics or in a callout means the behavior described requires the Pro plugin to be active.
• PHP namespaces are written EmbedPress\Foo\Bar (the leading \ from EMBEDPRESS_NAMESPACE is omitted in prose for readability).

docs/
├── README.md              ← you are here
├── architecture/          ← high-level design
├── providers/             ← provider system
├── elementor/             ← Elementor widget internals
├── gutenberg/             ← Gutenberg block internals
├── features/              ← per-feature deep dives
├── api/                   ← REST + external HTTP
├── guides/                ← cross-cutting how-tos
└── contributing/          ← local dev, PRs, release

When you ship a feature, update the matching doc in the same PR. Documentation that drifts is worse than no documentation.