Tautulli Integration

Background

If Plex is globally enabled, the Maker 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 (usually every 12 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. This is done by using Tautulli's ability to execute a custom script after an episode has been watched.

Setup

The Maker cannot set up this Tautulli integration for you, as setting up the custom notification agent must be done within the web interface. The 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. 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.

---

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

   Image

   

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.

7. Select the Script File as the file we created, update_card.sh

8. Enter some script timeout - I'd recommend between 30-120 seconds

9. Optionally enter some description like Update TitleCardMaker.

   Image

   

10. Go to the Triggers tab and toggle the Watched checkbox.

    Image

    

11. Go to the Conditions tab and add two conditions (replacing YOUR USERNAME with your actual username):

    Condition	Operator	Value
    Username	is	YOUR USERNAME
    Media Type	is	episode

    Image

    

    This ensures the script is only run when you watch an episode of TV (not anyone watching anything).

12. Go to the Arguments tab, expand Watched and in the text box enter the following:

    {rating_key}

    Image

    

13. Select Save to exit the Notification Agent setup.

14. 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

---