YAML Sync

Background

This is an optional subsection of the emby, jellyfin, plex, or sonarr sections of your global preferences file (preferences.yml). The TitleCardMaker can automatically create/update series YAML files so that cards can be created for series within Emby, Jellyfin, Plex, or Sonarr 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.

Recommended Setup

Syncing can be specified for Emby, Jellyfin, Plex, and/or Sonarr, with the only differences being speed (Emby, Jellyfin, and Plex being much slower than Sonarr), and that Sonarr has more flexibility for syncing/excluding series type. The basic functionality is otherwise identical, and all of them can even be set up at once.

Below are recommended setups that work for 99% of users if you change the paths and library names to match your setup.

Docker

Emby/Jellyfin

emby:       # or jellyfin
  url:      # YOUR URL
  api_key:  # YOUR API KEY
  username: # YOUR USERNAME
  sync:
  - card_directory: /config/cards
  - file: /config/sync_anime.yml
    libraries:
    - Anime
  - file: /config/sync_tv.yml
    libraries:
    - TV

Plex

plex:
  url:   # YOUR URL
  token: # YOUR TOKEN
  sync:
  - card_directory: /config/cards
  - file: /config/sync_anime.yml
    libraries:
    - Anime
  - file: /config/sync_tv.yml
    libraries:
    - TV

Sonarr

sonarr:
  url:     # YOUR URL
  api_key: # YOUR API KEY
  sync:
  - card_directory: /config/cards/
    downloaded_only: true
    monitored_only: true
    plex_libraries: # YOUR LIBRARY PATHS
      /media/tv: TV
      /media/anime: Anime
  - file: /config/sonarr_sync_anime.yml
    series_type: anime
  - file: /config/sonarr_sync_tv.yml
    series_type: standard

Non-Docker

NOTE: All paths shown below use the Unix-type pathing (e.g. forward slashes /) - this should work on Windows machines, but I strongly recommend Windows users use the Windows-type pathing (e.g. backslashes \).

Emby/Jellyfin

emby:       # or jellyfin
  url:      # YOUR URL
  api_key:  # YOUR API KEY
  username: # YOUR USERNAME
  sync:
  - card_directory: ./config/cards
  - file: ./config/sync_anime.yml
    libraries:
    - Anime
  - file: ./config/sync_tv.yml
    libraries:
    - TV

Plex

plex:
  url:   # YOUR URL
  token: # YOUR TOKEN
  sync:
  - card_directory: ./config/cards
  - file: ./config/sync_anime.yml
    libraries:
    - Anime
  - file: ./config/sync_tv.yml
    libraries:
    - TV

Sonarr

sonarr:
  url:     # YOUR URL
  api_key: # YOUR API KEY
  sync:
  - card_directory: ./config/cards/
    downloaded_only: true
    monitored_only: true
    plex_libraries: # YOUR LIBRARY PATHS
      /media/tv: TV
      /media/anime: Anime
  - file: ./config/sonarr_sync_anime.yml
    series_type: anime
  - file: ./config/sonarr_sync_tv.yml
    series_type: standard

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 first will apply to all subsequent syncs. This is implemented to avoid having to repeatedly specify anything.

See the example for more details.

Example

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)
  mode: sync

The first item in the list defines 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 mode being set to sync.

Attributes

NOTE: The Emby, Jellyfin, Plex, and Sonarr columns indicate whether that option can be specified for that interface. No options are required.

Name	YAML Attribute	Allowed Values	Default Value	Emby, Jellyfin, Plex	Sonarr
YAML File	`file`	Any valid file	-	✅	✅
Sync Mode	`mode`	Either `append` or `match`	`append`	✅	✅
Compact Mode	`compact_mode`	Boolean (`true` or `false`)	`true`	✅	✅
Card Directory	`card_directory`	Any valid path	-	✅	✅
Template	`add_template`	Any template name (string)	-	✅	✅
Filter Downloaded Only	`downloaded_only`	Boolean (`true` or `false`)	`false`	❌	✅
Filter Monitored Only	`monitored_only`	Boolean (`true` or `false`)	`false`	❌	✅
Required Tags	`required_tags`	A list of any tags	-	✅	✅
Filter Libraries	`libraries`	A list of any library names	-	✅	❌
Series Type	`series_type`	Either `anime`, `daily`, or `standard`	-	❌	✅
Docker Volumes	`volumes`	Any Plex directories corresponding to TitleCardMaker directories	-	✅	✅
Plex Libraries	`plex_libraries`	Any directories corresponding to library names	-	❌	✅
Exclusions	`exclusions`	A list of any excluded entries	-	✅	✅

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}
  # ...

Card Directory

Directory to put all title cards inside. This overrides any paths returned by the source, and is much easier if your folder structure is somewhat complicated.

TCM can still load the cards into your server as long as you have set up your library detection/assignment set up correctly. Storing the cards alongside the media is not required.

Template

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

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

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

These are the Emby, Jellyfin, or Sonarr tags, and the Sharing labels within Plex.

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 emby, jellyfin, and plex syncs

Libraries within Emby/Jellyfin/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.

Series Type

NOTE: This is only applicable to sonarr syncs

The series type to filter the sync by. If specified, only series that match this type will be synced. Otherwise, all series types will be synced. These are the same types assigned to a series within Sonarr, as shown below:

The only accepted values are anime, daily, and standard.

Docker Volumes

If your instances of Emby/Jellyfin/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 server_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 sub-folder, 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 Example 2 for details.

These paths should be specified before 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:
      /sonarr/media/TV/: TV
      /sonarr/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 /sonarr/media/TV/ to the TV library, meaning this series will be assigned to the TV library. It then writes the converted path into the sync file.

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. All series titles are excluded case insensitively.

There are three types of exclusions, all are listed below:

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

¹This 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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

YAML Sync

Background

Recommended Setup

Docker

Emby/Jellyfin

Plex

Sonarr

Non-Docker

Emby/Jellyfin

Plex

Sonarr

Syncing Multiple Files

Example

Attributes

YAML File

Sync Mode

Compact Mode

Card Directory

Template

Filter Downloaded Only

Filter Monitored Only

Required Tags

Filter Libraries

Series Type

Docker Volumes

Plex Libraries

Exclusions

Clone this wiki locally