-
-
Notifications
You must be signed in to change notification settings - Fork 23
Tautulli Integration
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.
# 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 ...
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 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.
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
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.
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.
"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.
The number of seconds to wait before Tautulli will terminate TitleCardMaker. Defaults to 30
, 0
(or any negative number) will disable the timeout altogether.
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.
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.
-
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). -
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
. -
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. -
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.
We now need to tell Tautulli to execute the above script whenever an episode has been watched.
-
Navigate to your Tautulli web UI (probably some URL like
http://196.168.x.xx:8181/home
). -
In the top right corner, click the Gear icons and then enter the Settings menu.
-
From the sidebar, select
Notification Agents
-
Select
Add a new Notification Agent
-
Scroll down to and click
Script
-
On the
Configuration
tab, select theScript Folder
from the dropdown menu and navigate to the folder where the file from Step 1 is located -
Select the
Script File
as the file we created,update_card.sh
(update_card.cmd
for Windows users) -
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.
-
Optionally enter some description like
Update TitleCardMaker
-
Go to the
Triggers
tab -
Toggle the
Watched
checkbox -
Go to the
Conditions
tab -
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
-
Go to the
Arguments
tab -
Expand
Watched
and in the text box enter the following:{rating_key}
-
Select
Save
to exit the Notification Agent setup. -
Repeat steps 4-16, with the following changes:
- On Step 11, select the trigger of
Recently Added
instead ofWatched
- On Step 12, only enter the condition
Media Type
is
show
orseason
orepisode
- On Step 15, enter
{rating_key}
in theRecently Added
text box instead of theWatched
text box
-
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, thenTV Episode Watched Percent
and enter90
(the other settings don't matter).
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.
-
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
. -
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 scriptupdate_card.sh
writes toupdate.txt
in that same directory. -
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.
-
Identify the full path to the
update_card.sh
file we created in Step 1. For example, if myupdate_card.sh
was at/Documents/tautulli/update_card.sh
, then the update file would be/Documents/tautulli/update.txt
. -
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
). -
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