Skip to content

Running the TitleCardMaker

Jump to bottom
Collin Heist edited this page Apr 5, 2024 · 30 revisions

Background

The Maker is run by executing main.py using Python. The most basic commands for this are:

pipenv install
pipenv run python main.py -r

The first command (pipenv install) installs all the required Python packages. The second command (pipenv run python main.py -r) runs the Maker.

NOTE: If using the Docker container, then just launching the container with the default entrypoint will run the Maker.

Docker Options

All the runtime options (except --no-color) can be specified/changed within the Docker container by specifying environment variables. The following table details which environment variables are used to specify each option:

Environment Variable Runtime Option Default Value
TCM_PREFERENCES --preferences /config/preferences.yml
TCM_RUNTIME --runtime -
TCM_FREQUENCY --frequency 12h
TCM_MISSING --missing /config/missing.yml
TCM_LOG --log INFO
TCM_TAUTULLI_UPDATE_LIST --tautulli-update-list -
TCM_TAUTULLI_UPDATE_FREQUENCY --tautulli-update-frequency -
PGID Group ID to use for all Maker-made files 100
PUID User ID to use for all Maker-made files 99
UMASK File mask to apply to all Maker-made files 002

All of these can be specified like -e {variable}={value} (with {} omitted) in the docker run command. For example, to specify the preference file to something other than /config/preferences.yml, I'd add the following to my docker command:

-e TCM_PREFERENCES="/yaml_files/preferences.yml"

Runtime Options

This file's -h or --help (help) menu is shown below:

Click to Expand 
pipenv run python3 main.py --help
usage: main.py [-h] [-p FILE] [-r] [-t HH:MM] [-f FREQUENCY[unit]] [-m FILE] [-l {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
               [-nc]

Start the TitleCardMaker

optional arguments:
  -h, --help            show this help message and exit
  -p FILE, --preferences FILE, --preference-file FILE
                        File to read global preferences from. Environment variable TCM_PREFERENCES. Defaults
                        to "/mnt/user/Media/TitleCardMaker/preferences.yml"
  -r, --run             Run the TitleCardMaker
  -s, --sync, --run-sync
                        Sync from Sonarr/Plex without running
  -t HH:MM, --runtime HH:MM, --time HH:MM
                        When to first run the TitleCardMaker (in 24-hour time). Environment variable
                        TCM_RUNTIME
  -f FREQUENCY[unit], --frequency FREQUENCY[unit]
                        How often to run the TitleCardMaker. Units can be s/m/h/d/w for
                        seconds/minutes/hours/days/weeks. Environment variable TCM_FREQUENCY. Defaults to
                        "12h"
  -m FILE, --missing FILE, --missing-file FILE
                        File to write the list of missing assets to. Environment variable TCM_MISSING.
                        Defaults to "/mnt/user/Media/TitleCardMaker/missing.yml"
  -l {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --log {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Level of logging verbosity to use. Environment variable TCM_LOG. Defaults to "INFO"
  -nc, --no-color       Omit color from all print messages
  -tl FILE, --tautulli-list FILE, --tautulli-update-list FILE
                        File to monitor for Tautulli-driven episode watch-status updates. Environment variable
                        TCM_TAUTULLI_UPDATE_LIST.
  -tf FREQUENCY, --tautulli-frequency FREQUENCY, --tautulli-update-frequency FREQUENCY
                        How often to check the Tautulli update list. Units can be s/m/h/d/w for
                        seconds/minutes/hours/days/weeks. Environment variable TCM_TAUTULLI_UPDATE_FREQUENCY.
                        Defaults to "4m"

-p, --preferences, --preference-file

Specify the global preference file for configuring the Maker. If unspecified, the Maker looks for a file called preferences.yml within the local execution directory1.

1 Unless using the Docker container, which looks at /config/preferences.yml

-r, --run

Whether to run the TitleCardMaker right away. This is required to actually have the Maker do anything, unless using the --time argument.

-s, --sync, --run-sync

Sync to any specified series YAML files without running the main TCM loop. This can be useful while you're setting up or debugging your sync setup.

-t, --time, --runtime

Schedule the Maker to run on a set interval, starting on this time. Should be specified in military/24-hour time - i.e. 17:30 would be 5:30 PM, 09:00 is 9:00 AM. If specified, the Maker will never exit on it's own (unless an error occurs).

-f, --frequency

On what interval to run the Maker. This should be specified as INTERVAL[unit], with the acceptable units being s, m, h, d, and w for seconds, minutes, hours, days, and weeks respectively. For example, providing --frequency 12h would run the Maker every 12 hours, --frequency 1d is once a day.

Must be used in conjunction with the above -t/--time/--runtime argument. If provided on its own, nothing will happen!

-m, --missing, --missing-file

File to write all missing assets to after the Maker has finished executing. If unspecified, the Maker writes to missing.yml within the local execution directory.

-l, --log

Minimum log level to use when executing the Maker. If unspecified, the Maker uses log level INFO. This must be one of DEBUG, INFO, WARNING, ERROR, or CRITICAL.

NOTE: This setting only adjusts the log level in the terminal/console, the Maker keeps a rolling scheduled log (up to 8 separate 6-hour log files) within the local logs directory of the Maker. This is always in DEBUG level.

Below are some examples of the types of messages printed at each log level.

DEBUG

The most verbose level of logging, this level is primarily intended to keep track of the major actions taken by the Maker. Examples of messages at this level are:

  • Generic translation detected for an episode title
  • Episode cannot be found on TMDb
  • TMDb has no images for a given episode
  • No images on TMDb meet the specified minimum resolution
  • Success or failure to create a title card or ShowSummary
    • Failure logs all the ImageMagick commands for the card, to aid in debugging
  • Episode title that is too long and might be poorly formatted for a given card type
  • Card has been deleted to update it's style
INFO

This level gives feedback on what the Maker is doing. Examples of messages at this level are:

  • New episodes being added to datafiles from Sonarr
  • Recommendation to add a TVDb episode ID to a given TMDb episode (this improves matching of the Maker)
  • Skipping ShowSummary creation because there are not enough episodes
  • Title translation added to a datafile
WARNING

This level logs potentially problematic behavior, and can be useful in identifying potential user errors. Examples of messages at this level are:

  • Characters missing from a font (if font validation is enabled)
  • Source file missing for genre cards
  • Missing data for template
  • Series cannot be found within Sonarr
  • Season titles specified via episode range, but episode has no absolute numbering or doesn't fall into a specified range
  • Episode text formatting specifies an absolute number, but episode does not have an absolute number
  • No series YAML files specified - i.e. no cards to make!
  • Series cannot be found within the given library within Plex
ERROR

This level logs all non-critical errors - i.e. errors that something went wrong, but the Maker is able to continue. Examples of messages at this level are:

  • Poorly formatted datafiles
  • Invalid series specification within a series YAML file
  • Series not found on TMDb
  • Invalid series within series YAML file
  • Specified library cannot be found within Plex
  • Cannot load card for Episode within Plex
CRITICAL

This level logs all critical errors - i.e. those that prevent the Maker from operating at all, and will lead to an immediate exit. Examples of messages at this level are:

  • Some error in the global preferences file
  • Failure to identify an ImageMagick installation
  • Poorly formatted YAML files that are "unreadable"
  • Sonarr cannot be queried (likely an invalid URL or API key)
  • Unauthorized Plex access (likely an invalid URL or X-Token)

-nc, --no-color

Whether to disable color printing for messages output by the Maker. This should be enabled if your terminal / command prompt does not support color output, and the print outs have text like [33;20m before print statements.

-tl, --tautulli-list, --tautulli-update-list

Update file/list to monitor for immediate title card updating after an episode has been watched. The specific integration is detailed here, but this is the update.txt file, not the .sh file.

If using a Docker container, this file must be available within the container - i.e. if the file is at /mnt/user/appdata/tautulli/update.txt, this can be mounted as a path in the TitleCardMaker container at /tautulli/update.txt and then this variable would be --tautulli-update-list /tautulli/update.txt

-tf, --tautulli-frequency, --tautulli-update-frequency

On what interval the tautulli update list should be read for cards to remake. This should be specified as INTERVAL[unit], with the acceptable units being s, m, h, d, and w for seconds, minutes, hours, days, and weeks respectively. For example, providing --tautulli-update-frequency 60s would check the update file every 60 seconds.

If the update file is empty (i.e. no episodes have been watched), the Maker exits immediately and does not use any processing resources. Because of this, I recommend setting this to execute pretty often - depending on how quickly you want cards to be remade.

Must be used in conjunction with the above --tautulli-update-list argument. If provided on its own, nothing will happen!

Miscellaneous Operations

In order to make "manually" creating images like title cards, show summaries, or genre cards, the mini maker should be used. It's functionality is detailed here

The Maker also has a few "fix"-related options, such as importing archives, downloading source images, etc. This functionality is detailed here.

Clone this wiki locally