Settings¶

Overview¶

The settings: attribute and subsequent settings can be used to command various aspects of the functionality of Kometa.

Examples of these settings include the ability to:

Cache each Plex GUID and IDs to increase performance.
Create asset folders for collections so that custom posters can be stored for upload.
Use a custom repository as the base for all git Metadata files.

The settings attribute and attributes can be specified individually per library, or can be inherited from the global value if it has been set. If an attribute is specified at both the library and global level, then the library level attribute will take priority.

There are some attributes which can be specified at the collection level using Settings.

Attributes set at the collection level will take priority over any library or global-level attribute.

Attributes¶

The available setting attributes which can be set at each level are outlined below:

asset_depth - Used to control the depth of search in the asset directory.¶

Specify how many folder levels to scan for an item within the asset directory.

At each asset level, Kometa will look for either medianame.ext [such as Star Wars.png] or a dedicated folder containing poster.ext.

For example, if your asset directory is /path/to/assets/, and your asset_depth is 2, then Kometa will look for an asset match in any of these locations:

/path/to/assets/level-0
/path/to/assets/level-0/level-1
/path/to/assets/level-0/level-1/level-2

The first match will be accepted.

Specifically, if Kometa is looking for the asset name "Star Wars (1977)", then it would be found in any of:

/path/to/assets/Star Wars (1977)
/path/to/assets/Movies/Star Wars (1977)
/path/to/assets/Movies/Sci-fi/Star Wars (1977)

Tip

asset_folders must be set to true for this to take effect.

increasing the amount of levels to scan will reduce performance

Attribute: asset_depth

Levels with this Attribute: Global/Library

Accepted Values: Any Integer 0 or greater.

Default Value: 0

Example

settings:
  asset_depth: 2

asset_directory - Used to define where local assets are located.¶

Specify the directories where assets (posters, backgrounds, etc) are located.

Tip

Assets can be stored anywhere on the host system that Kometa has visibility of (i.e. if using docker, the directory must be mounted/visible to the docker container).

Warning

Kometa will not create asset directories. Asset directories you specify here need to exist already.

Attribute: asset_directory

Levels with this Attribute: Global/Library

Accepted Values: Any Directory or List of Directories.

Default Value: [Directory containing YAML config]/assets

Example

settings:
  asset_directory: config/movies

settings:
  asset_directory:
    - config/assets/movies
    - config/assets/collections

asset_folders - Used to control the asset directory folder structure.¶

While true, Kometa will search the asset_directory for a dedicated folder per item vs while false will look for an image.

i.e. When true the example path would be <asset_directory_path>/Star Wars/poster.png instead of <asset_directory_path>/Star Wars.png.

Attribute: asset_folders

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  asset_folders: true

cache - Used to control Kometa's cache database.¶

Allow Kometa to create and maintain a local cache database for faster subsequent processing. The cache file is created in the same directory as the configuration file.

Critical Warning

We strongly advise you leave this setting to true

If you set this to false, any Overlays set against your libraries will be reapplied on each and every run. Kometa stores information on which Overlays it has applied in the cache file.

You will suffer from image bloat and your Kometa runs will be longer than needed if you do not use a cache file.

Attribute: cache

Levels with this Attribute: Global

Accepted Values: true or false.

Default Value: true

Example

settings:
  cache: true

cache_expiration - Used to control how long data is cached for.¶

Set the number of days before each cache mapping expires and has to be re-cached.

Attribute: cache_expiration

Levels with this Attribute: Global

Accepted Values: Integer greater than 0.

Default Value: 60

Example

settings:
  cache_expiration: 30

create_asset_folders - Used to automatically create asset folders when none exist.¶

Whilst searching for assets, if an asset folder cannot be found within the asset_directory one will be created.

Asset Searches can happen in a number of ways.

Any Collection specified under the collections header in a Collection File.
Any Item specified under the metadata header in a Collection File.
Any Playlist specified under the playlists header in a Playlist File.
Any Item in a library that is running the assets_for_all Library Operation.
Any Collection in a library that is running the assets_for_all_collections Library Operation.
Any Item that has an Overlay applied to it.
Any Item found by a Builder while the definition also has item_assets: true specified.

Attribute: create_asset_folders

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  create_asset_folders: true

custom_repo - Used to set up the custom repo file block type.¶

Specify where the repo attribute's base is when defining collection_files, metadata_files, playlist_file and overlay_files.

Note

Ensure you are using the raw GitHub link (i.e. https://github.com/Kometa-Team/Community-Configs/tree/master/meisnate12)

Attribute: custom_repo

Levels with this Attribute: Global

Accepted Values: Link to repository base.

Default Value: None

Example

settings:
  custom_repo: https://github.com/Kometa-Team/Community-Configs/tree/master/meisnate12

default_collection_order - Used to set the collection_order for every collection run.¶

Set the collection_order for every collection run by Kometa unless the collection has a specific collection_order.

Tip

custom cannot be used if more than one Builder is being used for the collection (such as imdb_list and trakt_list within the same collection).

Attribute: default_collection_order

Levels with this Attribute: Global/Library

Accepted Values:

`release`	Order Collection by Release Dates.
`alpha`	Order Collection Alphabetically.
`custom`	Order Collection Via the Builder Order.
Any `plex_search` sort option.

Default Value: None

Example

settings:
  default_collection_order: release

delete_below_minimum - Used to delete collections below minimum_items¶

When a collection is run, delete the collection if it is below the minimum number specified by minimum_items.

Tip

Relies on minimum_items being set to the desired integer.

Attribute: delete_below_minimum

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: false

Example

settings:
  delete_below_minimum: true

delete_not_scheduled - Used to delete collections not scheduled.¶

If a collection is skipped due to it not being scheduled, delete the collection.

Attribute: delete_not_scheduled

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: false

Example

settings:
settings:
  delete_not_scheduled: true

dimensional_asset_rename - Used to automatically rename asset files based on their dimensions.¶

Whilst searching for assets, scan the folders within the asset_directory and if an asset poster (i.e. /ASSET_NAME/poster.ext) was not found, rename the first image found that has a height greater than or equal to its width to poster.ext. If an asset background (i.e. /ASSET_NAME/background.ext), rename the first image found that has a width greater than its height to background.ext.

Tip

asset_folders must be set to true for this to take effect.

Attribute: dimensional_asset_rename

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  dimensional_asset_rename: true

download_url_assets - Used to download url images into the asset directory.¶

Whilst searching for assets, download images set within Collection/Metadata/Playlist files( i.e. images set by url_poster or url_background) into the asset folder if none are already present.

Attribute: download_url_assets

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  download_url_assets: true

ignore_ids - List of TMDb/TVDb IDs to ignore.¶

Set a List or comma-separated string of TMDb/TVDb IDs to ignore in all collections.

Note

This does not apply to smart_filter Collections.

Attribute: ignore_ids

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: List or comma-separated string of TMDb/TVDb IDs.

Default Value: None

Example

settings:
  ignore_ids: 572802,695721

ignore_imdb_ids - List of IMDb IDs to ignore.¶

Set a List or comma-separated string of IMDb IDs to ignore in all collections.

Note

Rhis does not apply to smart_filter Collections.

Attribute: ignore_imdb_ids

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: List or comma-separated string of IMDb IDs.

Default Value: None

Example

settings:
  ignore_imdb_ids: tt6710474,tt1630029

item_refresh_delay - Time to wait between each item_refresh.¶

Specify the number of seconds to wait between each item_refresh of every movie/show in a collection/playlist.

Note

Useful if your Plex Media Server is having issues with high request levels.

Attribute: item_refresh_delay

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: Any Integer 0 or greater. (value is in seconds)

Default Value: 0

Example

settings:
  item_refresh_delay: 5

minimum_items - Used to control minimum items requires to build a collection/playlist.¶

Set the minimum number of items that must be found in order to build or update a collection/playlist.

Attribute: minimum_items

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: Integer greater than 0

Default Value: 1

Example

settings:
  minimum_items: 5

missing_only_released - Used to filter unreleased items from missing lists.¶

Whilst running a collection or playlist, when Kometa handles missing items to either report it to the user, report it to a file, or send it to Radarr/Sonarr all unreleased items will be filtered out.

Attribute: missing_only_released

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: false

Example

settings:
  missing_only_released: true

only_filter_missing - Used to have the filter only apply to missing items.¶

Only items missing from a collection will be filtered. Only specific filters can filter missing. See Filters for more information.

Note

This can be used to filter which missing media items get sent to Sonarr/Radarr.

Attribute: only_filter_missing

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: false

Example

settings:
  only_filter_missing: true

overlay_artwork_filetype - Used to control the filetype used with overlay images.¶

Used to control the filetype used with overlay images. This setting will only be applied to images generated after the value is added to your config.

Attribute: overlay_artwork_filetype

Levels with this Attribute: Global/Library

Accepted Values:

`jpg`	Use JPG files for saving Overlays.
`png`	Use PNG files for saving Overlays.
`webp_lossy`	Use Lossy WEBP files for saving Overlays.
`webp_lossless`	Use Lossless WEBP files for saving Overlays.

Default Value: webp_lossy

Example

settings:
  overlay_artwork_filetype: png

overlay_artwork_quality - Used to control the JPG or Lossy WEBP quality used with overlay images.¶

Used to control the JPG or Lossy WEBP quality used with overlay images. This setting will only be applied to images generated after the value is added to your config.

Attribute: overlay_artwork_quality

Levels with this Attribute: Global/Library

Accepted Values: Any Integer 1-100 [Values over 95 are not recommended and may result in excessive image size, perhaps too large to be uploaded to Plex.

Default Value: None [when no value is provided the standard 90 is used.]

Example

settings:
  overlay_artwork_quality: 90

playlist_report - Used to print out a playlist report.¶

Set playlist_report to true to print out a playlist report at the end of the log.

Attribute: playlist_report

Levels with this Attribute: Global

Accepted Values: true or false.

Default Value: false

Example

settings:
  playlist_report: true

playlist_sync_to_users - Set the default playlist sync_to_users.¶

Set the default playlist sync_to_users. To Sync a playlist to only yourself leave playlist_sync_to_users blank.

Note

sharing playlists with other users will not share any posters associated with the playlist, this is a Plex limitation.

Attribute: playlist_sync_to_users

Levels with this Attribute: Global/Playlist

Accepted Values: all, list of users, or comma-separated string of users. Leave blank to not sync playlists to other users.

Example

settings:
  playlist_sync_to_users:
    - user1
    - user2

prioritize_assets - Used to prioritize asset_directory images over all other images types.¶

When determining which image to use on an item prioritize the asset_directory over all other image sources.

Standard priority is as follows:

url_poster
file_poster
tmdb_poster
tvdb_poster
Asset directory
tmdb_person
tmdb_collection_details

8+. all other _details methods

So if you have a poster for "Some Collection" specified as a url_poster and also as an asset, the url_poster will win and the asset will be ignored.

This setting pushes asset_directory to the top of the list, so the asset would win over teh url_poster.

Attribute: prioritize_assets

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  prioritize_assets: true

report_path - Used to specify the location of save_report.¶

Specify the location where save_report is saved.

Attribute: report_path

Levels with this Attribute: Library

Accepted Values: YAML file path location.

Default Value: [Directory containing YAML config]/[Library Mapping Name]_report.yml

Example

settings:
  report_path: config/TV_missing_report.yml

run_again_delay - Used to control the number of minutes to delay running run_again collections.¶

Set the number of minutes to delay running run_again collections after daily run is finished.

For example, if a collection adds items to Sonarr/Radarr, the library can automatically re-run "X" amount of time later so that any downloaded items are processed.

Tip

A collection is a run_again collection if it has the run_again Setting attribute set to true.

Attribute: run_again_delay

Levels with this Attribute: Global

Accepted Values: Any Integer 0 or greater.

Default Value: 0

Example

settings:
  run_again_delay: 5

run_order - Used to specify the run order of the library components.¶

Specify the run order of the library components [Library Operations, Collection Files and Overlay Files]

Attribute: run_order

Levels with this Attribute: Global/Library

Accepted Values: List or comma-separated string which must include operations, metadata and overlays in any order.

Default Value: operations,metadata,collections,overlays

Example

settings:
  run_order:
  - collections
  - overlays
  - operations
  - metadata

save_report - Used to save a report YAML file.¶

Save a report of the items added, removed, filtered, or missing from collections to a YAML file in the same directory as the file run.

Attribute: save_report

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: true

Important: Identifying these missing items can be extremely expensive in terms of runtime.

Example

settings:
  save_report: false

show_asset_not_needed - Used to show/hide the update not needed messages.¶

Whilst searching for assets, show or hide the update not needed messages.

Attribute: show_asset_not_needed

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  show_asset_not_needed: true

show_filtered - Used to show items filtered out.¶

List all items which have been filtered out of a collection or playlist. (i.e. if it doesn't meet the filter criteria)

Attribute: show_filtered

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: false

Example

settings:
  show_filtered: true

show_missing - Used to show missing items from collections or playlists.¶

While show_missing is true items missing from collections or playlists will be displayed.

Attribute: show_missing

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: true

Important: Identifying these missing items can be extremely expensive in terms of runtime.

Example

settings:
  show_missing: false

show_missing_assets - Used to print a message when assets are missing.¶

Display missing asset warnings for items, collections, and playlists.

Attribute: show_missing_assets

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: true

Example

settings:
  show_missing_assets: false

show_missing_episode_assets - Used to show any missing episode assets.¶

Whilst searching for assets, when scanning for assets for a TV Show, if an Episode Title Card is found (i.e. /ASSET_NAME/S##E##.ext), notify the user of any episodes which do not have an asset image.

Shows/Hides messages like these for episodes

"Asset Warning: No poster found for '{item_title}' in the assets folder '{directory}'"

"Asset Warning: No poster '{name}' found in the assets folders"

"\nMissing S##E## Title Card"

Attribute: show_missing_episode_assets

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  show_missing_episode_assets: true

show_missing_season_assets - Used to show any missing season assets.¶

Whilst searching for assets, when scanning for assets for a TV Show, if Season posters are found (i.e. /ASSET_NAME/Season##.ext), notify the user of any seasons which do not have an asset image.

Shows/Hides messages like these for seasons/albums

"Asset Warning: No poster found for '{item_title}' in the assets folder '{directory}'"

"Asset Warning: No poster '{name}' found in the assets folders"

"Missing Season {season_number} Poster"

Attribute: show_missing_season_assets

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  show_missing_season_assets: true

show_options - Used to show attribute options from plex.¶

While show_options is true the available options for an attribute when using plex_search, smart_filter or filters will be shown.

i.e. a smart_filter on the genre attribute will return all of the attributes within the specified library.

Attribute: show_options

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: false

Example

settings:
  show_options: true

show_unconfigured - Used to show collections not in the current run.¶

List all collections not configured in the current Kometa run at the end of each run.

Attribute: show_unconfigured

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  show_unconfigured: false

show_unfiltered - Used to show items which make it through filters.¶

List all items which have made it through the filters INTO a collection or playlist. (i.e. if it meets the filter criteria)

Attribute: show_unfiltered

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values: true or false.

Default Value: false

Example

settings:
  show_unfiltered: true

show_unmanaged - Used to show collections not managed by Kometa.¶

List all collections not managed by Kometa at the end of each run.

Attribute: show_unmanaged

Levels with this Attribute: Global/Library

Accepted Values: true or false.

Default Value: true

Example

settings:
  show_unmanaged: false

sync_mode - Used to set the sync_mode for collections and playlists.¶

Sets the sync_mode for collections and playlists. Setting the sync_mode directly in a collection or playlist definition will override the sync_mode for that definition.

Attribute: sync_mode

Levels with this Attribute: Global/Library/Collection/Playlist

Accepted Values:

`sync`	Will add and remove any items that are added/removed from the source Builder.
`append`	Will only add items that are added from the source Builder, but will not remove anything even if it is removed from the source Builder.

Default Value: append

Example

settings:
  sync_mode: sync

What does this mean?

You have a Trakt list of ten movies. You run Kometa and create a collection from the list. The collection contains those ten movies.

Tomorrow the list contains a different ten movies. You run Kometa.

sync_mode: sync - Kometa syncs the collection with the list, so the collection still has ten movies, but they are the ones that are in the Trakt list today. The original ten have been removed from the collection.

sync_mode: append - Kometa appends the ten new movies to the collection, which now has twenty movies in it.

The next day five movies change in the list. You run Kometa.

sync_mode: sync - Kometa syncs the collection with the list, so the collection still has ten movies, the ones that are in the Trakt list today. The five that are no longer in the Trakt list are removed from the collection.

sync_mode: append - Kometa appends the five new movies to the collection, which now has twenty-five movies in it.

tvdb_language - Specify the language to query TVDb in.¶

Specify the language to query TVDb in.

Note

If no language is specified or the specified language is not found then the original language is used.

Attribute: tvdb_language

Levels with this Attribute: Global

Accepted Values: Any ISO 639-2 Language Code.

Default Value: None

Example

settings:
  tvdb_language: eng

Default Values¶

The below in an extract of the config.yml.template and is the initial values that are set if you follow any of the installation guides.

Tip

We suggest users review each of these settings and amend as necessary, these are just default values to get you started.

settings: 
  run_order:
  - operations
  - metadata
  - collections
  - overlays
  cache: true
  cache_expiration: 60
  asset_directory:
  - config/assets
  asset_folders: true
  asset_depth: 0
  create_asset_folders: false
  prioritize_assets: false
  dimensional_asset_rename: false
  download_url_assets: false
  show_missing_season_assets: false
  show_missing_episode_assets: false
  show_asset_not_needed: true
  sync_mode: append
  minimum_items: 1
  default_collection_order: release
  delete_below_minimum: true
  delete_not_scheduled: false
  run_again_delay: 2
  missing_only_released: false
  only_filter_missing: false
  show_unmanaged: true
  show_unconfigured: true
  show_filtered: false
  show_unfiltered: false
  show_options: true
  show_missing: true
  show_missing_assets: true
  save_report: false
  tvdb_language: eng
  ignore_ids:
  ignore_imdb_ids:
  item_refresh_delay: 0
  playlist_sync_to_users:
  playlist_exclude_users:
  playlist_report: false
  verify_ssl: true
  custom_repo:
  overlay_artwork_filetype: webp_lossy
  overlay_artwork_quality: 90

Example Library-Level Settings¶

The below showcases how to set a library-level setting, assuming that the attribute is listed as a library-level compatible attribute in the above table.

If no library-level attribute is set, then the global attribute is used.

Tip

Press the icon to learn more.

libraries:
  Movies:
    settings:
      run_order: #(1)!
      - collections
      - metadata
      - operations
      - overlays
      minimum_items: 3 #(2)!
    collection_files:
      # stuff here
    overlay_files:
      # stuff here
    operations:
      # stuff here
  TV Shows:
    collection_files:
      # stuff here
    overlay_files:
      # stuff here
    operations:
      # stuff here
settings:
  run_order: #(3)!
  - operations
  - overlays
  - collections
  - metadata
  minimum_items: 1 #(4)!

Sets the run_order specifically for the Movies library.
Sets the minimum_items attribute specifically for the Movies library.
Sets the global run_order which will apply to all libraries unless a library-level run_order is found, as showcased in the above example.
Sets the global minimum_items which will apply to all libraries unless a library-level minimum_items is found, as showcased in the above example.

Settings¶

Overview¶

Attributes¶

Default Values¶

Example Library-Level Settings¶

YAML Lists Explained

1. List Within a Mapping

2. Inline Style

YAML Dictionaries Explained