*addClip

Configuration Article | CA-20220907-TP-42

VDG Sense | API | Functions | Media

This call adds a request to create a new video clip (in mp4 format). The server will generate the clips one by one from the ‘queue’ (getClips). In order to check if the clip finished, the call getClips should be used to poll for the status. When the status is finished, the call downloadClip can be used to download the clip.

Clips are unique based on serverid, deviceid, startdate, enddate, imagewidth, and imageheight. If exactly the same request is done twice, the server will return the first clip object and won’t start a new request.

The parameters ‘imagewidth’ and ‘imageheight’ resize/transcode the original video to the requested resolution. The time of creating a clip will increase when transcoding is required.

  • If one of the parameters is omitted, it will resize according to the original ratio.

  • If both parameter are sent with the request, it will add black bars to the bottom/top or sides and keeps the ratio of the video intact.

  • If both parameters are omitted, it will export the original resolution.

  • The width and height will be rounded to a power of 16.

  • The minimum width and height is 128 pixels.

  • The maximum width and height is the original resolution of the video stream.

Clips will be deleted based on their retention size and time. By default, clips will be removed after seven days or when the clip folder exceeds 1 GB. You can set this retention size and time in the native client under ‘Advanced settings’ in the ‘Server’ tab. To manually remove a clip from a server, use the call deleteClip.

Note: This function requires VDG Sense version 2.5.4 or higher

Request

command=addClip&serverid=[UID]&deviceId=[UID]&description=[String]&startdate=[timestamp]&enddate=[timestamp]&vca=[string]

Parameter

type

remarks

Parameter

type

remarks

serverid

[UID]

unique server id

deviceid

[UID]

unique device id

description

[string]

a user defined description

startdate

[timestamp]

UTC startdate of event clip

enddate

[timestamp]

UTC enddate of event clip

imagewidth

[number]

optional for transcoding

imageheight

[number]

optional for transcoding

vca

[none, alarms, objects, all]

include or exclude VCA metadata

Response

<result errorcode="0">   <clip>     <id>[UID]</id>     <serverid>[UID]</serverid>     <deviceid>[UID]</deviceid>     <startdate>[timestamp]</startdate>     <enddate>[timestamp]</enddate>     <description>[string]</description>     <filesize>[number]</filesize>     <imagewidth>[number]</imagewidth>     <imageheight>[number]</imageheight>     <status description="&#91;string&#93;">[string]</status>   </clip> </result>

 

node

value

remarks

node

value

remarks

/result

@errorcode

[number]

See error codes below

/result/clip

id

[UID]

unique id

serverid

[UID]

unique server id

deviceid

[UID]

unique device id

startdate

[timestamp]

Clips with a UTC timestamp >= startdate are returned.

enddate

[timestamp]

Clips with a UTC timestamp < = enddate are returned.

description

[string]

A user defined description

filesize

[number]

Size of the clip in bytes

imagewidth

[number]

Width of the clip in pixels

imageheight

[number]

Height of the clip in pixels

status

[string]

'pending', 'busy', 'finished', or 'failed'

error code

description

remarks

error code

description

remarks

0

Ok

Ok, no error

-2

No device

 No device found for the supplied cameraid/deviceid.

-4

Invalid Timestamp.

Invalid datetime format. See Timestamp.

-17

No server

There is no server with the supplied id.

-18

General error

An undefined error occurred.

-33

No serverID

No serverID parameter given.

-34

No deviceID

No deviceID parameter given.

-35

No startdate

No startdate parameter given.

-36

No enddate

No enddate parameter given.

-37

enddate before startdate

Enddate parameter is before the startdate parameter.

-38

Clip time to long

Enddate is >5 minutes than startdate.

See Also

Changelog

  • Sense 2.5.8 – Added vca parameter

  • 2.7.2 – Added