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 videoexport

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

Deleting a pending videoexport:

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 exportid’s 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.

Result:

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

In case of error:

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

Changelog

2.7.3 - Introduced

exportVideo

Request

Response

Related

Changelog