github fscorrupt/posterizarr 4.0.0
v4.0.0

one hour ago

Posterizarr artwork examples for posters, seasons, title cards, and backgrounds

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)

Dynamic Overlays workspace

  • Clean source files stay untouched: Import supported Kometa-style config.yml and 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 *-defaults templates (aspect, audio_codec, commonsense, regional content_rating, direct_play, episode_info, language_count, languages, mediastinger, network, ratings, resolution, ribbon, runtimes, status, streaming, studio, templates, versions, and video_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).

Live badge preview with resolution and rating overlays

Media Change Detection and automatic resync controls


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,760 hours) 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 TBA or Episode 2 updates 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 Titletext blank), 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).

Asset Title Review comparing current media-server titles against existing artwork


Web UI Redesign, Insights, Diagnostics & Setup

Insights runtime analytics and asset creation velocity

  • 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:9 vs 2: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, and imdb_dataset.db — with config.db excluded for security).

Read-only System Database Browser across Posterizarr SQLite databases

  • 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.

Redesigned About page with live runtime environment and inline release changelogs

  • 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/.lan hostnames. Backend, UI, overlay-sync, and cleanup logs now rotate cleanly to .old backups 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.

Optional Dynamic Overlays step in the first-run wizard


Opt-In External Provider APIs

  • Isolated Artwork Endpoint (/api/provider/v1/asset/{media_type}/{item_id}): Protected by API key (X-API-Key header, Authorization: Bearer token, or api_key query 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-rating source provenance and updated_at fields. 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 LogoExifCheck boolean 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 in UploadExistingAssets (#682), reinitializes parallel Fanart runspaces (#681), fixes Docker OSType detection with APP_DATA (#691), restricts Basic Auth headers to same-origin requests (#692), and redacts basicAuthPassword hashes 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 -log spacing and broken -ErrorAction Stop wrapping in ApiHandlers.ps1, skips excluded folders before traversing them in asset caching, avoids enumerating directory contents in backup/restore (#696), uses Jellyfin FullRefresh mode 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

  1. Back up /config first: 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.
  2. Keep RUN_TIME=disabled in Docker: If you use the Web UI Scheduler, keep RUN_TIME=disabled in your Compose environment so the container timer doesn't clash with it.
  3. 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.
  4. 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

New Contributors

Full Changelog: 3.3.7...4.0.0

Don't miss a new posterizarr release

NewReleases is sending notifications on new releases.