addClip

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