exportVideo

Configuration Article | CA-20240119-MF-20

VDG Sense | API | Functions | Media

1 Request
2 Response
3 Related
4 Changelog

Note:

This function requires an API license
Introduced in VDG Sense version 2.7.3

The exportVideo command can be used to create video exports in native format on the VDG Sense server. These exports can be stored on the server itself or on a user specified drive location such as a mapped network drive. They can not be downloaded directly via the API.

The exportVideo requires the POST method, with additional parameters in XML format as described below.
Using this command, it is possible to create an export of multiple cameras in one API request, each camera with independed start and end times as described in the <devices> node of the XML body.

Special care must be taken when including xml specific characters. These are ‘&’, ‘<' en '>‘. The ampersand (‘&’) character can not be sent by this command because it will be part of the URL. See next paragraph.

As the value of this event is in the query part of an URL, the ampersand character (‘&’) cannot be part of it. It must be URL Encoded. See i.e. http://www.w3schools.com/TAGS/ref_urlencode.asp. The best practive is to URL Encode the complete value.

Request

The exportVideo API function can be used in two ways:

To create a video export.
To remove a pending video export.

Creating a video export

POST exportVideo
<!--?xml version="1.0" ?-->
<export>
  <devices>
    <device>
      <serverid>[UID]</serverid>
      <deviceid>[UID]</deviceid>
      <starttime>[timestamp]</starttime>
      <endtime>[timestamp]</endtime>
    </device>
    <device>
    ...
    </device>
  </devices>
  <path>[path]</path>
  <bandwidth>[bandwidth]</bandwidth> 
</export>

The parameters in the XML body should be of the following format:

parameters	type	remarks

parameters	type	remarks
serverid	[UID]	Unique server id
deviceid	[UID]	Unique device id
starttime	[timestamp]	UTC Timestamp (format: yyyy-mm-dd hh:nn:ss.zzz)
endtime	[timestamp]	UTC timestamp (format: yyyy-mm-dd hh:nn:ss.zzz)
path	[string]	Path (on the server) to where the video is exported to, if the folder doesn’t exist it will be created
bandwidth	[value]	[optional] If the storage path is connected via a metered connection, then it’s possible to add a maximum bandwidth value here in bytes per second. If a value of 0 is used, it will try to copy with maximal available bandwith

Although it is possible to export video for multiple serverid+deviceid pairs in one exportVideo request, special care must be taken. If one of the serverid+deviceid pairs is not valid. I.e. serverid or deviceid does not exist. The whole video export will be cancelled.

Advice is to always check validity of serverid+deviceid pair via getDeviceList.

Removing a pending video export:

Post a request using the DELETE method, where exportid is the id of the export to be deleted.

127.0.0.1/command?command=exportVideo&exportid=[exportid]

Response

The server will return an exportid if the export is in progress. If it fails it will return an error message.

The exportids will only be valid during the currently open API session. After that, it will be reset to 1. Also after a SensePluginManager reset it will be reset to 1.

Result:

<!--?xml version="1.0" ?-->
<result errorcode="0">
  <export> 
    <exportid>[exportid]</exportid>
  </export> 
</result>

In case of error:

<!--?xml version="1.0" ?-->
<result errorcode="[error code]"> 
  <description>[description]</description>
</result>

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.
-33	No serverID	No serverID parameter given.
-34	No deviceID	No deviceID parameter given.
-37	Enddate before startdate	Enddate parameter is before the startdate parameter.
-48	No videodata for timestamp	No videodata for the given timestamp
-57	No exportid	in case of a DELETE, exportid needs to be added to the request
-58	Incorrect path	path does not exist
-60	Not enough disk space	there is not enough space to store the video in supplied path
-61	Unable to create directory	The directory could not be created on the server

Please note that the Sense Player (needed to playback exported video) is not part of the video export. It must be downloaded separately via this link: VDG Sense 2.7 downloads

Changelog

2.7.3 - Introduced

exportVideo

Request

Response

Related

Changelog