Plex-Meta-Manager/docs/config/libraries.md
2024-01-18 19:04:03 -05:00

23 KiB

search
boost
5

Library Attributes

Within the Configuration File, the libraries attribute specifies the Plex libraries that the user wants Plex Meta Manager to act on.

Attributes are used to instruct Plex Meta Manager what actions to take, such as "load the following libraries" or "execute the following Collection Definition files". These attributes can be specified individually per library, or can be inherited from the global value if it has been set. If an attribute is specified at both the library and global level, then the library level attribute will take priority.

Attributes

The available attributes for each library are as follows:

??? blank "library_name - Used to specify the Library's name."

<div id="library-name" />*Required only when trying to use multiple servers with the same name.*

Each library that the user wants Plex Meta Manager to interact with must be documented with a library attribute. 

A library attribute is represented by the mapping name (i.e. `Movies` or `TV Shows`), this must have a unique name 
that correlates with a library of the same name within the Plex Media Server.

In the situation that two servers are being connected to which both have libraries of the same name, the 
`library_name` attribute can be utilized to specify the real Library Name, whilst the library attribute's mapping 
name can be made into a placeholder. This is showcased below:

<hr style="margin: 0px;">

**Attribute:** `library_name`

**Accepted Values:** Library Name

**Default Value:** Base Attribute Name

???+ example "Example"
    
    ```yaml
    libraries:
      Movies01:
        library_name: Movies
      Movies02:
        library_name: Movies
        plex:
          url: http://192.168.1.35:32400
          token: ####################
      TV Shows:
      Anime:
    plex:
      url: http://192.168.1.12:32400
      token: ####################
    ```
    
    * In this example, `"Movies01"`, `"TV Shows"`, and `"Anime"` will all use the global plex server 
    (**http://192.168.1.12:32400**) which is defined using the global `plex` mapping. `"Movies02"` will use the plex
    server **http://192.168.1.35:32400** which is defined under its `plex` mapping over the global mapping.

??? blank "collection_files - Used to define Collection Files."

<div id="collection-files" />The `collection_files` attribute is used to define 
[Collection Files](../files/collections.md) by specifying the path type and path of the files that will be executed 
against the parent library. See [File Blocks](files.md) for how to define them.

<hr style="margin: 0px;">

**Attribute:** `collection_files`

**Accepted Values:** Location of Collection YAML files.

**Default Value:** `/config/<<MAPPING_NAME>>.yml`

???+ example "Example"
    
    ```yaml
    libraries:
      TV Shows:
        collection_files:
          - file: config/TV Shows.yml
          - pmm: tmdb
          - pmm: network
    ```

    By default, when `collection_files` is missing Plex Meta Manager will look within the root PMM directory for a 
    collection file called `<MAPPING_NAME>.yml`. In this example, Plex Meta Manager will look for a file named 
    `TV Shows.yml`.
    
    ```yaml
    libraries:
      TV Shows:
    ```

??? blank "metadata_files - Used to define Metadata Files."

<div id="metadata-files" />The `metadata_files` attribute is used to define Metadata Files by specifying the path of
the files that will be executed against the parent library. See [File Blocks](files.md) for how to define them.

???+ tip

    As of Plex Meta Manager 1.20.0 "Metadata Files" refers to YAML files which refers to managing the metadata of 
    items [movies, shows, music] within your library, and "Collection Files" refers to YAML files which define 
    Collections.

    In previous version of Plex Meta Manager, "Metadata Files" could mean either of the above.

<hr style="margin: 0px;">

**Attribute:** `metadata_files`

**Accepted Values:** Location of [Metadata Files](../files/metadata.md)

**Default Value:** `None`

???+ example "Example"
    
    ```yaml
    libraries:
      TV Shows:
        metadata_files:
          - file: config/metadata.yml
    ```

??? blank "overlay_files - Used to define Overlay Files."

<div id="overlay-files" />The `overlay_files` attribute is used to define [Overlay Files](../files/overlays.md) by 
specifying the path type and path of the files that will be executed against the parent library. See 
[File Blocks](files.md) for how to define them.

<hr style="margin: 0px;">

**Attribute:** `overlay_files`

**Accepted Values:** Location of [Overlay Files](../files/overlays.md)

**Default Value:** `None`

???+ example "Example"
    
    ```yaml
    libraries:
      TV Shows:
        collection_files:
          - file: config/TV Shows.yml
        overlay_files:
          - file: config/Overlays.yml
    ```

??? blank "report_path - Location to save the YAML Report file for a library."

<div id="report-path" />The `report_path` attribute is used to define where to save the YAML Report file. This file 
is used to store information about what media is added, removed, filtered, and missing from the Plex library 
compared to what is expected from the Collection, Metadata, Overlay or Playlist file.

If your Collection file creates a collection with `Movie 1`, `Movie 2` and `Movie 3` but your Plex library only has 
`Movie 1` and `Movie 3`, then the missing YAML file will be updated to inform the user that `Movie 2` was missing 
from the library.

<hr style="margin: 0px;">

**Attribute:** `report_path`

**Accepted Values:** Location to save the YAML Report file

**Default Value:** `/config/<<MAPPING_NAME>>_report.yml` where `<<MAPPING_NAME>>` is the name of the library 
attribute

???+ example "Example"
    
    If you want to call your Report YAML something different you can like so:

    ```yaml
    libraries:
      Movies:
        report_path: /config/My Movie Report.yml
    ```
    
    Alternatively, Report YAML files can be placed in their own directory, as below:
    
    ```yaml
    libraries:
      Movies:
        report_path: /config/reports/Movies.yml
        collection_files:
          - file: config/Movies.yml
        overlay_files:
          - file: config/Overlays.yml
    ```

??? blank "template_variables - Used to define Custom Template Variables for every file in a library."

<div id="template-variables" />Passes all given [Template Variables](../files/templates.md#template-variables) to 
every template in every Collection, Metadata, and Overlay file run.

<hr style="margin: 0px;">

**Attribute:** `template_variables`

**Accepted Values:** [Dictionary](../pmm/yaml.md#dictionaries) of values specified by each particular file.

**Default Value:** `None`

???+ example "Example"
    
    ```yaml
    libraries:
      Movies:
        template_variables:
          collection_mode: hide_items
        collection_files:
          - file: config/Movies.yml
        overlay_files:
          - file: config/Overlays.yml
    ```

??? blank "schedule - Used to schedule when a library is run."

<div id="schedule" />Used to schedule when a library is run using the [schedule options](schedule.md).

<hr style="margin: 0px;">

**Attribute:** `schedule`

**Accepted Values:** Any [schedule option](schedule.md)

**Default Value:** `daily`

???+ example "Example"
    
    ```yaml
    libraries:
      TV Shows:
        schedule: weekly(sunday)
        collection_files:
          - file: config/TV Shows.yml
        overlay_files:
          - file: config/Overlays.yml
    ```

??? blank "operations - Used to specify Library Operations to run."

<div id="operations" />Used to specify [Library Operations](operations.md) to run.

<hr style="margin: 0px;">

**Attribute:** `operations`

**Accepted Values:** Any [Library Operation](operations.md)

**Default Value:** `None`

???+ example "Example"
    
    ```yaml
    libraries:
      Movies:
        collection_files:
          - pmm: imdb
        operations:
          mass_critic_rating_update: tmdb
          split_duplicates: true
    ```

??? blank "remove_overlays - Used to remove overlays."

<div id="remove-overlays" />Used to remove overlays from this library only.

???+ warning "Proceed with Caution"

    When set to `true`, this will remove all overlays from your library every run, but will not delete 
    the overlaid images from your system, resulting in [image bloat](../pmm/scripts/image-cleanup.md).

<hr style="margin: 0px;">

**Attribute:** `remove_overlays`

**Accepted Values:** `true` or `false`

**Default Value:** `false`

???+ example "Example"
    
    ```yaml
        libraries:
          Movies:
            remove_overlays: true
            collection_files:
              - file: config/Movies.yml
            overlay_files:
              - file: config/Overlays.yml
    ```

??? blank "reapply_overlays - Used to reapply overlays."

<div id="reapply-overlays" />Used to reapply overlays from this library only. This will reapply overlays to every item in your library.

???+ warning "Proceed with Caution"

    When set to `true`, this will reapply all overlays on each run even if there is no need to do so, which will result in 
    [image bloat](../pmm/scripts/image-cleanup.md).

<hr style="margin: 0px;">

**Attribute:** `reapply_overlays`

**Accepted Values:** `true` or `false`

**Default Value:** `false`

???+ example "Example"
    
    ```yaml
        libraries:
          Movies:
            reapply_overlays: true
            collection_files:
              - file: config/Movies.yml
            overlay_files:
              - file: config/Overlays.yml
    ```

??? blank "reset_overlays - Used to reset overlays."

<div id="reset-overlays" />Used to reset overlays from this library only. This will reset overlays to every item in 
your library to your source choice. This will use the reset image when overlaying items in your library.

???+ warning "Proceed with Caution"

    This will reset all posters to the desired source on each run and will reapply 
    all overlays on each run, which will result in [image bloat](../pmm/scripts/image-cleanup.md).

<hr style="margin: 0px;">

**Attribute:** `reset_overlays`

**Accepted Values:** `plex` or `tmdb`

**Default Value:** `None`

???+ example "Example"
    
    ```yaml
        libraries:
          Movies:
            reset_overlays: tmdb
            collection_files:
              - file: config/Movies.yml
            overlay_files:
              - file: config/Overlays.yml
    ```

??? blank "schedule_overlays - Used to schedule overlays."

<div id="schedule-overlays" />Used to schedule overlays to run when desired. Overlays are applied all at once in a 
batch therefore you cannot schedule individual Overlay Files, as any unscheduled overlay file will be removed each 
time PMM is run.

<hr style="margin: 0px;">

**Attribute:** `schedule_overlays`

**Accepted Values:** [Any Schedule Option](schedule.md)

**Default Value:** `daily`

???+ example "Example"

    ```yaml
    libraries:
      TV Shows:
        schedule_overlays: weekly(sunday)
        collection_files:
          - file: config/TV Shows.yml
        overlay_files:
          - file: config/Overlays.yml
    ```

??? blank "settings - Used to override global setting attributes for this library only."

<div id="settings" />Used to override global [`setting` attributes](settings.md) for this library only.

<hr style="margin: 0px;">

**Attribute:** `settings`

**Accepted Values:** Any [`setting`](settings.md) attribute that overrides a global value.

**Default Value:** Global Value

???+ example "Example"
    
    ```yaml
    libraries:
      Movies:
        collection_files:
          - pmm: imdb
        settings:
          asset_directory: config/asssets/Movies
    ```

??? blank "plex - Used to override global plex attributes for this library only."

<div id="plex" />Used to override global [`plex` attributes](plex.md) for this library only. 

**`plex` Attribute is required either here or globally**

<hr style="margin: 0px;">

**Attribute:** `plex`

**Accepted Values:** Any [`plex`](plex.md) attribute that overrides a global value.

**Default Value:** Global Value

???+ example "Example"
    
    ```yaml
    libraries:
      Movies:
        collection_files:
          - file: config/Movies.yml
      Movies_on_Second_Plex:
        library_name: Movies
        collection_files:
          - file: config/Movies.yml
        plex:
          url: http://plex.boing.bong
          token: SOME_TOKEN
          timeout: 360
          db_cache: 8192
    ...
    plex:
      url: http://plex.bing.bang
      token: SOME_TOKEN
      timeout: 60
      db_cache: 4096
      clean_bundles: false
      empty_trash: false
      optimize: false
    ...
    ```

??? blank "radarr - Used to override global radarr attributes for this library only."

<div id="radarr" />Used to override global [`radarr` attributes](radarr.md) for this library only.

<hr style="margin: 0px;">

**Attribute:** `radarr`

**Accepted Values:** Any [`radarr`](radarr.md) attribute that overrides a global value.

**Default Value:** Global Value

???+ example "Example"
    
    ```yaml
    libraries:
      Library01:     # this library uses the default radarr config
        collection_files:
          - file: config/Movies.yml
    
      Library02:     # this library overrides radarr root path and profile
        collection_files:
          - file: config/Movies.yml
        radarr:
          root_folder_path: /data/media/movies/tony
          quality_profile: Better
    
      Library03:      # this library overrides radarr quality profile
        collection_files:
          - file: config/Movies.yml
        radarr:
          quality_profile: Best
    
      Library04:      # this library uses the 4K radarr instance
        collection_files:
          - file: config/Movies.yml
        radarr:
          url: https://radarr-4k.bing.bang
          token: SOME_OTHER_TOKEN
          root_folder_path: /data/media/movies/geezer
          quality_profile: Bestest
    
      Library05:      # movies get added by a custom script so they should get added to radarr-4k
        collection_files:
          - file: config/Movies.yml
        radarr:
          url: https://radarr-4k.bing.bang
          token: SOME_OTHER_TOKEN
          root_folder_path: /data/media/movies/bill
          quality_profile: Bestest
          add_existing: true
          sonarr_path: /data/media/movies/bill
          plex_path: /mnt/unionfs/movies/bill
    ...
    radarr:
      url: https://radarr.bing.bang
      token: SOME_TOKEN
      quality_profile: Good
      add_missing: true
      add_existing: false
      upgrade_existing: false
      monitor_existing: false
      root_folder_path: /movies
      monitor: movie
      availability: released
      tag:
      search: false
      radarr_path:
      plex_path:
    ...
    ```

??? blank "sonarr - Used to override global sonarr attributes for this library only."

<div id="sonarr" />Used to override global [`sonarr` attributes](sonarr.md) for this library only.

<hr style="margin: 0px;">

**Attribute:** `sonarr`

**Accepted Values:** Any [`sonarr`](sonarr.md) attribute that overrides a global value.

**Default Value:** Global Value

???+ example "Example"
    
    ```yaml
    libraries:
      Library01:     # this library uses the default sonarr config
        collection_files:
          - file: config/TV.yml
    
      Library02:     # this library overrides sonarr root path and profile
        collection_files:
          - file: config/TV.yml
        sonarr:
          root_folder_path: /data/media/shows/tony
          quality_profile: Better
    
      Library03:      # this library overrides sonarr quality profile
        collection_files:
          - file: config/TV.yml
        sonarr:
          quality_profile: Best
    
      Library04:      # this library uses the 4K sonarr instance
        collection_files:
          - file: config/TV.yml
        sonarr:
          url: https://sonarr-4k.bing.bang
          token: SOME_OTHER_TOKEN
          root_folder_path: /data/media/shows/geezer
          quality_profile: Bestest
    
      Library05:      # shows get added by a custom script so they should get added to sonarr-4k
        collection_files:
          - file: config/TV.yml
        sonarr:
          url: https://sonarr-4k.bing.bang
          token: SOME_OTHER_TOKEN
          root_folder_path: /data/media/shows/bill
          quality_profile: Bestest
          add_existing: true
          sonarr_path: /data/media/shows/bill
          plex_path: /mnt/unionfs/shows/bill
    
    ...
    sonarr:
      url: https://sonarr.bing.bang
      token: SOME_TOKEN
      add_missing: false
      add_existing: false
      upgrade_existing: false
      monitor_existing: false
      root_folder_path: /data/media/shows/ozzy
      monitor: all
      quality_profile: Good
      language_profile: English
      series_type: standard
      season_folder: true
      tag:
      search: false
      cutoff_search: false
      sonarr_path:
      plex_path:
    ...
    ```

??? blank "tautulli - Used to override global tautulli attributes for this library only."

<div id="tautulli" />Used to override global [`tautulli` attributes](tautulli.md) for this library only.

<hr style="margin: 0px;">

**Attribute:** `tautulli`

**Accepted Values:** Any [`tautulli`](tautulli.md) attribute that overrides a global value.

**Default Value:** Global Value

???+ example "Example"
    
    ```yaml
        libraries:
          Movies:
            collection_files:
              - file: config/Movies.yml
          TV Shows:
            collection_files:
              - file: config/TV.yml
            tautulli:
              url: http://192.168.1.14:8659
              apikey: SOME_KEY
        ...
        tautulli:
          url: http://192.168.1.12:8659
          apikey: SOME_KEY
        ...
    ```

Example

This example is an advanced version of the library mappings which highlights some attributes being set at the global level, and some being set at the library level:

???+ example "Example Library Mappings"

In this example, the `"TV Shows On Second Plex"` library has a library-level `plex` configuration, which takes priority over the `plex` configuration set at the global level.

The `"Anime"` library also has a library-level `radarr` configuration, which takes priority over the `radarr` configuration set at the global level.

```yaml
libraries:
  Movies:
    collection_files:
      - file: config/Movies.yml
      - pmm: imdb
      - pmm: studio
      - pmm: genre
      - pmm: actor
    operations:
      mass_critic_rating_update: tmdb
      split_duplicates: true
  TV Shows:
    collection_files:
      - file: config/TV Shows.yml
      - pmm: tmdb
      - pmm: network
    remove_overlays: false
    overlay_files:
      - file: config/Overlays.yml
  TV Shows On Second Plex:
    library_name: TV Shows
    plex:
      url: http://192.168.1.98:32400
      token: ####################
    collection_files:
      - file: config/TV Shows.yml
      - pmm: tmdb
      - pmm: network
  Anime:
    collection_files:
      - file: config/Anime.yml
      - pmm: myanimelist
    radarr:
      url: http://192.168.1.45:7878
      token: ################################
      root_folder_path: S:/Anime
    settings:
      asset_directory: config/assets/anime
plex:
  url: http://192.168.1.12:32400
  token: ####################
radarr:
  url: http://192.168.1.12:7878
  token: ################################
  add: true
  root_folder_path: S:/Movies
  monitor: true
  availability: announced
  quality_profile: HD-1080p
  tag: pmm
  search: false
```