Mirrors/Plex-Meta-Manager
2
0
Fork 0
mirror of https://github.com/meisnate12/Plex-Meta-Manager synced 2024-11-21 20:13:05 +00:00
Code Issues Projects Releases Packages Wiki Activity

Add info on creating files

Browse source
This commit is contained in:
Chaz Larson 2024-11-04 17:16:07 -06:00
parent 4fe23ef787
commit 2d84df1444
3 changed files with 381 additions and 107 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
docs/config/images/VSCode.gif Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 13 MiB

87
docs/config/overview.md
View file

@ -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)

393
docs/files/overview.md
View file

@ -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.
???+ example "Builder Example"
=== "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.
```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:
any:
genre: Action
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
```
### Filters
That will create a collection of the movies on that particular MDB list
[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.**
=== "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:
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 are again common to all types of definitions.
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:
plex_all: true
filters:
tmdb_keyword: aftercreditsstinger, duringcreditsstinger
1981 by search:
plex_search:
all:
year: 1981
```
### Settings
When run against a Plex library of 8842 items, produced a collection containing 46 items, and took 3 seconds:
[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.
???+ example "Setting Example"
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).
```
|==========================================================================================|
| Finished 1981 by search Collection |
| Collection Run Time: 0:00:03 |
|==========================================================================================|
```
=== "Movies from 1981 created by `plex_all` and `filters`"
While this:
```yaml
collections:
My Test Collection 1:
sync_mode: sync
1981 by filter:
plex_all: true
filters:
year: 1981
```
When run against the same Plex library of 8842 items, produced the same collection containing the same 46 items, and took over 5 minutes:
```
|==========================================================================================|
| Finished 1981 by filter Collection |
| Collection Run Time: 0:05:30 |
|==========================================================================================|
```
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.
Examples:
=== "Filtering on TMDB votes"
```yaml
collections:
Romance Movies that TMDB members liked:
plex_search:
all:
genre: Romance
filters:
tmdb_vote_count.gte: 1000
tmdb_vote_average.gte: 7.5
```
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.
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.
=== "Filtering on TVDB status"
```yaml
collections:
All cancelled shows:
plex_all: true
filters:
tvdb_status: ended
```
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:
Romance Movies:
plex_search:
all:
genre: Romance
url_poster: https://theposterdb.com/api/assets/213090
```
Adds a poster to the collection, using one of the attributes [here](./updates.md).
=== "Change collection sort order"
```yaml
collections:
Romance Movies:
plex_search:
all:
genre: Romance
collection_order: release.desc
```
Sorts the items in the collection by descending release date, using one of the attributes [here](./updates.md).
=== "Override global Radarr tag"
```yaml
collections:
Romance Movies:
plex_search:
all:
genre: Romance
radarr_tag: romance_tag
```
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).
=== "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
```
Sets a label on all items in Plex that are part of the IMDB Top 250, but doesn't build the collection.
Uses attributes from [here](./item_updates.md) and [here](./settings.md).
=== "Set a minumum collection size"
```yaml
collections:
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.
### Radarr/Sonarr Settings
`OVERLAY DETAILS` is where you'd set up the attributes of an overlay.
[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.
???+ example "Setting Example"
This sets the colleciton to add missing movies from the builders to Radarr.
```yaml
collections:
My Test Collection 1:
radarr_add_missing: true
imdb_search:
type: movie
limit: 100
genre: action
votes.gte: 1000
```
### Collection/Playlist Metadata Updates
[Updates](updates.md) are attributes placed at the top level of the definition that tells Kometa Metadata Changes for the
Collection/Playlist.
???+ example "Collection/Playlist Metadata Update Example"
```yaml
collections:
My Test Collection 1:
summary: This is my test collection's summary
plex_search:
any:
genre: Action
```
### Item Metadata Updates
[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.
???+ example "Item Metadata Update Example"
This will add the genre `Credits` to every item found after builders and filters are run.
```yaml
collections:
My Test Collection 1:
item_genre: Credits
plex_all: true
filters:
tmdb_keyword: aftercreditsstinger, duringcreditsstinger
```
There are a number of examples of overlays [here](./overlays.md).