diff --git a/docs/config/images/VSCode.gif b/docs/config/images/VSCode.gif new file mode 100644 index 00000000..af852b6a Binary files /dev/null and b/docs/config/images/VSCode.gif differ diff --git a/docs/config/overview.md b/docs/config/overview.md index bc9b374f..bddb4bb5 100644 --- a/docs/config/overview.md +++ b/docs/config/overview.md @@ -1,9 +1,19 @@ -# Config File +## General Overview -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`. A template Configuration File can be found in the [GitHub Repo](https://github.com/Kometa-Team/Kometa/blob/master/config/config.yml.template). @@ -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: +``` +# yaml-language-server: $schema=https://raw.githubusercontent.com/Kometa-Team/Kometa/nightly/json-schema/config-schema.json +``` + +### Suggested Editors + +Preferred: + +[Visual Studio Code](https://code.visualstudio.com/) (Windows/Mac/Linux, Opensource & Free) + +Additionally, install the indent-rainbow by oderwat extension and the YAML by Red Hat extension. + +Other options: + +[Notepad++](https://notepad-plus-plus.org/) (Windows only, Opensource & Free) + +[Sublime Text](https://www.sublimetext.com/) (Windows/Mac/Linux, Paid) + +[BBEdit](https://www.barebones.com/) (Mac only, Paid) + +For further details and a short list of highly recommended extensions, you can also take a look [here](https://l33tlamer.github.io/yml-tips/). + +Here is an example of how Visual Studio Code works with the recommended plugins and using our Kometa schema: + +![](./images/VSCode.gif) diff --git a/docs/files/overview.md b/docs/files/overview.md index 4f901115..db83b902 100644 --- a/docs/files/overview.md +++ b/docs/files/overview.md @@ -6,134 +6,331 @@ * **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/). + + ```yaml + collections: + Top Movies of The Week: + # mdblist_list is the builder + mdblist_list: https://mdblist.com/lists/linaspurinis/top-watched-movies-of-the-week + ``` + + 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: + + ``` + |==========================================================================================| + | Finished 1981 by search Collection | + | Collection Run Time: 0:00:03 | + |==========================================================================================| + ``` + +=== "Movies from 1981 created by `plex_all` and `filters`" + While this: + ```yaml + collections: + 1981 by filter: plex_all: true filters: - tmdb_keyword: aftercreditsstinger, duringcreditsstinger + year: 1981 ``` -### Settings + When run against the same Plex library of 8842 items, produced the same collection containing the same 46 items, and took over 5 minutes: -[Settings](settings.md) are attributes placed at the top level of the definition that tells Kometa how to run the -definition. Each setting will affect how the definition is run or shown in the log. + ``` + |==========================================================================================| + | Finished 1981 by filter Collection | + | Collection Run Time: 0:05:30 | + |==========================================================================================| + ``` -???+ example "Setting Example" +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. + +=== "Filtering on file attributes" + ```yaml + collections: + Best Movies of 2020 with Commentary: + trakt_list: https://trakt.tv/users/chazlarson/lists/looper-best-movies-of-2020 + filters: + audio_track_title: Commentary + ``` + + That will create a collection of movies from that Looper list for which your copies have commentary tracks. + + The builder is the list of movies from the Looper list, and the filter looks for the commentary track. + +### Step three: Metadata Details + +`METADATA DETAILS` is where you'd set things like a poster or a sort order or the like. + +You can also set metadata for items within the collection. + +Some of these are usable with all types of definitions; some are not. Refer to the specific page for details. + +Settings to control how the collection is built are listed [here](./settings.md). + +Settings to override Radarr/Sonarr settings are listed [here](./arr.md). + +Settings to update the metadata of the collection/playlist are listed [here](./updates.md). + +Settings to update the metadata of the items in the collection/playlist are listed [here](./item_updates.md). + +Examples: +=== "Add a poster to a collection" ```yaml collections: - My Test Collection 1: - radarr_add_missing: true - imdb_search: - type: movie - limit: 100 - genre: action - votes.gte: 1000 + Romance Movies: + plex_search: + all: + genre: Romance + url_poster: https://theposterdb.com/api/assets/213090 ``` -### Collection/Playlist Metadata Updates + Adds a poster to the collection, using one of the attributes [here](./updates.md). -[Updates](updates.md) are attributes placed at the top level of the definition that tells Kometa Metadata Changes for the -Collection/Playlist. +=== "Change collection sort order" + ```yaml + collections: + Romance Movies: + plex_search: + all: + genre: Romance + collection_order: release.desc + ``` -???+ example "Collection/Playlist Metadata Update Example" + Sorts the items in the collection by descending release date, using one of the attributes [here](./updates.md). +=== "Override global Radarr tag" ```yaml collections: - My Test Collection 1: - summary: This is my test collection's summary + Romance Movies: plex_search: - any: - genre: Action + all: + genre: Romance + radarr_tag: romance_tag ``` -### Item Metadata Updates + Sets a tag in Radarr on items in the collection instead of any tag specified in the settings, using one of the attributes [here](./arr.md). -[Item Updates](item_updates.md) are attributes placed at the top level of the definition that tells Kometa Metadata Changes -for every item found in the Collection/Playlist. +=== "Label items ONLY; no collection built" + ```yaml + collections: + Tag IMDB Top 250 Tagger: + imdb_chart: top_movies + item_label: imdb_top_250 + build_collection: false + ``` -???+ example "Item Metadata Update Example" + Sets a label on all items in Plex that are part of the IMDB Top 250, but doesn't build the collection. - This will add the genre `Credits` to every item found after builders and filters are run. + Uses attributes from [here](./item_updates.md) and [here](./settings.md). +=== "Set a minumum collection size" ```yaml collections: - My Test Collection 1: - item_genre: Credits - plex_all: true - filters: - tmdb_keyword: aftercreditsstinger, duringcreditsstinger + At least ten action movies: + minimum_items: 10 + plex_search: + any: + genre: Action ``` + This will create a collection of action movies from your plex library, **but** only if there are at **minimum 10 items** found by the search. + +`OVERLAY DETAILS` is where you'd set up the attributes of an overlay. + +There are a number of examples of overlays [here](./overlays.md).