Command Line Interface

Topaz Video AI supports executing scripts using a command line interface.

This is designed for advanced users comfortable working in such an environment and offers more flexibility in customizing a variety of scripted processes.

We highly recommend using the app’s user interface for those not comfortable working in a command terminal.

The majority of the commands for this build will be FFmpeg commands.

There is no need to install FFmpeg, it is automatically included with the TVAI installer. This article will outline the basic functions for TVAI’s CLI, however, you will want to familiarize yourself with FFmpeg commands for more complex use cases.

Getting Started with CLI

Before using the CLI for the first time, we recommend launching the GUI and logging into the app. This eliminates the need to use a command to log into the app and will allow you to launch the terminal directly from the GUI.

After logging in, select Process > Open Command Prompt, this will set the model directory automatically. The next time you want to launch the CLI without the GUI, follow the steps below:

You must manually set the TVAI_MODEL_DATA_DIR and TVAI_MODEL_DIR environment variables if launching without the GUI. Please see the Environment Variables section below.

cd "C:\Program Files\Topaz Labs LLC\Topaz Video AI"

If you log out and need to log back in without launching the GUI:

.\login

You must manually set the TVAI_MODEL_DATA_DIR and TVAI_MODEL_DIR environment variables if launching without the GUI. Please see the Environment Variables section below.

cd /Applications/Topaz\ Video\ AI.app/Contents/MacOS

If you log out and need to log back in without launching the GUI:

./login

Basic TVAI Filters

Upscaling & Enhancement

tvai_up

Interpolation

tvai_fi

Stabilization

tvai_cpe + tvai_stb

Video AI Command Line Usage

Environment Variables

TVAI_MODEL_DATA_DIR

This variable should be set to the folder where you want model files to be downloaded. A location with ~80 GB of free space will work best.
Default value:
- Chosen during initial installation (Windows)
- /Applications/Topaz Video AI.app/Contents/Resources/models (macOS)

TVAI_MODEL_DIR

This variable should be set to the folder containing the model definition files (.json), your authentication file (auth.tpz), and the tvai.tz file.
In most cases, this value should not be changed from its default setting.
Default value:
- Chosen during initial installation (Windows)
- /Applications/Topaz Video AI.app/Contents/Resources/models (macOS)

GPU-Specific Usage Notes

TVAI is used as an FFmpeg filter, and all models will work on graphics devices from Intel, AMD, Nvidia, and Apple using a command like this example:

-vf "tvai_up=model=aaa-10:scale=2"

However, different graphics cards may support different encoders and options. Similarly, different encoders support different options, so you may need to tweak settings on different machines. The following options can be used to take advantage of hardware acceleration features from different GPU manufacturers:

On some newer Intel devices, it may be necessary to set the `Computer\HKEY_CURRENT_USER\Software\Topaz Labs LLC\Topaz Video AI\OVUseDeviceIndex` registry entry. You can set the device by adding `device=#` to the filter argument, where # is the device index:

-vf "tvai_up=model=aaa-10:scale=2:device=0"

General Usage

Add the `-strict 2 -hwaccel auto` flags
Set `-c:v` to `hevc_qsv` or `h264_qsv`
Add `-profile main -preset medium -max_frame_size 65534`
Set `-global_quality` to the desired quality
Add `-pix_fmt yuv420p -movflags frag_keyframe+empty_moov`
Provide TVAI filter string

Example Command:

./ffmpeg -hide_banner -nostdin -y -strict 2 -hwaccel auto -i "input.mp4" -c:v hevc_qsv -profile main -preset medium -max_frame_size 65534 -global_quality 19 -pix_fmt yuv420p -movflags frag_keyframe+empty_moov -vf "tvai_up=model=amq-13:scale=2:device=0" "output-artemis.mp4"

The above command performs the following:

Hides the FFmpeg startup banner
Enables hardware acceleration, and uses the hevc_qsv encoder (H.265)
Uses the main profile with the medium preset for the encoder
Sets the CRF to 19
Sets the output pixel format to yuv420p
Creates 100% fragmented output, allowing the file to be read if the processing is interrupted
Upscales 2x using Artemis v13 on GPU #0

Add the `-strict 2 -hwaccel auto` flags
Set `-c:v` to `hevc_nvenc` or `h264_nvenc`
Add `-profile main -preset medium`
Set `-global_quality` to the desired quality
Add `-pix_fmt yuv420p -movflags frag_keyframe+empty_moov`
Provide TVAI filter string

Example Command:

./ffmpeg -hide_banner -nostdin -y -strict 2 -hwaccel auto -i "input.mp4" -c:v hevc_nvenc -profile main -preset medium -global_quality 19 -pix_fmt yuv420p -movflags frag_keyframe+empty_moov -vf "tvai_up=model=amq-13:scale=2" "output-artemis.mp4"

The above command performs the following:

Hides the FFmpeg startup banner
Enables hardware acceleration, and uses the hevc_nvenc encoder (H.265)
Uses the main profile with the medium preset for the encoder
Sets the CRF to 19
Sets the output pixel format to yuv420p
Creates 100% fragmented output, allowing the file to be read if the processing is interrupted
Upscales 2x using Artemis v13

Add the `-strict 2 -hwaccel auto` flags
Set `-c:v` to `hevc_amf` or `h264_amf`
Add `-profile main`
Set `-global_quality` to the desired quality
Add `-pix_fmt yuv420p -movflags frag_keyframe+empty_moov`
Provide TVAI filter string

Example Command:

./ffmpeg -hide_banner -nostdin -y -strict 2 -hwaccel auto -i "input.mp4" -c:v hevc_amf -profile main -global_quality 19 -pix_fmt yuv420p -movflags frag_keyframe+empty_moov -vf "tvai_up=model=amq-13:scale=2" "output-artemis.mp4"

The above command performs the following:

Hides the FFmpeg startup banner
Enables hardware acceleration, and uses the hevc_amf encoder (H.265)
Uses the main profile for the encoder
Sets the CRF to 19
Sets the output pixel format to yuv420p
Creates 100% fragmented output, allowing the file to be read if the processing is interrupted
Upscales 2x using Artemis v13

Add the `-strict 2 -hwaccel auto` flags
Set `-c:v` to `h264_videotoolbox` or `hevc_videotoolbox` or `prores_videotoolbox`
Add `-profile main` for H264 or HEVC outputs, or `-profile hq` for ProRes 422 HQ output
Set `-global_quality` to the desired quality
Add `-pix_fmt yuv420p` for H.264 or HEVC, add `-pix_fmt p210le` for ProRes
Provide TVAI filter string

Example Command:

./ffmpeg -hide_banner -nostdin -y -strict 2 -hwaccel auto -i "input.mp4" -c:v "hevc_videotoolbox" "-profile:v" "main" "-pix_fmt" "yuv420p" "-allow_sw" "1" -vf "tvai_up=model=amq-13:scale=2" "output-artemis.mp4"

The above command performs the following:

Hides the FFmpeg startup banner
Enables hardware acceleration, and uses the VideoToolbox encoder (H.265)
Uses the main profile for the encoder
Sets the output pixel format to yuv420p
Upscales 2x using Artemis v13

Selecting Models with CLI

Scaling Models

aaa-10	Artemis Aliased & Moire v10
aaa-9	Artemis Aliased & Moire v9
ahq-10	Artemis High Quality v10
ahq-11	Artemis High Quality v11
ahq-12	Artemis High Quality v12
alq-10	Artemis Low Quality v10
alq-12	Artemis Low Quality v12
alq-13	Artemis Low Quality v13
alqs-1	Artemis Strong Dehalo v1
alqs-2	Artemis Strong Dehalo v2
amq-10	Artemis Medium Quality v10
amq-12	Artemis Medium Quality v12
amq-13	Artemis Medium Quality v13
amqs-1	Artemis Dehalo v1
amqs-2	Artemis Dehalo v2
ddv-1	Dione Interlaced DV v1
ddv-2	Dione Interlaced DV v2
ddv-3	Dione Interlaced DV v3
dtd-1	Dione Interlaced Robust v1
dtd-3	Dione Interlaced Robust v3
dtd-4	Dione Interlaced Robust v4
dtds-1	Dione Interlaced Robust Dehalo v1
dtds-2	Dione Interlaced Robust Dehalo v2
dtv-1	Dione Interlaced TV v1
dtv-3	Dione Interlaced TV v3
dtv-4	Dione Interlaced TV v4
dtvs-1	Dione Interlaced Dehalo v1
dtvs-2	Dione Interlaced Dehalo v2
gcg-5	Gaia Computer Graphics v5
ghq-5	Gaia High Quality v5
prap-2	Proteus Auto-Parameter v2
prob-2	Proteus 6-Parameter v2
thd-3	Theia Fine Tune Detail v3
thf-4	Theia Fine Tune Fidelity v4

Interpolation Models

apo-8	Apollo v8
apf-1	Apollo Fast v1
chr-2	Chronos v2
chf-1	Chronos Fast v1
chf-2	Chronos Fast v2
chf-3	Chronos Fast v3
chr-1	Chronos Slo-Mo / FPS Conversion v1
chr-2	Chronos Slo-Mo / FPS Conversion v2

Stabilization Models

cpe-1	Camera Pose Estimation (first pass)
cpe-2	Camera Pose Estimation (first pass) + rolling shutter correction
ref-2	Stabilization Model (final pass)

Additional Information on the Stabilization Models: To use the stabilization model, there are two commands that need to be run one after another.

Step 1:

./ffmpeg -hide_banner -nostdin -y -i /path/to/input_video -vf tvai_cpe=model=cpe-1:filename=temp/path/cpe.json -f null -

Step 2 (Full-Frame):

./ffmpeg -hide_banner -nostdin -y -i /path/to/input_video -vf tvai_stb=filename=temp/path/cpe.json:smoothness=6:full=1 path/to/output_video

Step 2 (Auto-Crop):

./ffmpeg -hide_banner -nostdin -y -i /path/to/input_video -vf tvai_stb=filename=temp/path/cpe.json:smoothness=6:full=0 path/to/output_video

Custom Encoder Options

Second Pass Enhancement