Posterizarr Plugin for Emby
Middleware for asset lookup. Maps local assets to library items as posters, backgrounds, or titlecards.
Port & Credits
This plugin is an Emby port of the original Posterizarr Jellyfin Plugin by fscorrupt. All credit for the original idea, architecture, and implementation goes to him.
This port was vibecoded using Claude (Anthropic).
Overview
The Posterizarr Plugin acts as a local asset proxy for Emby. It is designed to work alongside the Posterizarr automation script, allowing your media server to utilize locally generated or managed assets (posters, backgrounds, title cards) as metadata.
For supported native overlays, Posterizarr can upload directly to Emby. Plex mirroring is optional, not a prerequisite for overlays. Keep local-image sync, direct overlay uploads, and Plex mirroring scoped so they do not compete over the same artwork.
Middleware purpose
This middleware does not allow you to browse, search, or download assets. Its sole purpose is to replace the default artwork by mapping library items to your local file system.
Features
- Local Asset Mapping: Maps local files to library items without replacing original metadata permanently in some configurations.
- Metadata Provider: Registers as a metadata provider for images.
- Support for Multiple Asset Types: Handles Posters, Backgrounds, Seasons, and Title Cards.
- Real-Time WebSocket Sync: Connects directly to Posterizarr's event stream. Automatically refreshes Emby library items immediately when artwork is created, edited, or overlay-processed in Posterizarr.
- Optional Plex Artwork Mirroring: Mirrors active Plex artwork into Emby for movies, TV series, seasons, episode title cards, and backdrops. Detects changes via Plex artwork version timestamps, independently of which tool produced it.
- Hybrid Sync (Combined Real-Time & Plex Sync): Run real-time WebSocket sync and Plex Direct Sync together. New Posterizarr artwork applies via events, while scheduled Plex sync runs replace it whenever the selected Plex artwork differs.
- Scheduled Sync Task: Registers a background task to keep library images in sync with your local assets automatically on a customized schedule.
Installation
Optional Plex artwork source
Enable Plex Direct Sync only when Plex should be the source of artwork for this workflow. It can mirror Posterizarr's native overlay results or other selected Plex artwork. Direct native uploads to Emby do not require this option.
- Download the latest version of
Posterizarr.Plugin.Emby.dllfrom the GitHub Releases. - Copy
Posterizarr.Plugin.Emby.dllinto your Emby Server's plugin directory:- Docker:
/config/plugins/ - Windows:
%appdata%\Emby-Server\programdata\plugins
- Docker:
- Restart your Emby Server.
Configuration
- After restarting, go to Dashboard → Plugins → Installed Plugins and click Posterizarr Emby.
- Click on Settings.
- Configure your Root Asset Folder Path (the directory where your curated images are stored, e.g.,
/assets). - Image Target Types: Select which artwork types to automatically apply (Posters, Season Posters, Titlecards, Backdrops, Thumbnails).
- Real-Time Sync (WebSocket) Settings:
- Enable Real-Time Sync (WebSocket): Check this box to enable instant updates.
- Posterizarr URL: Enter your Posterizarr server URL (e.g.,
http://192.168.1.50:8000orhttp://localhost:8000). - Posterizarr API Key (Required): Enter your Posterizarr API key. The key is transmitted securely via the
X-API-KeyHTTP header and is mandatory for WebSocket authentication.
- Plex Direct Sync Settings (Optional):
- Enable Plex Direct Sync: Check this box to mirror artwork directly from Plex.
- Plex Server URL: Base URL of your Plex server (e.g.,
http://192.168.1.50:32400). - Plex Token: Your Plex authentication token (
X-Plex-Token). - Libraries to Sync (Optional): Comma-separated list of Plex libraries to sync, or leave blank for all.
- Artwork Types: Choose which artwork types to mirror (Posters, TV Shows, Seasons, Titlecards, Backdrops).
- Click Save.
- Go to your Dashboard → Libraries.
- Manage a library (e.g., Movies).
- Enable Posterizarr under the Image Fetchers settings.
- Ensure it is prioritized according to your preferences.
- Refresh metadata (Search for missing metadata → Replace existing images) for your library to pick up local assets for the first time.
Combining Real-Time Sync & Plex Direct Sync (Hybrid Mode)
You can enable both Real-Time Sync and Plex Direct Sync simultaneously to get the best of both worlds:
flowchart TD
subgraph Instant["1. Instant Real-Time Sync"]
A[Posterizarr finishes rendering] -->|WebSocket event| B[Emby Plugin applies artwork immediately]
B --> C[Plex sync cache invalidated for item]
end
subgraph Scheduled["2. Scheduled Plex Direct Sync"]
D[Scheduled Plex Sync runs] --> E{Compare Plex artwork with Emby}
E -->|Different artwork| F[Plex sync wins: applies selected Plex artwork]
E -->|Identical| G[Skips re-save & updates cache]
end
Instant -.-> Scheduled
- Instant Updates: You don't have to wait for a daily or scheduled Plex sync task to see fresh artwork in Emby. The WebSocket listener updates Emby immediately upon rendering.
- Plex Source Priority: When the scheduled Plex Sync task runs, the selected Plex artwork takes precedence, including artwork produced by native Dynamic Overlays or another uploader. Identical artwork avoids redundant downloads and disk writes.
Local Collection Syncing in Plex Sync Mode
Since Plex Direct Sync only mirrors movie, show, season, title card, and backdrop artwork (Plex does not sync collection artwork directly), Collections are managed locally:
* When Enable Plex Direct Sync is active, the Update Collections checkbox remains active and selectable, while movie and TV checkboxes are disabled to prevent overwriting Plex artwork.
* The scheduled Posterizarr Sync Task will automatically restrict its run exclusively to Collections (BoxSets).
* Image lookup is strictly confined to collection asset directories (Collections/, Collections/<Library>, <Library>/Collections), bypassing individual media folders.
Real-Time Synchronization (WebSocket)
The Emby plugin includes a real-time event listener service (PosterizarrWebSocketListener) that connects directly to Posterizarr's /ws/events WebSocket endpoint.
How It Works
sequenceDiagram
participant Engine as Posterizarr Engine / WebUI
participant Backend as Posterizarr Backend (/ws/events)
participant Plugin as Emby Plugin
participant Emby as Emby Media Server
Engine->>Backend: Render Asset / Upload / Replace Artwork
Backend-->>Plugin: WebSocket event: "asset_updated"
Plugin->>Plugin: Validate path & confine to Asset Root (CWE-22)
Plugin->>Emby: Lookup item & SetImage(...)
Plugin->>Emby: UpdateItem (Instant Refresh)
- Instant Event Broadcast: Whether artwork is generated during automated runs (Tautulli Recently Added, Sonarr/Radarr webhooks, manual runs, scheduled runs) or replaced in the WebUI,
LogsWatcherdetects the change and immediately broadcasts anasset_updatedevent over/ws/events. - Direct Image Application: Upon receiving the event, the Emby plugin directly opens the rendered file from disk and applies it to the library item via Emby's internal
SetImageandUpdateItemAPIs. The item refreshes in under a second without requiring a full library scan or waiting for scheduled tasks. - Autonomous Operation: Even if Posterizarr is configured with
UsePlex: trueandUseJellyfin: false/UseEmby: false, the Emby plugin operates autonomously by monitoring the shared/assetsdirectory. When an asset is modified, Emby updates instantaneously without waiting for the daily scheduled task. - Smart Cache Synchronization: Once an item is updated via real-time sync, its hash is updated in the plugin's
SyncCacheManager, ensuring scheduled tasks skip it without redundant re-processing.
Security Highlights
- Strict Header-Based Authentication: The API key is never passed in the URL or query parameters. It is transmitted securely via the
X-API-KeyHTTP header during the WebSocket upgrade handshake, preventing accidental disclosure in web server access logs or proxy headers. - Path Traversal Protection (CWE-22): All event paths are strictly sanitized against directory traversal sequences (
..), invalid characters, and rooted paths, and are cryptographically verified to reside within the canonicalAssetFolderPathroot boundary before any file operation takes place. - DoS & Buffer Protections (CWE-400): Incoming frames are enforced with maximum message limits (64 KB) to avoid memory exhaustion.
Scheduled Tasks & Automation
The plugin registers a scheduled background task (default: daily at 02:00 AM) that automatically syncs and refreshes your libraries against local assets.
Configuring the Sync Schedule
- Open your Emby Dashboard.
- In the left sidebar under the Server section, navigate to Scheduled Tasks.
- Locate the Posterizarr Sync Task in the list.
- Click on the task to customize its triggers:
- You can configure the task to run on an interval, at a specific time of day (e.g., daily at 3:00 AM), on system startup, or on a weekly schedule.
- You can also trigger the task manually at any time by clicking the Play (Run) button next to it.
Building from Source
If you prefer to compile the plugin yourself from source code, run:
The compiled Posterizarr.Plugin.Emby.dll will be located inside the publish/ directory.