Skip to content

Getting Started

Migrating from an existing installation?

If you have previously used TitleCardMaker version 1 and are simply migrating to version 2, see the Migration Guide for help with what steps to take.

Installation

There are several ways to install TitleCardMaker - Docker Compose, Docker, non-Docker, and Unraid. Docker Compose is generally recommended because it comes with all the requirements (Python, ImageMagick, etc.), and does not require copying any long commands.

Unraid users can directly add the container as a "template" within the UI.

  1. Open a terminal1 of your choice, and go to your desired install location.

    Example 
    cd "~/Your/Install/Directory/TitleCardMaker"

    cd "~/Your/Install/Directory/TitleCardMaker"

    cd 'C:\Your\Install\Directory\TitleCardMaker'

    cd 'C:\Your\Install\Directory\TitleCardMaker'

  2. Determine your timezone, a full list is available here. You will want to take note of the text in the TZ Identifier column - e.g. America/Los_Angeles - for the next step.

  3. Write the following contents to a file named docker-compose.yml in your desired install directory (from Step 1):

    docker-compose.yml
    name: titlecardmaker
services:
  tcm:
    image: "ghcr.io/titlecardmaker/titlecardmaker:latest" # (4)!
    container_name: titlecardmaker
    restart: unless-stopped
    network_mode: bridge
    ports:
      - 4242:4242
    environment:
      - TZ=America/Los_Angeles # (1)!
      # (3)
    volumes:
      - ~/Your/Install/Directory/TitleCardMaker/config:/config # (2)!
    1. Replace this with your timezone.
    2. Replace this with your install directory.
    3. You may also add add PGID, PUID, and UMASK here as environment variables if you want to control the permissions of TCM.
    4. To use the 'experimental' branch, change :latest to :develop

  4. Create (and launch) the Docker container by executing the following command.

    docker compose up -d

  5. Verify your volumes are mapped correctly by looking for a db.sqlite file inside the config directory. If you do not see one, then correct the volumes specified in Step 3 (double check your quotes are in the correct position).

  1. Open a terminal1 of your choice, and go to your desired install location.

    Example 
    cd "~/Your/Install/Directory/TitleCardMaker"

    cd "~/Your/Install/Directory/TitleCardMaker"

    cd 'C:\Your\Install\Directory\TitleCardMaker'

    cd 'C:\Your\Install\Directory\TitleCardMaker'

  2. Determine your timezone, a full list is available here. You will want to take note of the text in the TZ Identifier column - e.g. America/Los_Angeles - for the next step.

  3. Create (and launch) the Docker container by executing the following command - make sure to replace the install directory and timezone with your directory (from Step 1) and timezone (from Step 2).

    docker run -itd --net="bridge" -v "~/Your/Install/Directory/TitleCardMaker/config/":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "ghcr.io/titlecardmaker/titlecardmaker:latest"

    docker run -itd --net="bridge" -v "~/Your/Install/Directory/TitleCardMaker/config/":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "ghcr.io/titlecardmaker/titlecardmaker:latest"

    docker run -itd --net="bridge" -v "C:/Your/Install/Directory/TitleCardMaker/config":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "ghcr.io/titlecardmaker/titlecardmaker:latest"

    docker run -itd --net="bridge" -v "C:/Your/Install/Directory/TitleCardMaker/config":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "ghcr.io/titlecardmaker/titlecardmaker:latest"
    User ID, Group ID, and UMASK

    If you want to set the user and group which TCM is running under, then you may define the PUID, PGID, and UMASK environment variables as needed.

  4. Verify your volumes are mapped correctly by looking for a db.sqlite file inside the config directory. If you do not see one, then correct the volumes specified in Step 5 (double check your quotes are in the correct position).

Downloading Python

Depending on your Linux distro, Python may already be installed. If not, most likely you are able to install Python on your own.

Install a current Python 3 release from python.org or via Homebrew (brew install python). The system Python that ships with macOS is not recommended for running TitleCardMaker.

Download the latest version of Python from python.org. Be sure to download the "latest version" listed at the top, not necessarily the latest one listed in the release table, as that table includes pre-release versions.

Download the latest version of Python from python.org. Be sure to download the "latest version" listed at the top, not necessarily the latest one listed in the release table, as that table includes pre-release versions.

Downloading ImageMagick

Depending on your Linux distro, you might be able to use whatever package manager comes installed. Some of the common installations are detailed here. For example, the following command works on Debian and Ubuntu:

sudo apt-get install imagemagick

If this is not available, then you must use Docker.

Follow the ImageMagick installation and setup instructions listed here.

Download the Windows Binary Release from the ImageMagick website.

During the installation, be sure to check the Add application directory to your system path and Install legacy utilities (e.g. convert) boxes. The other options are optional.

Download the Windows Binary Release from the ImageMagick website.

During the installation, be sure to check the Add application directory to your system path and Install legacy utilities (e.g. convert) boxes. The other options are optional.

Downloading the Code

  1. Open a terminal1 of your choice, and go to your desired install location.

    Example 
    cd "~/Your/Install/Directory/"

    cd "~/Your/Install/Directory/"

    cd 'C:\Your\Install\Directory\'

    cd 'C:\Your\Install\Directory\'

  2. In your install directory from Step 1, clone the repository with the following command - this will create a TitleCardMaker subdirectory.

    git clone https://github.com/TitleCardMaker/TitleCardMaker.git

Running TitleCardMaker

  1. Enter the TCM installation directory that was just created.

    Example 
    cd "~/Your/Install/Directory/TitleCardMaker"

    cd "~/Your/Install/Directory/TitleCardMaker"

    cd 'C:\Your\Install\Directory\TitleCardMaker'

    cd 'C:\Your\Install\Directory\TitleCardMaker'

  2. Create a subfolder named config.

    mkdir config

  3. Enter the backend directory.

    cd backend

  4. Run the following commands to install the required Python packages and launch the TCM interface.

    python3 -m pip install uv

    python3 -m uv run uvicorn server:app --host "0.0.0.0" --port 4242

  5. You should see an output like this:

    INFO:     Started server process [17385]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:4242 (Press CTRL+C to quit)
Interface not accessible?

If your log shows

INFO:     Application startup complete.

And neither the http://0.0.0.0:4242, http://localhost:4242, or your local IP address URL load into the TCM UI, then replace the 0.0.0.0 part of the previous command with your local IP address - e.g. 192.168.0.10. If you still have issues, reach out on the Discord.

  1. Determine your timezone from the TZ Identifier column (e.g. America/Los_Angeles), and choose a host path for TCM's config directory (e.g. /mnt/user/appdata/titlecardmaker).

  2. At the bottom of the Docker tab of the Unraid interface, click Add Container.

  3. Make sure Advanced View is toggled in the top-right corner.

  4. Enter the following information - leaving all other options blank or default.

    Option Value
    Name TitleCardMaker
    Repository ghcr.io/titlecardmaker/titlecardmaker:latest
    Icon URL https://raw.githubusercontent.com/TitleCardMaker/TitleCardMaker/web-ui/.github/logo.png
    WebUI http://[IP]:[PORT:4242]/

  5. At the bottom of the page, click Add another Path, Port, Variable, Label or Device and enter each of the following (hitting Add after each one):

    Option Value
    Config Type Path
    Name Config
    Container Path /config
    Host Path The config directory from Step 2
    Option Value
    Config Type Port
    Name UI
    Container Port 4242
    Host Port 4242
    Option Value
    Config Type Variable
    Name Timezone
    Key TZ
    Value The timezone from Step 2

  6. Hit Apply.

Success

TitleCardMaker is now accessible at http://localhost:4242/ (or http://0.0.0.0:4242). It may also be at your LAN IP.

Next, configure at least one media server Connection (Plex, Jellyfin, or Emby) plus TMDb — see Configuring Connections.

The Tutorial

The following pages of the tutorial walk you through the basics of using TitleCardMaker — from Connections through creating example Title Cards. The tutorial uses Breaking Bad as the example Series throughout.

It is designed for completely new users of TCM, but is still helpful for those migrating from TCM v1.0 (the command line tool). For more detailed information about specific aspects of TitleCardMaker, look at the User Guide (after you finish the tutorial!).

    • For Linux, I will assume you know what a Terminal is 😉
    • For Mac users, this is Terminal and can be found via the Spotlight
    • For Windows users, this is Command Prompt or PowerShell. Both can be accessed from the search menu

    ↩↩↩