-
Notifications
You must be signed in to change notification settings - Fork 1
Kometa Integration
CHUB and Kometa are designed to work together: Kometa manages Plex metadata and collections, CHUB manages the poster files and media chores that feed them. poster_renamerr specifically reads Kometa's asset output so your renamed posters land in the right places.
This page covers the one-time setup so the two tools see the same world.
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ Kometa │ │ CHUB │ │ Plex │
│ │ │ │ │ │
│ writes posters to │─────▶ │ poster_renamerr │─────▶ │ applies posters to │
│ its asset folder │ │ renames + copies │ │ library items │
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
- Kometa writes original posters to its
asset_directory. - CHUB's
poster_renamerrreads from that directory, matches each poster against your ARR / Plex libraries, renames the files, and copies/moves/hardlinks them into yourdestination_dir. - Plex picks the renamed posters up (optionally pushed directly via the Plex API when you enable
add_posters).
In your Kometa config.yml, make sure asset folders are enabled:
settings:
asset_directory:
- /config/assets # where Kometa drops posters
asset_folders: true # one folder per item: Movie (2020)/poster.jpg
asset_depth: 0Key points:
-
asset_folders: trueis required. CHUB'sposter_renamerrextractstitle,year, andtmdb_id/tvdb_id/imdb_idfrom the folder and the filename, so a per-item folder improves matching accuracy a lot. -
asset_directorycan be a list. CHUB can read from multiple.
CHUB's container needs to read the same folder Kometa writes to. In your CHUB compose.yaml:
services:
chub:
volumes:
- /srv/kometa/assets:/kometa # Kometa's asset_directory, mounted into CHUB
- /srv/apps/chub/posters:/posters # CHUB's destination_dirIf Kometa writes to /srv/kometa/assets on the host, CHUB sees it at /kometa inside its container.
Permissions: CHUB's PUID/PGID must be able to read the Kometa folder. If Kometa writes as 1000:1000 and CHUB runs as 99:100 (Unraid defaults), CHUB won't be able to open the files. Either align the UIDs or run both containers with the same PUID/PGID.
Read/write: if you set poster_renamerr.action_type to move, CHUB removes the file from the Kometa folder after renaming. For copy or hardlink, read access is enough.
In CHUB's config.yml (or Settings → Modules → poster_renamerr):
poster_renamerr:
source_dirs: [/kometa] # matches the mount above
destination_dir: /posters # where renamed copies land
action_type: hardlink # copy | move | hardlink
asset_folders: true # expects per-item folders, matches Kometa
instances:
- radarr_main
- sonarr_main
- plex_main:
library_names: ["Movies", "TV Shows"]
add_posters: true # push straight into Plex via the APIKey points:
-
source_dirs= the in-container path of your Kometa asset volume. -
asset_folders: truemust match your Kometa setting. -
action_type: hardlinkis the cheapest — no extra disk use, both trees point at the same inode. Source and destination must be on the same filesystem. -
add_posters: trueon Plex instances pushes the renamed poster directly via the Plex API after CHUB copies it intodestination_dir. Without it, Plex only picks up posters if it's scanning the folder. -
Source priority: when you list more than one entry under
source_dirs, the bottom of the list wins. Later entries overwrite earlier ones for the same item. If you point CHUB at both/kometaand a Google Drive sync folder and want the Drive posters to take precedence, list/kometafirst and the Drive folder below it.
asset_renamerr extends the same flow to non-poster art. On its kometa apply method it writes Kometa-named files into destination_dir for Kometa to pick up — Kometa reads logo and background from asset directories (PR #2681):
| Layout | Logo | Background | Season logo |
|---|---|---|---|
asset_folders: true |
<Title (Year)>/logo.ext |
<Title (Year)>/background.ext |
<Title (Year)>/Season##_logo.ext |
| Flat | <Title (Year)>_logo.ext |
<Title (Year)>_background.ext |
<Title (Year)>_Season##_logo.ext |
Keep asset_renamerr.asset_folders aligned with your Kometa asset_folders setting, exactly as for posters. Square art is not read from Kometa asset directories — use the direct apply method (uploads to Plex via the API) for square art. See the asset_renamerr module page for the source/apply matrix.
Your source art still uses the poster filename convention plus a type tag — Title (Year) {tmdb-123} - Logo.png, … - Background.png — so a single Google Drive set can carry posters and logos side by side.
Kometa rewrites poster files every time it runs an overlay pass, leaving the previous generation behind in Plex's Uploads/posters folder. Over months this is gigabytes of dead files. poster_cleanarr is the tool for sweeping them — but if you also upload your own custom posters directly through Plex, the default cleaner will treat any of your customs that have rolled out of Plex's currently-referenced set as bloat and delete them too.
Set overlays_only: true on poster_cleanarr to gate every deletion on Kometa's EXIF marker (0x04bc == "overlay"). Only files actually written by Kometa get swept; your custom uploads, screenshots, and anything else lacking the marker are left untouched. The run summary surfaces a "Skipped (non-overlay)" row so you can see how many of your customs were spared.
If you only use Kometa (no hand uploads), the default overlays_only: false is fine and slightly faster.
- Run Kometa once so it writes a few items to
asset_directory. - In CHUB, go to Dashboard → New run → poster_renamerr with
dry_run: trueand click Run. - Open the run log — you should see per-item match attempts and proposed rename paths. No files are touched in dry-run mode.
- Turn
dry_runoff and run again. Files show up indestination_dirwith ARR/Plex-friendly names.
If poster_renamerr reports "No matching ARR items", enable debug log level and look at the match attempts — usually it means an ID is missing from the filename and the folder, or the Kometa folder doesn't follow the Movie (2020) / Series (2020) naming convention.