Cinegy Capture 24.1 REST API Manual

Reading time ~7 minutes

General Information

Capture REST API allows you to use both data types: JSON and XML. The data format sent should be indicated with the appropriate 'Content-Type' HTTP header, while the data format requested should be indicated with the appropriate 'Accept' HTTP header.
The base URL to access the Capture engine via REST API has the following format: http://<engine_host>:<8000+n>/REST where 'n' is the Capture engine number [1…9].

POST Methods

Capture Session Start

Name

Start

Method

POST

URL

http://localhost:8001/REST/Start

Description

Start the capture session with the pre-loaded template.

Usage

function Start() {
    $.ajax({
        url: "http://localhost:8001/REST/Start",
        type: "POST",
    });
}

Capture Session Stop

Name

Stop

Method

POST

URL

http://localhost:8001/REST/Stop

Description

Stop the current capture session.

Capture Session Split

Name

Split

Method

POST

URL

http://localhost:8001/REST/Split

Description

Split the target file(s) and create a new Roll in Cinegy Archive.

Capture Session Configuration

Name

LoadJob

Method

POST

URL

http://localhost:8001/REST/LoadJob

Message Body

String: Capture profile XML

Description

Set up the capture session by passing the job profile as the XML.

Capture Session Configuration by Template ID

Name

LoadJobById

Method

POST

URL

http://localhost:8001/REST/LoadJobById

Message Body

String: Template ID (GUID)

Description

Set up the capture session by using the template with the specified ID.

Usage

function LoadTemplate(id) {
    $.ajax({
        url: "http://localhost:8001/REST/LoadJobById",
        type: "POST",
        contentType: "application/json",
        data: JSON.stringify(id),
    });
}

Capture Session Start by Template ID

Name

StartByJobTemplateId

Method

POST

URL

http://localhost:8001/REST/StartByJobTemplateId

Message Body

String: Template ID (GUID)

Caution

If Template ID is not specified in the parameters, the StartByJobTemplateId method will use the default template, set in Cinegy Capture Control.

Description

Start the capture session by using the template with the specified ID.

Capture Session Start by Template ID and Custom Metadata

Name

StartByJobTemplateIdEx

Method

POST

URL

http://localhost:8001/REST/StartByJobTemplateIdEx

Message Body

{
   "TemplateId": "<TEMPLATE-ID>",
   "CustomMetadata":
    [
       {"Name": "FileName", "Value": "<FILE-NAME-PATTERN"},
       {"Name": "ClipName", "Value": "<CLIP-NAME>"},
       {"Name": "TapeName", "Value": "<TAPE-NAME>"}
    ]
}

Note	All parameters in the `CustomMetadata` group are optional and may be omitted.

Caution

If Template ID is not specified in the parameters, the StartByJobTemplateIdEx method will use the default template, set in Cinegy Capture Control.

Description

Start the capture session by using the template with the specified ID and defined custom metadata.

GET Methods

Get Info

Name

Info

Method

GET

URL

http://localhost:8001/REST/Info

Response

API version
engine version

Response Example

Response example (application/json):

{
  "APIVersion": 2,
  "EngineVersion": "24.1.174.31529",
}

Get Capture Engine Status

Name

Status

Method

GET

URL

http://localhost:8001/REST/Status

Response

Engine status as a serialized object (CaptureStatus)

Description

Return the detailed Capture engine status (see Table 1.1).

Table 1.1: CaptureStatus Type Members

CaptureStatus	Types
ErrorDescription	String
HasLicense	Bool
JobShortState	JobShortState (see Table 1.2)
RtpPreviewsForWS	Enumerable of RtpPreviewForWS (see Table 1.3)
JobStatus	String
PreviewState	String
Status	String
Timecode	String
TVFormatInfo	TVFormatInfo (see Table 1.4)

CaptureStatus

Types

ErrorDescription

String

HasLicense

Bool

JobShortState

JobShortState (see Table 1.2)

RtpPreviewsForWS

Enumerable of RtpPreviewForWS (see Table 1.3)

JobStatus

String

PreviewState

String

Status

String

Timecode

String

TVFormatInfo

TVFormatInfo (see Table 1.4)

Table 1.2: JobShortState Type Members

JobShortState	Types
ErrorDescription	String
Id	Guid
Status	JobStatusType enum (see Table 1.5)
DroppedFramesCount	Uint
RepairedFramesCount	Uint
ProcessedFramesCount	Uint
TimecodeBreaksCount	Uint
StartTimecode	String
CurrentTimecode	String
StopTimecode	String
CreatedTime	DateTime
StartedTime	Nullable DateTime
CompletedTime	Nullable DateTime
PercentageCompleted	Uint
ElapsedDuration	TimeSpan

JobShortState

Types

ErrorDescription

String

Guid

Status

JobStatusType enum (see Table 1.5)

DroppedFramesCount

Uint

RepairedFramesCount

Uint

ProcessedFramesCount

Uint

TimecodeBreaksCount

Uint

StartTimecode

String

CurrentTimecode

String

StopTimecode

String

CreatedTime

DateTime

StartedTime

Nullable DateTime

CompletedTime

Nullable DateTime

PercentageCompleted

Uint

ElapsedDuration

TimeSpan

Table 1.3: RtpPreviewForWS Type Members

RtpPreviewForWS	Types
RTPPreviewURL	String
MulticastSourceIP	Bool
WebSocketPort	Int

RtpPreviewForWS

Types

RTPPreviewURL

String

MulticastSourceIP

Bool

WebSocketPort

Int

Table 1.4: TVFormatInfo Type Members

TVFormatInfo	Types
AspectRatio	Size (see Table 1.6)
FrameRate	Double

TVFormatInfo

Types

AspectRatio

Size (see Table 1.6)

FrameRate

Double

Table 1.5: JobStatusType Enum Type Members

Pending

Ready

Started

Completed

Failed

Table 1.6: Size Type Members

Measurement	Types
Width	Int
Height	Int

Measurement

Types

Width

Int

Height

Int

Usage

function getStatus() {
    $.ajax(
    {
        url: "http://localhost:8001/REST/Status",
        type: "GET",
        dataType: ‘json’,
        contentType: ‘application/json’,
        success: onGetStatusSuccess,
        cache: false,
    });
  }

function onGetStatusSuccess(response) {
 if(response.responseJSON != null) {
  console.log(response.responseJSON.JobShortState);
 }
}

Response Example

{
	ErrorDescription: ""
	HasLicense: true
	JobShortState: {
		CompletedTime: "/Date(1445488435000)/"
		CreatedTime: "/Date(1445499234927)/"
		CurrentTimecode: "00:02:10:08"
		DroppedFramesCount: 0
		ElapsedDuration: "PT0S"
		ErrorDescription: "SSCR_ProcessingError"
		Id: "0f31487c-c807-4482-a3e7-d6c41e480a56"
		PercentageCompleted: 0
		ProcessedFramesCount: 2
		RepairedFramesCount: 0
		StartTimecode: "00:02:10:07"
		StartedTime: "/Date(1445488435000)/"
		Status: 4
		StopTimecode: "00:02:10:09"
		TimecodeBreaksCount: 0
	}
	JobStatus: "Failed"
	PreviewState: "Started"
	RtpPreviewsForWS: [1]
	{
		MulticastSourceIP: "192.168.10.107"
		RTPPreviewURL: "rtp://239.1.1.182:1234"
		WebSocketPort: 10010
	}
	Status: "Ready"
	TVFormatInfo:
	{
		AspectRatio:
		{
			height: 9
			width: 16
		}
		FrameRate: 29.97
	}
	Timecode: "04:10:46:27"
}

Get Capture Engine Preview

Name

Preview

Method

GET

URL

http://localhost:8001/REST/Preview

Response

Image: Engine real-time feedback preview

Description

Return the real-time preview from the Capture engine.

Usage

<img id="preview" />
...
function updateImagePreview() {
     ‘http://localhost:8001/REST/Preview?cacheHack=’ + new Date().getTime();
 $(‘#preview’).attr(‘src’, imageSrc);
}

Get Templates List

Name

JobTemplates

Method

GET

URL

http://localhost:8001/REST/JobTemplates

Response

Capture templates list

Description

Return the enumerated list of available capture templates as "Id" / "Name" pairs on the server.

Usage

function getTemplates() {
    var templates = $.ajax(
    {
        url: "http://localhost:8001/REST/JobTemplates",
        type: "GET",
        dataType: ‘json’,
        success: onGetJobTemplatesSuccess,
        cache: false,
        crossDomain: true,
    });
    return templates;
}

function onGetJobTemplatesSuccess(response) {
 if (response.responseJSON != null) {
  var templates = response.responseJSON;

  console.log(templates);
 }
}

Response Example

{
	Id: "84dc0061-ff61-466f-8487-cf39928b9162"
	Name: "UHD MPEG-2 Long 80Mb"
}
{
	Id: "8d421e4f-6621.4-400a-a414-19876b3d9781"
	Name: "MP4 4k"
}
{
	Id: "87bd3b9d-e0d5-44cd-8ff4-ffc9e779ce58"
	Name: "MP4"
}
{
	Id: "60f7c410-ae4c-46de-904b-d9674c9a2eb9"
	Name: "Stand"
}
{
	Id: "c6a691ef-c7e2-4f63-b0dd-67c173972a92"
	Name: "XDCAM HD 50"
}
{
	Id: "57206284-296a-41d2-afb8-f99f31030226"
	Name: "OPAtom"
}
{
	Id: "ceadfa16-bd3d-4f5b-bbad-db3918134db6"
	Name: "MAM Rushes"
}
{
	Id: "81600477-de5f-420c-b87d-b9c5aff21eb9"
	Name: "S"
}
{
	Id: "0fba421.49-2a00-483c-9fa9-8e71662bf6d1"
	Name: "UHD MPEG-2 Long + Mpeg Audio"
}

Get Template Details

Name

JobTemplate

Method

GET

URL

http://localhost:8001/REST/JobTemplate?id={templateId}

Response

Capture template details

Description

Return the capture template details as an XML text.

Usage

function getTemplate(id) {
    var template = $.ajax(
    {
        url: "http://localhost:8001/REST/JobTemplate?id=" + id,
        type: "GET",
        dataType: ‘json’,
        success: onGetJobTemplateSuccess,
        cache: false,
        crossDomain: true,
    });
    return template;
}

function onGetJobTemplateSuccess(response) {
 if (response.responseJSON != null) {
  var templateContent = response.responseJSON;

  console.log(templateContent);
 }
}

Response Example

{
<JobConfiguration>
  <AudioMapping i:nil="true"/>
  <BreakType i:nil="true"/>
  <EncodeTasks>
   <EncodeTask>
    ....
   </EncodeTask>
  </EncodeTasks>
  <EncoderWrapperMap>
   <MapItem>
    <DestinationId>f5d3a090-fdec-407a-b9b2-1f7d1cdc14c1</DestinationId>
    <SourceId>896c643e-593a-4785-b76c-bdc698a41d47</SourceId>
   </MapItem>
  </EncoderWrapperMap>
  <FileName i:nil="true"/>
  <FilterEncoderMap i:nil="true"/>
  <FilterTasks i:nil="true"/>
  <Id>383bdabe-a114-4f23-8817-d1e911121.4851</Id>
  <Metadata>
   ....
  </Metadata>
  <StartType i:nil="true"/>
  <StopType i:nil="true"/>
  <TimecodeAnalyzer>
   <MaxTCInconsistency>3</MaxTCInconsistency>
   <MinTCConsistent>2</MinTCConsistent>
  </TimecodeAnalyzer>
  <WrapTasks>
   ....
  </WrapTasks>
 </JobConfiguration>
}

Get Job Info

Name

Job Info

Method

GET

URL

http://localhost:8001/REST/Job

Response

Detailed information about the loaded/running/previous task.

Description

Return detailed information about the task loaded by the last calling the "LoadJob" or "LoadJobById" method. The following information is provided: template configuration, synchronization status, job parameters, timecode report, etc.

Response Example

Response example (application/json):

{
"DetailedInfo":{"Configuration":{"AudioMapping":........."StopTimecode":null,"TimecodeBreaksCount":0}
}

Get Job Triggers

Name

Job Triggers

Method

GET

URL

http://localhost:8001/REST/Job/Triggers

Response

Return triggers of the loaded/running/previous task.

Description

Return triggers of the task loaded by the last call to the "LoadJob" or "LoadJobById" method.

This method returns start/stop triggers as well as automatic split intervals for the pre-loaded Cinegy Capture task.

Response Example

Response example (application/json):

{
  "Break": {
    "TimeType": "Timecode",
    "Value": "01:00:00:00"
  },
  "Start": {
    "TimeType": "Timecode",
    "Value": "14:00:00:00"
  },
  "Stop": {
    "TimeType": "Timecode",
    "Value": "15:00:00:00",
    "AsDuration": false,
  }
}

Parameters

Start – defines the start time of the task.

Stop – defines the stop time of the task.

Break – defines the auto-split time. If this parameter is not set, the task will not be split.

The "TimeType" parameter can be defined as "Timecode" with a value in HH:MM:SS:FF format or "Time" with the value set as HH:MM:SS.

PUT Method

Get Job Triggers

Name

Job Triggers

Method

PUT

URL

http://localhost:8001/REST/Job/Triggers

Response

Change/Update triggers of the loaded/running task.

Description

Update triggers of the task loaded by the last call to the "LoadJob" or "LoadJobById" method.

By default, the Cinegy Capture task has manual start and stop triggers and starts by receiving the "Start" command. However, in some cases, it is required to start or stop the task at the dedicated time automatically. This method allows updating start/stop triggers as well as setting automatic split intervals for the pre-loaded Cinegy Capture task.

Request Example

Request example (application/json):

{
  "Break": {
    "TimeType": "Timecode",
    "Value": "01:00:00:00"
  },
  "Start": {
    "TimeType": "Timecode",
    "Value": "14:00:00:00"
  },
  "Stop": {
    "TimeType": "Timecode",
    "Value": "15:00:00:00",
    "AsDuration": false
  }
}

Parameters

Start – defines the start time of the task. If "TimeType" is defined as "Timecode", its value should be set as HH:MM:SS:FF.

Stop – defines the stop time of the task. If the "AsDuration" parameter is set to true, this time defines the task duration rather than the end time of the task. Note that you can call this method when the capture task is already running to change its end time.

Break – defines the auto-split time. If this parameter is not set, the task will not be split.

All parameters are optional and can be passed in any combination.

Note	If you change the "Start" task trigger after calling the "LoadJob" or "LoadJobById" method, you do not need to call the "Start" command – the task will start automatically according to the new value of the "Start" trigger.