*addClip

Configuration Article | CA-20220907-TP-42

VDG Sense | API | Functions | Media

1 Request
2 Response
3 See Also
4 Changelog

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.

Changelog

Sense 2.5.8 – Added vca parameter
2.7.2 – Added

Request

Response

See Also

Changelog