Command Line Interface (CLI) Instructions for Topaz Video AI v3.0

This is a support article to document the use of the Command Line Interface (CLI) for Topaz Video AI (formerly Video Enhance AI) v3.0. This build is currently only available to members of our Video Beta Tester program. 
This documentation is not relevant for builds released prior to v3.0.
The majority of the commands for this build will be FFmpeg commands. There is no need to install FFmpeg, the TVAI installer will automatically install FFmpeg. 
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

First things first, 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, go ahead and select Advanced > 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:
Mac:
1.  You must manually set VEAI_MODEL_DIR if launching without the GUI
2.
 cd /Applications/Topaz\ Video\ AI.app/
	
Win: 1.
 cd "C:\Program Files\Topaz Labs LLC\Topaz Video AI ALPHA"
	
If for some reason you log out and need to log back in without launching the GUI:
 ./login 'email' 'password'
	
Basic Filters specific to TVAI:
Upscaling
  veai_up
	
Interpolation
 veai_fi
	

Stabilization

 veai_cpe + veai_stb
	

Advanced Usage

* If you have an existing models folder, you may select it by setting the VEAI_MODEL_DIR setting in your system environment variables. If you do not already have downloaded models in this folder, you will need to copy the model JSON files from the download into this folder. 
* The FFmpeg command can be invoked to perform VEAI sessions.
Video AI Command Line Usage

Environment Variables

The `VEAI_MODEL_DIR` environment variable must be set to the path to your model's directory. This directory should contain, at minimum, the .json files for the models and the tvai.tz file.

Steps for Logging In

If needed, invoke the command line login program:
```
/login 'username' 'password'
```
	
An auth.tpz file will be stored in `VEAI_MODEL_DIR`

Further Notes on Usage Specific to Hardware

VEAI may be used as an FFmpeg filter, for example:
 `-vf "veai_up=model=aaa-10:scale=2"`
	
Note that 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.

For Intel Devices

1. Use with Newer Devices
On some newer devices, it may be necessary to set the `Computer\HKEY_CURRENT_USER\Software\Topaz Labs LLC\Topaz Video AI ALPHA\OVUseDeviceIndex` registry entry. You may then choose the device by adding `device=#` to the filter argument, where # is the device index:
 ```
-vf "veai_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 VEAI filter string
Example 1
 ```
./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 "veai_up=model=amq-13:scale=2:device=0" "output-artemis.mp4" 
 ```
	

This script shows the following: 

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

For Nvidia Devices

- 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 VEAI filter string
Example 2
``` 
./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 "veai_up=model=amq-13:scale=2" "output-artemis.mp4" 
 ```
	
This script shows the following: 
1. Hides the FFmpeg startup banner
2. Enables hardware acceleration, and uses the hevc_nvenc encoder (H.265)
3. Uses the main profile with the medium preset for the encoder
4. Sets the CRF to 19
5. Sets the output pixel format to yuv420p
6. Creates 100% fragmented output, allowing the file to be read if the processing is interrupted
7. Upscales 2x using Artemis v13

For AMD Devices

- 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 VEAI filter string
Example 3
```
./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 "veai_up=model=amq-13:scale=2" "output-artemis.mp4"
``
	
This script shows the following: 
1. Hides the FFmpeg startup banner
2. Enables hardware acceleration, and uses the hevc_amf encoder (H.265)
3. Uses the main profile for the encoder
4. Sets the CRF to 19
5. Sets the output pixel format to yuv420p
6. Creates 100% fragmented output, allowing the file to be read if the processing is interrupted
7. Upscales 2x using Artemis v13

Using Models with CLI

Available Scaling Models

Now you will want to make sure that the models have been downloaded properly by running the following command:
Mac:
 ls "$VEAI_MODEL_DIR"
	
Win:
 dir "%VEAI_MODEL_DIR%"
	

Here are all of the available model options along with their command:

Enhancement 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

Available Interpolation Models

* 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

Available Stabilization Models

* cpe-1 : Camera Pose Estimation (first pass)
* ref-1 : Stabilization Model (final pass) More on the Stabilization Models
To use the full-frame stabilization model, there are two commands that need to be run one after another.
1st one:
 ./ffmpeg -hide_banner -nostdin -y -i /path/to/input_video -vf veai_cpe=model=cpe-1:filename=temp/path/cpe.json -f null -
	
AND 2nd one: Full-frame stabilization
 ./ffmpeg -hide_banner -nostdin -y -i /path/to/input_video -vf veai_stb=filename=temp/path/cpe.json:smoothness=6:full=1 path/to/output_video
	

OR:  Auto-crop

 ./ffmpeg -hide_banner -nostdin -y -i /path/to/input_video -vf veai_stb=filename=temp/path/cpe.json:smoothness=6:full=0 path/to/output_video
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.