Kometa config core

Kometa Config Core

Own config.yml and nothing else.

Goal

• Produce or review valid-looking config.yml.
• Wire libraries to collection, metadata, overlay, and playlist files.
• Keep collection, overlay, metadata, and playlist bodies out of this file.

Output Contract

Always return:

1. YAML for config.yml
2. 2-5 short bullets explaining the structure
3. Caveats for required secrets, downstream dependencies, and file path placeholders

File Boundary

Belongs here:

• global connectors such as plex, tmdb, trakt, mdblist, tautulli, radarr, sonarr
• root settings
• root playlist_files
• libraries
• library-level collection_files, metadata_files, overlay_files
• library-level operations
• library-level report_path, remove_overlays, reapply_overlays, reset_overlays
• file-block attributes like template_variables, schedule, asset_directory

Does not belong here:

• raw collections: bodies
• raw overlays: bodies
• raw metadata: edit bodies
• raw playlists: bodies

Hard Rules

• playlist_files is root-level, never under a library
• overlay files cannot be individually scheduled; use library schedule_overlays
• collection, metadata, and playlist file blocks can use schedule
• keep secrets blank or explicit placeholders
• if later files rely on Trakt, MDBList, Tautulli, Radarr, or Sonarr, mention that dependency in caveats

File Block Rules

Supported location types to prefer when relevant:

• file
• folder
• url
• default
• git
• repo

Use these by intent:

• local repo path: file
• many local YAMLs in one folder: folder
• raw hosted YAML: url
• built-in defaults: default
• official community config repo path: git
• custom external repo path: repo

Scheduling Rules

Know the level:

• file-block schedule: collection / metadata / playlist files
• library schedule: whole library run
• library schedule_overlays: all overlays for that library

Do not invent per-overlay-file scheduling.

Library Rules

• library mapping name should match the Plex library name unless library_name overrides it
• library template_variables apply to every templated file in that library
• remove_overlays: true is a cleanup action, not a normal default
• report_path is valid when the user wants a report file path

Operations Rules

• operations: belongs under the library, not under root settings
• a single operations block is the normal default
• a YAML list of operation blocks is valid when each block needs its own schedule
• assets_for_all and assets_for_all_collections are the important switches for item art and unmanaged collection art
• mass_poster_update and mass_background_update are powerful but risky around overlays
• metadata_backup, split_duplicates, genre_mapper, and rating sync operations are valid library-level tools

Asset And Poster Workflow

• safest overlay workflow: asset_directory + prioritize_assets: true + assets_for_all: true
• asset images become clean-art source of truth when overlays run
• reapply_overlays: true is a repair knob, not a steady-state recommendation
• mass_poster_update can reset art and trigger repeated overlay uploads, so call out image-bloat risk

Reporting Rules

• keep report_path on the library block
• keep save_report, show_missing, show_filtered, and show_unfiltered under root or library settings
• only_filter_missing and missing_only_released are for missing-item handling, not for changing the built collection itself
• report-heavy runs can be expensive on large libraries

Minimal Skeleton

libraries:
  Movies:
    collection_files:
      - file: config/collections/movies.yml
settings:
  cache: true
plex:
  url: http://plex:32400
  token: PLEX_TOKEN_HERE
tmdb:
  apikey: TMDB_API_KEY_HERE

Multi-Library Example

libraries:
  Movies:
    collection_files:
      - file: config/collections/movies.yml
        schedule: weekly(friday)
    metadata_files:
      - file: config/metadata/movies.yml
    overlay_files:
      - default: resolution
        template_variables:
          horizontal_align: left
          vertical_align: top
    operations:
      mass_critic_rating_update: imdb
  TV Shows:
    collection_files:
      - file: config/collections/shows.yml
    overlay_files:
      - default: network
    schedule_overlays: weekly(saturday)
playlist_files:
  - file: config/playlists/shared.yml
    schedule: weekly(sunday)
settings:
  cache: true
plex:
  url: http://plex:32400
  token: PLEX_TOKEN_HERE
tmdb:
  apikey: TMDB_API_KEY_HERE
trakt:
  client_id: TRAKT_CLIENT_ID_HERE
  client_secret: TRAKT_CLIENT_SECRET_HERE

Asset-First Overlay Example

libraries:
  Movies:
    overlay_files:
      - default: resolution
    operations:
      assets_for_all: true
settings:
  asset_directory: config/assets
  asset_folders: true
  prioritize_assets: true

Scheduled Operations Example

libraries:
  Movies:
    operations:
      - schedule: weekly(friday)
        mass_critic_rating_update:
          - tmdb
          - imdb
      - schedule: weekly(saturday)
        split_duplicates: true

Report-Aware Library Example

libraries:
  Movies:
    report_path: config/reports/movies.yml
    operations:
      split_duplicates: true
settings:
  save_report: true
  show_missing: true
  show_filtered: false

Local References

Read only what matches the request:

• references/cards/config--overview.md
• references/cards/config--file_types.md
• references/cards/config--files.md
• references/cards/config--file-blocks.md
• references/cards/config--libraries.md
• references/cards/config--libraries-deep.md
• references/cards/config--operations.md
• references/cards/config--asset-workflow.md
• references/cards/config--reports.md
• references/cards/config--playlists.md
• references/cards/config--schedule.md
• references/cards/kometa--guides--assets.md

Use these examples first:

• examples/gold/gold-config-minimal.yml
• examples/gold/gold-library-wiring.yml
• examples/gold/gold-default-playlist-call.yml
• examples/gold/gold-asset-first-overlay-config.yml
• examples/gold/gold-asset-directory-multi-root.yml
• examples/gold/gold-operations-blocks-scheduled.yml
• examples/gold/gold-delete-unconfigured-managed-collections.yml
• examples/gold/gold-reporting-config.yml
• examples/gold/gold-reporting-missing-pipeline.yml

Review Checklist

• is this really config.yml and not another file type?
• are playlist files at root level?
• are file references under the correct library?
• is schedule applied at the correct level?
• are operations under the library and not under settings?
• if operations are scheduled, are they YAML list items rather than one mapping with schedule?
• is report_path on the library rather than root settings?
• is report_path kept out of file blocks?
• does the overlay or poster workflow create avoidable image bloat?
• if asset art should hit items, is assets_for_all present?
• are required connectors present for downstream builders and operations?

Stopping Condition

Finish when:

• the user has a clean config.yml shape
• file blocks are on the right level
• all non-config bodies have been kept out of the file