Kometa uses a YAML configuration file; this file contains settings that determine how Kometa behaves, and the required
connection details needed to connect to Plex Media Server, Radarr, Sonarr, and other third-party services via API.
Kometa uses YAML files for its configuration.
By default, and unless otherwise stated, Kometa looks for the configuration file at `/config/config.yml`.
There is one required YAML file (`config.yml`); any others are optional and would be used to define [collections](../files/collections.md), [overlays](../files/overlays.md), and [metadata changes](../files/metadata.md). Files other than `config.yml` are not required for Kometa to function.
Typically, files other than `config.yml` will be referred to as "metadata files" or "external YAML files". They are independent of each other; generally speaking, anything that is documented as part of `config.yml` cannot be used in a metadata file and vice versa.
This page will discuss the `config.yml` file and its settings. For information on metadata files, see the [Metadata Files](../files/overview.md) page.
## Config File
The `config.yml` file is used to define the settings that Kometa will use to connect to your Plex server, as well as required
connection details needed to connect to Plex Media Server, Radarr, Sonarr, and other third-party services via API. It is also used to define the libraries that Kometa will be working with and the settings that determine how Kometa behaves.
By default, and unless otherwise stated, Kometa looks for the configuration file at `config/config.yml`.
@ -33,7 +43,31 @@ requirements for setup that can be found by clicking the links within the table
## Configuration File Example
This example outlines what a "standard" config.yml file might look like when in use.
### Minimal Configuration File
The absolute minimum configuration file would look like this:
```yaml
libraries: # A CONFIG NEEDS AT LEAST ONE LIBRARY
Movies: # This is the name of the library
collection_files: # A library needs at least one metadata section [collections, overlays, metadata, operations]
- default: basic # At least one metadata file is required [this is a random one for illustration]
plex: # There needs to be a plex section
url: YOUR_PLEX_URL_GOES_HERE
token: YOUR_TOKEN_GOES_HERE
# There are other settings, but they all have defaults
tmdb: # There needs to be a tmdb section
apikey: YOUR_TMDB_API_KEY_GOES_HERE
# There are other settings, but they all have defaults
```
Typically, a configuration file will be much more complex than this, but this is the absolute minimum that is required for Kometa to function.
Kometa will fill in the defaults for any settings that are not explicitly defined in the configuration file. Those defaults will then be inserted into the file and written back out, which means that the minimal config will become more complete as soon as Kometa is run. This behavior [writing out the filled-in config] can be overridden with a [runtime flag](../kometa/environmental.md).
This example outlines what a "standard" config.yml file might look like when in use. This example is the same file as is linked to above.
~~~yaml
{%
@ -41,3 +75,46 @@ This example outlines what a "standard" config.yml file might look like when in
comments=false
%}
~~~
## Editing the Configuration File
YAML is a structured file format where things like indentation and spacing are important. A large number of issues on the Discord are due to incorrect YAML formatting. This is why it is important to use a good editor when working with YAML files.
Standard text editors (such as Notepad and TextEdit) often save text in a rich-text format which can result in text formatted in a way that Kometa cannot read. But not only that, they also make it very hard to visually distinguish the formatting, such as indentation.
YAML requires indents to be consistent, and does not allow tab characters. If you have one space too much, or too few, it is very hard to notice that with a editor like Notepad.
An editor that is more focused on editing code instead of text can automatically detect the .YML file format and adjust things to make it easier to work. They can also try to detect possible errors even before you actually run the .yml in Kometa.
### YAML Schema
Kometa has a schema file available that can be used to validate the configuration file in the editor.
If your editor supports it, you can use the schema file to validate the configuration file as you are editing it. This can save a lot of time and headaches.
Leverage the schema file by adding this line to the top of your config.yml file:
* **See [File Blocks](../config/files.md) for more information on how to define files in the config.**
## Definition Component Overview
## Structure of a collection/overlay/playlist file
There are a few different types of attributes that can be used in any given Collection/Overlay/Playlist File.
A collection/overlay/playlist file is a YAML file that defines a collection, overlay, or playlist. It is made up of a series of attributes that define how the collection/overlay/playlist is built and what metadata is associated with it.
### Builders
The structure of a collection/overlay/playlist file is as follows:
[Builders](builders/overview.md) are attributes placed at the top level of the definition that tell Kometa what items
belong in a collection/overlay/playlist. Multiple builders can be used in one definition. These could come from a
variety of sources including but not limited to:
=== "collection"
```yaml
collections:
COLLECTION_ONE:
# BUILDERS
# FILTERS
# METADATA DETAILS
COLLECTION_TWO:
# BUILDERS
# FILTERS
# METADATA DETAILS
```
* Your own Plex Sever using the Advance Filters.
* A Tautulli instance with your most played items.
* A List of media online on a site like IMDb, TMDb, or TVDb.
`COLLECTION_ONE` and `COLLECTION_TWO` are the names of the collections as shown in Plex. These are arbitrary, but should be unique.
=== "overlay"
```yaml
overlays:
OVERLAY_ONE:
# BUILDERS
# FILTERS
# OVERLAY DETAILS
OVERLAY_TWO:
# BUILDERS
# FILTERS
# OVERLAY DETAILS
```
`OVERLAY_ONE` and `OVERLAY_TWO` are the names of the overlays. With overlays specifically, those names refer to the images that will be used, unless you specify differently in the `OVERLAY DETAILS`.
=== "playlist"
```yaml
playlists:
PLAYLIST_ONE:
# BUILDERS
# FILTERS
# METADATA DETAILS
PLAYLIST_TWO:
# BUILDERS
# FILTERS
# METADATA DETAILS
```
`PLAYLIST_ONE` and `PLAYLIST_TWO` are the names of the playlists as shown in Plex. These are arbitrary, but should be unique.
### Step one: Builders
A "Builder" is an attribute that tells Kometa what items belong in a collection/overlay/playlist. Builders are placed at the top level of the definition. Multiple builders can be used in one definition.
This might be something like a search in Plex for a specific genre, or a list of items from a specific source.
All available builders are listed [here](builders/overview.md).
Builders are common to all types of definitions.
Every collection/overlay/playlist needs at least one builder, since without a starting point, there's nothing to build.
Here are some examples:
=== "Collection: Plex search"
[plex_search](./builders/plex.md#plex-search) is a builder that searches your Plex library for items that match the criteria you provide.
???+ example "Builder Example"
```yaml
collections:
My Test Collection 1:
plex_search:
any:
genre: Action
My Test Collection 2:
imdb_chart: top_movies
My Test Collection 3:
imdb_search:
type: movie
limit: 100
genre: action
votes.gte: 1000
plex_search:
Documentaries:
plex_search: # This is the builder
all:
genre: Documentary
```
That will create a collection of all documentaries in your Plex library.
=== "Collection: MDB List"
[mdblist_list](./builders/mdblist.md#mdblist-list) is a builder that finds every item in a [MDBList List](https://mdblist.com/toplists/).
That will create a collection of the movies on that particular MDB list
=== "Collection: Plex All"
[plex_all](./builders/plex.md#plex-all) is a builder that finds every item in your Plex library.
It is typically used with filters.
```yaml
collections:
Everything in Plex:
plex_all: true # This is the builder
```
That will create a collection of everything in your Plex library.
=== "Overlay: 4K Banner"
[plex_search](./builders/plex.md#plex-search) is a builder that searches your Plex library for items that match the criteria you provide.
```yaml
overlays:
4K: # Since this is a minimal overlay, Kometa will look for '4K.png' in the overlays folder.
plex_search: # This is the builder
all:
resolution: 4K
```
That would apply the `4K.png` overlay to all items in your Plex library that have a resolution of 4K.
=== "Overlay: IMDB Top 250"
[imdb_chart](./builders/imdb.md#imdb-chart) is a builder that finds items based on IMDB charts.
```yaml
overlays:
IMDB-Top-250: # Since this is a minimal overlay, Kometa will look for 'IMDB-Top-250.png' in the overlays folder.
imdb_chart: top_movies # This is the builder
```
That would apply the `IMDB-Top-250.png` overlay to whatever of the top 250 movies on IMDB you have in your library.
=== "Playlist: Plex Search"
[plex_search](./builders/plex.md#plex-search) is a builder that searches your Plex library for items that match the criteria you provide.
```yaml
playlists:
1990s Movies:
plex_search: # This is the builder
any:
genre: Action
decade: 1990
```
That will create a playlist of all movies from the 1990s in your Plex library.
All of the available builders work similarly, but have different attributes that you can use to define what items are included in the collection.
Some might require a URL, some might require a list of genres, some might require a list of keywords, etc.
Some might allow you to specify a minimum number of items to include, or a maximum number of items to include, etc.
With the builder, you have the initial list of items that you want to include in the collection.
### Step two: Filters
A filter is an attribute that tells Kometa to filter out items from the builder that don't meet the criteria you provide. Filters are placed under the `filters` attribute.
All available filters are listed [here](./filters.md).
### Filters
Filters are again common to all types of definitions.
[Filters](filters.md) are all put under a single attribute `filters`. These attributes will filter out items only after
builders find them. **Filters alone do nothing, they need builders.**
Filters *require* builders; without a builder, there is nothing for the filter to do.
There are some specific filters that can filter missing items sent to Radarr/Sonarr and if needed you can use the
[`only_filter_missing` setting](settings.md) to have the filter only effect the missing items.
Running filters are often slower than builders so whenever possible use only builders to build the definition.
Filters are optional, and generally speaking you should try to avoid using them if you can. They are slower than builders, and can slow down the process of building a collection.
???+ example "Filter Example"
For example:
This uses the `plex_all` Buidler to get every item currently in the plex library and then checks TMDb if they have
either `aftercreditsstinger` or `duringcreditsstinger` as a keyword.
It's faster to ask Plex for a list of movies released in 1981 than it is to ask Plex for a list of all movies and then look at all 8000 filter out the ones released in 1981.
=== "Movies from 1981 created by `plex_search`"
This:
```yaml
collections:
My Test Collection 1:
1981 by search:
plex_search:
all:
year: 1981
```
When run against a Plex library of 8842 items, produced a collection containing 46 items, and took 3 seconds:
In some cases, however, filters are unavoidable. For example, if you want to filter out items that don't have a specific keyword, you have to use a filter.
This sets the colleciton to only build if the builders find at **minimum 10 items** and will sync items to the
collection (removing items that no longer are found by the builders).
Examples:
=== "Filtering on TMDB votes"
```yaml
collections:
My Test Collection 1:
sync_mode: sync
minimum_items: 10
Romance Movies that TMDB members liked:
plex_search:
any:
genre: Action
all:
genre: Romance
filters:
tmdb_vote_count.gte: 1000
tmdb_vote_average.gte: 7.5
```
### Radarr/Sonarr Settings
That will create a collection of all romance movies in your Plex library that have a vote count of at least 1000 and a vote average of at least 7.5 on TMDb.
[Radarr/Sonarr Settings](arr.md) are attributes placed at the top level of the definition that tells Kometa how
Radarr/Sonarr is handled in this specific definition.
You can search Plex for the romance genre, but Plex cannot access TMDB vote count or average, so those things need to use a filter in Kometa.
???+ example "Setting Example"
=== "Filtering on TVDB status"
```yaml
collections:
All cancelled shows:
plex_all: true
filters:
tvdb_status: ended
```
This sets the colleciton to add missing movies from the builders to Radarr.
That will create a collection of all cancelled shows in your Plex TV library.
Plex cannot access TVDB status, so that needs to use a filter in Kometa.
Chaz Larson
2 months ago
