*addClip
- Tom Polman
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 |
|---|---|---|
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="[string]">[string]</status>
  </clip>
</result> |
Â
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 |
|---|---|---|
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