User Guide

Under Construction

This documentation is actively being developed.

Not for New Users

The User Guide is not intended to be an introduction to TitleCardMaker for new users - it is a detailed reference for those already familiar with the basics. New users should follow the Getting Started tutorial.

Pages

The TitleCardMaker interface is separated into various pages which can be navigated to via the sidebar or buttons on the header. Each page is detailed below:

Selecting a Branch / Tag

TitleCardMaker follows the typical design pattern of lots of software packages, separating changes which are "in development" and "finalized". As a result, you have the option of selecting between either of these branches (or tags) for your version of TCM.

Develop Branches / Tags

If using the develop version of TCM, expect to encounter bugs which may require frequently updating. If this sounds cumbersome, stick to the main branch.

Backwards Compatibility

If there are changes to the TCM database schema, these are often irreversible - meaning swapping from develop to main is not possible.

Docker

Tag Name	Description	Recommended For..
`latest`	The most up-to-date (stable) release	Most users¹
`main`	Same as `latest`	It's recommended to use `latest`
`develop`	The most feature-rich (unstable) release	Those wanting to try the latest features
`main-armv7`	Same as `latest`, but for those on an ARMv7 architecture	See `latest`
`develop-armv7`	Same as `develop`, but for those on an ARMv7 architecture	See `develop`

Non-Docker

Branch Name	Description	Recommended For..
`main`	The most up-to-date (stable) release	Most users¹
`develop`	The most feature-rich (unstable) release	Those wanting to try the latest features

Environment Variables

Specifying an Environment Variable

Docker Compose Docker Non-Docker

Add all environment variables under the environment section of your compose file, like so:

docker-compose.yml

name: titlecardmaker
services:
  tcm:
    # etc.
    environment:
      - TZ=America/Los_Angeles
      - TCM_LOG_STDOUT=WARNING
    # etc.

Specify the environment variable with the -e commands in your Docker run command, like so:

-e TZ=America/Los_Angeles -e TCM_LOG_STDOUT=WARNING

The easiest method is to create a file named .env in the main TCM installation directory (where you type your python command) - like so:

.env

TZ=America/Los_Angeles
TCM_LOG_STDOUT=WARNING

While a vast majority of TCM's behavior can be adjusted within the UI, there are a few options which can only be adjusted with environment variables. These are described below:

TCM_BACKUP_RETENTION: How long to keep old backups before deleting them. This is an integer number of days. The default is 21.
TCM_IM_DOCKER: Name of a standalone Docker container to execute ImageMagick commands within. This is only required if TCM is not executing within Docker, but ImageMagick is. This is unspecified by default.
TCM_LOG: This has been deprecated in place of TCM_LOG_STDOUT.
TCM_LOG_STDOUT: The minimum log level for the standard (console) output. Log messages at a level lower than this will not be transmitted. This can be either TRACE, DEBUG, INFO, WARNING, ERROR, or CRITICAL. The default is INFO.
TCM_LOG_FILE: The minimum log level for the logging file output. Log messages at a level lower than this will not be written to any log files. This can be either TRACE, DEBUG, INFO, WARNING, ERROR, or CRITICAL. The default is TRACE and it is not recommended to change this, as it can make it much more difficult to diagnose or debug issues.
TCM_LOG_WEBSOCKET: The minimum log level for live messages which appear in the UI (toggled here). Log messages at a level lower than this will not be displayed in the UI. This can be either TRACE, DEBUG, INFO, WARNING, ERROR, or CRITICAL. The default is INFO.
TCM_LOG_RETENTION: How long to keep log files before they are deleted. This can be any human- readable duration - e.g. 2 days, 3 weeks, etc. The default is 7 days.
TCM_NEW_SERIES_VIEW: As of v2.0-alpha.10.0, this setting is no longer requires as the "old" Series view has been removed.
TCM_PLEX_LOGGING: Set to TRUE to reroute all Plex API log messages to TCM's internal logging mechanism. Plex can be fine-tuned, see below.
TZ: The timezone which is used for all local time reporting (most notably logging). To determine your timezone, a full list is available here. You will want to take note of the text in the TZ Identifer column. The default is UTC.
TCM_DISABLE_AUTH: Whether to reset and disable authentication access to the TCM UI. This is only read when TCM first boots, and if set to TRUE then your previously established username and password will be deleted. For more details, see here. This is unspecified by default.

Plex Variables

TCM uses the plexapi module to communicate with Plex, and as such can be configured by configuring their assigned environment variables - these are all detailed here.

The most popular one is the API timeout - PLEXAPI_PLEXAPI_TIMEOUT.

Unless you've encountered a bug which you personally require and is only available on develop. ↩↩