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:


Basic TVAI Filters

Upscaling & Enhancement





tvai_cpe + tvai_stb

Video AI Command Line Usage

Environment Variables


  • 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 (macOS)


  • This variable should be set to the folder containing the model definition files (.json), your authentication file (auth.tpz), and the file.
  • In most cases, this value should not be changed from its default setting.
  • Default value:
    • Chosen during initial installation (Windows)
    • /Applications/Topaz Video (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

  1. Add the `-strict 2 -hwaccel auto` flags
  2. Set `-c:v` to `hevc_qsv` or `h264_qsv`
  3. Add `-profile main -preset medium -max_frame_size 65534`
  4. Set `-global_quality` to the desired quality
  5. Add `-pix_fmt yuv420p -movflags frag_keyframe+empty_moov`
  6. 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

Selecting Models with CLI

Scaling Models

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

Interpolation Models

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

Stabilization Models

cpe-1Camera Pose Estimation (first pass)
cpe-2Camera Pose Estimation (first pass) + rolling shutter correction
ref-2Stabilization 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