# 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](https://www.themoviedb.org/collection/10-star-wars-collection), [Harry Potter](https://www.themoviedb.org/collection/1241), 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 `<>` 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 ```yaml 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. ```yaml dynamic_collections: Countries: # mapping name does not matter, just needs to be unique type: country title_format: <> 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. ```yaml 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. ??? example "Dynamic Collection Example (click to expand)" This example will create a collection for every TMDb Collection associated with items in the library. ```yaml dynamic_collections: TMDb Collections: # This name is the mapping name type: tmdb_collection remove_suffix: "Collection" ``` ### Attributes ??? blank "`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](dynamic_types.md) ??? blank "`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 "Example" For example when making a `genre` dynamic collection definition you can exclude "Horror" from having a collection created from the key. ```yaml dynamic_collections: Genres: # mapping name does not matter, just needs to be unique type: genre exclude: - Horror ``` ??? blank "`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](../kometa/yaml.md#dictionaries) where the key is the `dynamic key` and the value is a list of `dynamic keys` to combine. ???+ example "Example" In this example the attribute is used to merge "MTV2", "MTV3" and "MTV (UK)" into the "MTV" collection. ```yaml dynamic_collections: networks: type: network addons: MTV: - MTV2 - MTV3 - MTV (UK) ``` ??? blank "`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 "Example" In this example the template removes the limit on the `smart_filter` so it shows all items in each network. Press the :fontawesome-solid-circle-plus: icon to learn more ```yaml templates: network collection: #(1)! smart_filter: sort_by: critic_rating.desc all: network: <> dynamic_collections: Networks: #(2)! type: network title_format: <> template: network collection #(3)! ``` 1. This is the mapping name of the template. 2. This is the mapping name of the Dynamic Collection Definition. 3. This must match the mapping name of the template you want to use. ??? blank "`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](../kometa/yaml.md#dictionaries) where the key is the template variable and the value is another [Dictionary](../kometa/yaml.md#dictionaries) 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 "Example" For example, when using `type: tmdb_collection` and you want to define a poster url for some collections. ```yaml templates: my_template: optional: - my_collection_poster tmdb_collection_details: <> collection_order: release url_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)! ``` 1. Template variables are placed under `template_variables`. 2. `my_collection_poster` is the template variable being changed. 3. For key `119` use the url as the my_collection_poster template variable. 4. For key `531241` use the url as the my_collection_poster template variable. ??? blank "`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 "Example" When using `type: tmdb_collection` you may not want every collection title to end with `Collection`. ```yaml dynamic_collections: TMDb Collections: # This name is the mapping name type: tmdb_collection remove_suffix: "Collection" ``` ??? blank "`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 "Example" When using `type: tmdb_collection` you may not want every collection title to start with `The`. ```yaml dynamic_collections: TMDb Collections: # This name is the mapping name type: tmdb_collection remove_prefix: "The" ``` ??? blank "`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`: * `<>` is **required** and is what will be replaced by the dynamic key name. * `<>` will be replaced the limit template variable if passed to the definition. * `<>` will be replaced with either `movie`, `show`, `artist`, or `video` depending on your library type. * `<>` will be replaced with either `Movie`, `Show`, `Artist`, or `Video` depending on your library type.
**Attribute:** `title_format` **Accepted Values:** String with `<>` in it. ???+ example "Example" ```yaml dynamic_collections: Genres: # mapping name does not matter just needs to be unique type: genre title_format: Top 50 <> <>s ``` ??? blank "`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](../kometa/yaml.md#dictionaries) where the key is the key name you want to change and the value is what to change that key name to. ???+ example "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. ```yaml dynamic_collections: Countries: # mapping name does not matter, just needs to be unique type: country title_format: <> Cinema key_name_override: France: French ``` ??? blank "`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](../kometa/yaml.md#dictionaries) where the key is the `dynamic key` you want to change and the value is what to change the title to. ???+ example "Example" This example will override the TMDb Star Wars collection which has an TMDb ID of `10` with `Star Wars Universe. ```yaml 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 ``` ??? blank "`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 "Example" ```yaml dynamic_collections: TMDb Collections: # mapping name does not matter, just needs to be unique type: tmdb_collection remove_suffix: "Collection" custom_keys: false ``` ??? blank "`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 "Example" ```yaml dynamic_collections: Genres: # mapping name does not matter just needs to be unique type: genre test: true ``` ??? blank "`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 "Example" ```yaml dynamic_collections: Trakt Liked Lists: # mapping name does not matter just needs to be unique type: trakt_liked_lists sync: true ``` ??? blank "`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`](#addons) list.
**Attribute:** `include` **Accepted Values:** `true` or `false` ???+ example "Example" ```yaml 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 ``` ??? blank "`other_name` - Used to create an "other" collection."
Will create an "other" collection when also using the [`include`](#include) by specifying the "other" collection's name as `other_name`. When defined, all keys not in [`include`](#include) or [`addons`](#addons) will be combined into this collection.
**Attribute:** `other_name` **Accepted Values:** String to make the "other" collection's name ???+ example "Example" ```yaml 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 ``` ??? blank "`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`](#include) and [`other_name`](#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 "Example" ```yaml templates: Other: plex_search: any: genre: 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` {% include-markdown "./dynamic_examples.md" %}