Getting Started

Installation

Downloading ImageMagick

Non-Docker Users Only

The Docker container comes with an installation of ImageMagick, so this step can be skipped by all Docker users.

Linux MacOS Windows (Powershell) Windows (Non-Powershell)

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

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.

mkdir config

Downloading the Code

Sponsors of the project will be invited to a private GitHub repository. These steps will walk you through getting the code from that repository.

1. After being invited, you will recieve an email at your GitHub's associated email address, open it and accept the invitation to collaborate (while signed into your GitHub account).

2. Follow these instructions to get a classic personal access token (PAT) so that you can retrieve the TCM code from git. Check the repo scope section. Copy this code.

   Why is this necessary?

   Because the repository is private, the git clone command requires authentication. You can download the zipped code from the website, but this makes getting updates difficult.

   A PAT is required instead of a password because GitHub does not allow passwords to be used from the command line.

   Security Warning

   Keep this access code private, as it can be used to access your GitHub account.

3. Open a terminal of your choice, and go to the desired install location. Then clone the repository with:

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

4. Enter your account Username and the PAT from Step 2. The TCM code will now be downloaded into a subdirectory named TitleCardMaker-WebUI.

Running TitleCardMaker

Setup

1. Navigate to the installation directory within the command line.

   Example

   Linux MacOS Windows (Powershell) Windows (Non-Powershell)

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

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

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

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

   Replace the example path with the directory from Step 3 above.

2. Within the main installation directory, create the required folder for TCM - this is config - by executing the following command:

   Linux MacOS Windows (Powershell) Windows (Non-Powershell)

   mkdir config
   

   mkdir config
   

   mkdir config
   

   mkdir config
   

3. We now need to make sure this directory has the correct permissions assigned to it.

   Linux MacOS Windows (Powershell) Windows (Non-Powershell)

   With the Group and User ID that you would like TCM to execute with, run the following command:

   sudo chown -R {group}:{user} ./config # (1)!
   

   1. Replace {group} and {user} with the actual group and user (or their ID's) - e.g. 99:100.

   With the Group and User ID that you would like TCM to execute with, run the following command:

   sudo chown -R {group}:{user} ./config # (1)!
   

   1. Replace {group} and {user} with the actual group and user (or their ID's) - e.g. 99:100.

   Changing the permissions is (generally) not necessary on Windows.

   Changing the permissions is (generally) not necessary on Windows.

Choice of Installation

You now have the choice of building and running the Docker container yourself, or launching the Python script directly.

The Docker container is the recommended method for all operating systems.

Launching the Interface

Docker Non-Docker

1. Build the Docker image under the tag titlecardmaker:latest, by executing the following command:

   Linux MacOS Windows (Powershell) Windows (Non-Powershell)

   docker build -t "titlecardmaker:latest" .
   

   docker build -t "titlecardmaker:latest" .
   

   docker build -t "titlecardmaker:latest" .
   

   docker build -t "titlecardmaker:latest" .
   

2. Determine your timezone, a full list is available here. You will want to take note of the text in the TZ Identifer 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 America/Los_Angeles with your timezone from the previous step.

   Linux MacOS Windows (Powershell) Windows (Non-Powershell)

   docker run -itd --net="bridge" -v "$(pwd)/config/":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "titlecardmaker:latest"
   

   docker run -itd --net="bridge" -v "$(pwd)/config/":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "titlecardmaker:latest"
   

   docker run -itd --net="bridge" -v "$(pwd)\config":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "titlecardmaker:latest"
   

   docker run -itd --net="bridge" -v "%cd%\config":"/config/" -e TZ="America/Los_Angeles" -p 4242:4242 --name "TitleCardMaker" "titlecardmaker:latest"
   

Docker invalid reference format Error

If you get an error from Docker saying invalid reference format - this means that the command has some typo. Try specifying the command in one- line (removing the ending character from each line).

Windows users can also manually specify their install directory rather than using $(pwd) or %cd$, with all forward slashes (/) instead of back slashes - e.g. C:/Users/Documents/TitleCardMaker-WebUI/config in place of $(pwd)\TitleCard\config.

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

pipenv install
pipenv run uvicorn app-main:app --host "0.0.0.0" --port 4242

And you should see an output like:

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)

Success

TitleCardMaker is now accessible at the http://0.0.0.0:4242 or http://localhost:4242/ URL.

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.

Getting Started

The following pages of the tutorial are designed to walk you through all of the basics of using TitleCardMaker. It covers each step between installing TCM up through creating example Title Cards. You can skip directly to Configuring Connections.

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.

---

1. The exact purpose of this command breaks down as follow:

   docker run -itd ^ # (1)!
       --net="bridge" ^ # (2)!
       -v "%cd%\config":"/config/" ^ # (3)!
       -e TZ="America/Los_Angeles" ^ # (4)!
       -p 4242:4242 ^ # (5)!
       --name "TitleCardMaker" ^ # (6)!
       titlecardmaker
   

   1. Launch the container in the background.
   2. Ensure that TCM has access to the ports of your other Docker containers.
   3. Make your current directory available inside the container.
   4. Set the internal timezone equal to your local timezone.
   5. Make the TCM WebUI accessible at port 4242 on your machine.
   6. Name the container TitleCardMaker.

   ↩