Dynamic Collections¶

Kometa can dynamically create collections based on different criteria, such as

Collections based on the Collections from TMDb for every item in the library. ( Star Wars, Harry Potter, etc...)
Collections based on each of a Users Trakt Lists
Collections for the top X popular people on TMDb (Bruce Willis, Tom Hanks, etc...)
Collections for each decade represented in the library (Best of 1990s, Best of 2000s, etc...)
Collections for each of the moods/styles within a Music library (A Cappella, Pop Rock, etc...)

The main purpose of dynamic collections is to automate the creation of collections which would otherwise require considerable user input and repetition (such as creating a collection for every genre).

Using Dynamic Collections¶

Each dynamic collection definition creates a set of collection definitions based on some given criteria and uses either the built-in default template or a user defined custom template to dynamically create collection definitions.

Collection Naming¶

By default, the collections generated will be named for the thing being used to create them; things like genres, countries, actors, or even Trakt List Names.

To change the name of the collection, you can use dynamic collection attributes including title_format, remove_suffix, remove_prefix, key_name_override, and title_override all detailed below.

Dynamic Keys & Key Names¶

A dynamic key or key for short is used to refer to a specific value/result from the dynamic collection criteria that will be used to create the collection.

A key_name is the name that replaces <<key_name>> in title_format to create the collection titles for each key.

An example of some keys and their names that would be generated from a tmdb_collection dynamic collection are:

key: "10"
- key_name: Star Wars Collection
key: "1241"
- key_name: Harry Potter Collection

`key`	`key_name`
10	Star Wars Collection
1241	Harry Potter Collection

Example Key Usage¶

Keys can be used for a number of purposes, examples can be found throughout this page. A few examples are shown below:

Excluding the "Horror" key from the Genre dynamic collection definition

dynamic_collections:
  Genres:         # mapping name does not matter, just needs to be unique
    type: genre
    exclude:
      - Horror

Using the key_name_override attribute to change the formatting of "France" to "French" so that a collection can be named "French Cinema" instead of simply "France"
- This particular example also uses the title_format attribute to manipulate the naming convention of the collections.

dynamic_collections:
  Countries:         # mapping name does not matter, just needs to be unique
    type: country
    title_format: <<key_name>> Cinema
    key_name_override:
      France: French

Using the addons attribute to combine multiple keys, i.e. merging "MTV2", "MTV3" and "MTV (UK)" into one "MTV" collection.
- When doing this, individual collections will not be created for the individual MTV collections, instead they will be merged within the "MTV" collection.

dynamic_collections:
  networks:
    type: network
    addons:
      MTV:
        - MTV2
        - MTV3
        - MTV (UK)

Dynamic Collection Definition¶

Each dynamic collection definition must have a mapping name (just like standard collections) under the dynamic_collections attribute, which is also attached to the collection as a label to mark it as having been created by this dynamic collection.

Dynamic Collection Example (click to expand)

This example will create a collection for every TMDb Collection associated with items in the library.

dynamic_collections:
  TMDb Collections:          # This name is the mapping name
    type: tmdb_collection
    remove_suffix: "Collection"

Attributes¶

type & data - Used to specify the type of Dynamic Collection.¶

Used to specify the type of Dynamic Collection and its data. type is required for every dynamic collection and data is required for any type that uses the attribute.

Attribute: type & data

Accepted Values: See Dynamic Collection Types & Data

exclude - Used to exclude a list of keys from being created into collections.¶

Used to exclude a list of dynamic keys from being created into collections.

Attribute: exclude

Accepted Values: List of keys

Example

For example when making a genre dynamic collection definition you can exclude "Horror" from having a collection created from the key.

dynamic_collections:
  Genres:         # mapping name does not matter, just needs to be unique
    type: genre
    exclude:
      - Horror

addons - Used to define how multiple keys can be combined under a parent key.¶

Used to define how multiple dynamic keys can be combined under a parent key.

You can define custom parent keys under addons by just using the a key that doesnt exist; it will be considered a custom key combining all keys into one key.

Attribute: addons

Accepted Values: Dictionary where the key is the dynamic key and the value is a list of dynamic keys to combine.

Example

In this example the attribute is used to merge "MTV2", "MTV3" and "MTV (UK)" into the "MTV" collection.

dynamic_collections:
  networks:
    type: network
    addons:
      MTV:
        - MTV2
        - MTV3
        - MTV (UK)

template - Used to define which templates are used.¶

Used to define which templates are used for these dynamic collections. Each dynamic collection type has its own default template, but if you want to define and use your own template you can.

Each template is passed a few template variables you can use.

value: The list of keys and addons
key: The dynamic key
key_name: The key after key_name_override, remove_prefix, or remove_suffix are run on it.

Attribute: template

Accepted Values: Name of template or list of templates to use

Example

In this example the template removes the limit on the smart_filter so it shows all items in each network.

Press the icon to learn more

templates:
  network collection: #(1)!
    smart_filter:
      sort_by: critic_rating.desc
      all:
        network: <<value>>
dynamic_collections:
  Networks: #(2)!
    type: network
    title_format: <<key_name>>
    template: network collection #(3)!

This is the mapping name of the template.
This is the mapping name of the Dynamic Collection Definition.
This must match the mapping name of the template you want to use.

template_variables - Used to define template variables by key.¶

Used to define template variables by key. This attribute will allow multiple template variables to be set per dynamic key.

Tip

You can set a default value for a variable by using default instead of the dynamic key.

Attribute: template_variables

Accepted Values: Dictionary where the key is the template variable and the value is another Dictionary where the key is the dynamic key of the collection you want change the template variable for and the value is the new value for the template variable.

Example

For example, when using type: tmdb_collection and you want to define a poster url for some collections.

templates:
  my_template:
    optional:
      - my_collection_poster
    tmdb_collection_details: <<value>>
    collection_order: release
    url_poster: <<my_collection_poster>>
dynamic_collections:
  TMDb Collections:          # This name is the mapping name
    type: tmdb_collection
    remove_suffix: "Collection"
    template: my_template
    template_variables: #(1)!
      my_collection_poster: #(2)!
        119: https://www.themoviedb.org/t/p/original/oENY593nKRVL2PnxXsMtlh8izb4.jpg #(3)!
        531241: https://www.themoviedb.org/t/p/original/nogV4th2P5QWYvQIMiWHj4CFLU9.jpg #(4)!

Template variables are placed under template_variables.
my_collection_poster is the template variable being changed.
For key 119 use the url as the my_collection_poster template variable.
For key 531241 use the url as the my_collection_poster template variable.

remove_suffix - Used to remove the defined suffixes.¶

Used to remove the defined suffixes from the key before it’s used in the collection title.

Attribute: remove_suffix

Accepted Values: List or comma-separated string of suffixes to remove

Example

When using type: tmdb_collection you may not want every collection title to end with Collection.

dynamic_collections:
  TMDb Collections:          # This name is the mapping name
    type: tmdb_collection
    remove_suffix: "Collection"

remove_prefix - Used to remove the defined prefixes.¶

Used to remove the defined prefixes from the key before it’s used in the collection title.

Attribute: remove_prefix

Accepted Values: List or comma-separated string of prefixes to remove

Example

When using type: tmdb_collection you may not want every collection title to start with The.

dynamic_collections:
  TMDb Collections:          # This name is the mapping name
    type: tmdb_collection
    remove_prefix: "The"

title_format - Used to specify the format you want the collection titles to be.¶

Used to specify the format you want the collection titles to be.

There are a few special tags you can include in the title_format:

<<key_name>> is required and is what will be replaced by the dynamic key name.
<<limit>> will be replaced the limit template variable if passed to the definition.
<<library_type>> will be replaced with either movie, show, artist, or video depending on your library type.
<<library_typeU>> will be replaced with either Movie, Show, Artist, or Video depending on your library type.

Attribute: title_format

Accepted Values: String with <<key_name>> in it.

Example

dynamic_collections:
  Genres:         # mapping name does not matter just needs to be unique
    type: genre
    title_format: Top 50 <<key_name>> <<library_type>>s

key_name_override - Used to override key names before being formatted into titles.¶

Defines how key names can be overridden before they are formatted into collection titles.

Attribute: key_name_override

Accepted Values: Dictionary where the key is the key name you want to change and the value is what to change that key name to.

Example

This example uses key_name_override to change the formatting of "France" to "French" so that a collection can be named "French Cinema" instead of simply "France".

This particular example also uses the title_format attribute to manipulate the naming convention of the collections.

dynamic_collections:
  Countries:         # mapping name does not matter, just needs to be unique
    type: country
    title_format: <<key_name>> Cinema
    key_name_override:
      France: French

title_override - Used to override titles ignoring title formatting.¶

Defines how collection titles can be overridden ignoring title formatting.

Attribute: title_override

Accepted Values: Dictionary where the key is the dynamic key you want to change and the value is what to change the title to.

Example

This example will override the TMDb Star Wars collection which has an TMDb ID of 10 with `Star Wars Universe.

dynamic_collections:
  TMDb Collections:          # mapping name does not matter, just needs to be unique
    type: tmdb_collection
    remove_suffix: "Collection"
    title_override:
      10: Star Wars Universe

custom_keys - Used to allow the use of custom keys.¶

Defines if custom keys are allowed. Defaults to true

Attribute: custom_keys

Accepted Values: true or false

Example

dynamic_collections:
  TMDb Collections:          # mapping name does not matter, just needs to be unique
    type: tmdb_collection
    remove_suffix: "Collection"
    custom_keys: false

test - Used to run all collections in this set as tests.¶

Used to run all collections in this set with test: true in each collection definition. Defaults to fales

Attribute: test

Accepted Values: true or false

Example

dynamic_collections:
  Genres:         # mapping name does not matter just needs to be unique
    type: genre
    test: true

sync - Used to remove dynamic collections that are no longer in the creation list.¶

Will remove dynamic collections that are no longer in the creation list. Defaults to fales

Warning

The mapping name is added as a label to any collection created using this dynamic collection set and because of this when sync is true all collections with that label not found in this run will be deleted.

Attribute: sync

Accepted Values: true or false

Example

dynamic_collections:
  Trakt Liked Lists:          # mapping name does not matter just needs to be unique
    type: trakt_liked_lists
    sync: true

include - Used to define a specific list of keys to be made into collections.¶

Define a list of keys to be made into collections.

Warning

This cannot be used with exclude.

Tip

Use with the other_name attribute to create a catch-all collection for all keys not in the include list or in any addons list.

Attribute: include

Accepted Values: true or false

Example

dynamic_collections:
  Genres:         # mapping name does not matter just needs to be unique
    type: genre
    include:
      - Action
      - Adventure
      - Animation
      - Comedy
      - Family
      - Fantasy
      - Horror
      - Romance
      - Science Fiction
      - War

other_name - Used to create an "other" collection.¶

Will create an "other" collection when also using the include by specifying the "other" collection's name as other_name. When defined, all keys not in include or addons will be combined into this collection.

Attribute: other_name

Accepted Values: String to make the "other" collection's name

Example

dynamic_collections:
  Genres:         # mapping name does not matter just needs to be unique
    type: genre
    other_name: Other Genres
    include:
      - Action
      - Adventure
      - Animation
      - Comedy
      - Family
      - Fantasy
      - Horror
      - Romance
      - Science Fiction
      - War

other_template - Used to define which templates the dynamic other collection uses.¶

Used to define which templates are used for the dynamic other collection when they need to be different from the regular collection templates.

Tip

To use an other collection you must be using the include and other_name attributes.

Each template is passed a few template variables you can use.

value: The list of keys and addons
key: The dynamic key
key_name: The key after key_name_override, remove_prefix, or remove_suffix are run on it.
included_keys: The list of included keys
used_keys: The list of all keys used (included_keys and their addon keys)

Attribute: other_template

Accepted Values: Name of template or list of templates to use for the other collection only

Example

templates: 
  Other:
    plex_search:
      any:
        genre: <key>
    summary: Other Genres found in the library.
dynamic_collections:
  Genres:         # mapping name does not matter just needs to be unique
    type: genre
    other_name: Top Other Genres
    other_template: Other
    include:
      - Action
      - Adventure
      - Animation
      - Comedy
      - Family
      - Fantasy
      - Horror
      - Romance
      - Science Fiction
      - War

Dynamic Collection Template Variables¶

When calling a collection file with dynamic collection all the following are automatically accepted as template variables which will just replace the same attribute when running the file.

data
exclude
addons
remove_suffix
remove_prefix
title_format
key_name_override
title_override
custom_keys
test
sync
include
other_name

There are also several template variables that will be automatically append/remove from data, exclude, include, and addons so they can be changed by the user on the fly when needed.

append_data
remove_data
append_exclude
remove_exclude
append_include
remove_include
append_addons
remove_addons

Dynamic Collection Examples¶

Example

templates:
  genre collection: #(4)!
    smart_filter:
      limit: 100
      sort_by: critic_rating.desc
      all:
        genre: <<value>>
dynamic_collections:
  Genres:
    type: genre #(1)!
    exclude: #(2)!
      - Talk Show
    template: genre collection #(3)!

Uses the genre type to create dynamic collections based on each genre found in the library.
Uses exclude to exclude the Talk Show genre.
Uses the template called genre collection for these collections.
This is the same template as the default for genre but the limit has been increased to 100 from 50.

Example:¶

Create dynamic collections based on each genre found in the library (TV and Movies)
Amend the template to increase the limit from 50 to 100
Exclude the "Talk Show" genre
Name the collection "Top [Genre] Movies" or "Top [Genre] Shows"

templates:
  genre collection:
    smart_filter:
      limit: 100
      sort_by: critic_rating.desc
      all:
        genre: <<value>>
dynamic_collections:
  Genres:         # mapping name does not matter just needs to be unique
    type: genre
    exclude:
      - Talk Show
    title_format: Top <<key_name>> <<library_type>>s
    template: genre collection

Example:¶

Create dynamic collections based on each content rating found in the library (TV and Movies)
Amend the template to increase the limit from 50 to 100

templates:
  content rating collection:
    smart_filter:
      limit: 100
      sort_by: critic_rating.desc
      all:
        content_rating: <<value>>
dynamic_collections:
  Content Ratings:         # mapping name does not matter just needs to be unique
    type: content_rating
    template: content rating collection

Example¶

Create dynamic collections based on each year found in the library (TV and Movies)
Use the include attribute to only show collections for years "2020", "2021" and "2022"
Name the collection "Best of [Year]"

dynamic_collections:
  Years:         # mapping name does not matter just needs to be unique
    type: year
    include:
      - 2020
      - 2021
      - 2022
    title_format: Best of <<key_name>>

Example:¶

Create a collection for each decade found in the library (TV and Movies)
Name the collection "Top [Decade] Movies"
Rename the 2020 collection name to "Top 2020 Movies (so far)"

dynamic_collections:
  Decades:         # mapping name does not matter just needs to be unique
    type: decade
    title_format: Top <<key_name>> <<library_type>>s
    title_override:
      2020: Top 2020 Movies (so far)

Example:¶

Create a collection for the top movies from each country found in the library
Name the collection "Top [Country] Cinema"
The key_name_override attribute is used here in combination with the title_format to change the collection name from "France" which would be the default title, to "Top French Cinema"

dynamic_collections:
  Countries:         # mapping name does not matter just needs to be unique
    type: country
    title_format: Top <<key_name>> Cinema
    key_name_override:
      France: French
      Germany: German
      India: Indian

Example:¶

Create a collection for each resolution found in the library
Name the collection "[Resolution] Movies"

Combine 480p, 576p and SD into a collection called "SD Movies"

dynamic_collections:
  Resolutions:         # mapping name does not matter just needs to be unique
    type: resolution
    addons:
      480p:
        - 576p
        - SD
    title_override:
      480p: SD Movies

Example:¶

Create a collection for the top 20 artists for each mood found in the Music library
Amend the template to increase the limit from 10 to 20
Name the collection "Top 20 [Mood] Artists"

templates:
  mood collection:
    smart_filter:
      limit: 20
      sort_by: plays.desc
      all:
        artist_mood: <<value>>
dynamic_collections:
  Moods:         # mapping name does not matter just needs to be unique
    type: mood
    title_format: Top 20 <<key_name>> Artists
    template: mood collection

Example:¶

Create a collection for the top 20 albums for each mood found in the Music library
Amend the template to increase the limit from 10 to 20
Name the collection "Top 20 [Mood] Albums"

templates:
  mood collection:
    smart_filter:
      limit: 20
      sort_by: plays.desc
      all:
        album_mood: <<value>>
dynamic_collections:
  Moods:         # mapping name does not matter just needs to be unique
    type: album_mood
    title_format: Top 20 <<key_name>> Albums
    template: mood collection

Example:¶

Create a collection for the top 100 tracks for each mood found in the Music library
Amend the template to increase the limit from 50 to 100
Name the collection "Top 100 [Mood] Tracks"

templates:
  mood collection:
    smart_filter:
      limit: 100
      sort_by: plays.desc
      all:
        track_mood: <<value>>
dynamic_collections:
  Moods:         # mapping name does not matter just needs to be unique
    type: track_mood
    title_format: Top 100 <<key_name>> Tracks
    template: mood collection

Example:¶

Create a collection for the top 10 artists for each style found in the Music library
Name the collection "Top [Style] Artists"

templates:
  style collection:
    smart_filter:
      limit: 10
      sort_by: plays.desc
      all:
        artist_style: <<value>>
dynamic_collections:
  Styles:         # mapping name does not matter just needs to be unique
    type: style
    title_format: Top <<key_name>> <<library_type>>
    template: style collection

Example:¶

Create a collection for the top 10 albums for each style found in the Music library
Name the collection "Top [Style] Albums"

templates:
  style collection:
    builder_level: album
    smart_filter:
      limit: 10
      sort_by: plays.desc
      all:
        album_style: <<value>>
dynamic_collections:
  Styles:         # mapping name does not matter just needs to be unique
    type: album_style
    title_format: Top <<key_name>> Albums
    template: style collection