TrickyTroll / good-bot

Automating the recording of documentation videos.

good-bot 🤖

Automating the recording of documentation videos.

good-bot automates the process of recording documentation for your projects. It even provides voice-over using Google TTS.

Quickstart

How to quickly get started with good-bot.

The easiest way to install good-bot is to pull the Docker image. The image has every tool required by the program pre-installed. The only requirement is that you have a working Docker installation.

Once you have pulled the image, you can try good bot using the following command.

docker run -it trickytroll/good-bot:latest

Note: You can also just run the previous command and the image will be pulled automatically.

Every good-bot command also requires a configuration file. Since those files reside on your computer, you will need to pass them to the container so that the program can read them.

Passing files to a container is quite simple using volumes. In short you will need to add the following flag and argument to the previous docker run command.

--volume $PWD:/project

The complete command looks like this:

docker run -it --volume $PWD:/project trickytroll/good-bot:latest

This will bind your current working directory to the container's /project directory.

You can now use good-bot's command line interface to record a video.

If you are not feeling like writing a script for now but still want to see what good-bot is capable of, you can use the no audio example.

For more detailed instructions on unlocking all of good-bot's capabilities, see the full installation instructions.

Install

Installing the most recent version of good-bot locally and installing with Docker.

Local installation

⚠️ Warnings

1. good-bot has quite a few dependencies. Installing locally is not the most straightforward way of using this program.

2. By following your instructions, this program might install new software on your computer. It might also edit text files and modify your system. Using this program in a container ensures that your environment is not affected by your demos. It also lets you install programs many times in a row for your demos without having to uninstall them between each recording session.

Dependencies

The Docker image is built on the Ubuntu Linux distribution, which uses the apt package manager and a specific repository to fetch it's packages.

The following program can be installed on Ubuntu using apt, but they are probably distributed for your package manager too. If they are not, please see each program's website for more in-depth installation instructions.

Dependency	Version
python	3.9
asciinema	2.0.3
pip	20.0.2

Python dependencies are specified in the requirements.txt file.

These dependencies are only the ones required for good-bot to work. Your own scripts might require other programs to work. It is up to you to install those other missing parts.

Install locally

good-bot should be installed using pip. From the root of this project, run the following command. Also make sure that you are installing from branch main. The latest branch contains more recent changes, but there is no guarantee that the program will work if installed from latest.

pip install .

This will install runner in your current Python environment.

Docker installation

Using docker build

good-bot is a containerized application. To use the app, you must have a working Docker installation.

To build the container, simply run docker build -t [SOME TAG] . in the same directory as the Dockerfile. [SOME TAG] is to be replaced by a name of your choosing.

Pull the image

The image is built on the main branch on every change. The following command will pull the good-bot container image.

docker pull trickytroll/good-bot:latest

Usage

Instructions on how to use good-bot, whether it is installed locally or in a Docker container.

Writing a configuration file

To tell good-bot what you want to record, you will need to write a script. A script is a yaml file so that the syntax is easy to get used to.

Keywords

For now, good-bot has 3 keywords:

• commands: A list of shell commands that the program will type to a bash prompt.
• expect: A list of things that you expect will be printed to the prompt following the completion of the corresponding command.
• read: What will be read by the Text-to-Speech application while the commands are running. This is how you can add narration to your video documentation.

Scenes

Those keywords are used in what is called a scene. A scene is a group of commands, expect, and read statements that will be executed in order.

Statements are grouped that way so that things can run in parallel. This means that you cannot expect that scene_1 will be recorded before scene_3, for example.

If you want some commands to be executed in a certain order, you must group them in the same scene.

An example

You can find other examples in the examples directory.

Docker usage

Creating a project with the Docker image

Once you have written your configuration file, you can create your project using good-bot's setup command.

docker run -it -v $PWD:/project -t [SOME TAG] setup [CONFIG NAME]

Where

• [SOME TAG] is the tag previously chosen.
• [CONFIG NAME] is the name of the configuration file.

Keep in mind that this command mounts the current working directory in the container. If your configuration file is not under your current working directory, the previous command won't work.

Recording your video in a container

If you have a project directory, you can record your clips using

docker run -it -v $PWD:/project -t [SOME TAG] record [PROJECT NAME]

Where

• [SOME TAG] is the tag previously chosen.
• [PROJECT NAME] is the name of the project file.

Note: This is where you need to include the --env and -v flags mentioned earlier.

Local usage

If installed locally, this program's command line interface can be used with the good-bot command.

Setting up locally

The setup command separates your script in shorter ones that good-bot's extensions understand. It also creates a directory that will be used by the program to save its recordings.

Once you have written your script, you can use the setup command like so.

good-bot setup [path/to/script.yaml]

Where [path/to/script.yaml] is to be replaced by the path to your own script.

Recording locally

Once your project has been set up, you can record it using the record command.

good-bot record [path/to/setup]

Where [path/to/setup] is the path towards the directory created using the setup command. The recordings will be added to your setup directory.

If your script contains audio instructions (with the read keyword), see the adding voice-over section.

Adding voice-over

If you want to use Google TTS, you will need an API key for the service. To get your code, you can follow the instructions provided by Google.

Once you have activated the API, you'll be able to download a .json file that contains your key. As mentioned in the Google TTS documentation, you will also need to bind the path to your .json file to the GOOGLE_APPLICATION_CREDENTIALS variable.

When goodbot runs, it will look for the value of the GOOGLE_APPLICATION_CREDENTIALS environment variable. Instructions on setting this variable depend on the installation method.

TTS on your local machine

Once you have downloaded the API key file, the last step is to set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path towards the location of the key on your computer. On UNIX-like systems, this can be done using the following command.

export GOOGLE_APPLICATION_CREDENTIALS=[path/to/file.json]

where [path/to/file.json] must be replaced by the path to your own credentials file.

TTS with the Docker image

This is where instructions differ from the ones in Google's documentation. Since your host's environment variables are not sent to the container by default, you will need to pass the .json credentials file to the container. The environment variable needs to be set for the container, not just the host.

To copy your private key to the container, you can add the following flag when using the run command:

-v [PATH/TO/FILE]:/.env

Where [PATH/TO/FILE] needs to be replaced by the path towards the directory that contains your key on your host's file system. This mounts the previously mentioned directory in your container under the path /.env.

Now that your API key is accessible from the container, you can set the GOOGLE_APPLICATION_CREDENTIALS variable using the following command:

--env GOOGLE_APPLICATION_CREDENTIALS="/.env/[KEY-NAME].json

Where KEY-NAME needs to be replaced by the name of the .json file previously downloaded.

Voice-over summary

To use voice-over, you will need to activate the Google Text to Speech API for your Google Cloud account. You will also need an API key, which can be downloaded as a .json file.

Once you have your key on your host computer, you can share the key to the container and enable it by adding the following flags to the docker run command (see Recording your video).

-v [PATH/TO/FILE]:/.env --env GOOGLE_APPLICATION_CREDENTIALS="/.env/[KEY-NAME].json

[PATH/TO/FILE] and [KEY-NAME] must be replaced by your own values.

For the old version

To see the first release, please go to the old branch.