Kometa custom collections

Kometa Custom Collections

Own standalone collection files with collections:.

Goal

• Produce valid-looking Kometa collection YAML.
• Keep collection logic in the correct file type.
• Pick builders that match the user's real source of truth.
• Explain ordering, filters, schedules, and connector dependencies without drifting into config.yml.

Output Contract

Always return:

1. YAML for a collection file
2. 2-5 short bullets explaining why the builder and structure fit
3. A short caveat block for placeholders, auth dependencies, or ordering constraints

File Boundary

Belongs in this file:

• collections:
• collection-local templates
• builder keys such as tmdb_discover, trakt_list, imdb_search, plex_search, smart_filter, tautulli_popular
• filters
• definition settings such as sync_mode, collection_order, schedule, smart_label, build_collection
• collection operations such as item_label, radarr_add_missing, sonarr_add_missing

Does not belong in this file:

• root libraries:
• Plex, TMDb, Trakt, Tautulli, Radarr, or Sonarr auth setup
• playlist_files: or playlists:
• item-level metadata edits that belong in a metadata file

If the user also needs config.yml wiring:

• mention collection_files: briefly
• do not paste the whole collection body into config.yml

Base Shape

Use this as the default mental model:

collections:
  Example Name:
    builder_key: builder_value
    filters:
      field: value
    sync_mode: sync
    collection_order: custom

Never invent a builders: wrapper unless the docs explicitly call for it. For normal collection files, builder keys sit directly under the collection entry.

Builder Choice

Pick the builder family from the user's source of truth:

• TMDb: discover constraints, IDs, keywords, companies, networks, regions, charts
• Trakt: list URLs, charts, recommendations, box office
• IMDb: awards, niche search, interests, keywords, watchlists, vote thresholds
• Plex: only local library state, smart collections, local filtering
• Tautulli: actual Plex watch behavior
• Arr: tag backfills, missing-item pushes, operations-only behavior
• text file: hand-curated local order is the real truth

If the request mixes multiple sources:

• multiple builders are valid
• say that ranking becomes blended, not purely source-native
• keep collection_order: custom, custom.asc, or custom.desc to one real ranked builder

Core Rules

• builder sort_by controls provider query order
• collection_order controls Plex item order inside the collection
• sort_title controls where the collection sits in the library
• collection-level schedule is valid here; file-level schedule belongs in config.yml
• filters run after builders and require at least one builder
• smart_label is the right tool for third-party inputs that should end as Plex smart collections
• collection-level save_report, show_missing, show_filtered, show_unfiltered, only_filter_missing, and missing_only_released are valid
• report_path does not belong here; it belongs in the library config
• run_again: true is for missing-item workflows that need a second pass

Definition Settings

Reach for these only when the request needs them:

• blank_collection: true for empty shells or presentation-only entries
• build_collection: false for operations-only, Arr pushes, or server-preroll entries
• only_run_on_create: true for one-time bootstrap behavior
• ignore_blank_results: true when empty provider returns should not fail hard
• delete_collections_named for cleanup of known Plex collections
• changes_webhooks for definition-local notifications
• sync_to_trakt_list plus sync_missing_to_trakt_list for pushback to Trakt
• server_preroll for Plex preroll changes, usually with build_collection: false
• tmdb_region for TMDb chart-region control

Collection Metadata Updates

These still belong in collection files:

• presentation: summary, sort_title, collection_mode, collection_order
• visibility: visible_home, visible_library, visible_shared
• collection labels: label, label.remove, label.sync
• artwork: url_poster, file_poster, tmdb_poster, tvdb_poster, url_background
• remote summaries: trakt_description, tmdb_summary, tvdb_summary, letterboxd_description
• these are collection or playlist presentation updates, not metadata-file edits

Item Updates

Use item updates when the collection is a selector for downstream bulk edits:

• labels and genres: item_label, item_label.sync, item_genre, item_genre.sync
• language prefs: item_metadata_language, item_audio_language, item_subtitle_language, item_use_original_title
• show policies: item_episode_ordering, item_episode_sorting, item_keep_episodes, item_delete_episodes
• maintenance: item_assets, item_analyze, item_refresh, item_refresh_delay

Hard rules:

• item updates do not work in playlists or overlays
• show-only item updates should not be suggested for movie libraries
• item_refresh_delay only matters when item_refresh: true

Arr Overrides Versus Arr Item Tags

• use radarr_add_missing, sonarr_add_missing, radarr_folder, sonarr_quality, and similar keys to control add behavior
• use item_radarr_tag* or item_sonarr_tag* to retag things that already exist in Arr
• path mapping between Plex and Arr belongs in config, not here

Provider Shortcuts

• TMDb: prefer for exact discover logic; keep sort_by inside tmdb_discover; watch_region and region stay uppercase
• Trakt: prefer for list URLs and charts; use normal browser list URLs, not share links; time_period does not apply to trending or popular
• IMDb: prefer for niche search and awards; language filters use IMDb-style three-letter codes
• Plex: use smart_filter or plex_search for local self-updating collections; plex_search starts with any or all
• Tautulli: use for watched or popular activity; tune list_days, list_size, and list_minimum
• MDBList: multi-list inputs should be YAML lists or object form, not one comma-packed string
• Letterboxd: movie-only; push back on TV collection asks
• AniDB: relation builders want an AniDB ID or URL, not a title string
• MAL: search needs at least one real subattribute

For detailed provider syntax, load only the matching provider card and deep card.

Text File Builder

Use text_file when:

• the user already has a hand-curated list in a local .txt file
• exact file order matters more than live provider ranking
• season or episode collections need explicit tvdb_season or tvdb_episode targeting

Rules:

• pair it with sync_mode: sync and collection_order: custom when order must match the file
• multiple text files are concatenated into one ordered input
• builder_level: episode plus tvdb_season expands to every episode in that season
• builder_level: episode plus tvdb_episode targets one specific episode
• prefer typed prefixes like imdb: or tvdb_episode: when mixed context would be ambiguous

Review Mode

When reviewing broken YAML, classify findings under:

• valid
• wrong file type
• wrong nesting
• missing dependency
• unsafe assumption

Always check:

• top-level collections:
• builder keys directly under the collection entry
• no fake builders: wrapper
• no libraries: root leakage
• ordering choice matches builder count
• provider dependency is named when needed

Collection Templates

Collection files can own templates:, external_templates:, and per-collection template: calls.

Rules:

• templates can hold builders, filters, settings, updates, and item updates
• templates cannot nest another template call
• use external_templates when many files share one source
• keep external_templates in the same standalone file that uses them
• do not confuse defaults-style template_variables with general templates
• a variable cannot be both default and optional
• a conditional variable cannot also be declared under default or optional
• setting an optional variable to null on the call is a valid way to drop that attribute

If the user asks for reusable collection patterns, prefer a template over copy-pasting.

Embedded Examples

TMDb discover

collections:
  High Vote Sci-Fi:
    collection_order: custom
    sync_mode: sync
    tmdb_discover:
      with_genres: 878
      vote_average.gte: 7.2
      vote_count.gte: 500
      sort_by: vote_average.desc

Trakt list into smart collection

collections:
  Marvel Cinematic Universe:
    trakt_list: https://trakt.tv/users/jawann2002/lists/marvel-cinematic-universe-movies?sort=rank,asc
    smart_label:
      sort_by: release.desc
      all:
        label: <<smart_label>>

IMDb search

collections:
  Top Heist Movies:
    collection_order: custom
    sync_mode: sync
    imdb_search:
      type: movie
      interests: heist
      rating.gte: 7.0
      votes.gte: 50000
      sort_by: rating.desc

Operations-only

collections:
  Radarr Backfill:
    build_collection: false
    radarr_taglist: backlog
    item_label: backlog

Text file with preserved order

collections:
  Hand Curated Watchlist:
    text_file: config/lists/watchlist.txt
    collection_order: custom
    sync_mode: sync

Local References

Read only the relevant reference card for the job:

• core shape: references/cards/collections--core.md
• ordering: references/cards/collections--ordering.md
• reporting and reruns: references/cards/collections--reporting.md
• long-tail settings: references/cards/collections--definition-settings.md
• collection presentation: references/cards/collections--metadata-updates.md
• item bulk edits: references/cards/collections--item-updates.md
• Arr behavior: references/cards/collections--arr-settings.md
• provider cards: references/cards/collections--provider-*.md
• provider edge cases: references/cards/collections--provider-*-deep.md
• smart collections: references/cards/collections--smart-label.md
• text file lists: references/cards/builders--textfile.md
• template mechanics: references/cards/templates--core.md, references/cards/templates--variables.md, references/cards/templates--conditionals.md, references/cards/templates--external.md, references/cards/templates--reuse.md

Use these tiny examples for prompt grounding:

• mainline: gold-tmdb-discover-sci-fi, gold-trakt-list-smart-label, gold-imdb-search-heist, gold-plex-smart-filter-unwatched, gold-tautulli-popular-30d
• provider depth: gold-tmdb-watch-provider-region, gold-imdb-language-keyword, gold-trakt-list-details-summary, gold-trakt-chart-time-window, gold-mdblist-object-limit, gold-letterboxd-note-filter, gold-anilist-country-tag, gold-anidb-relation-franchise, gold-mal-studio-score
• long-tail: gold-tvdb-arrowverse, gold-mdblist-weekly-top, gold-letterboxd-90s-endings, gold-anidb-tag-anime, gold-anilist-current-season, gold-mal-top-action, gold-sonarr-tag-series, gold-boxofficemojo-worldwide
• templates and ops: gold-template-external-actor, gold-template-external-reuse, gold-template-conditional, gold-template-optional-null, gold-smart-label-expanded, gold-textfile-ranked-order, gold-textfile-episode-builder-level, gold-radarr-tag-operations, gold-collection-report-controls, gold-remove-overlay-label-season, gold-server-preroll-schedule, gold-sync-to-trakt-list, gold-item-language-preferences, gold-item-episode-retention, gold-item-arr-tag-sync
• repair/clean-art: gold-remove-overlay-label-episode, gold-collection-name-mapping-assets

Stopping Condition

Finish when:

• the YAML matches a collection-file shape
• the builder family fits the user's source
• ordering and dependency caveats are called out
• no config.yml or playlist-only leakage remains