Kometa Integration

🏠 Home › Kometa Integration

Kometa Integration

Kometa manages Plex metadata and collections; CHUB renames the poster files that feed it. This page covers the one-time setup so both tools see the same folders.

The dataflow

  ┌─────────────────────┐      ┌─────────────────────┐      ┌─────────────────────┐
  │      Kometa         │      │       CHUB          │      │       Plex          │
  │  writes posters to  │ ───▶ │  poster_renamerr    │ ───▶ │  applies posters to │
  │  its asset folder   │      │  renames + copies   │      │  library items      │
  └─────────────────────┘      └─────────────────────┘      └─────────────────────┘

1. Kometa writes original posters to its asset_directory.
2. CHUB's poster_renamerr (on apply_method: kometa) reads that directory, matches each poster against your ARR/Plex libraries, renames the files, and copies/moves/hardlinks them into destination_dir.
3. Kometa/Plex pick up the renamed posters.

Alternatively, set apply_method: plex to skip destination_dir and upload posters straight to Plex via the API. The two methods are mutually exclusive.

Kometa side

Enable asset folders in your Kometa config.yml:

settings:
  asset_directory:
    - /config/assets            # where Kometa drops posters (can be a list)
  asset_folders: true           # one folder per item: Movie (2020)/poster.jpg
  asset_depth: 0

asset_folders: true is required — CHUB matches on title, year, and IDs pulled from both the folder and the filename.

Docker mount alignment

CHUB must read the same folder Kometa writes to. In CHUB's 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

CHUB's PUID/PGID must be able to read the Kometa folder — align UIDs or run both containers as the same user. See Installation for PUID/PGID details.

Gotcha: With action_type: move, CHUB removes files from the Kometa folder after renaming, so it needs write access. copy and hardlink only need read access.

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]           # in-container path of the Kometa volume
  destination_dir: /posters        # where renamed copies land
  action_type: hardlink            # copy | move | hardlink
  asset_folders: true              # must match your Kometa setting
  instances:
    - radarr_main
    - sonarr_main
    - plex_main:
        library_names: ["Movies", "TV Shows"]
        add_posters: true          # only used on apply_method: plex

Field	Note
source_dirs	In-container path of the Kometa asset volume. Multiple entries: bottom of the list wins for the same item.
asset_folders	Must match your Kometa asset_folders setting.
action_type	hardlink is cheapest (shared inode, no extra disk); source and destination must share a filesystem.
apply_method	kometa writes into destination_dir; plex uploads via the API. Either/or.
add_posters	Only matters on apply_method: plex; ignored on the kometa path.

Logos & backgrounds via asset_renamerr

asset_renamerr extends the same flow to non-poster art. On apply_method: kometa it writes Kometa-named logo and background files into destination_dir (Kometa 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

Square art is not read from Kometa asset directories — use apply_method: plex for it. See Modules → asset_renamerr for the full source/apply matrix.

Cleaning up old Kometa overlays

Kometa leaves the previous poster generation behind in Plex's Uploads/posters folder on every overlay pass. poster_cleanarr sweeps them.

If you also upload custom posters directly through Plex, set overlays_only: true on poster_cleanarr so deletions are gated on Kometa's EXIF overlay marker (0x04bc == "overlay") — only Kometa-written files get swept. Kometa-only setups can leave the default overlays_only: false.

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, set 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.
4. Turn dry_run off and run again. Files appear in destination_dir with ARR/Plex-friendly names.

Gotcha: "No matching ARR items" usually means an ID is missing from both the filename and the folder, or the folder doesn't follow Movie (2020) / Series (2020) naming. Enable debug log level to see the match attempts.

---

Next: UI Guide · Related: Modules, Configuration