Definition Options¶

Control how an individual collection, playlist, or overlay definition runs and handles its results. Place options beside the builder, not inside its dictionary. Availability varies by option; collection-only restrictions are noted below.

Quick start¶

Selects Action movies, caps the definition at 50 items, and synchronizes membership on each run. 50 is an integer; sync is a mode string. The name shown in Plex is different from the YAML mapping key.

collections:
  Weekly Action:
    name: Action Picks
    plex_search:
      all:
        genre: Action
    limit: 50
    sync_mode: sync

Option reference¶

Inherited means the same-named setting from the configuration settings is used unless overridden here. A dash means this page does not specify a default. Booleans use unquoted true or false; names, IDs, and paths use the value forms indicated.

Names and templates¶

Collection creation and membership¶

Scheduling and execution¶

Errors, exclusions, and missing items¶

Reports, artwork, and server actions¶

External list destinations¶

For asset filenames, name_mapping can replace characters that are invalid in a path while name keeps the desired Plex display title. Windows filenames cannot contain <, >, :, ", /, \, ?, or *.

Artwork overrides¶

asset_directory overrides artwork directories for one collection. It accepts an existing directory, a list of directories, or a mapping with movies, shows, music, and collections keys. All accepted forms affect only the collection's own artwork, not item_assets directories. Media-type keys choose artwork according to the library type.

Explicit overrides use the collection name or name_mapping for asset names. Empty values inherit the collection-file, library, or global setting; when none is configured, the existing asset_directory applies. See collection asset settings for layout and download behaviour.

This collection uses the specified directory for its own artwork. Replace it with an existing directory; the dictionary does not relocate artwork for the movies selected by plex_all.

collections:
  My Collection:
    asset_directory:
      collections: config/assets/my_collection_artwork
    plex_all: true

Scheduling and run conditions¶

run_definition accepts movie, show, artist, true, or false, as a single value, YAML list, or comma-separated string. One false or unmatched library type prevents the definition from running.

tmdb_birthday and tmdb_deathday use the dates for tmdb_person. Each accepts this_month as a boolean and before / after as numbers of days, zero or greater.

This example runs an actor collection during their birthday month. this_month is a nested boolean; 2157 identifies Robin Williams on TMDb. The definition also includes its builder, rather than relying on the date option to select items.

collections:
  Robin Williams Birthday Month:
    tmdb_person: 2157
    tmdb_birthday:
      this_month: true
    tmdb_actor: 2157

test: true selects a definition when running in test mode (--run-tests); definitions without that flag are skipped in test mode.

Hub priority¶

hub_priority requires the collection to be promoted through visible_library, visible_home, or visible_shared, and requires Plex Pass. Lower positive numbers appear first, before any auto_sort_hubs ordering.

Hub sorting, including priority, is skipped for targeted --run-collections or --run-files runs because those runs do not know every collection's priority.

External list syncing¶

These options sync movie/show results to external lists. They are separate from sync_mode, which controls membership in the Kometa definition.

MDBList sync example¶

sync_to_mdb_list finds a static list by exact name, creating it if absent. Use a name string or a dictionary containing name and optional mode. mode: sync is the default: it adds missing items and removes entries no longer present. append adds without removing existing entries.

collections:
  Recently Added:
    plex_search:
      all:
        added: 30
    sync_to_mdb_list: "Recently Added"

collections:
  Favourites:
    plex_search:
      all:
        user_rating.gte: 8.0
    sync_to_mdb_list:
      name: "Favourites"
      mode: append

FlickList sync example¶

sync_to_flicklist_list accepts a numeric list ID or exact name among your own FlickList lists. A matching list is reused; a list is created if no match exists.

Selects recently added items and syncs them to the named list. The boolean sync_missing_to_flicklist_list also enables syncing missing items.

collections:
  Recent FlickList Picks:
    plex_search:
      all:
        added: 30
    sync_to_flicklist_list: "Recently Added"
    sync_missing_to_flicklist_list: true

WeTrakr sync example¶

sync_to_wetrakr_list also accepts a numeric list ID or exact name among your own lists, reusing a match or creating a list when no match exists. Free accounts are limited to 5 lists of 250 items each. Exceeding either limit produces the account's upgrade message.

This example uses a numeric ID instead of a list-name string. Replace 13255 with one of your own list IDs. Missing items are included when the boolean is enabled.

collections:
  Recent WeTrakr Picks:
    plex_search:
      all:
        added: 30
    sync_to_wetrakr_list: 13255
    sync_missing_to_wetrakr_list: true

Smart label definitions¶

Smart labels use non-Plex builder results to create a Plex smart collection. Kometa labels each selected item, then creates a smart filter for that label. Plex reevaluates the filter as labels change; the external source is not fetched again until Kometa runs. Users can also add or remove the label themselves.

collections:
  Marvel Cinematic Universe:
    mdblist_list: https://mdblist.com/lists/stealthgyro/marvel-cinematic-universe-mcu
    smart_label: release.desc

collections:
  Marvel Cinematic Universe:
    mdblist_list: https://mdblist.com/lists/stealthgyro/marvel-cinematic-universe-mcu
    smart_label:
      sort_by: release.desc
      all:
        label: <<smart_label>>

collections:
  Unplayed MCU With Robert Downey Jr:
    mdblist_list: https://mdblist.com/lists/stealthgyro/marvel-cinematic-universe-mcu
    smart_label:
      sort_by: release.desc
      all:
        label: <<smart_label>>
        unplayed: true
        actor: "Robert Downey Jr."

Smart labels & Plex collectionless¶

Smart collections avoid the usual manual-collection show/hide rules and can resolve collectionless display issues. Use the method consistently: a useful rule is no more than one manual collection per library item, with broader groups implemented as smart labels.

Smart collections cannot use custom sorting to preserve the external builder's order. If you need that order together with collection visibility handling, use Plex Collectionless instead.

Default percent example¶

default_percent sets the threshold for episodes, seasons, tracks, and albums special filters when they do not specify a threshold. It defaults to 50 and accepts integers from 1 through 100.

This collection requires at least 35% of a show's episodes to have a user rating of 7 or higher. 35 is a percentage, while 7 is the nested rating threshold. The option belongs in the definition file, not config.yml.

collections:
  Shows With Rated Episodes:
    plex_all: true
    default_percent: 35
    filters:
      episodes:
        user_rating.gte: 7

Server preroll example¶

server_preroll sets Plex's Movie pre-roll video field under Settings > Extras. Use it with a schedule to change prerolls over the year. Place this in a definition file, not config.yml; build_collection: false avoids creating a Plex collection. Use file paths appropriate to your Plex server. See Plex Extras.

collections:
  January Preroll:
    build_collection: false
    server_preroll: /media/prerolls/january.mp4
    schedule: range(01/01-01/31)
  Base Preroll:
    build_collection: false
    server_preroll: /media/prerolls/base1.mp4;/media/prerolls/base2.mp4
    schedule: range(02/01-11/30)
  December Preroll:
    build_collection: false
    server_preroll: /media/prerolls/december.mp4
    schedule: range(12/01-12/31)

collections:
  Random Preroll:
    build_collection: false
    server_preroll:
      - /media/prerolls/file1.mp4
      - /media/prerolls/file2.mp4
      - /media/prerolls/file3.mp4

collections:
  Preroll Sequence:
    build_collection: false
    server_preroll:
      - - /media/prerolls/file1.mp4
        - /media/prerolls/file2.mp4
        - /media/prerolls/file3.mp4

collections:
  Mixed Prerolls:
    build_collection: false
    server_preroll:
      - /media/prerolls/file1.mp4
      - - /media/prerolls/file2.mp4
        - /media/prerolls/file3.mp4
      - /media/prerolls/file4.mp4

The mixed form produces /media/prerolls/file1.mp4;/media/prerolls/file2.mp4,/media/prerolls/file3.mp4;/media/prerolls/file4.mp4.