Skip to content

Emby

Jump to bottom
Collin Heist edited this page Mar 16, 2023 · 8 revisions

Background

This is an optional YAML section of your global preferences file (preferences.yml) for outlining how the Maker should interact with an instance of Emby. Cards are created and can be placed alongside media files, but if properly setup, this allows the Maker to directly load the title cards within Emby.

Emby can also be used to determine an episode's watched status and modify a title card based on it.

Complete Example

# preferences.yml
emby:
  url: http://192.168.0.1:8096/
  api_key: e25b06a1aee34fc0949c35d74f379d03
  username: CollinHeist
  verify_ssl: true
  watched_style: unique
  unwatched_style: blur
  filesize_limit: 4 MB
  sync:
  - file: ./yaml/emby_sync.yml
    mode: append
    compact_mode: true
    add_template: my_template
    libraries:
    - TV Shows
    - Anime
    exclusions:
    - series: Pokémon (1997)
    - yaml: ./yaml/ignore.yml

options:     # Global options ...
archive:     # Archive options ...
plex:        # Plex options ...
jellyfin:    # Jellyfin options ...
sonarr:      # Sonarr options ...
tautulli:    # Tautulli options ...
tmdb:        # TMDb options ...
imagemagick: # Imagemagick options ...

Attributes

Name YAML Attribute Allowed Values Default Value Required
Emby URL url A valid Emby URL - ✅
Emby API Key api_key A valid Emby API Key - ✅
Emby Username username Username - ✅
Verify SSL verify_ssl Boolean (true or false) true ❌
Watched Style watched_style A valid style unique ❌
Unwatched Style unwatched_style A valid style unique ❌
Filesize Limit filesize_limit Any valid file size - ❌
YAML Syncing sync A sync configuration - ❌

Emby URL

URL of Emby to send API requests to, should include the port number (likely 8096).

Emby API Key

Emby requires an API key in order to validate requests from external services. This is required for TCM to function.

Finding the API Key

  1. Navigate to the Emby web interface, and click the Gear icon in the top right corner

  2. In the left sidebar, scroll to the bottom and select Api Keys

  3. Create a new API key

  4. Give a descriptive name (like TitleCardMaker) and then hit Ok

  5. Copy the created API key into your preferences file

Emby Username

A valid username is required for TCM to query Emby for a user's watch history, even if a non-default style is not being used. This username is only used to query an episode's watch status - loaded assets apply for all users (i.e. title cards are visible to all users).

Verify SSL

By default, TCM will attempt to verify the security of the API requests made to Emby. However, for some users running TCM or Emby on machines without valid SSL certificates, this can result in communication failures. Disabling this setting can prevent those errors.

Disabling SSL verification does have marginal security risks, but given that TCM will likely be communicating with Emby internally (local to your network), the real risk is quite low.

Styles

Watched Style

Style of cards to create for all watched episodes. Defaults to unique.

Unwatched Style

Style of cards to create for all unwatched episodes. If an episode's watch status cannot be determined, then the episode is assumed to be unwatched, and this style is used. Defaults to unique.

Background

The Maker can use the watched status of an episode within Emby to determine whether to modify the source image of the card (by applying a "style" to it) or not. The default style of unique is to use a unique, unmodified, image for each episode. These settings can each be changed globally (here), or per-series.

The style can be any combination of the modifiers unique, art, blur, and grayscale - except unique and art cannot be combined. The order of the style does not matter (i.e. art blur is identical to blur art). A brief description of each possible modifier is listed below:

Style Description Example
art Use generic series backdrop art1 for all episodes
blur Apply a blurred effect to each image
grayscale Apply a grayscale (black & white) effect to each image
unique Use an unmodified unique image for each episode

1 Backdrop art will attempt to be downloaded from TMDb, but any file located at backdrop.jpg in the local source directory can be used.

These styles can be combined to compound their effects. For example, specifying a style of blur grayscale will apply a blurring and grayscale effect to the source image. A showcase of all valid styles is shown below:

All Valid Styles
Style Example
art
art blur
art grayscale
art blur grayscale
blur
blur grayscale
blur unique Same as blur
blur grayscale unique Same as blur grayscale
grayscale
grayscale unique Same as grayscale
unique

Changing the Watched Status

Every time the Maker is run, it checks the "spoil status" of the last-loaded card to see if it needs to be updated. This means that if a spoiler-free card was loaded and then the episode was watched within Emby, the next time the Maker runs it will delete and remake the title card in a spoiler variant (unless art_all or blur_all is the specified unwatched action).

The Maker will also check the type of spoiler-free card that's been loaded, so using blur and then switching to art will initiate a recreation of all the previously blurred cards.

Filesize Limit

NOTE: Unlike Plex, Emby does not enforce any hard limit on the file size of a single asset, and so this setting is disabled by default.

Limit on the file size of assets uploaded to Emby. This applies to both title cards and season posters - and will reduce the size of your Emby metadata. This should be specified as {digit} {unit} - e.g. 10 MB, 5000 KiB, etc. The acceptable units are: B, KB, KiB, MB, MiB, GB, GiB, TB, and TiB.

When specified, the card will be created and stored in the original quality - even if it exceeds this file size limit. However, when the file is being uploaded to Emby, it will be incrementally compressed until below this limit. If a file cannot be compressed below the limit, it will be logged and skipped.

YAML Sync

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

This functionality is detailed here.

Clone this wiki locally