Stremio WP is a WordPress plugin built specifically for self-hosted Stremio users. It bridges your WordPress site and Stremio Server (EngineFS), letting you monitor all active torrent downloads in real time, launch playback in VLC / IINA with one click, and even push completed files straight to your Nextcloud private cloud — all without leaving the browser.
Picture this: you pick a movie on Stremio Web, switch back to your WordPress site, and the download progress, speed, and peer count are right there in front of you. When it’s done, one click and VLC starts playing. Or tap the push button, and the file quietly lands in your Nextcloud — ready to watch on any device, anytime.
Stremio WP isn’t “yet another download manager.” It’s a streaming management workbench with WordPress as the control center, EngineFS as the data engine, and Nextcloud as the storage backend — elevating your self-hosted Stremio experience from command-line logs to a polished web interface.
🏗️ The Big Picture: One Plugin, Three Layers of Capability
Stremio WP’s architecture is organized around three core layers. Each can be used independently, or combined to unlock even greater power:
┌───────────────────────────────────────────────────────────┐
│ WordPress Site │
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Stremio WP Plugin (v2.7.0) │ │
│ │ │ │
│ │ 📊 Real-Time Monitoring ▶️ Playback Control │ │
│ │ ├─ Download/Upload Speed ├─ One-Click VLC │ │
│ │ ├─ Peers / Swarm Status ├─ One-Click IINA │ │
│ │ ├─ File List & Sizes ├─ Copy Stream URL │ │
│ │ ├─ Download Progress Bar └─ Stremio Web Link │ │
│ │ └─ Online/Offline Badge │ │
│ │ │ │
│ │ ☁️ Storage Push 🔒 Security & Access │ │
│ │ ├─ One-Click NC Push ├─ Login/Public ACL │ │
│ │ ├─ Zero-Disk Streaming ├─ SSRF Protection │ │
│ │ ├─ Live Push Tracking ├─ REST API Nonce │ │
│ │ └─ Atomic Lock Anti-Dup └─ Input Sanitization │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Stremio Server (EngineFS) · VLC / IINA Player │ │
│ │ Nextcloud (via Nextcloud WP) │ │
│ └────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────┘The Real-Time Monitoring layer is the foundation — a single shortcode embeds a download dashboard on any page. The Playback Control layer turns monitoring into action — you can actually operate, not just observe. The Storage Push layer completes the last mile — finished downloads land in your private cloud, accessible from any device at any time.
📊 Real-Time Download Monitoring — Your Stremio Dashboard
At the core of Stremio WP is a feature-rich, real-time download monitoring panel. With a simple WordPress shortcode — [stremio_downloads] — you can embed this panel on any page or post across your site.
⚡ Real-Time Polling, Zero Lag
The panel continuously polls EngineFS’s /stats.json endpoint at a configurable interval (default: 5 seconds). All data refreshes silently in the background — no manual refresh button needed. What you see is always the latest state.
Each active torrent is displayed as a card with the following key details:
- 📥 Download / Upload Speed — real-time bandwidth data, automatically formatted into human-readable units (KB/s, MB/s, GB/s, etc.)
- 👥 Peers / Swarm Status — current peer count and total swarm size, helping you gauge resource health
- 📦 File List & Sizes — expand to view every file inside the torrent, each with its precise file size
- 📊 Download Progress Bar — a gradient progress bar (blue gradient) for an at-a-glance completion percentage
- 🟢 Online / Offline Status — a top badge indicates EngineFS server connectivity in real time, turning red when offline
🧠 Smart Metadata Enrichment
EngineFS’s /stats.json endpoint has a known limitation: the torrent data it returns frequently lacks names and file listings. Faced with this incomplete data, most tools settle for displaying an inscrutable hash string.
Stremio WP takes a smarter approach: automatic enrichment. When a torrent is missing its name or file info, the plugin automatically hits that torrent’s individual /{hash}/stats.json endpoint, retrieves the full metadata, and merges it into the overview. This process is completely transparent to the user — you always see meaningful filenames, never a wall of 40-character hex strings.
What most tools show:
├─ 7a3f8c1b2d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a ← What is this?
└─ (no file listing)
What Stremio WP shows:
├─ The.Matrix.1999.Remastered.2160p.UHD.BluRay ← Auto-enriched
└─ 📂 2 files (12.8 GB) ← Auto-fetchedThis “invisible intelligence” philosophy runs through the entire plugin — technical details are handled elegantly behind the scenes, and users only need to focus on the content itself.
🗑️ Torrent Management: Not Just Watching — Taking Action
The monitoring panel isn’t a read-only dashboard. Each torrent card has a delete button in the top-right corner — click it and a destroy command is sent directly to EngineFS, freeing up resources. The removal animation uses smooth opacity and height transitions, so the card gracefully fades out of view.
Under the hood, the destroy operation employs a dual-endpoint fallback strategy: it first attempts the more reliable /remove endpoint, and automatically falls back to /destroy if that fails — maximizing the chance of a successful operation.
▶️ One-Click Playback — From Monitoring to Watching, Zero Friction
The whole point of downloading is watching, and Stremio WP compresses the path from “content discovery to playback” down to a single click.
🎬 VLC: A Clever Custom Protocol Design
Browsers have a natural limitation: they can’t directly hand an http:// link to VLC. Stremio WP solves this with an elegant protocol bridging scheme:
Browser click ──► vlc-stream://your-site/sm-play/{hash}/{idx}/video.mkv
│
▼
WordPress route intercept
│
▼
302 redirect to EngineFS
│
▼
http://stremio:11470/{hash}/{idx}
│
▼
VLC starts playing 🎬How it works: The plugin registers a custom vlc-stream:// protocol. When you click the “▶ VLC” button, the browser hands the link to a pre-registered protocol handler, which replaces vlc-stream:// with http:// and launches VLC with the HTTP stream. On the WordPress side, the /sm-play/ route handles the 302 redirect to the actual EngineFS stream address.
Set it up once, and it works forever. The plugin’s admin settings page includes complete installation guides, with one-click-copy terminal commands for macOS and Linux:
- 🍎 macOS — auto-compiles an AppleScript app
VLCHandler.appand registers it as the system handler forvlc-stream:// - 🐧 Linux — auto-creates an XDG
.desktopfile and registers the protocol association viaxdg-mime
🍎 IINA: Out-of-the-Box for macOS Users
If you’re on macOS using IINA, the experience is even smoother — IINA automatically registers the iina:// protocol at install time, so no extra configuration is needed whatsoever. Click the “▶ IINA” button and IINA starts playing immediately. That’s it.
📋 Copy Stream URL: Flexibility for Power Users
If your player of choice is neither VLC nor IINA, or you have other needs (like playing on a smart TV), the “📋” button copies the raw EngineFS HTTP stream URL to your clipboard. The button briefly shows “✓” to confirm the copy — a small but thoughtful interaction detail.
☁️ Nextcloud Integration — Completing the Last Mile of Storage
This is one of Stremio WP’s most distinctive capabilities: pushing completed torrent files directly to your Nextcloud private cloud. This means you can access your media content on any device — phone, tablet, smart TV, another computer — anytime.
🔗 Deep Collaboration with Nextcloud WP
The Nextcloud push feature works through the Nextcloud WP plugin. When Stremio WP detects that the plugin is active and properly configured, it automatically displays a “☁️ → NC” push button next to each file. The entire integration requires zero additional configuration — install, enable, start pushing.
💨 Zero-Disk Streaming Transfer
Traditional file relay approaches typically work like this: download from the source to local disk → upload from local disk to the destination. This means your WordPress server needs enough disk space to temporarily store media files that could be tens of gigabytes in size.
Stremio WP takes a fundamentally different approach: direct streaming. Files flow from EngineFS’s HTTP endpoint in 10 MB chunks directly to Nextcloud’s WebDAV interface. The WordPress server acts purely as a pipe — data flows through but never stays. Disk usage: zero.
EngineFS ──── 10 MB chunks ────► WordPress ──── WebDAV ────► Nextcloud
(source) HTTP stream (pipe) direct (target)
Disk usage: 0🔒 Atomic Locks & Status Tracking
Pushing large files can take minutes or even longer. During that window, Stremio WP needs to solve two critical problems:
Preventing duplicate pushes — What if a user accidentally clicks the button twice, or multiple browser tabs trigger the same operation? The plugin uses a database-backed atomic lock mechanism (INSERT IGNORE) to ensure that even if two requests arrive within milliseconds of each other, only one acquires the lock and begins pushing. The lock also includes a 30-minute auto-expiry (safety net) to prevent deadlocks caused by crashes.
Real-time status feedback — During a push, the button transitions to an “⏳ Pushing…” state (with a spinning animation), then becomes “✅ NC” and locks upon success. If a push gets stuck, the user can force-cancel it. All status information piggybacks on the existing frontend polling responses — cleverly achieving zero additional HTTP requests.
🎨 A Polished Frontend Experience
Stremio WP’s frontend panel isn’t a rough functional prototype — it’s a carefully crafted UI component.
🌓 Automatic Dark Mode
The plugin adapts to the system theme automatically via the CSS @media (prefers-color-scheme: dark) media query — no manual toggling required:
- ☀️ Light theme — clean white background with soft gray borders, blue gradient progress bar
- 🌙 Dark theme — Catppuccin Mocha color scheme (
#1e1e2ebackground +#cdd6f4text), high-contrast and easy on the eyes
Every button state (VLC orange, IINA green, Copy blue, Stremio purple, Nextcloud blue) has been individually color-tuned for both themes, ensuring clear legibility in any environment.
📱 Responsive Layout
The panel uses Flexbox with a max-width of 780px and auto-centering. File action buttons wrap naturally on narrow screens, keeping the experience comfortable even on mobile browsers.
🔄 Multi-Instance, Zero Conflicts
You can place multiple [stremio_downloads] shortcodes on different pages across the same WordPress site. Each instance gets its own DOM ID (sm-fe-1, sm-fe-2, …) and isolated JavaScript scope, and CSS is only output once — zero collisions guaranteed.
⚙️ Shortcode Parameters: Flexible Customization
The [stremio_downloads] shortcode supports several optional parameters, letting you tailor behavior to each page’s requirements:
| Parameter | Default | Description |
|---|---|---|
poll | Settings page value (default 5s) | Polling interval; lower values improve responsiveness but increase server load |
show_vlc | 1 | Whether to show the VLC play button |
show_iina | Follows settings page | Whether to show the IINA play button (only relevant on macOS) |
show_copy | 1 | Whether to show the copy URL button |
Usage examples:
<!-- Default configuration -->[stremio_downloads]
<!– High refresh rate, hide IINA (non-macOS environment) –>
[stremio_downloads poll=”3″ show_iina=”0″]
<!– Embedded on a mobile-only page, copy functionality only –> [stremio_downloads show_vlc=”0″ show_iina=”0″ show_copy=”1″]
🛡️ Security Design: Defense in Depth
As a plugin that proxies internal network services, Stremio WP takes security seriously with a thoughtfully layered approach:
- 🔐 SSRF Protection — Server address configuration undergoes strict validation: AWS/Alibaba Cloud metadata addresses (
169.254.x.x,100.100.100.200) are blocked, IPv6 is rejected, inputs containing protocol schemes or paths are refused, and cloud metadata hostnames (metadata.google.internal, etc.) are denied. Your WordPress server will never be exploited as an SSRF pivot - 🔑 REST API Authentication — All API endpoints use WordPress Nonce verification. Admin endpoints (settings, debug) require
manage_optionscapability; frontend endpoints follow a configurable access control policy - 🛡️ Input Sanitization — All user input is processed through
sanitize_text_field(), and info hashes are strictly validated against a 40-character hexadecimal regex - 🔒 Access Control — The frontend panel is visible only to logged-in users by default. You can choose to open it to all visitors, but that’s an opt-in setting — never the default
🔧 Admin Panel
Stremio WP provides a full-featured settings page in the WordPress admin, organized into four sections:
🖥️ Server Configuration
Configure your Stremio Server (EngineFS) connection here:
- Server Host — EngineFS IP or hostname (default
127.0.0.1, suited for co-located Docker deployments) - EngineFS Port — EngineFS HTTP port (default
11470) - Stremio Web Port — Stremio Web UI port (default
9080), used for the “🎬 Stremio Web” shortcut button on the frontend - Poll Interval — Frontend polling interval (1–60 seconds), balancing responsiveness with server load
🎮 Player Configuration
- VLC — Displays the
vlc-stream://protocol instructions, reminding users of the one-time protocol handler registration - IINA — A single checkbox controls whether the IINA button appears on the frontend (can be turned off for non-macOS environments)
☁️ Nextcloud Integration Settings
The settings page intelligently detects Nextcloud WP’s installation and configuration status, showing one of three states:
- ⚠️ Not installed — Prompts you to install and activate Nextcloud WP
- ⚠️ Installed but not configured — Provides a direct link to the configuration page
- ✅ Ready — Displays an enable toggle, the connected Nextcloud URL, and target folder configuration
🔍 Connection Testing & Debugging
A section that ops engineers will love:
- Test Stremio Connection — one-click EngineFS connectivity test; on success, displays the number of settings returned
- Debug: Show Raw API — displays the raw JSON response from EngineFS
/stats.json - Debug: Show Enriched API — displays the data after Stremio WP’s smart enrichment pass
Debug output uses a dark terminal aesthetic (#1d2327 background + #50fa7b green text) with auto-formatted JSON — as intuitive as running jq in a terminal.
🌐 REST API: An Extensible Data Interface
Stremio WP exposes a complete set of endpoints through the WordPress REST API, all under the /wp-json/stremio-wp/v1/ namespace:
| Method | Endpoint | Permission | Description |
|---|---|---|---|
GET | /settings | Admin | Proxy EngineFS /settings |
POST | /options | Admin | Save plugin options |
GET | /frontend-stats | Frontend* | Get enriched torrent stats |
DELETE | /torrent?hash={hash} | Frontend* | Destroy a specific torrent |
POST | /nc-push | Admin | Push a file to Nextcloud |
DELETE | /nc-push?key={key} | Admin | Cancel a stuck push |
GET | /debug-stats | Admin | Raw EngineFS data (for debugging) |
GET | /debug-enriched | Admin | Enriched data (for debugging) |
* Frontend permission depends on access control settings (logged-in users or public)
This means you can build your own custom frontend, mobile app, or integrate with other automation tools on top of these APIs — Stremio WP isn’t just a UI, it’s a data middleware layer.
📐 Technical Architecture: Clean Object-Oriented PHP
Stremio WP uses a clear object-oriented architecture with well-defined layers:
stremio-wp/
├── stremio-wp.php # Bootstrap: constants, activation hooks, shortcode, REST routes
├── includes/
│ ├── class-stremio-api.php # EngineFS API wrapper: requests, error handling, URL building
│ └── class-sm-nc-push.php # Nextcloud push: lock mechanism, state management, streaming
└── admin/
└── class-admin-page.php # Admin settings page: forms, validation, player setup guides- SM_Stremio_API — encapsulates all communication with EngineFS, including request dispatch, error handling, JSON parsing, and URL construction. All HTTP requests use WordPress’s native
wp_remote_get()with built-in timeout control and error wrapping - SM_NC_Push — manages the full Nextcloud push lifecycle: atomic lock acquisition/release, active-state tracking, streaming execution, and push logging. REST route registration is also handled within this class
- SM_Admin_Page — the complete implementation of the WordPress admin page: menu registration, form rendering, settings persistence, connection test UI, and player installation guides
The entire plugin relies on no frontend frameworks — the frontend uses vanilla JavaScript (IIFE pattern), and all CSS is output inline and rendered only once. Lightweight by design, uncompromising on functionality.
🚀 Getting Started
Just a few simple steps to add Stremio download management to your WordPress site:
📋 Prerequisites
- ✅ WordPress 5.6 or later
- ✅ PHP 7.4 or later
- ✅ A running Stremio Server (Docker), with the EngineFS port accessible from your WordPress server
If you also want Nextcloud push capability:
- ✅ Nextcloud WP plugin (installed and configured with a Nextcloud connection)
📥 Three-Step Installation
1️⃣ Upload and activate — Upload the stremio-wp folder to wp-content/plugins/, then activate Stremio WP on the WordPress plugins page.
2️⃣ Configure the connection — Go to Stremio → Settings, enter your EngineFS server address and port. Click “Test Stremio Connection” to verify — when you see the green “✅ Connected!” badge, you’re good to go.
3️⃣ Embed on a page — Insert [stremio_downloads] into any page or post, save and publish — the download monitoring panel goes live instantly, ready to use out of the box.
If you want VLC playback, don’t forget to copy the platform-specific installation command from the Settings → Player Setup Guides section and run it once in your terminal to permanently register the vlc-stream:// protocol.
📊 Feature Overview
| Capability | Description |
|---|---|
| 📊 Real-Time Download Monitoring | ✅ Configurable polling interval, auto-refresh |
| 🧠 Smart Metadata Enrichment | ✅ Auto-fetches torrent names and file listings |
| ▶️ One-Click VLC Playback | ✅ Custom protocol bridging, macOS + Linux |
| 🍎 One-Click IINA Playback | ✅ Out-of-the-box on macOS |
| 📋 Copy Stream URL | ✅ Works with any player |
| 🎬 Stremio Web Shortcut | ✅ One-click jump to Web UI |
| 🗑️ Torrent Delete / Destroy | ✅ Dual-endpoint fallback strategy |
| ☁️ Nextcloud Push | ✅ Zero-disk streaming transfer |
| 🔒 Atomic Push Lock | ✅ Database-level deduplication |
| 🛡️ SSRF Protection | ✅ Multi-layer address validation |
| 🔑 Access Control | ✅ Logged-in / public access configurable |
| 🌓 Dark Mode | ✅ Follows system theme automatically |
| 📱 Responsive Design | ✅ Desktop + mobile adaptive |
| 🔄 Multi-Instance Support | ✅ Multiple shortcodes on the same site, zero conflicts |
| 🔧 Debug Tools | ✅ Connection test + Raw/Enriched JSON viewer |
| 🌐 REST API | ✅ 8 standard endpoints, ready for third-party integration |
| 🎮 Player Setup Guides | ✅ Built-in one-click install commands for macOS / Linux |
🔮 What’s Ahead: More Possibilities for Self-Hosted Streaming
As streaming content restrictions continue to tighten, more and more users are turning to self-hosted solutions — their own servers, their own content, their own rules. The Stremio Server + Docker combination already provides a solid foundation for this trend, and Stremio WP takes it a step further.
🏠 WordPress as a Personal Digital Hub
We chose WordPress as the host for Stremio’s management interface not because it’s a “blogging platform,” but because it’s becoming an increasingly popular personal digital hub. Your knowledge management lives here (Trilium AI), your cloud storage bridge lives here (Nextcloud WP), and now your streaming management lives here too (Stremio WP).
One unified entry point, one unified authentication system, one unified set of workflows — that’s the unique value of WordPress as the center of a self-hosted ecosystem.
🧩 Plugin Synergy
Stremio WP is designed to play naturally within WordPress’s plugin ecosystem. It already has deep integration with Nextcloud WP, and there’s potential for synergy with many more plugins in the future:
- 📊 Analytics plugins — track download history, viewing frequency, storage usage trends
- 🔔 Notification plugins — push alerts via Telegram / Email / Webhook when downloads complete
- 👥 User management plugins — configure different access permissions and feature sets for different user roles
This isn’t a distant roadmap — WordPress’s hook system makes these integrations possible at any time.
💡 Why Stremio WP?
Among self-hosted Stremio solutions, what sets Stremio WP apart is that it’s not a replacement — it’s an enhancement:
🎯 It doesn’t replace Stremio Web — it complements it. Stremio Web is the gateway for content discovery and selection. Stremio WP is the control center for download management and playback. Each does what it does best, seamlessly connected by a single shortcut button.
🏠 It doesn’t break away from your existing ecosystem — it fits right in. If you’re already using WordPress as your personal portal, Stremio WP makes Stremio a natural extension of that portal, rather than yet another standalone system requiring a separate login.
☁️ It goes beyond monitoring — it closes the loop. Pick content on Stremio Web → monitor the download in WordPress → one-click push to Nextcloud → watch on any device. The entire workflow completes in a single browser tab.
🔒 It doesn’t trade security for convenience. SSRF protection, atomic locks, nonce authentication, input sanitization — every security detail has been carefully considered, so you can confidently deploy it on an internet-facing WordPress site.
🧑💻 About the Project
Stremio WP is released under the GPL-2.0-or-later open-source license. The code is fully open, relies on no frontend frameworks, and is implemented in pure native PHP + JavaScript — staying lightweight while delivering comprehensive functionality.
💡 Stremio WP — Your torrents shouldn’t exist only in a Docker log buried in some terminal. They deserve an elegant interface, one-click playback, and a direct pipeline to your private cloud. Take your self-hosted streaming experience from “it works” to “it works beautifully,” and let WordPress become the true hub of your digital life — no complicated deployment required. One shortcode is all it takes.