--- title: "Using the Vicon Video Converter tool" canonical: "https://help.vicon.com/space/VVV115/649822288/Using%20the%20Vicon%20Video%20Converter%20tool" format: markdown --- 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 part of a video - 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. - Video anonymization It is used to convert videos saved from Vicon applications, in particular VVID files. > ℹ️ **Note** > ℹ️ > ℹ️ Vicon Video Converter 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](http://www.ffmpeg.org/). > ⚠️ **Use with compressed video from Vicon Vanguard cameras** > ⚠️ To transcode compressed video from Vicon Vanguard cameras, Vicon Video Converter requires a Vicon Shogun Markerless license to be available. This is a restriction of the license. > Macro (scroll-pagebreak) This guide contains the following information. > Macro (toc) > Macro (scroll-pagebreak) ## Basic usage By default, Vicon Video Converter is installed in *C:\Program Files\Vicon\VideoViewer*. 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. ```plaintext "C:\Program Files\Vicon\VideoViewer\VideoConverter.exe" --help VideoConverter 1.15.0+166058h Copyright (C) 2025 Vicon Motion Systems Ltd. All rights reserved. Default:VideoPlugins -> Loaded VideoPluginCodingFFMPEG.vpc Default:VideoPlugins -> Loaded VideoPluginCodingH264.vpc Default:VideoPlugins -> Loaded VideoPluginCodingJPEG.vpc Default:VideoPlugins -> Loaded VideoPluginCodingPNG.vpc Default:VideoPlugins -> Loaded VideoPluginCodingTIFF.vpc Default:VideoPlugins -> Loaded VideoPluginContainerAVI.vpc Default:VideoPlugins -> Loaded VideoPluginContainerBMFF.vpc Default:VideoPlugins -> Loaded VideoPluginContainerImageSequence.vpc Default:VideoPlugins -> Loaded VideoPluginContainerMKV.vpc Default:VideoPlugins -> Loaded VideoPluginContainerVVID.vpc Default:VideoPlugins -> Loaded VideoPluginCodingJpegXS.vpc -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 calibration. -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 Quality 0-100 in full JPEG scale. Applies to JPEG only. Default value is 85. --output-quality-h264 arg (=Medium) Quality: Lowest, Low, Medium, High, Best. Applies to H.264 only. Best quality results in larger file. --interframe-mode arg Specify types of frames to produce 'i' (i frame only), 'ip' (i and p frames). Not all Vicon apps can decode interframe files. Only one encode thread is permitted when writing interframe files. --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 length. --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 centre of the image. Video file must contain lens calibration. Only supported for GPU conversions. --starting-frame arg Frame number from which the processing starts. 1-based. --frame-count arg Number of frames to be processed. If unspecified, the entire sequence is processed. --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. --face-anonymization Attempt to detect faces in the video file and obscure them in the output. --face-anonymization-threshold arg (=0.600000024) Threshold level for detecting faces. Recommended range: 0.5 to 1.5. Low numbers increase false positives, high numbers increases missed faces. --face-anonymization-method arg (=pixelate) Method for obscuring faces, which can be 'blur' or 'pixelate'. --face-anonymization-highlighting Draw boxes around faces to easily show detections, for understanding face detector performance. --cpu-only Use CPU for video pixel conversions. This allows multi-threaded conversions and is usually the best option if lens correction is not required. --gpu-only Use GPU for video pixel conversions. This means conversions must be single-threaded but lens correction can be used. --threads arg (=4) Number of threads to use. If gpu-only is enabled, this must be set to 1. --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 part of a video You can convert just a section of a video using the `--starting-frame` and `--frame-count` options. These options can be used either separately or together. The conversion starts from the frame specified with the `--starting-frame` option, which is counted from one (not zero). If this option is omitted, the conversion starts from the beginning of the file as normal. The number of frames in the output file is determined by the `--frame-count` option. If this option is omitted, the conversion continues to the end of the file as normal. If the file contains a starting timecode, and `--starting-frame` is specified, then the starting timecode is increased so that timecode of the frames in the new file are correct. However, if the original file contains no timecode then the new file will contain no timecode either. (In some players, when there is no timecode saved in the file, a starting timecode of 00:00:00:00 is shown, so the original and new file may appear to start at the same time, but this is actually because there was no timecode in the original file.) If the starting frame is past the end of file, or there aren't enough frames in the file for the frame count specified, an error is generated. ### Example of converting part of a video: In the following example, the first 24 frames are skipped and then 240 frames are converted into a new video. If this was a 24Hz video, this would mean the first 1 second is dropped and the following 10 seconds of video form the new file. ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile.mov -v ImageJPEG --starting-frame 25 --frame-count 240 ``` If this was a 24Hz video with timecode, and the video started at 09:34:11:00, the new file would start at 09:34:12:00, so the timecode of the first frame in the new file is the same as the 25th frame in the original file. ## 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. ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile.mov -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. ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile.mov -v ImageJPEG -q 40 ``` > Macro (scroll-pagebreak) ## Convert a video to an image sequence To convert a video to an image sequence, you need to specify an image file format (such as `.jpg`) in the output file and also specify the special string `%FRAME_NUMBER%` in the filename. The `%FRAME_NUMBER%` string is replaced by the frame number (counted from one) when the files are written out. ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\Img_%FRAME_NUMBER%.jpg -v ImageJPEG ``` A common use case is to extract a single image from a video sequence: ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\Img_%FRAME_NUMBER%.jpg -v ImageJPEG --starting-frame 50 --frame-count 1 ``` > ⚠️ **Note** > ⚠️ `%FRAME_NUMBER%` will be replaced with the frame number counted from one. Alternatively, `%FRAME%` can be used to get the frame number counted from zero. The additional options `--frame-number-pad-width` and `--frame-index-pad-width` can be used to control the padding with zeros for `%FRAME_NUMBER%` and `%FRAME%` respectively. For example, to produce output files padded to 8 digits (`Img_00000001.jpg`, `Img_00000002.jpg`, ...) the option would be used like this: ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\Img_%FRAME_NUMBER%.jpg -v ImageJPEG --frame-number-pad-width 8 ``` By default, the padding width is the minimum needed to ensure that all the frames in the file can be represented by equal length strings (not just the subset to be extracted). For example, if the file contains between 100 and 999 frames, the default padding will be to 3 digits: i.e. 001, 002, ..., 999. ## 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. ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile.mov -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: ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile.mov -v ImageJPEG --gamma 2.1 --saturation 1.5 ``` > Macro (scroll-pagebreak) ## 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) > Macro (inline-media-image) , where: > Macro (inline-media-image) = world point in homegeneous coordinates ***K*** is a 3x3 camera matrix given by: ![image](media://d16d15dd-736d-4ac1-b163-660b747c08f3) and the resulting 2D point: ![image](media://6ce219b6-4e05-49b7-9ff6-fd1e7040437d) 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 > Macro (inline-media-image) . > Macro (scroll-pagebreak) ### 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: ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile.mov -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. ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile.mov -v ImageJPEG --correct-lens-distortion --threads 1 --calibration-file C:\temp\Calibration.xcp --calibration-device-urn dv:123456 ``` > Macro (scroll-pagebreak) ## Video anonymization The video converter includes a feature for attempting to detect faces, and then blur or pixelate them to anonymize the video. To enable this feature, use the `--face-anonymization` option. To adjust the sensitivity of the face detection, use the `--face-anonymization-threshold` option. The recommended range is 0.5 (find more faces with false positives) to 1.5 (fewer false positives, but potentially miss faces). To set the anonymization method, use the `--face-anonymization-method` option. The two methods available are `blur `and `pixelate`. > ℹ️ **Note** > ℹ️ Face detection is particularly CPU intensive and slows the conversion process considerably. To improve performance improvement, try enable multi-threading by using the `--threads` option. ### Examples of video anonymization: Detect with a low threshold, find all possible faces, but with potentially lots of false positives, and blur out the faces found: ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile.mov -v ImageJPEG --face-anonymization --face-anonymization-threshold 0.5 --face-anonymization-method blur ``` Detect with a high threshold, fewer false positives but potentially miss real faces, pixelate the faces found: ```plaintext VideoConverter -i C:\temp\VideoInputFile.vvid -o C:\temp\VideoOutputFile.mov -v ImageJPEG --face-anonymization --face-anonymization-threshold 1.5 --face-anonymization-method pixelate ```