Skip to content

YAML Sync

Jump to bottom
Collin Heist edited this page Sep 25, 2022 · 48 revisions

Background

The TitleCardMaker can automatically create/update series YAML files so that cards can be created for series within Sonarr or Plex automatically, without the need to add all your series manually. This behavior is disabled by default.

NOTE: It can be useful to just run the sync functionality of TCM while you first set it up. To do this without starting the main TCM loop, use --sync in your main.py command - this is described here.

Complete Example

Syncing can be specified for both Plex and Sonarr, with the only differences being speed (Plex being much slower than Sonarr), and that Sonarr has more flexibility for syncing/excluding by tag. The basic functionality is otherwise identical, and both can even be set up at once.

NOTE: This is an example and will need to be changed to work with your setup. Please read about each option, below.

Plex

 
plex:
  url: # YOUR URL
  sync:
  - mode: append
    compact_mode: true
    volumes: 
      /plex/media/: /maker/media/
    exclusions:
    - series: Pokémon (1997)
    - yam: ./yaml/ignore.yml

  - file: ./yaml/plex_sync_anime.yml
    add_template: anime_template
    libraries:
    - Anime
    
  - file: ./yaml/plex_sync_tv.yml
    add_template: tv_template
    libraries:
    - TV

Sonarr

 
sonarr:
  url: http://192.168.0.1:8989/
  api_key: abcdef01234567890
  sync:
  - mode: append
    compact_mode: true
    downloaded_only: true
    monitored_only: true
    plex_libraries:
      /maker/media/tv: TV
      /maker/media/anime: anime
    volumes:
      /sonarr/media/tv: /maker/media/tv
    exclusions:
    - series: Pokémon (1997)
    - tag: widescreen-shows
    - yaml: ./yaml/ignore.yml
  
  - file: ./yaml/sonarr_sync_anime.yml
    required_tags:
    - anime
    - ongoing
    add_template: anime_template

  - file: ./yaml/sonarr_sync_tv.yml
    required_tags:
    - tv
    - ongoing
    add_template: tv_template

Syncing Multiple Files

Multiple series YAML files can be synced at once. To enable this, the sync must be specified as a list. If done, the item specified will apply to all subsequent syncs. This is implemented to avoid having to repeatedly specify anything.

See the example for more details.

Example

 
sync:
- sync_mode: append
  volumes:
    /docker/tv/: /tcm/tv/

- file: ./yaml/sync_file_1.yaml
  add_template: template_1

- file: ./yaml/sync_file_2.yaml
  exclusions:
  - series: Breaking Bad (2008)
  sync_mode: sync

The first item in the list defines sync_mode and volumes, but will not result in any sync because there is no file specification. However, because it is the first element, these will be carried over into the two following syncs. The third element in the list showcases how these "carried-over" attributes can be overwritten with the sync_mode being set to sync.

Attributes

Name YAML Attribute Allowed Values Default Value Applicable Interfaces Required
YAML File file Any valid filepath - plex and sonarr ❌1
Sync Mode mode Either append or match append plex and sonarr ❌
Compact Mode compact_mode Boolean (true or false) true plex and sonarr ❌
Template add_template Any template name (string) - plex and sonarr ❌
Filter Downloaded Only downloaded_only Boolean (true or false) false sonarr ❌
Filter Monitored Only monitored_only Boolean (true or false) false sonarr ❌
Required Tags required_tags A list of any tags - sonarr ❌
Filter Libraries libraries A list of any library names - plex ❌
Docker Volumes volumes Any Plex directories corresponding to TitleCardMaker directories - plex and sonarr ❌
Plex Libraries plex_libraries Any directories corresponding to library names - sonarr ❌
Exclusions exclusions A list of any excluded entries - plex and sonarr ❌

1A file must be specified in order to actually make TCM sync anything, but if omitted no error will be thrown.

Each of these options is explained in greater detail below.

YAML File

The filepath that the Maker should create/modify with series YAML.

Specifying a file here does not mean that the Maker will create title cards for it - the file must also be listed as a YAML file in the global options.

Sync Mode

The mode in which the Maker should write/update the specified YAML file. append mode will look at the file and skip and not modify any series/libraries that are already defined; while match mode will also remove series that are not present in the synced interface/filter (see below for details).

For example, if syncing to Plex and match mode is indicated, if a series is deleted from Plex, the entry in the synced file will also be removed. The same will happen if syncing to Sonarr, and a series is removed from Sonarr, untagged, or otherwise changed to no longer be in the sync.

Compact Mode

Whether the Maker should write the series YAML in "compact" mode or not. This is entirely an aesthetic option, but can make scrolling through very long files (if you have a lot of series being synced) much easier.

Example

If compact_mode: false is specified, the YAML file will be formatted like this:

libraries:
  TV:
    path: /media/TV
series:
  11.22.63 (2016):
    library: TV
  30 Rock (2006):
    library: TV
  American Vandal (2017):
    year: 2017
  Breaking Bad (2008):
    library: TV
  # ...

If compact_mode: true is specified, these same series would be written as:

libraries:
  TV:
    path: /media/TV
series:
  11.22.63 (2016): {library: TV}
  30 Rock (2006): {library: TV}
  American Vandal (2017): {library: TV}
  Breaking Bad (2008): {library: TV}
  # ...

Template

Optional template name to add to all synced files. This does not define or pass any arguments to the template, just specifies its name for the series. See the example for more details.

Should likely be used in append mode, so you can edit the synced file to add the template definition.

Example

The following example specifies my_template for each synced, series:

sonarr: 
  url: ...
  api_key: ...
  sync:
    file: ./yml/plex_sync.yml
    add_template: my_template

Which, would result in ./yml/plex_sync.yml (hypothetically) looking like:

templates: # CREATED BY ME, NOT THE SYNC
  my_template:
    card_type: roman
    archive: false
series:
  11.22.63 (2016): {library: TV, template: my_template}
  30 Rock (2006): {library: TV, template: my_template}
  American Vandal (2017): {library: TV, template: my_template}
  Breaking Bad (2008): {library: TV, template: my_template}
  # ...

Where the definition of my_template was added manually by me.

Filter Downloaded Only

NOTE: This is only applicable to sonarr syncs

Whether to only sync series that have any downloaded episodes within Sonarr. If enabled, series with no episodes will be rejected.

Filter Monitored Only

NOTE: This is only applicable to sonarr syncs

Whether to only sync series that are Monitored within Sonarr. If enabled, unmonitored series will be rejected.

Required Tags

NOTE: This is only applicable to sonarr syncs

List of tags to filter the synced series by. If specified, only series that have all of the provided tags will be synced. This must be specified as a list, like so:

required_tags:
- tag1
- tag2
Example

The following example will only sync series to the specified file that are tagged with both dolby-vision and ongoing will be written:

sonarr:
  url: ...
  api_key: ...
  sync:
    file: ./yaml/sonarr_sync.yml
    required_tags:
    - dolby-vision
    - ongoing

Filter Libraries

NOTE: This is only applicable to plex syncs

Libraries within Plex to filter the synced series by. If specified, only series that are within any of the listed libraries will be synced. Otherwise, all series from all TV libraries will be synced.

Docker Volumes

If your instances of Plex/Sonarr are running in a Docker container, the reported media paths might not match TitleCardMaker. To accommodate this, you can define the volumes you've mounted to the containers and the Maker will substitute these paths to their Maker-equivalents. These should be specified as plex_path: tcm_path or sonarr_path: tcm_path, see the example for details.

Windows users should specify their filepaths with forward-slashes, e.g. C:\\Users\Documents\ should be written as C:/Users/Documents.

Example

If I have mounted /documents/Media/ on my machine to /media/ within the Plex docker container, and have then mounted /documents/Media/ to /libraries/media/ within the TitleCardMaker docker container, then the following would be a suitable volume specification:

sonarr:
  url: ...
  api_key: ...
  sync:
    file: ./yaml/sonarr_sync.yml
    volumes:
      /documents/Media/: /libraries/Media/

Plex Libraries

NOTE: This is only applicable to sonarr syncs

If you've grouped your libraries by subfolder, this section can define what paths within TCM should be assigned to which libraries. This needs to be specified as {path}: {library name}. This setting can be confusing if both Sonarr and TitleCardMaker are in Docker containers, see the example 2 for details.

These paths should be specified after any replacements done by specifying any docker volumes.

Example 1

If Sonarr puts my TV library at /media/TV/, and Anime library at /media/Anime/, then I want to define those two libraries here, like so:

sonarr:
  url: ...
  api_key: ...
  sync:
    file: ./yaml/sonarr_sync.yml
    plex_libraries:
      /media/TV/: TV
      /media/Anime/: Anime

This means when Sonarr reports to TCM that a given series, such as Breaking Bad, is located at /media/TV/Breaking Bad (2008)/ then TCM will be able to assign this series to the TV library automatically.

Example 2

If Sonarr is in a Docker container and puts Media for the TV library at /sonarr/media/TV/ and the Anime library at /sonarr/media/Anime/, and I've mounted these paths at /maker/media/TV and /maker/media/Anime in my TitleCardMaker container, then my volumes and plex_libraries specification should look like this:

sonarr:
  url: ...
  api_key: ...
  sync:
    file: ./yaml/sonarr_sync.yml
    volumes:
      /sonarr/media/: /maker/media/
    plex_libraries:
      /maker/media/TV/: TV
      /maker/media/Anime/: Anime

This means that Sonarr reports a path like /sonarr/media/TV/Breaking Bad (2008)/ to TCM. TCM then converts the /sonarr/media/ portion of that path to with /maker/media/, becoming /maker/media/TV/Breaking Bad (2008)/. Finally, TCM looks at the specified libraries and matches /maker/media/TV/ to the TV library, meaning this series will be assigned to the TV library.

Exclusions

A list of exclusions to not sync to the specified file. This can be useful if there are series you either don't want cards for, or have custom cards specified in another file.

There are two types of exclusions applicable to Plex, both are listed below:

Exclusion Name Description Example
series Full name of a series series: Breaking Bad (2008)
tag Sonarr tag1 tag: ignore_tag
yaml Series YAML file to exclude all entries of2 yaml: ./path/to/yaml_file.yml

1This is only applicable when specified for within a sonarr sync.

2This can be useful if you have many series to exclude, or you have a YAML file of customized cards that you don't want the sync to override. All entries in the given file's series will be ignored.

This must be given as a list, like so:

exclusions:
- series: ...
- tag: ...
- yaml: ...
Example of an excluded YAML file

If there are a lot of series you want to exclude - the most efficient way to do this is to create an excluded YAML file, and add it to your sync. An example of how this file might looks is:

series:
  Beastars (2019): {}
  Dark (2017): {}
  The Lord of the Rings: The Rings of Power (2022): {}
  # etc.

Each 'entry' in the file must be under the series key (like a normal series YAML file), but there is no need to specify any actual "content" (e.g. custom fonts, card types, etc.) as TCM will just look at the name of the series.

Clone this wiki locally