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:

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.

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

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

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.

i.e. <path_to_assets>/Star Wars/poster.png and <path_to_assets>/Star Wars.png are both asset depth 0, whilst <path_to_assets>/Movies/Star Wars/poster.png and <path_to_assets>/Movies/Star Wars.png are both asset level 1.

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

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 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

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 images types.

Attribute: prioritize_assets

Levels with this Attribute: Global/Library

Accepted Values: true or false

Default Value: true

Example

settings:
  prioritize_assets: 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

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_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_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

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

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

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

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

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

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

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

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_filtered - Used to show filtered items.¶

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_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_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

Example

settings:
  show_missing: false

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

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

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

Example

settings:
  save_report: false

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

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

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

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

Default Value: all

Example

settings:
  playlist_sync_to_users: 
    - user1
    - user2

playlist_exclude_users - Set the default playlist exclude_users.¶

Set the default playlist exclude_users.

Attribute: playlist_exclude_users

Levels with this Attribute: Global/Playlist

Accepted Values: list of users or comma-separated string of users

Default Value: None

Example

settings:
  playlist_exclude_users: 
    - user1
    - user2

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

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

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

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: jpg

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 75 is used]

Example

settings:
  overlay_artwork_quality: 95

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:
  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_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: all
  playlist_exclude_users:
  playlist_report: false
  verify_ssl: true
  custom_repo:
  overlay_artwork_filetype: jpg
  overlay_artwork_quality: 75

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:
    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