KSConvert - Kinect Studio Clip Conversion Tool

The Kinect Studio Clip Conversion tool (ksconvert.exe) is a command-line tool that converts raw data into processed data; it is also used to upgrade raw data from an older format to the current format.

Clips that contain raw data captured directly from the sensor array are not usable by titles, whereas clips that contain processed data are usable by titles. Raw data is stored in an Xbox Raw File (XRF); processed data is stored in an Xbox Event File (XEF).

Here is the syntax for running the tool:

ksconvert [/?] [/nologo] [/x:address] source-file destination-file

Option	Description
/?	Displays usage information.
/nologo	Suppresses copyright messages.
/x:address	Specifies the IP address of the targeted console. Setting this value does not change the default console for the system.
/c	Continues conversion in a batch even if an error is encountered while converting a file.
/s	Searches the specified directory and all subdirectories for source files for conversion.
/compress	Loss-less encoding of the Raw IR data stream. Shrinks size by ~40%.
/decompress	Returns a compressed file to its original size and format.
/stripColor	When used with conversion or compression, the color stream will not be included in the result file. Removing color can significantly decrease the result file’s size.
/pii	Copies metadata marked as ‘personally identifiable information’ to the result file. All other metadata will be copied by default.
/LongExposureIR	When converting a raw file, records the long exposure IR stream in the new processed file. If this flag is omitted, then the long exposure IR stream is not recorded in the resultant file.
source-file	Specifies a file to convert, either a raw capture (XRF) or a previously processed recording (XEF). This file may be located on the development computer or on the console. To specify a file on the console, prefix the path with "x". For example, "xd:\clips\raw.xrf" specifies a file on the d: drive on the current console.
destination-file	Specifies a name for the converted file. This file may be located on the development computer or on the console. To specify a file on the console, prefix the path with "x". For example, "xd:\clips\processed.xef" specifies a file on the d: drive on the current console.

Usage Examples

Convert a raw XRF into a processed XEF:
```
    ksconvert raw.xrf processed.xef  
```
Convert a raw XRF into a processed XEF and verify the converted file.
```
    ksconvert /v raw.xrf processed.xef  
```
Compress a raw XRF on the default console and write the result file to a network share.
```
    ksconvert /compress xd:\clips\rawIR.xrf \\myshare\compressedIR.xrf  
```

Decompress a raw XRF on a network share and strip color from the result file

    ksconvert /decompress /stripColor \\myshare\compressedIRColor.xrf \\myshare\RawIRNoColor.xrf

On a dev kit, convert a raw XRF into a processed XEF:

    ksconvert xd:\clips\raw.xrf xd:\clips\processed.xef

Convert an older, existing XEF into an upgraded, processed XEF.
```
    ksconvert existing.xef processed.xef  
```
Convert a raw XRF on the development computer and write the resulting XEF to the current dev kit.
```
    ksconvert c:\temp\raw.xrf xd:\clips\processed.xef  
```
Convert a raw XRF on a network share and write the resulting XEF to the current dev kit.
```
    ksconvert \\myshare\raw.xrf xd:\clips\processed.xef  
```

Best Practices

KSConvert.exe does two things:

Converts raw data (IR) into processed data (depth, IR, body).
Updates raw data (depth, IR, and body if the user was tracked) or a processed file (body if the user was tracked) to the latest data format.

The KSConvert.exe tool is updated periodically to work with the latest version of the NUI pipeline. Therefore, use the tool to convert input data (either raw or processed) to data that matches the latest version of the NUI pipeline. This allows you to preserve your investment in capture gestures. Simply follow this sequence:

Record sensor data (using the March 2014 XDK for example). Create gestures and save them in a XRF/XEF file.
Upgrade your dev kit to the latest XDK (using the June 2014 XDK for example).
Run KSConvert.exe on your existing XRF/XEF file. Any new XDK improvements (additional joints, joint orientation data etc.) will be added to the XEF file.
Use the updated XEF file with the rest of the XDK tools.

Processed data files are significantly smaller than raw data files but they are limited in the amount of NUI data that can be regenerated. Be sure to save your raw data as you can use this tool to update them to the latest data format.

If long-term storage capacity is limited, be sure to compress the raw files before committing them to storage.