Tautulli Integration - CollinHeist/TitleCardMaker GitHub Wiki

Background

This is an optional YAML section for outlining how the Maker should set up Tautulli integration for you. This does not actually activate Tautulli integration, which needs to be done by specifying the --tautulli-list and --tautulli-frequency arguments (or their docker equivalents). The specifics of this integration is described below.

If Plex is globally enabled, TCM can monitor an episode's watched status (i.e. watched/unwatched) and modify its card accordingly (such as blurring/un-blurring). Enabling this functionality is detailed here. Normally, the process of replacing a card only happens every time the Maker is run, which most users will not schedule very frequently (on the order of hours).

To address this, the Maker can integrate with Tautulli and bypass the normal (long) run process to specifically remake cards almost immediately after an episode has been watched, or new episodes have been added. This is done by using Tautulli's ability to execute a custom script after custom conditions are met.

Complete Example

# preferences.yml
tautulli:
  url: http://192.168.0.1:8181/          # Your Tautulli URL
  api_key: abcdef0123456789              # Your API key
  update_script: /config/update_card.sh
  verify_ssl: true
  username: CollinHeist
  agent_name: Update TitleCardMaker      # Your Username
  script_timeout: 120 

options:     # Global options ....
archive:     # Archive options ...
plex:        # Plex options ...
sonarr:      # Sonarr options ...
imagemagick: # Imagemagick options ...

Attributes

Name YAML Attribute Allowed Values Default Value Required
Tautulli URL url A valid Tautulli API URL - ✅
Tautulli API Key api_key A valid Tautulli API key - ✅
Update Script update_script Tautulli path to the update script - ✅
Verify SSL verify_ssl Boolean (true or false) true ❌
Username username Any string - ❌
Agent Name agent_name Any string Update TitleCardmaker ❌
Script Timeout script_timeout Any integer 30 ❌

Tautulli URL

URL to communicate with Tautulli.

Tautulli API Key

Tautulli requires an API key to validate external requests. This can be accessed via Settings > Web Interface > API Key (at the very bottom).

While you're here, ensure you have enabled the Tautulli API. This must be checked.

Update Script

Path to the script update script created in Step 1 of the setup process. You can specify either the full path to the script - e.g. /config/update_card.sh; or, if the file is named update_card.sh, the directory containing the script - e.g. /config/.

If Tautulli is in a Docker container, this must be the path within the Tautulli container.

This script file should look like this:

#!/bin/sh
echo "$@" >> update.txt

Verify SSL

By default, TCM will attempt to verify the security of the API requests made to Tautulli. However, for some users running TCM or Tautulli on machines without valid SSL certificates, this can result in Tautulli 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 Tautulli internally (local to your network), the real risk is quite low.

Username

Optional username to add as a condition in the script's execution. If you are the only one using your Plex server, you can omit this option. Otherwise, it's best to set your Plex/Tautulli username here.

If provided, an additional condition will be configured within the Notification Agent that only triggers the script when you are watching TV.

Agent Name

"Friendly" name of the Notification Agents to configure (this will appear in the GUI). Defaults to Update TitleCardMaker, which will create two agents called Update TitleCardMaker - Watched and Update TitleCardMaker - Recently Added.

When first run, TCM searched for agents starting with this name in order to detect whether integration has already been set up.

Script Timeout

The number of seconds to wait before Tautulli will terminate TitleCardMaker. Defaults to 30, 0 (or any negative number) will disable the timeout altogether.

Setup

The Maker can set up this integration for you, but setting up the custom notification agent can also be done within the web interface. However, even if setting up automatically, you must complete Step 1. The manual process is quite simple, and detailed below.

NOTE: The process of installing and setting up Tautulli is not covered here. But it is fairly easily, especially compared to some other Plex-integration apps.

Step 1. Adding the Script

Because most users have Tautulli (and TitleCardMaker) running in Docker containers, it is not feasible to have the Maker and Tautulli directly communicate with eachother. To circumvent this, the two containers "communicate" only through a shared file. Adding this is step 1.

  1. Navigate to the configuration directory for your instance of Tautulli. This might be /Documents/Tautulli/config, or /mnt/user/appdata/tautulli/ on Unraid. The specific directory isn't important, but it must be accessible within both your Tautulli docker container, and your host computer (if it is running in Docker).

  2. If you are on Windows, skip to step 4. For Docker/Linux/Mac users: within the configuration directory from 1.1, create a file called update_card.sh and put the following text:

    #!/bin/sh
echo "$@" >> update.txt

    The technical details of this file aren't relevant, but it basically writes whatever text we send to the file from Tautulli to a local file update.txt.

  3. If you're on Linux/MacOS, make sure the created file is executable by executing chmod +x ./update_card.sh from the command line/terminal.

  4. For Windows users only: Within the configuration directory from 1.1, create a file called update_card.cmd and put the following text:

    echo "$@" >> update.txt

    The technical details of this file aren't relevant, but it basically writes whatever text we send to the file from Tautulli to a local file update.txt.

NOTE: Step 1 is the only required step if you are having TitleCardMaker set up Tautulli for you. See here for ensuring Tautulli's API is enabled.

Step 2. Setting up Tautulli

We now need to tell Tautulli to execute the above script whenever an episode has been watched.

  1. Navigate to your Tautulli web UI (probably some URL like http://196.168.x.xx:8181/home).

  2. In the top right corner, click the Gear icons and then enter the Settings menu.

    image

  3. From the sidebar, select Notification Agents

  4. Select Add a new Notification Agent

    image

  5. Scroll down to and click Script

    image

  6. On the Configuration tab, select the Script Folder from the dropdown menu and navigate to the folder where the file from Step 1 is located

  7. Select the Script File as the file we created, update_card.sh (update_card.cmd for Windows users)

  8. Enter some script timeout - I'd recommend between 2-10 seconds. This is just the timeout for Tautulli executing the above script, not for TCM to create the cards.

  9. Optionally enter some description like Update TitleCardMaker

    image

  10. Go to the Triggers tab

  11. Toggle the Watched checkbox

    image

  12. Go to the Conditions tab

  13. Add the following two conditions (replacing YOUR USERNAME with your actual username) - this ensures the script is only run when you watch an episode of TV:

    Condition Operator Value
    Username is YOUR USERNAME
    Media Type is episode
    image

  14. Go to the Arguments tab

  15. Expand Watched and in the text box enter the following:

    {rating_key}
    image

  16. Select Save to exit the Notification Agent setup.

  17. Repeat steps 4-16, with the following changes:

  • On Step 11, select the trigger of Recently Added instead of Watched
  • On Step 12, only enter the condition Media Type is show or season or episode
  • On Step 15, enter {rating_key} in the Recently Added text box instead of the Watched text box

  1. Finally, Plex reports episodes as "watched" when 90% of their runtime has been viewed, so Tautulli needs to be configured to match this as well. Go to General on the sidebar, then TV Episode Watched Percent and enter 90 (the other settings don't matter).

    image

Step 3. Integrating with TitleCardMaker

Now that Tautulli will write the rating key (think of this as a unique number the Maker can use to identify which episode you just watched) to the file (update.txt) every time you watch an episode of TV, the only remaining part is to tell the Maker what file to look at, and how often.

Docker

  1. You need to make sure the file we created in Step 1 is accessible within the TitleCardMaker container. This means passing the volume into the container. For example, if I created update_card.sh at /mnt/user/appdata/tautulli/update_card.sh, then I need to ensure that /mnt/user/appdata/tautulli/ is passed into the container, let's choose to mount this at /tautulli.

  2. Now we want to define the environment variables TCM_TAUTULLI_UPDATE_LIST and (optionally) TCM_TAUTULLI_UPDATE_FREQUENCY in our Docker container so the Maker knows what file to look at. In my example, this is -e TCM_TAUTULLI_UPDATE_LIST="/tautulli/update.txt" since the script update_card.sh writes to update.txt in that same directory.

  3. Launch the updated TitleCardMaker container. This command might look like:

    $ docker run -dit --name TitleCardMaker \
{...} \
-v "/mnt/user/appdata/tautulli/":"/tautulli/" \
-e TCM_TAUTULLI_UPDATE_LIST="/tautulli/update.txt" \
-e TCM_TAUTULLI_UPDATE_FREQUENCY="4m" \
collinheist/titlecardmaker:master

    Where {...} is the rest of your normal Docker configuration.

Non-Docker

  1. Identify the full path to the update_card.sh file we created in Step 1. For example, if my update_card.sh was at /Documents/tautulli/update_card.sh, then the update file would be /Documents/tautulli/update.txt.

  2. Identify how often you want the Maker to check this file - the more frequent, the faster cards will be remade but the more processing power is spent checking the file (although minor). For this example, I'll check the file every minute (1m).

  3. Specify this filepath and frequency as arguments to main.py run command. In my example, this looks like:

    $ pipenv run python main.py --run \
--tautulli-update-list "/Documents/tautulli/update.txt" \
--tautulli-update-frequency 1m
⚠️ **GitHub.com Fallback** ⚠️