Files¶

Files define the structure and format for creating Collections, Overlays, Playlists, and Metadata Edits within your libraries.

Files are modular and when properly leveraged, they not only facilitate the management of your library's collections and metadata but also serve as a crucial backup resource in case a restore is necessary.

These are the File types that can be utilized against Plex servers:

File Type	Description	Parent Attribute
Collection Files	Defines the data for building collections, allowing you to group and showcase your library in unique ways.	`collection_files`
Overlay Files	Defines the data for building overlays, allowing you to place information such as resolutions and ratings onto your posters.	`overlay_files`
Metadata Files	Defines the data for editing metadata, allowing you to find and manipulate the metadata on individual items within your library.	`metadata_files`
Playlist Files	Defines the data for building playlists, allowing you to combine media from multiple libraries and share them with users on your server.	`playlist_files`
Template Files	Defines templates in external files, allowing you to use the same templates across multiple other files.	`external_templates`

Example File Blocks (click to expand)

In this example, multiple file blocks are defined for the "TV Shows" library:

libraries:
  TV Shows:
    collection_files:
      - file: config/TVShows.yml
      - folder: config/TV Shows/
    overlay_files:
      - default: imdb
      - repo: overlays
playlist_files:
  - url: https://somewhere.com/Playlists.yml

Unlike the others, Playlist Files are not defined per-library.

Within the above example, Kometa will:

First, look within the root of the Kometa directory (also known as config/) for a collection file named TVShows.yml. If this file does not exist, Kometa will skip the entry and move to the next one in the list.
Then, look within the root of the Kometa directory (also known as config/) for a directory called TV Shows, and then load any collection files within that directory.
Then, look in the defaults folder within the local Kometa folder [or docker container] for a file called imdb.yml.
Then, look within the Custom Defined Repo for a file called overlays.yml.
Finally, load the playlist file located at https://somewhere.com/Playlists.yml

See File Blocks for more information on how to define files in the config.

Definition Component Overview¶

There are a few different types of attributes that can be used in any given Collection/Overlay/Playlist File.

Builders¶

Builders are attributes placed at the top level of the definition that tell Kometa what items belong in a collection/overlay/playlist. Multiple builders can be used in one definition. These could come from a variety of sources including but not limited to:

Your own Plex Sever using the Advance Filters.
A Tautulli instance with your most played items.
A List of media online on a site like IMDb, TMDb, or TVDb.

Builder Example

collections:
  My Test Collection 1:
    plex_search:
      any:
        genre: Action
  My Test Collection 2:
    imdb_chart: top_movies
  My Test Collection 3:
    imdb_search:
      type: movie
      limit: 100
      genre: action
      votes.gte: 1000
    plex_search:
      any:
        genre: Action

Filters¶

Filters are all put under a single attribute filters. These attributes will filter out items only after builders find them. Filters alone do nothing, they need builders.

There are some specific filters that can filter missing items sent to Radarr/Sonarr and if needed you can use the only_filter_missing setting to have the filter only effect the missing items.

Running filters are often slower than builders so whenever possible use only builders to build the definition.

Filter Example

This uses the plex_all Buidler to get every item currently in the plex library and then checks TMDb if they have either aftercreditsstinger or duringcreditsstinger as a keyword.

collections:
  My Test Collection 1:
    plex_all: true
    filters:
      tmdb_keyword: aftercreditsstinger, duringcreditsstinger

Settings¶

Settings are attributes placed at the top level of the definition that tells Kometa how to run the definition. Each setting will affect how the definition is run or shown in the log.

Setting Example

This sets the colleciton to only build if the builders find at minimum 10 items and will sync items to the collection (removing items that no longer are found by the builders).

collections:
  My Test Collection 1:
    sync_mode: sync
    minimum_items: 10
    plex_search:
      any:
        genre: Action

Radarr/Sonarr Settings¶

Radarr/Sonarr Settings are attributes placed at the top level of the definition that tells Kometa how Radarr/Sonarr is handled in this specific definition.

Setting Example

This sets the colleciton to add missing movies from the builders to Radarr.

collections:
  My Test Collection 1:
    radarr_add_missing: true
    imdb_search:
      type: movie
      limit: 100
      genre: action
      votes.gte: 1000

Collection/Playlist Metadata Updates¶

Updates are attributes placed at the top level of the definition that tells Kometa Metadata Changes for the Collection/Playlist.

Collection/Playlist Metadata Update Example

collections:
  My Test Collection 1:
    summary: This is my test collection's summary
    plex_search:
      any:
        genre: Action

Item Metadata Updates¶

Item Updates are attributes placed at the top level of the definition that tells Kometa Metadata Changes for every item found in the Collection/Playlist.

Item Metadata Update Example

This will add the genre Credits to every item found after builders and filters are run.

collections:
  My Test Collection 1:
    item_genre: Credits
    plex_all: true
    filters:
      tmdb_keyword: aftercreditsstinger, duringcreditsstinger