Skip to content

Kometa Integration

Jump to bottom
chodeus edited this page May 31, 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 (on its kometa apply method) reads from that directory, matches each poster against your ARR / Plex libraries, renames the files, and copies/moves/hardlinks them into your destination_dir.
  • Kometa/Plex then pick the renamed posters up. (Alternatively, set apply_method: plex to skip destination_dir entirely and upload posters straight to Plex via the API — the two methods are mutually exclusive; see below.)

🔧 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:
  apply_method: kometa             # this page's flow; use "plex" to upload instead
  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          # only used on apply_method: plex

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.
  • apply_method chooses the destination, and it's either/or: kometa (shown here) writes renamed files into destination_dir for Kometa/Plex to pick up and uploads nothing; plex uploads straight to Plex via the API and writes nothing to destination_dir.
  • add_posters: true on a Plex instance only matters on the plex apply method — it opts that instance in to direct uploads. On the kometa path it's ignored (Kometa/Plex pick the files up from destination_dir).
  • 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.

🪧 Logos & backgrounds via the asset directory

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

🧹 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