Vicon Video Converter is a command line video-processing tool that is supplied with the Vicon Video Viewer. It provides direct access to some of the video conversion functionality that is present in other Vicon applications.

Vicon Video Converter enables advanced users to manipulate video in the following ways:

  • Convert between video container formats such as VVID, AVI and MOV.
  • Convert between various video encoding formats (codecs), particularly pixel formats such as Bayer, RGB and YUV.
  • Convert a video file to an image sequence.
  • Convert between PCM audio formats and remove audio tracks.
  • Add a burnt-in timecode to a video using metadata that is saved from a Vicon application.
  • Adjust gamma correction when converting from Bayer formats.
  • Adjust color saturation when converting from Bayer formats.
  • Correct lens distortion using calibration information saved in the metadata of a video file.

It is used to convert videos saved from Vicon applications, in particular VVID files.


ViconVideoConverter is for use with video files generated by Vicon applications. It does not read most common video formats, most of which are highly compressed. If you need a general-purpose video conversion tool that supports a range of modern compressed formats, consider using FFMPEG.

This guide contains the following information:


Basic usage

By default, Vicon Video Converter is installed in C:\Program Files\Vicon\ViconVideoViewer. You can change into this directory to run it, or you can add it to the paths in the PATH environment variables so that it is easier to run from the directory containing your video.

To display a summary of the options available, use the --help switch.

"C:\Program Files\Vicon\ViconVideoViewer\ViconVideoConverter.exe" --help

ViconVideoConverter Alpha
Copyright (C) 2023 Vicon Motion Systems Ltd. All rights reserved.

  -h [ --help ]                         Show this help message.
  -l [ --list-formats ]                 Show list of supported video containers
                                        and audio/video payloads.
  -i [ --input-file ] arg               Path to input video file.
  -o [ --output-file ] arg              Path to output video file.
  --calibration-file arg                Path to calibration file.  Required for
                                        distortion correction if video does not
                                        contain calibration.
  --calibration-device-urn arg          URN of camera.  Required for distortion
                                        correction if video does not contain 
  -v [ --video-payload ] arg            Video payload to use in destination.
  -a [ --audio-payload ] arg (=None)    Audio payload to use in destination. 
                                        Can be 'None' (default), 'Preserve' or 
                                        an uncompressed sample format.
  -q [ --output-quality ] arg (=85)     Quality 0-100 in full JPEG scale. 
                                        Applies to JPEG only.
  --output-quality-h264 arg (=Medium)   Quality: Lowest, Low, Medium, High, 
                                        Best. Applies to H.264 only. Best 
                                        quality results in larger file.
  --burn-in-timecode                    Add a burnt-in timecode.
  --burn-in-timecode-size arg (=medium) Size of time code.  Valid options: 
                                        x-small, small, medium (default), 
                                        large, or x-large.
  --burn-in-timecode-sub-frames         Include the sub-frame fraction in the 
                                        burnt-in timecode.
  --burn-in-timecode-x arg (=0)         X position of timecode to be added.
  --burn-in-timecode-y arg (=0)         Y position of timecode to be added.
  --frame-index-pad-width arg           Pad image sequence frame index to given
                                        length. Default is minimum digits for 
  --frame-number-pad-width arg          Pad frame number to given length. 
                                        Default is minimum digits for length.
  --gamma-correction arg                Override gamma correction instead of 
                                        using value set at capture time.
  --saturation arg                      Override saturation instead of using 
                                        value set at capture time.
  --correct-lens-distortion             Distort video to correct for lens 
                                        distortion.  Video file must contain 
                                        lens calibration.  Only supported for 
                                        GPU conversions.
  --centre-principal-point              Shift video such that the calibrated 
                                        principal point (corresponding to the 
                                        straight ahead camera axis) is shifted 
                                        to the center of the image. Video file 
                                        must contain lens calibration.  Only 
                                        supported for GPU conversions.
  --agents arg                          Comma-separated list of agents and 
                                        ports to use, eg:
  --starting-frame arg (=1)             Frame index from which the processing 
                                        starts. 1-based. Ignored if the output 
                                        is not vvid.
  --frame-count arg                     Number of frames to be processed. If 
                                        unspecified, the entire sequence is 
                                        processed. Ignored if the output is not
  --avi-compatibility-mode              When writing an AVI containing RGB 
                                        data, use the ordering of data that 
                                        maximizes compatibility, at slight cost
                                        in performance. Ignored if not writing 
                                        an AVI with uncompressed RGB data.
  --agent                               Run as an agent accepting connections 
                                        from master (only --server-port, 
                                        --cpu-only --gpu-only, --threads, 
                                        --force-gles options permitted)
  --server-port arg (=6000)             Listen on given port (agent mode only).

  --cpu-only                            Do not use GPU for video conversions.  
                                        This permits multi-threaded 
                                        conversions and can be used if there is
                                        a problem with the graphics adapter.
  --gpu-only                            Use GPU for video conversions and fail 
                                        rather than fall back on software CPU 
                                        conversion.  This is useful for testing
                                        graphics adapter is compatible.
  --threads arg (=4)                    Number of threads to use. Not supported
                                        if gpu-only is enabled, as only one 
                                        encode thread is permitted.
  --force-gles                          Enable graphics compatibility layer 
                                        which converts OpenGL calls to DirectX 
                                        on Windows.

To display the list of supported container and video and audio payload formats, use the --list-formats switch. These correspond to the arguments allowed for the --video-payload and --audio-payload format. The input and output container formats are determined from the filename of the video file, such as vvid, avi or mov.

Convert between formats

A common use of Vicon Video Converter is to convert a VVID format to a MOV file. VVID files are Vicon's own uncompressed video format. Converting a VVID file to a MOV file enables the file to be recognized in third-party video software, and compressing the data as ImageJPEG can significantly reduce the size of the video with minimal cost in loss of quality.

In this example, the -i and -o short versions of the --input-file and --output-file switches are used.

ViconVideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\ -v ImageJPEG

To change the JPEG quality, use the -q switch. The scale is 0 (small file, large loss of quality) to 100 (large file, minimal quality loss).  The most useful range for practical purposes is around 40 to 90.

ViconVideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\ -v ImageJPEG -q 40

Convert a video to an image sequence

To convert a video to an image sequence, specify an image file format such as .jpg in  the output file and specify the special string %FRAME% in the filename.  The %FRAME% string is replaced by the frame number when the files are written out.

ViconVideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile_%FRAME%.jpg -v ImageJPEG

Add burnt-in timecodes

You can add burnt-in timecodes to videos for editorial/reference purposes. Burnt-in timecodes cannot be removed, so it is important to keep the original video. In this example, a large timecode is displayed at coordinates 20, 20. These are measured from the top-left of the image and specify the top-left of the timecode text.

ViconVideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\ -v ImageJPEG --burn-in-timecode --burn-in-timecode-size large --burn-in-timecode-x 20 --burn-in-timecode-y 20

Change gamma and saturation

If the video format is Bayer-based then the gamma and saturation values used for display at the time of capture are stored in the VVID file. By default, these are applied during conversion to a non-Bayer format. You can also override these values with different values if desired. For example, to set gamma to 2.1 and saturation to 1.5, you could use the following command:

ViconVideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\ -v ImageJPEG --gamma 2.1 --saturation 1.5

Correct lens distortion

If a video was created on a system that was calibrated and the calibration was stored in either the video file or a separate calibration file, you can correct for lens distortion.

By default, the resulting video can be interpreted using a pinhole camera model, requiring knowledge of the following information about the camera:

  • World position t
  • World orientation, expressed by 3x3 rotation matrix R
  • Focal length F
  • Principal point (px,py)

The projection of a 3D point onto the image is given by the expression:

x (homogenous 3 vector) , where:

= world point in homegeneous coordinates

K is a 3x3 camera matrix given by:

and the resulting 2D point:

An option (--centre-principal-point) has been added to the lens distortion correction to apply an offset so that the principal point can be assumed to be the image center

Undistort videos from Shogun Live

Video files from Vicon Shogun Live 1.2.1 or later contain calibration information in the VVID file, so you can undistort them without specifying a separate calibration file:

ViconVideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\ -v ImageJPEG --correct-lens-distortion --threads 1

Undistort videos from Nexus

Video files from Vicon Nexus do not contain calibration information so you must specify an XCP file containing the calibration. Because XCP files typically contain the lens calibration information for many cameras, you must specify the required camera, using the device URN.

For calibrations from Shogun Live, the URNs typically take the form mx:123456 or vi:01.

For calibrations from Vicon Nexus, they are likely to be similar to dv:123456.

To open the XCP file, use a text editor.

ViconVideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\ -v ImageJPEG --correct-lens-distortion --threads 1 --calibration-file C:\temp\Calibration.xcp --calibration-device-urn dv:123456

Known issues for Vicon Video Converter

This issue is known to exist in the current release of Vicon Video Converter:

When converting H.264 files with threads set to any value except 1, Vicon Video Converter stops responding.When carrying out multi-threaded H.264 decoding, use --threads 1