Repository navigation
Posterizarr 4.0.0
One container for clean artwork generation, native Dynamic Overlays, anime classification, and server maintenance across Plex, Jellyfin, and Emby.
☕ Support on Ko-fi · 💬 Discord · Documentation · Dynamic Overlays Guide · Artwork Showcase · Web UI Guide · Quick Start
After months of work (plus a few helpful PR fixes from the community), Posterizarr 4.0.0 is finally here.
In v3, Posterizarr focused on creating clean artwork while relying on external tools if you wanted dynamic overlays on top. In v4, Posterizarr can generate your clean posters, seasons, backgrounds, and title cards and apply ratings, resolution, language flags, studio logos, and status badges on its own before uploading, while keeping your original clean files untouched on disk.
☕ Enjoying Posterizarr? Posterizarr is free, open source. If 4.0.0 makes your library look great, consider supporting Posterizarr on Ko-fi or starring the repo, every bit of support helps keep development going!
Highlights at a Glance
| Feature | What It Gives You in 4.0.0 |
|---|---|
| Native Dynamic Overlays | Import Kometa-style config.yml and overlay YAMLs, arrange badges visually in Live Preview, monitor library media changes automatically, run targeted single-item syncs, download official Kometa *-defaults templates/images/fonts, share portable ZIP bundles, and sync straight to Plex, Jellyfin, or Emby without a separate overlay container (Guide). |
| AniMetaFill | Scan anime episodes for Canon, Filler, and Mixed status with provider matching, editable overrides, toggleable overlay categories, per-show thresholds, and optional title card badges. |
| Ratings & Local IMDb Data | Cache and filter ratings from IMDb, RT Critic/Audience, TMDb, Trakt, Metacritic, Letterboxd, MDBList, SIMKL, and MyAnimeList across movies, shows, episodes, and anime seasons, with configurable auto-refresh, OMDb daily-limit protection, and optional local IMDb dataset imports. |
| Asset Title Review & Cleanup | Spot renamed movies, shows, seasons, and episodes to rebuild affected artwork; crop or load replacement images from URL; replace backdrops and collection posters; pick Reset Posters libraries in a modal; and audit old unused Plex metadata images with Plex Image Cleanup. |
| Insights, DB Browser & Support | Unified workspace UI, date-filtered Runtime History with aspect-aware thumbnails, read-only multi-database System Database Browser, sanitized one-click Support Bundles, redesigned About page with inline changelogs, and one-time post-update "What's New" release notes (Web UI Guide). |
| Jellyfin & Emby Plugins | Real-time WebSocket updates, optional Plex Direct Sync mirroring, hybrid sync mode, local collection syncing, and [boxset] name matching fixes (Jellyfin · Emby). |
| Opt-In Provider APIs | Authenticated endpoints for external tools to fetch/generate isolated artwork (/api/provider/v1/asset) or read cached ratings (/api/provider/v1/ratings) (API Docs). |
Native Dynamic Overlays (No Separate Container Required)
- Clean source files stay untouched: Import supported Kometa-style
config.ymland overlay YAML, adjust per-library rules, move badges around in Live Preview, and upload directly to Plex, Jellyfin, or Emby. Overlays are composited in memory right before upload, so your clean posters and title cards on disk are never overwritten. (Note: This covers overlay rendering and syncing. It is not a replacement for Kometa's collection builders or other unrelated features; see Optional Kometa Compatibility.) - Live Preview Studio & Visual Controls: Includes a visual Position Picker, dashed Asset Preview Guides for title/logo boundaries, a toggle to preview base Posterizarr asset overlays and borders alongside dynamic badges, multi-provider rating score layout controls (sizing, alignment, positioning, and themes), localized template variable tooltips across all 5 UI languages, and pre-flight readiness & asset-freshness checks before syncing.
- Target posters or backdrops: Limit any overlay rule to posters, backdrops, or both (#685).
- Fast library checks & targeted single-item syncs: Run an on-demand Changes Only sync anytime instead of waiting for a schedule (a daily incremental run is still recommended; a 34,000+ item library can be checked in minutes depending on your server, storage, and rules). You can also search for a single movie or show (Select Movie / Show) to run an asset-scoped sync or Force Reapply for specific servers, libraries, and artwork types.
- Background Media Change Detection & Auto-Resync: Periodically checks connected media servers in the background for updated audio tracks, editions, runtimes, series status changes, or newly added items, and can automatically re-render and push updated overlays while respecting Dry Run.
- Overlaid artwork right away on new items: When Sonarr, Radarr, or Tautulli triggers on a new movie or episode, Posterizarr suppresses the plain upload, applies your overlays first, and pushes the finished image straight to your server (usually within seconds).
- Supported overlay rules: Resolution and quality badges, ribbons, ratings, runtime, audio and subtitle languages (with independent round, square, or half flag styles), aspect ratio, audio codec, video source, studio and network logos, streaming services (with regional availability), series status, Common Sense Media age ratings, and anime Canon/Filler/Mixed labels. Also supports optional parent-level stream aggregation, per-variant asset overrides, and preserving individual movies inside Jellyfin/Emby box sets.
- Official Kometa defaults built in: Import or download all 20 official
*-defaultstemplates (aspect,audio_codec,commonsense, regionalcontent_rating,direct_play,episode_info,language_count,languages,mediastinger,network,ratings,resolution,ribbon,runtimes,status,streaming,studio,templates,versions, andvideo_format), along with official overlay images (defaults/overlays/images/) and fonts (fonts/) directly from Kometa's GitHub. Missing assets download automatically when needed, and default templates can be updated on a schedule. - Portable Overlay Bundles: Export your custom YAML, custom images/fonts, badge layouts, rating-source selections, and portable settings into a shareable ZIP (
posterizarr-overlays.zip). Official Kometa files are referenced by checksum instead of bloated duplicates, credentials and server connections are stripped/redacted, and importing maps profiles to your local libraries while starting safely in Dry Run (Bundle Guide).
AniMetaFill: Anime Episode Classification
- Automatic Canon / Filler / Mixed detection: Scan your anime episodes with provider matching, fix edge cases manually in the UI, customize badge labels/fonts, and target specific libraries.
- Granular overlay categories & per-show thresholds: Choose individually which Canon, Filler, and Mixed badges to render, and apply per-show thresholds (minimum total episodes, filler episodes, or non-canon percentage) before generating overlays.
- Use straight as overlays: Show Canon, Filler, and Mixed badges right on your episode title cards via Dynamic Overlays.
Ratings, Local IMDb Datasets & Asset Maintenance
- Ratings Cache, MDBList & Auto-Refresh: Refresh, browse, and filter cached ratings (by source, score provider, or missing scores) across IMDb, RT Critic/Audience, TMDb, Trakt, Metacritic, Letterboxd, MDBList (episodes), SIMKL, and MyAnimeList — including episode ratings and anime season ratings (Ratings Guide). Configure a persisted auto-refresh interval (
1–8,760hours) with age-tiered refresh rules and OMDb daily-limit protection, and clear an item's cached rating to cleanly reset its overlay metadata for the next sync. - Local IMDb Datasets & Episode Mappings: Optionally download official IMDb dumps into a local index for fast lookups, conservative episode matching (including absolute episode verification), and manual season/episode IMDb ID overrides (Local IMDb Guide).
- Asset Title Review (rebuild when titles change): Checks text-enabled movies, shows, seasons, and episodes against your media server so you catch renamed titles (for example when
TBAorEpisode 2updates to the real name). Includes media-type filters, bulk dismissal (Hide selected), media-specific confirmation prompts, Fast Normal Run or queued rebuilds, and optional automatic regeneration (paused while Dry Run is on; older ImageChoices mismatches stay manual-only so you can check them first). - Plex Image Cleanup & Extra Asset Tools: Adds Image Cropping, Load from URL, poster/background replacement filters, Backdrop Replacement, Collection-Poster Replacement, Per-Library Background Language Overrides, Textless Season Posters (leaving
Titletextblank), a Reset Posters modal with a library selector filtered to movie/TV libraries, and persistent Auto-Queue for Manual Mode (Run Modes Guide). Plex Image Cleanup scans Plex's metadata directory for old, unselected images on a schedule or on demand — starting in Read Only (Report) by default, with a Quarantine gallery to inspect files before deleting and tracking of freed disk space (Plex Cleanup Guide).
Web UI Redesign, Insights, Diagnostics & Setup
- Insights, Runtime History & Multi-Database Browser: Expanded Insights analytics with date-range filters (
24H,7D,30D,90D,1Y,ALL), legacy history migration, aspect-aware thumbnail framing (16:9vs2:3), interactive Sample Telemetry Preview, and a read-only searchable/sortable System Database Browser covering Posterizarr's SQLite databases (overlay_cache.db,animetafill.db,imagechoices.db,runtime_stats.db,media_export.db,server_libraries.db,plex_push_cache.db,queue.db, andimdb_dataset.db— withconfig.dbexcluded for security).
- Refreshed Workspace UI, About Page & Post-Update Release Notes: Introduces a unified workspace layout, updated sidebar with live asset counts and conditional navigation, context-aware embedded Dashboard Danger Controls, chronological upcoming scheduler jobs, independent top-navbar task badges (Overlay Sync, Ratings Refresh, Plex Image Cleanup), paginated Action Center for large libraries, and full 5-language localization (EN, DE, FR, IT, PT). The redesigned About page displays live runtime environment details, one-click sanitized System Info copy, and inline expandable GitHub release changelogs — paired with a one-time Tautulli-style "What's New" popup whenever a container updates to a new stable release.
- Sanitized Support Bundles & Log Rotation: Generate one-click support archives (logs, configs, reports, and consistent SQLite snapshots) with automatic masking of API keys, tokens, passwords, webhooks, local IPs, and
.local/.lanhostnames. Backend, UI, overlay-sync, and cleanup logs now rotate cleanly to.oldbackups on size thresholds. - Simpler First-Run Setup & Documentation: Onboarding includes an optional Dynamic Overlays step (starting in Dry Run), works with just TMDb or TVDB instead of requiring both, and makes Fanart.tv optional (#690). Documentation has moved to a modernized site with a new First-Time Setup, Web UI Guide, and Artwork Showcase.
Opt-In External Provider APIs
- Isolated Artwork Endpoint (
/api/provider/v1/asset/{media_type}/{item_id}): Protected by API key (X-API-Keyheader,Authorization: Bearertoken, orapi_keyquery parameter). Returns an existing matching asset or renders posters, backgrounds, season posters, and episode title cards on demand using your configured TMDb/TVDB provider order and language rules inside an isolated temporary workspace and separate cache (database/provider_posters), never touching existing assets or media servers. - Cached Ratings Endpoint (
/api/provider/v1/ratings/{media_type}/{item_id}): Returns unexpired Dynamic Overlays ratings cache entries (without live upstream lookups) for movies, shows, episodes (by IMDb ID or series TMDb ID + season/episode), and mapped anime seasons (by TVDB, TMDb, or IMDb ID + season), including per-ratingsourceprovenance andupdated_atfields. A startup migration backfills missing episode coordinates for existing Plex, Jellyfin, and Emby rating-cache entries. (Laid down as groundwork for a future Kometa adapter; Kometa does not consume this natively yet. See the External Provider API Reference.)
Experimental: Silo Support
- Work in progress: Includes early Silo native API v2 integration for catalog discovery, artwork uploads, overlay sync, and change detection. Coverage is still limited (episode artwork uploads are not supported) and not at parity with Plex, Jellyfin, or Emby.
Jelly/Emby Plugin Changes:
- Plex Direct Sync: Optionally mirror selected Plex posters, shows, seasons, episode title cards, and backdrops, with persistent matching caches.
- Hybrid updates: Combine scheduled Plex mirroring with real-time Posterizarr WebSocket updates.
- Collections: Keep local collection syncing available when Plex Direct Sync owns the other artwork types, and normalize collection names by stripping only
[boxset]markers. - Opt-in mirroring: Plex Direct Sync remains disabled by default; native Dynamic Overlays can upload directly to Jellyfin or Emby without Plex.
Bug Fixes & Improvements
- Media-server metadata & matching: Includes Plex stream elements across libraries, paginates Emby/Jellyfin episode queries for large libraries, logs library fetch failures, handles empty season data safely (#693), and prevents SyncJelly/SyncEmby from copying an HD or 4K copy's poster onto a matching-ID item in the same library (#689).
- Plex artwork lookup, logos & HDR: Finds season posters and title cards manually even when asset folder names differ from Plex display titles (#687), recognizes Plex 1.43.4+ HDR10+ metadata (#675), fixes
LogoExifCheckboolean handling (#679), and clears cached thumbnails after media-server logo uploads. - PowerShell stability, timeouts & security: Adds HTTP timeouts at startup so a stalled request won't hang a run for 16 minutes (#686), fixes
FileTestOnTrigger: false(#683), fixes bracketed[]asset paths inUploadExistingAssets(#682), reinitializes parallel Fanart runspaces (#681), fixes DockerOSTypedetection withAPP_DATA(#691), restricts Basic Auth headers to same-origin requests (#692), and redactsbasicAuthPasswordhashes in config responses. - Community PR fixes & cleanup: Fixes collection-poster aspect-ratio validation in Asset Replacer (#684), fixes TMDb season poster selection (
$response.posters), fixes-Color Cyan -logspacing and broken-ErrorAction Stopwrapping inApiHandlers.ps1, skips excluded folders before traversing them in asset caching, avoids enumerating directory contents in backup/restore (#696), uses JellyfinFullRefreshmode properly, fixes textless/custom season-title behavior (#678), improves Radarr cross-library matching, and preserves grayscale source colors. Big thanks to @kevbentz and everyone who opened PRs or reported bugs!
Upgrading from 3.x & Getting Started
- Back up
/configfirst: Save a copy of your persistent data (database,config.json, overlays) before upgrading, and pull the latest image (ghcr.io/fscorrupt/posterizarr:latest) so frontend and backend update together. - Keep
RUN_TIME=disabledin Docker: If you use the Web UI Scheduler, keepRUN_TIME=disabledin your Compose environment so the container timer doesn't clash with it. - Verify before going live: Dynamic Overlays starts in Dry Run by default, and Plex Image Cleanup defaults to Read Only (Report). Check your previews and reports first before enabling live uploads or file cleanup.
- Update your companion plugins: If you use the Jellyfin Plugin or Emby Plugin, update it to 4.0.0 to get Plex Direct Sync, hybrid updates, and the
[boxset]collection matching fix.
Check out the First-Time Setup, Web UI Guide, Dynamic Overlays Guide, Plex Image Cleanup Guide, Artwork Showcase, and API Endpoints Reference for setup steps and examples. If Posterizarr helps keep your library looking great, consider starring the repo, sharing your setup on Discord, or buying a coffee on Ko-fi!
What's Changed
- Sync main2dev by @fscorrupt in #674
- Support collection posters in asset replacement by @6c65726f79 in #684
- Bug Fixes by @kevbentz in #696
- Release 4.0.0: native overlays, artwork sync, and Web UI improvements by @fscorrupt in #697
New Contributors
- @6c65726f79 made their first contribution in #684
Full Changelog: 3.3.7...4.0.0










