Skip to content

Kometa Integration

Jump to bottom
chodeus edited this page May 23, 2026 · 6 revisions

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.

📐 The setup in one picture

  ┌─────────────────────┐       ┌─────────────────────┐       ┌─────────────────────┐
  │      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_renamerr reads from that directory, matches each poster against your ARR / Plex libraries, renames the files, and copies/moves/hardlinks them into your destination_dir.
  • Plex picks the renamed posters up (optionally pushed directly via the Plex API when you enable add_posters).

🔧 Kometa side

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: 0

Key points:

  • asset_folders: true is required. CHUB's poster_renamerr extracts title, year, and tmdb_id/tvdb_id/imdb_id from the folder and the filename, so a per-item folder improves matching accuracy a lot.
  • asset_directory can be a list. CHUB can read from multiple.

🐳 Docker mount alignment

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_dir

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

⚙️ CHUB side

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 API

Key points:

  • source_dirs = the in-container path of your Kometa asset volume.
  • asset_folders: true must match your Kometa setting.
  • action_type: hardlink is the cheapest — no extra disk use, both trees point at the same inode. Source and destination must be on the same filesystem.
  • add_posters: true on Plex instances pushes the renamed poster directly via the Plex API after CHUB copies it into destination_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 /kometa and a Google Drive sync folder and want the Drive posters to take precedence, list /kometa first and the Drive folder below it.

🧹 Cleaning up old Kometa overlays safely

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.

✅ Verifying it works

  1. Run Kometa once so it writes a few items to asset_directory.
  2. In CHUB, go to Dashboard → New run → poster_renamerr with dry_run: true and click Run.
  3. Open the run log — you should see per-item match attempts and proposed rename paths. No files are touched in dry-run mode.
  4. Turn dry_run off and run again. Files show up in destination_dir with 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.

Related

Getting Started

Guides

Help

Developer

Clone this wiki locally