Overview

iPi Integration Add-on allows to control iPi Recorder and iPi Mocap Studio from external application by sending JSON commands via Windows dll. It can be used for:

Using iPi Recorder and iPi Mocap Studio as a part of a third-party solution
Automation of repeatable tasks
Automation of custom workflow

Note: iPi Integration Add-on requires separate license key, which you need to activate in iPi Mocap Studio. 30-days free trial provided.

License and Trial

iPi Integration Add-on requires separate license key, which you need to activate in iPi Mocap Studio. You can order your license here, or activate 30-days free trial. Follow the steps below to start working with iPi Integration Add-on

Select menu item Help > Manage Licenses > Integration Add-on.
Press Start 30-days Free Trial Period or Enter Integration License Key and follow further on-screen instructions

Note: To use iPi Integration Add-on with iPi Recorder, you have to install iPi Mocap Studio on the same computer and activate iPi Integration Add-on following the instructions above.

Using iPi Integration Add-on

Command Syntax

Commands are strings based on JSON syntax. Commands are submitted via JSON requests that include command name and may optionally include command arguments.

The response is also JSON string. The response include success flag. In case of error the response include error message. In case of success the response may optionally include result that is JSON object.

Long actions (recording, background evaluation, etc.) initiated by commands generate asynchroneous events on action completion. Event is described by JSON string that include event name and may include optional arguments, depending on type of event.

SYNOPSIS

// Request for command without arguments
{
    "command": "<command_name_string>"
}
 
// Request for command with arguments
{
    "command": "<command_name_string>",
    "arguments": 
    {
        <arguments_list_json_string>
    }
}
 
// Simple response in case of success
{
    "success": true
}
 
// Response including command result field in case of success
{
    "success": true,
    "result":
    {
      <result_json_string>
    } 
}
 
// Response in case of error
{
    "success": false,
    "error": "<error_message_string>"
}
 
// Event without arguments
{
    "event": "<event_name_string>"
}
 
// Event including arguments
{
    "event": "<event_name_string>",
    "arguments": 
    {
        <arguments_list_json_string>
    }
}

iPi Recorder Commands

General Commands

get-app-info

get-app-info command returns the name of application and its version.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
`appName`	string	mandatory	`iPi Recorder 3`	Application name.
`appVersion`	string	mandatory	Version number in the format `XX.XXX.XXX.XXX`	Application version number.

EXAMPLE

// Request
{
    "command": "get-app-info"
}
 
// Response
{
    "success":true,
    "result":
    {
        "appName": "iPi Recorder 3",
        "appVersion": "99.876.543.210"
    }
}

open-studio

open-studio command opens iPi Mocap Studio and creates the project from specified .iPiVideo file.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	mandatory	Valid file path	Full path of .iPiVideo file.
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-studio",
    "arguments": 
    {
        "filePath": "D:\iPiMocap\test_record.iPiVideo"
    }
}
 
// Response
{
    "success": true
}

exit

exit command closes iPi Recorder.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "exit"
}
 
// Response
{
    "success": true
}

Recording Commands

open-home-screen

open-home-screen opens HOME screen of iPi Recorder.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-home-screen"
}
 
// Response
{
    "success": true
}

refresh-device-list

refresh-device-list returns the list of available devices.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Array of JSON objects, each representing recording device. Fields of array items:
`kind`	string	mandatory	`camera` `depth-sensor` `microfon`	Device type.
`model`	string	mandatory	Supported device model	Device model.
`id`	string	mandatory	Unique string, format depends on device model	Unique string that is used to identify recording devices in open-recorder command.
`selected`	boolean	mandatory	`true false`	Device selected status.
`failed`	boolean	mandatory	`true false`	Device filed status.
`error`	string	optional	Error message string	Error message if device is in failed status.

EXAMPLE

// Request
{
    "command": "refresh-device-list"
}
 
// Response
{
    "success":true,
    "result":
    [
        {
            "kind": "camera",
            "model": "PlayStation Eye",
            "id": "\\\\?\\usb#vid_1415&pid_2000&mi_00#7&2ed872d7&0&0000#{4cff9941-d72f-4951-9291-03d8fc97fe30}",
            "selected": false,
            "failed": false
        },
        {
            "kind": "depth-sensor",
            "model": "Kinect 2 for Windows",
            "id": "Default Kinect 2",
            "selected": true,
            "failed": true,
            "error": "Is not available"
        },    
        {
            "kind": "microphone",
            "model": "USB Camera-B4.04.27.1",
            "id": "Microphone (USB Camera-B4.04.27 [VID=-1; PID=-1; Driver=256; Channels=2; Supports=WAVE_FORMAT_11M08, ...]",
            "selected": false,
            "failed": false
        }
    ]
}

open-recorder

open-recorder selects devices for recording and switches to SETUP stage.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`selectedDevices`	string array	mandatory	List of device id strings	Selecting devices for recording. Device ids are returned by refresh-device-list command.
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-recorder"
    "arguments":
    {
        "selectedDevices":
        [
            "\\\\?\\usb#vid_1415&pid_2000&mi_00#7&2ed872d7&0&0000#{4cff9941-d72f-4951-9291-03d8fc97fe30}",
            "\\\\?\\usb#vid_1415&pid_2000&mi_00#7&1c1ec232&0&0000#{4cff9941-d72f-4951-9291-03d8fc97fe30}"
        ]
    }    
 
}
 
// Response
{
    "success":true
}

evaluate-background

evaluate-background runs background evaluation.

Tip: If parameter is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`duration`	number	optional	Integer number of seconds from 2 to 10	Setting duration of background evaluation.
`startDelay`	number	optional	Integer number of seconds from 0 to 30	Setting start delay for background evaluation.
Result
Empty result
Events
background-evaluation-stopped event is generated when background evaluation is competed or cancelled
`success`	boolean	mandatory	`true false`	Success flag. Set to `true` if background evaluation was completed successfully.
`cancelled`	boolean	mandatory	`true false`	Cancellation flag. Set to `true` if background evaluation was cancelled by user or due to error.

EXAMPLE

// Request
{
    "command": "evaluate-backgorund",
    "arguments": 
    {
        "duration": 3,
        "startDelay": 1
    }
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "background-evaluation-stopped",
    "arguments":
    {
        "success": true,
        "cancelled": false
    }
}

start-recording

start-recording starts recording.

Tip: If parameter is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	optional	Valid file path	Full path to destination file for recording.
`startDelay`	number	optional	Integer number of seconds from 0 to 60	Setting start delay for recording.
Result
Empty result
Events
recording-stopped event is generated when recording is stopped
`success`	boolean	mandatory	`true false`	Success flag. Set to `true` if background evaluation was completed successfully.
`cancelled`	boolean	mandatory	`true false`	Cancellation flag. Set to `true` if background evaluation was cancelled by user or due to error.
`filePath`	string	mandatory	Valid file path	Full path to destination file.
`fileSize`	number	mandatory	Non-negative integer	Size of the recorded file in bytes.
`duration`	string	mandatory	Timespan value in format `hh:mm:ss.sssssss`	Duration of the recording.
`frameCount`	number	mandatory	Non-negative integer	Number of the recorded frames.

EXAMPLE

// Request
{
    "command": "start-recording",
    "arguments": 
    {
        "filePath": "D:\iPiMocap\test_record.iPiVideo",
        "startDelay": 1
    }
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "recording-stopped",
    "arguments":
    {
        "success": true,
        "cancelled": false,
        "filePath": "D:\iPiMocap\test_record.iPiVideo",
        "fileSize": 39975560,
        "duration": "00:00:04.0155425",
        "frameCount": 197
    }
}

stop-recording

stop-recorder command stops recording.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
Events
recording-stopped event is generated when recording is stopped
`success`	boolean	mandatory	`true false`	Success flag. Set to `true` if background evaluation was completed successfully.
`cancelled`	boolean	mandatory	`true false`	Cancellation flag. Set to `true` if background evaluation was cancelled by user or due to error.
`filePath`	string	mandatory	Valid file path	Full path to destination file.
`fileSize`	number	mandatory	Non-negative integer	Size of the recorded file in bytes.
`duration`	string	mandatory	Timespan value in format `hh:mm:ss.sssssss`	Duration of the recording.
`frameCount`	number	mandatory	Non-negative integer	Number of the recorded frames.

EXAMPLE

// Request
{
    "command": "stop-recording"
}
 
// Response
{
    "success": true
}
 
// Event 
{
    "event": "recording-stopped",
    "arguments":
    {
        "success": true,
        "cancelled": false,
        "filePath": "D:\iPiMocap\test_record.iPiVideo",
        "fileSize": 39975560,
        "duration": "00:00:04.0155425",
        "frameCount": 197
    }
}

get-devices-state

get-devices-state returns the state and statistics for all selected devices.

Tip: This command is used to make sure recording process is ok. You can use it before and after recording.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Array of JSON objects, each representing selected device. Fields of array items:
`kind`	string	mandatory	`camera` `depth-sensor` `microfon`	Device type.
`model`	string	mandatory	Supported device model	Device model.
`id`	string	mandatory	Unique string, format depends on device model	Unique string that is used to identify recording devices in open-recorder command.
`selected`	boolean	mandatory	`true false`	Device selected status.
`failed`	boolean	mandatory	`true false`	Device failed status.
`error`	string	optional	Error message string	Error message if device is in failed status.
`statistics`	JSON object	optional		Camera statistics.
`frameRate`	number	mandatory	Double	Average frame rate.
`frameDropsPerSecond`	number	mandatory	Double	Average frame drops per second.
`badFramesPerSecond`	number	mandatory	Double	Average bad frames per second.
`totalFrameDrops`	number	mandatory	Integer	Total frame drops.
`totalBadFrames`	number	mandatory	Integer	Total bad frames.

EXAMPLE

// Request
{
    "command": "refresh-device-list"
}
 
// Response
{
    "success":true,
    "result":
    [
        {
            "kind": "camera",
            "model": "PlayStation Eye",
            "id": "\\\\?\\usb#vid_1415&pid_2000&mi_00#7&2ed872d7&0&0000#{4cff9941-d72f-4951-9291-03d8fc97fe30}",
            "selected": false,
            "failed": false,
            "statistics":
            {
                "frameRate":50.0,
                "frameDropsPerSecond":0.0,
                "badFramesPerSecond":0.0,
                "totalFrameDrops":0,
                "totalBadFrames":0
            }        
        },
        {
            "kind": "microphone",
            "model": "USB Camera-B4.04.27.1",
            "id": "Microphone (USB Camera-B4.04.27 [VID=-1; PID=-1; Driver=256; Channels=2; Supports=WAVE_FORMAT_11M08, ...]",
            "selected": false,
            "failed": false,
            "statistics":
            {
                "frameRate":50.0,
                "frameDropsPerSecond":0.0,
                "badFramesPerSecond":0.0,
                "totalFrameDrops":0,
                "totalBadFrames":0
            }        
        }
    ]
}

get-recorder-props

get-recorder-props command gets current properties for setup, background and recording stages specified in user interface.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Properties for SETUP Stage:
`videoMode`	string	mandatory	Available modes depend on camera model.	Selected RGB video mode.
`videoModeList`	string array	mandatory	List of available modes depend on camera model.	Possible `videoMode` values.
`audioMode`	string	optional	Available modes depend on microphone model.	Selected audio mode. This field is included into the response, if microphone selected.
`audeoModeList`	string array	optional	List of available modes depend on camera model.	Possible `audioMode` values. This field is included into the response, if microphone selected.
`globalDeviceProps`	JSON object	optional		Device-specific list of properties visible in “SHARED SETTINGS” section of SETUP stage.
`PlayStation Eye: Darkening for Calibration`	string	optional	`"None"` `"Darkening"` `"Extra Darkening"`	Selected darkening mode for Sony PS3 Eye cameras. This field is included into the response, if Sony PS3 Eye camera is selected.
`PlayStation Eye: Darkening for Calibration/List`	string array	optional	List of available modes	Available darkening modes for Sony PS3 Eye cameras. This field is included into the response, if Sony PS3 Eye camera is selected.
`screensInRow`	number	mandatory	Integer from 1 to number of cameras	Selected number of screens in a row for multiple camera video view.
`screenLayout`	string	mandatory	For RGB cameras: `"Color"` For depth sensors: `"Depth"` `"Picture in picture"` `"Side by side"`	Selected screen layout.
`screenLayoutList`	string array	mandatory	Available screenLayout modes.	Available screen layout modes. Depend on type of selected cameras.
Properties for BACKGROUND Stage:
`backgroundEvaluationDuration`	number	mandatory	Integer number of seconds from 2 to 10	Selected duration of background evaluation.
`backgroundEvaluationStartDelay`	number	mandatory	Integer number of seconds from 0 to 30	Selected start delay for background evaluation.
`showEvaluatedBackground`	boolean	mandatory	`true false`	Selected show background mode.
Properties for RECORD Stage:
`recordingStartDelay`	number	mandatory	Integer number of seconds from 0 to 60	Selected start delay for recording.
`hideBackgroundWhenRecording`	boolean	mandatory	`true false`	Selected hide background mode.
`destinationFilePath`	string	mandatory	Valid file path	Selected full path to destination file for recording.
`colorCompression`	string	mandatory	`"None"` `"Background subtraction"` `"JPEG"`	Selected RGB video compression mode.
`jpegQuality`	number	mandatory	integer from 0 to 100	Selected JPEG quality for JPEG compression.
`depthCompression`	string	mandatory	`"None"` `"Background subtraction"`	Selected depth compression mode.
Result
Empty result

EXAMPLE

// Request
{
    "command": "get-recorder-props"
}
 
// Response
{
    "success": true,
    "result":
    {
        "videoMode": "640x480 color @ 50Hz",
        "videoModeList":
        [
            "640x480 color @ 60Hz",
            "640x480 color @ 50Hz",
            "640x480 color @ 40Hz",
            "640x480 color @ 30Hz",
            "640x480 color @ 25Hz",
            "320x240 color @ 60Hz",
            "320x240 color @ 50Hz",
            "320x240 color @ 37Hz",
            "320x240 color @ 30Hz"
        ],
        "screensInRow": 1,
        "screenLayout": "Color",
        "screenLayoutList":
        [
            "Color"
        ],
        "globalDeviceProps":
        {
            "PlayStation Eye: Darkening for Calibration": "None",
            "PlayStation Eye: Darkening for Calibration/List":
            [
                "None",
                "Darkening",
                "Extra Darkening"
            ]
        },
        "backgroundEvaluationStartDelay": 5,
        "backgroundEvaluationDuration": 2,
        "showEvaluatedBackground": false,
        "recordingStartDelay": 1,
        "hideBackgroundWhenRecording": true,
        "destinationFilePath": "D:\iPiMocap\<time stamp>.iPiVideo",
        "colorCompression":"Jpeg",
        "jpegQuality":100,
        "depthCompression":"BackgroundSubtraction"
    }
 
}

set-recorder-props

set-recorder-props command sets properties for setup, background and recording stages.

Tip: If property is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
Properties for SETUP Stage:
`videoMode`	string	optional	Available modes depend on camera model.	Setting RGB video mode. You can see available modes in "Video Mode" combobox at SETUP stage, or get it in the result of get-recorder-props command.
`audioMode`	string	optional	Available modes depend on microphone model.	Setting audio mode. You can see available modes in "Audio Mode" combobox at SETUP stage, or get it in the result of get-recorder-props command.
`globalDeviceProps`	JSON object	optional		Device-specific list of properties visible in “SHARED SETTINGS” section of SETUP stage.
`PlayStation Eye: Darkening for Calibration`	string	optional	`"None"` `"Darkening"` `"Extra Darkening"`	Darkening mode for Sony PS3 Eye cameras
`screensInRow`	number	optional	Integer from 1 to number of cameras	Setting number of screens in a row for multiple camera video view.
`screenLayout`	string	optional	For RGB cameras: `"Color"` For depth sensors: `"Depth"` `"Picture in picture"` `"Side by side"`	Setting screen layout.
Properties for BACKGROUND Stage:
`backgroundEvaluationDuration`	number	optional	Integer number of seconds from 2 to 10	Setting duration of background evaluation.
`backgroundEvaluationStartDelay`	number	optional	Integer number of seconds from 0 to 30	Setting start delay for background evaluation.
`showEvaluatedBackground`	boolean	optional	`true false`	Show background mode on / off.
Properties for RECORD Stage:
`recordingStartDelay`	number	optional	Integer number of seconds from 0 to 60	Setting start delay for recording.
`hideBackgroundWhenRecording`	boolean	optional	`true false`	Show hide background mode on / off.
`destinationFilePath`	string	optional	Valid file path	Full path to destination file for recording.
`colorCompression`	string	optional	`"None"` `"Background subtraction"` `"JPEG"`	Setting RGB video compression mode.
`jpegQuality`	number	optional	integer from 0 to 100	JPEG quality for JPEG compression.
`depthCompression`	string	optional	`"None"` `"Background subtraction"`	Setting depth compression mode.
Result
Empty result

EXAMPLE

// Request
{
    "command": "set-recorder-props",
    "arguments":
    {
        "colorCompression": "jpeg",
	"globalDeviceProps":
        {
	    "PlayStation Eye: Darkening for calibration":"None"
        },
    "hideBackgroundWhenRecording": true,
    "recordingStartDelay": 0,
    "videoMode": "640x480 color @ 50Hz"
    }
}
 
// Response
{
    "success": true
}

Player Commands

set-player-props

set-player-props command sets properties for player.

Tip: If property is not specified in command arguments, current value in user interface will be used.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`screensInRow`	number	optional	Integer from 1 to number of cameras	Setting number of screens in a row for multiple camera video view.
`hideBackground`	boolean	optional	`true false`	Turn hide background mode on / off.
Result
Empty result

EXAMPLE

// Request
{
    "command": "set-player-props",
    "arguments":
    {
        "screensInRow": 2,
	"hideBackground": true
    }
}
 
// Response
{
    "success": true
}

open-player

open-player command opens .iPiVideo file in player.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`filePath`	string	mandatory	Valid file path	Full path to file to be opened in player.
Result
Empty result

EXAMPLE

// Request
{
    "command": "open-player",
    "arguments": 
    {
        "filePath": "D:\iPiMocap\test_record.iPiVideo"
    }
}
 
// Response
{
    "success": true
}

play-forward

play-forward starts playing video forward starting from the current frame. If current frame is the last frame playing starts from the first frame.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
playing-stopped event is generated when playing is competed (reached the last frame) or stopped by user
No event arguments

EXAMPLE

// Request
{
    "command": "play-forward"
}
 
// Response
{
    "success": true
}

play-backward

play-backward starts playing video backward starting from the current frame. If current frame is the first frame playing starts from the last frame.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result
playing-stopped event is generated when playing is competed (reached the first frame) or stopped by user
No event arguments

EXAMPLE

// Request
{
    "command": "play-backward"
}
 
// Response
{
    "success": true
}

frame-forward

frame-forward steps one frame forward. If current frame is the last frame error message returned.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "frame-forward"
}
 
// Response
{
    "success": true,
    "error": "Last frame reached"
}

frame-backward

frame-backward steps one frame backward. If current frame is the first frame error message returned.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
No arguments
Result
Empty result

EXAMPLE

// Request
{
    "command": "frame-backward"
}
 
// Response
{
    "success": true,
    "error": "First frame reached"
}

go-to-frame

go-to-frame command select current frame. If case of invalid frame index error message returned.

Parameter Name	Type	Mandatory / Optional	Allowed Values	Description
Arguments
`frameIndex`	number	mandatory	Non-negative integer	Frame index. The first frame index is 0, the last frame index is <total number of frames> - 1.
Result
Empty result

EXAMPLE

// Request
{
    "command": "go-to-frame",
    "arguments": 
    {
        "frameIndex": 27
    }
}
 
// Response
{
    "success": true
}

iPi Automation Add-on

Contents

Overview

License and Trial

Using iPi Integration Add-on

Command Syntax

iPi Recorder Commands

General Commands

get-app-info

open-studio

exit

Recording Commands

open-home-screen

refresh-device-list

open-recorder

evaluate-background

start-recording

stop-recording

get-devices-state

get-recorder-props

set-recorder-props

Player Commands

set-player-props

open-player

play-forward

play-backward

frame-forward

frame-backward

go-to-frame

Navigation menu

Personal tools

Namespaces

Variants

Views

Actions

Search

Navigation

Other Resources

Tools