Skip to content

Library Attributes

Within the Configuration File, the libraries attribute specifies the Plex libraries that the user wants Kometa to act on.

Attributes are used to instruct Kometa what actions to take, such as "load the following libraries" or "execute the following Collection Definition files". These 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.

Attributes

The available attributes for each library are as follows:

library_name - Used to specify the Library's name.

Required only when trying to use multiple servers with the same name.

Each library that the user wants Kometa to interact with must be documented with a library attribute.

A library attribute is represented by the mapping name (i.e. Movies or TV Shows), this must have a unique name that correlates with a library of the same name within the Plex Media Server.

In the situation that two servers are being connected to which both have libraries of the same name, the library_name attribute can be utilized to specify the real Library Name, whilst the library attribute's mapping name can be made into a placeholder. This is showcased below:


Attribute: library_name

Accepted Values: Library Name

Default Value: Base Attribute Name

Example
libraries:
  Movies01:
    library_name: Movies
  Movies02:
    library_name: Movies
    plex:
      url: http://192.168.1.35:32400
      token: ####################
  TV Shows:
  Anime:
plex:
  url: http://192.168.1.12:32400
  token: ####################
  • In this example, "Movies01", "TV Shows", and "Anime" will all use the global plex server (http://192.168.1.12:32400) which is defined using the global plex mapping. "Movies02" will use the plex server http://192.168.1.35:32400 which is defined under its plex mapping over the global mapping.
collection_files - Used to define Collection Files.

The collection_files attribute is used to define Collection Files by specifying the path type and path of the files that will be executed against the parent library. See File Blocks for how to define them.


Attribute: collection_files

Accepted Values: Location of Collection YAML files.

Default Value: /config/<<MAPPING_NAME>>.yml

Example
libraries:
  TV Shows:
    collection_files:
      - file: config/TV Shows.yml
      - default: tmdb
      - default: network

By default, when collection_files is missing Kometa will look within the root Kometa directory for a collection file called <MAPPING_NAME>.yml. In the example below, Kometa will look for a file named TV Shows.yml.

libraries:
  TV Shows:
metadata_files - Used to define Metadata Files.

The metadata_files attribute is used to define Metadata Files by specifying the path of the files that will be executed against the parent library. See File Blocks for how to define them.

Tip

As of Kometa 1.20.0 "Metadata Files" refers to YAML files which refers to managing the metadata of items [movies, shows, music] within your library, and "Collection Files" refers to YAML files which define Collections.

In previous version of Kometa, "Metadata Files" could mean either of the above.


Attribute: metadata_files

Accepted Values: Location of Metadata Files

Default Value: None

Example
libraries:
  TV Shows:
    metadata_files:
      - file: config/metadata.yml
overlay_files - Used to define Overlay Files.

The overlay_files attribute is used to define Overlay Files by specifying the path type and path of the files that will be executed against the parent library. See File Blocks for how to define them.


Attribute: overlay_files

Accepted Values: Location of Overlay Files

Default Value: None

Example
libraries:
  TV Shows:
    collection_files:
      - file: config/TV Shows.yml
    overlay_files:
      - file: config/Overlays.yml
report_path - Location to save the YAML Report file for a library.

The report_path attribute is used to define where to save the YAML Report file. This file is used to store information about what media is added, removed, filtered, and missing from the Plex library compared to what is expected from the Collection, Metadata, Overlay or Playlist file.

If your Collection file creates a collection with Movie 1, Movie 2 and Movie 3 but your Plex library only has Movie 1 and Movie 3, then the missing YAML file will be updated to inform the user that Movie 2 was missing from the library.


Attribute: report_path

Accepted Values: Location to save the YAML Report file

Default Value: /config/<<MAPPING_NAME>>_report.yml where <<MAPPING_NAME>> is the name of the library attribute

Example

If you want to call your Report YAML something different you can like so:

libraries:
  Movies:
    report_path: /config/My Movie Report.yml

Alternatively, Report YAML files can be placed in their own directory, as below:

libraries:
  Movies:
    report_path: /config/reports/Movies.yml
    collection_files:
      - file: config/Movies.yml
    overlay_files:
      - file: config/Overlays.yml
template_variables - Used to define Custom Template Variables for every file in a library.

Passes all given Template Variables to every template in every Collection, Metadata, and Overlay file run.


Attribute: template_variables

Accepted Values: Dictionary of values specified by each particular file.

Default Value: None

Example
libraries:
  Movies:
    template_variables:
      collection_mode: hide_items
    collection_files:
      - file: config/Movies.yml
    overlay_files:
      - file: config/Overlays.yml
schedule - Used to schedule when a library is run.

Used to schedule when a library is run using the schedule options.


Attribute: schedule

Accepted Values: Any schedule option

Default Value: daily

Example
libraries:
  TV Shows:
    schedule: weekly(sunday)
    collection_files:
      - file: config/TV Shows.yml
    overlay_files:
      - file: config/Overlays.yml
operations - Used to specify Library Operations to run.

Used to specify Library Operations to run.


Attribute: operations

Accepted Values: Any Library Operation

Default Value: None

Example
libraries:
  Movies:
    collection_files:
      - default: imdb
    operations:
      mass_critic_rating_update: tmdb
      split_duplicates: true
remove_overlays - Used to remove overlays.

Used to remove overlays from this library only.

Proceed with Caution

When set to true, this will remove all overlays from your library every run, but will not delete the overlaid images from your system, resulting in image bloat.


Attribute: remove_overlays

Accepted Values: true or false

Default Value: false

Example
    libraries:
      Movies:
        remove_overlays: true
        collection_files:
          - file: config/Movies.yml
        overlay_files:
          - file: config/Overlays.yml
reapply_overlays - Used to reapply overlays.

Used to reapply overlays from this library only. This will reapply overlays to every item in your library.

Note that this is typically NEVER required. Kometa will automatically update overlays as needed as part of a regular overlay run.

Proceed with Caution

When set to true, this will reapply all overlays on each run even if there is no need to do so, which will result in image bloat.

If you think you need to use this setting, please think hard about why you have that impression, as you are almost certainly mistaken.

In general use, this setting will only extend runtimes and cause image bloat in the Plex metadata for no good reason.


Attribute: reapply_overlays

Accepted Values: true or false

Default Value: false

Example
    libraries:
      Movies:
        reapply_overlays: true
        collection_files:
          - file: config/Movies.yml
        overlay_files:
          - file: config/Overlays.yml
reset_overlays - Used to reset overlays.

Used to reset overlays from this library only. This will reset overlays to every item in your library to your source choice. This will use the reset image when overlaying items in your library.

Proceed with Caution

This will reset all posters to the desired source on each run and will reapply all overlays on each run, which will result in image bloat.


Attribute: reset_overlays

Accepted Values: plex or tmdb

Default Value: None

Example
    libraries:
      Movies:
        reset_overlays: tmdb
        collection_files:
          - file: config/Movies.yml
        overlay_files:
          - file: config/Overlays.yml
schedule_overlays - Used to schedule overlays.

Used to schedule overlays to run when desired. Overlays are applied all at once in a batch therefore you cannot schedule individual Overlay Files, as any unscheduled overlay file will be removed each time Kometa is run.


Attribute: schedule_overlays

Accepted Values: Any Schedule Option

Default Value: daily

Example
libraries:
  TV Shows:
    schedule_overlays: weekly(sunday)
    collection_files:
      - file: config/TV Shows.yml
    overlay_files:
      - file: config/Overlays.yml
settings - Used to override global setting attributes for this library only.

Used to override global setting attributes for this library only.


Attribute: settings

Accepted Values: Any setting attribute that overrides a global value.

Default Value: Global Value

Example
libraries:
  Movies:
    collection_files:
      - default: imdb
    settings:
      asset_directory: config/asssets/Movies
plex - Used to override global plex attributes for this library only.

Used to override global plex attributes for this library only.

plex Attribute is required either here or globally


Attribute: plex

Accepted Values: Any plex attribute that overrides a global value.

Default Value: Global Value

Example
libraries:
  Movies:
    collection_files:
      - file: config/Movies.yml
  Movies_on_Second_Plex:
    library_name: Movies
    collection_files:
      - file: config/Movies.yml
    plex:
      url: http://plex.boing.bong
      token: SOME_TOKEN
      timeout: 360
      db_cache: 8192
...
plex:
  url: http://plex.bing.bang
  token: SOME_TOKEN
  timeout: 60
  db_cache: 4096
  clean_bundles: false
  empty_trash: false
  optimize: false
...
radarr - Used to override global radarr attributes for this library only.

Used to override global radarr attributes for this library only.


Attribute: radarr

Accepted Values: Any radarr attribute that overrides a global value.

Default Value: Global Value

Example
libraries:
  Library01:     # this library uses the default radarr config
    collection_files:
      - file: config/Movies.yml

  Library02:     # this library overrides radarr root path and profile
    collection_files:
      - file: config/Movies.yml
    radarr:
      root_folder_path: /data/media/movies/tony
      quality_profile: Better

  Library03:      # this library overrides radarr quality profile
    collection_files:
      - file: config/Movies.yml
    radarr:
      quality_profile: Best

  Library04:      # this library uses the 4K radarr instance
    collection_files:
      - file: config/Movies.yml
    radarr:
      url: https://radarr-4k.bing.bang
      token: SOME_OTHER_TOKEN
      root_folder_path: /data/media/movies/geezer
      quality_profile: Bestest

  Library05:      # movies get added by a custom script so they should get added to radarr-4k
    collection_files:
      - file: config/Movies.yml
    radarr:
      url: https://radarr-4k.bing.bang
      token: SOME_OTHER_TOKEN
      root_folder_path: /data/media/movies/bill
      quality_profile: Bestest
      add_existing: true
      sonarr_path: /data/media/movies/bill
      plex_path: /mnt/unionfs/movies/bill
...
radarr:
  url: https://radarr.bing.bang
  token: SOME_TOKEN
  quality_profile: Good
  add_missing: true
  add_existing: false
  upgrade_existing: false
  monitor_existing: false
  root_folder_path: /movies
  monitor: false
  availability: released
  tag:
  search: false
  radarr_path:
  plex_path:
...
sonarr - Used to override global sonarr attributes for this library only.

Used to override global sonarr attributes for this library only.


Attribute: sonarr

Accepted Values: Any sonarr attribute that overrides a global value.

Default Value: Global Value

Example
libraries:
  Library01:     # this library uses the default sonarr config
    collection_files:
      - file: config/TV.yml

  Library02:     # this library overrides sonarr root path and profile
    collection_files:
      - file: config/TV.yml
    sonarr:
      root_folder_path: /data/media/shows/tony
      quality_profile: Better

  Library03:      # this library overrides sonarr quality profile
    collection_files:
      - file: config/TV.yml
    sonarr:
      quality_profile: Best

  Library04:      # this library uses the 4K sonarr instance
    collection_files:
      - file: config/TV.yml
    sonarr:
      url: https://sonarr-4k.bing.bang
      token: SOME_OTHER_TOKEN
      root_folder_path: /data/media/shows/geezer
      quality_profile: Bestest

  Library05:      # shows get added by a custom script so they should get added to sonarr-4k
    collection_files:
      - file: config/TV.yml
    sonarr:
      url: https://sonarr-4k.bing.bang
      token: SOME_OTHER_TOKEN
      root_folder_path: /data/media/shows/bill
      quality_profile: Bestest
      add_existing: true
      sonarr_path: /data/media/shows/bill
      plex_path: /mnt/unionfs/shows/bill

...
sonarr:
  url: https://sonarr.bing.bang
  token: SOME_TOKEN
  add_missing: false
  add_existing: false
  upgrade_existing: false
  monitor_existing: false
  root_folder_path: /data/media/shows/ozzy
  monitor: all
  quality_profile: Good
  language_profile: English
  series_type: standard
  season_folder: true
  tag:
  search: false
  cutoff_search: false
  sonarr_path:
  plex_path:
...
tautulli - Used to override global tautulli attributes for this library only.

Used to override global tautulli attributes for this library only.


Attribute: tautulli

Accepted Values: Any tautulli attribute that overrides a global value.

Default Value: Global Value

Example
    libraries:
      Movies:
        collection_files:
          - file: config/Movies.yml
      TV Shows:
        collection_files:
          - file: config/TV.yml
        tautulli:
          url: http://192.168.1.14:8659
          apikey: SOME_KEY
    ...
    tautulli:
      url: http://192.168.1.12:8659
      apikey: SOME_KEY
    ...

Example

This example is an advanced version of the library mappings which highlights some attributes being set at the global level, and some being set at the library level:

Example Library Mappings

In this example, the "TV Shows On Second Plex" library has a library-level plex configuration, which takes priority over the plex configuration set at the global level.

The "Anime" library also has a library-level radarr configuration, which takes priority over the radarr configuration set at the global level.

libraries:
  Movies:
    collection_files:
      - file: config/Movies.yml
      - default: imdb
      - default: studio
      - default: genre
      - default: actor
    operations:
      mass_critic_rating_update: tmdb
      split_duplicates: true
  TV Shows:
    collection_files:
      - file: config/TV Shows.yml
      - default: tmdb
      - default: network
    remove_overlays: false
    overlay_files:
      - file: config/Overlays.yml
  TV Shows On Second Plex:
    library_name: TV Shows
    plex:
      url: http://192.168.1.98:32400
      token: ####################
    collection_files:
      - file: config/TV Shows.yml
      - default: tmdb
      - default: network
  Anime:
    collection_files:
      - file: config/Anime.yml
      - default: myanimelist
    radarr:
      url: http://192.168.1.45:7878
      token: ################################
      root_folder_path: S:/Anime
    settings:
      asset_directory: config/assets/anime
plex:
  url: http://192.168.1.12:32400
  token: ####################
radarr:
  url: http://192.168.1.12:7878
  token: ################################
  add: true
  root_folder_path: S:/Movies
  monitor: true
  availability: announced
  quality_profile: HD-1080p
  tag: kometa
  search: false