Installation
Silent install of Line can be implemented through the key“/S”(from version 7.0.5). The additional keys of Silent Mode Installation(from version 7.1.0):
/NO_KERNEL=YES ; do not install or run kernel service; ;/NO_DRIVERS=YES ; do not install drivers for video capture cards.
After version 6.6.2, Line lets you run the Observer module (including archive playback) with specific command line options.
Video stream and single frames may be acquired through Line’s webserver. This option provides the ability to integrate with third party software.
Working with observer.exe from command line
Common format
observer.exe [options] [modes] modes: --simple ; open in simplified view -a, --archive ; open in archive view -m, --allow-multiple-instances ; allow execution many instances of observer --safe-mode ; starting observer in the mode with forced display of the second stream options: -s, --server default: localhost -g, --connect-to-group no default value -p, --port default: 9780 -l, --login default: guard --pwd default: "" -c, --cam-index default: 0 ; available only in --simple mode --cam-stream default: -1 ; available only in --simple mode --pos, --window-pos coordinates format: X1 Y1 X2 Y2 ;default - last time coordinates before closing window --tray ; start program hidden in tray -t, --time date format: YYYY-MM-DD ; default - current date time format: hh:mm:ss ; default - current time -h, --help ; display help message
Comments
You can run Observer with command line options with certain arguments.
This options consist of:
- Mode-change options
- Initialization options
Options
Modes
- –simple – Simplified view mode.
Opens application for one particular cam, e.g., from third-party software. - -a, –archive – Opens application in Archive Playback mode. If aplication’s state is Observer mode, then state will be changed to playback with connection to same server.
- -m, –allow-multiple-instances – Execution another copy of observer.
- –safe-mode – starting observer with output of the second stream.
Allows to force switch pictures from the common grid cameras to the second stream
Init
- -s, –server [localhost]
If empty, then will be initiated connect to 127.0.0.1 - -g, –connect-to-group
Parameters allow specifying a group to be connected; group identifier is in the “grp_id” line of the configuration file C:ProgramDataDevLineLiniagroups.cfg or C:Documents and SettingsAll UsersApplication DataDevLineLiniagroups.cfg
Examples:
–connect-to-group 1cff07ad-dc71-498d-87e1-1ef69206d370
-g 1cff07ad-dc71-498d-87e1-1ef69206d370
When connecting to the Line Cloud account:
–connect-to-group sample@google.com
-g sample@google.com - -p, –port [9780]
Connection port. If empty, then connection will be done with standart port, 9780 - -l, –login [guard]
Default user – guard (usually, most limited user) - –pwd [“”]
User’s password. Default – empty. - -c, –cam-index [0]
Available only in –simple mode. While connecting within –simple mode Observer use local “view” (that is only one, selected cam).
By default, cam ID equal 0. - –cam-stream [-1]
Available only in –simple mode. While connecting within –simple mode Observer use local “view” (that is only one, selected cam).
By default, equal -1. - –window-pos
Postion and size of windows at start.
coordinates: X1 Y1 X2 Y2 – absolute window’s coordinates.
where (X1, Y1) – coordinates for top-left corner, and (X2, Y2) – coordinates for bottom-right corner.
By default application will be opened at same place, where it was closed last time. - –tray
Start program hidden in tray - -t, –time
WEB-Server specification
- WEB-Server specification
- Data format
- Authentication
- Resources
- Cameras
- Image
- PTZ
- Microphones
- Audio
- OSD (on-screen display)
- Archive Event (Since version 6.9.4)
- RPC (Remote Procedure Call)
- Other
- Change history
Data format
Supporting JSON or XML (UNIX format line break only) object representations (MIME-types application/json
and application/xml
). The representation will be chosen based on the analysis of the client’s request Accept header. If it is not possible to determine the desired representation from the Accept header, objects will be sent using the default view (XML).
Authentication
Proceed by HTTP Digest Authentication. Username and password must be in UTF-8 encoding.
Resources
Every resource may be described by next field sets:
URI: absolute path to resource on server.
Version: interface version, where this resource is available.
MIME-types: data type, which this resource may be represented.
Methods: methods that may be applied to this resource.
Common resource’s description, access methods to it, requests parameters, data formats etc.
Cameras
All cameras
URI: /cameras
Version: 1.2
MIME-types: application/json
, application/xml
Methods: GET
List all cameras available at server. JSON representation — objects array camera
. XML representation:
Single cam in JSON representation:
{ "uri": /* string */, "name": /* string */, "width": /* number (current resolution) */, "height": /* number (current resolution) */, "image-uri": /* string */, "video-uri": /* string */, "osd-uri": /* string */, "ptz": { "pan-tilt": { "absolute-uri": /* string */, "relative-uri": /* string */ }, "zoom": { "absolute-uri": /* string */, "relative-uri": /* string */ }, "focus": { "absolute-uri": /* string */, "relative-uri": /* string */ }, "menu": { "show-uri": /* string */, "hide-uri": /* string */, "activate-uri": /* string */, "move-uri": /* string */ }, "presets-uri": /* string */ } }
Single cam in XML representation:
Example for resource’s interaction:
GET /cameras HTTP/1.1 Host: 127.0.0.1 Accept: application/json
HTTP/1.1 200 OK Date: Mon, 23 May 2005 21:07:53 GMT Content-Type: application/json [ { "uri": "http://127.0.0.1/3r5ggsbJHke", "name": "Newton", "width": 640, "height": 480, "image-uri": "http://127.0.0.1/Ogei7uquahbohyae", "video-uri": "http://127.0.0.1/pamua8Eif4moh6ae" }, "osd-uri": "http://127.0.0.1/knnfHg6" }, { "uri": "http://127.0.0.1/7GheuI95dfghk", "name": "Newton PTZ", "width": 1280, "height": 800, "image-uri": "http://127.0.0.1/PeevupeeNgeir7eu", "video-uri": "http://127.0.0.1/EK8Shadi3fa3noe1", "osd-uri": "http://127.0.0.1/Ldh485h" }, "ptz": { "focus": { "relative-uri": "http://127.0.0.1/ahgae6Shah1oothi" }, "menu": { "activate-uri": "http://127.0.0.1/quee0tieMe1weiRa", "show-uri": "http://127.0.0.1/uGai8doosho7Ohfi", "hide-uri": "http://127.0.0.1/Fohbureit0eedoo0", "move-uri": "http://127.0.0.1/EiY3aach4Nuutha8" }, "pan-tilt": { "relative-uri": "http://127.0.0.1/isai7chahCuChait" }, "zoom": { "relative-uri": "http://127.0.0.1/quieJae7zeish3oo" }, "presets-uri": "http://127.0.0.1/neeloe2po1Hua3xa" } }, { "uri": "http://127.0.0.1/hdUneK3oe8", "name": "camera1", "width": 320, "height": 240, "image-uri": "http://127.0.0.1/ethieSho5ching4e", "video-uri": "http://127.0.0.1/cee9rahtoo4uRooh" }, "osd-uri": "http://127.0.0.1/Jy8Uj8" }, { "uri": "http://127.0.0.1/Heo89qli3J", "name": "hallway", "width": 320, "height": 240, "image-uri": "http://127.0.0.1/xohpai8jeQuohm6f", "video-uri": "http://127.0.0.1/euDaiheejiaGae3s" } "osd-uri": "http://127.0.0.1/Oje654fgbd" } ]
Image
Single frame
URI:
Version: 1.0
MIME-type: image/jpeg
, image/png
Methods: GET
Request parameters:
- quality — image quality. Set by integer from 0 (maximum compression) to 100 (maximum quality). If is not set, then using default value for this cam.
- resolution — image resolution. If is not set, then using current resolution for this cam.
- keep_aspect_ratio — keep aspect ratio: 0 – no, 1 – yes. Default 0(no).
Resource interaction example:
GET /ethieSho5ching4e?keep_aspect_ratio=1&resolution=640x480 HTTP/1.1 Host: 127.0.0.1 Accept: image/*
HTTP/1.1 200 OK Date: Mon, 23 May 2005 23:15:27 GMT Content-Type: image/jpeg Content-Length: 23185 [Image data]
M-JPEG stream
URI:
Version: 1.0
MIME-types: multipart/x-mixed-replace
, image/jpeg
Methods: GET
Request parameters:
- fps — maximum frames per second. If is not set, then using current value for cam.
- quality — image quality. Set by integer from 0 (maximum compression) to 100 (maximum quality). If is not set, then using default value for this cam.
- resolution — image resolution. If is not set, then using current resolution for this cam.
- keep_aspect_ratio — keep aspect ratio: 0 – no, 1 – yes. Default 0(no).
Resource interaction example:
GET /cee9rahtoo4uRooh?keep_aspect_ratio=0&fps=5&resolution=320x240 HTTP/1.1 Host: 127.0.0.1
HTTP/1.1 200 OK Date: Mon, 23 May 2005 23:15:27 GMT Content-Type: multipart/x-mixed-replace; boundary=xyzzy --xyzzy Content-Type: image/jpeg Content-Length: 15382 [Frame 1 data] --xyzzy Content-Type: image/jpeg Content-Length: 16105 [Frame 2 data] [и т.д.]
H.264-stream
URI:
Methods: GET
In order to get a streaming link, use stream value and stream identifier that consists of name and extension. At this point you can use the following names:
- sub – secondary stream (low resolution);
- main – primary stream (high resolution).
and the following extensions:
- flv – Flash Video;
- m3u8 – HTTP Live Streaming (HLS) playlist.
Here are some examples of streaming links (“/kfd3ado1sdrms” is uri of Camera object):
/kfd3ado1sdrms/streaming/main.flv - primary stream in Flash Video; /kfd3ado1sdrms/streaming/sub.m3u8 - secondary stream in HLS; /kfd3ado1sdrms/streaming/sub.flv - secondary stream in Flash Video; /kfd3ado1sdrms/streaming/main.m3u8 - primary stream in HLS.
If it is impossible to authorize request using standard methods (HTTP Digest/Basic Authentication), you can transfter Authorization header using one of the request parameters, for example:
/kfd3ado1sdrms/streaming/main.flv?authorization=Basic%20d2ViOg==
RTSP stream
Protocol: RTSP
Port: 9784 (default)
URI: /cameras/
Methods: OPTIONS, DESCRIBE, SETUP, TEARDOWN, PLAY, PAUSE
Limitations: Not implemented in the Windows version
To generate a link for the stream, use the camera’s serial number (
- sub – second stream (low resolution);
- main – first stream (high resolution).
Examples of stream links:
rtsp://login:@192.168.0.123:9784/cameras/0/streaming/main rtsp://login:password@192.168.0.123:9784/cameras/15/streaming/sub
For clients if it is not possible to authorise the request using standard means (HTTP Digest/Basic Authentication), the Authorization heading can be transferred by one of the request parameters, for example
rtsp://192.168.0.123:9784/cameras/2/streaming/main?authorization=Basic%20d2ViOg==
PTZ
Camera’s PTZ-control
URI:
Version: 1.0
MIME-types: application/json
, application/xml
Methods: PUT
PTZ-control prduced by record with specified objects URIs pan-tilt-data
and zoom-data
.
JSON-representation pan-tilt-data
{ "x": /* number */, "y": /* number */, "speed": /* number */ }
XML-representation:
JSON-representation zoom-data:
{ "zoom": /* number */, "speed": /* number */ }
XML-representation:
Valid values of speed
parameter are in interval [0, 1]. Parameters x
, y
and zoom
for commands of relative rotation set in abstract units – it is only -1 and +1 now.
Example — relative rotation from current position:
PUT /isai7chahCuChait HTTP/1.1 Host: 127.0.0.1 Content-Type: application/xml xml version="1.0" encoding="UTF-8"?>-1.0 0.0 1.0
HTTP/1.1 204 No Content Date: Tue, 24 May 2005 17:21:15 GMT
Example — relative scaling:
PUT /quieJae7zeish3oo HTTP/1.1 Host: 127.0.0.1 Content-Type: application/xml xml version="1.0" encoding="UTF-8"?>1.0 1.0
HTTP/1.1 204 No Content Date: Tue, 24 May 2005 17:21:37 GMT
Camera’s focus control
URI:
Version: 1.0
MIME-types: application/json
, application/xml
Methods: PUT
JSON-representation of focus data:
{ "focus": /* number */, "speed": /* number */ }
XML-representation:
Valid values of speed
parameter are in interval [0, 1]. Parameter focus
for commands of relative focus changing set in abstract units – it is only -1 and +1 now.
Example for resource’s interaction:
PUT /ahgae6Shah1oothi HTTP/1.1 Host: 127.0.0.1 Content-Type: application/json { "focus": -1.0, "speed": 1.0 }
HTTP/1.1 204 No Content Date: Tue, 24 May 2005 17:38:27 GMT
Work with Camera’s On-Screen Menu
URI:
Version: 1.0
MIME-types: application/json
, application/xml
Methods: PUT
Resources self-provide commands executed by method PUT. Into resources with activate-uri
(choice menu item), show-uri
(show menu) hide-uri
(hide menu) allowed record without request body.
Menu moving proceed by recording menu’s command into resource with move-uri
.
JSON-representation menu’s command:
{ "action": /* string */ }
XML-representation:
action="xs:string"/>
Where action valid in one of: left
, right
, up
or down
.
Example for menu’s interaction — show menu:
PUT /uGai8doosho7Ohfi HTTP/1.1 Host: 127.0.0.1
HTTP/1.1 204 No Content Date: Tue, 24 May 2005 13:28:15 GMT
Moving bottom to the next menu item:
PUT /EiY3aach4Nuutha8 HTTP/1.1 Host: 127.0.0.1 Content-Type: application/json { "action": "down" }
HTTP/1.1 204 No Content Date: Tue, 24 May 2005 13:28:19 GMT
Choice menu item:
PUT /quee0tieMe1weiRa HTTP/1.1 Host: 127.0.0.1
HTTP/1.1 204 No Content Date: Tue, 24 May 2005 13:28:22 GMT
Hide menu:
PUT /Fohbureit0eedoo0 HTTP/1.1 Host: 127.0.0.1
HTTP/1.1 204 No Content Date: Tue, 24 May 2005 13:28:24 GMT
All Cameras’ PTZ-presets.
URI:
application/json
, application/xml
Methods: GET, POST
Single Camera’s PTZ-preset.
Example for resource’s interaction:
GET /neeloe2po1Hua3xa HTTP/1.1 Host: 127.0.0.1 Accept: application/xml
HTTP/1.1 200 OK Date: Tue, 24 May 2005 17:14:16 GMT Content-Type: application/xml xml version="1.0" encoding="UTF-8"?>Unu
POST /neeloe2po1Hua3xa HTTP/1.1 Host: 127.0.0.1 Accept: application/xml Content-Type: application/xml xml version="1.0" encoding="utf-8"?>Kvar
HTTP/1.1 201 Created Date: Tue, 24 May 2005 17:14:23 GMT Content-Type: application/xml xml version="1.0" encoding="utf-8"?>Kvar http://127.0.0.1/owaSiewahch3ohch http://127.0.0.1/xie4Aoz8aqu0aigh http://127.0.0.1/laeMeef4Kariphu6 http://127.0.0.1/ahghohK4iezoovah
Single Camera’s PTZ-preset
URI:
application/json
, application/xml
Methods: DELETE, GET, PUT
JSON representation:
{ "name": /* string */, "activate-uri": /* string */, "preview-uri": /* string */, "update-uri": /* string */ }
XML representation:
Example for resource’s interaction:
GET /phiwohGh5aer0ye4 HTTP/1.1 Host: 127.0.0.1 Accept: application/json
HTTP/1.1 200 OK Date: Tue, 24 May 2005 14:39:18 GMT Content-Type: application/json { "name": "Xyzzy!", "activate-uri": "http://127.0.0.1/ju9moT7wuciiW7ae", "preview-uri": "http://127.0.0.1/eite4ohLiQu5Veoc", "update-uri": "http://127.0.0.1/WieB4ahng4ieghi9" }
PUT /phiwohGh5aer0ye4 HTTP/1.1 Host: 127.0.0.1 Accept: application/xml Content-Type: application/json { "name": "Zyxxy?", "activate-uri": "http://127.0.0.1/ju9moT7wuciiW7ae", "preview-uri": "http://127.0.0.1/eite4ohLiQu5Veoc", "update-uri": "http://127.0.0.1/WieB4ahng4ieghi9" }
HTTP/1.1 200 OK Date: Tue, 24 May 2005 14:39:37 GMT Content-Type: application/xml xml version="1.0" encoding="utf-8"?>Zyxxy? http://127.0.0.1/ju9moT7wuciiW7ae http://127.0.0.1/phiwohGh5aer0ye4 http://127.0.0.1/eite4ohLiQu5Veoc http://127.0.0.1/WieB4ahng4ieghi9
PTZ-preset’s image preview
URI:
image/jpeg
, image/png
Methods: GET
Size of preview image depends from camera.
Example for resource’s interaction:
GET /eite4ohLiQu5Veoc HTTP/1.1 Host: 127.0.0.1 Accept: image/png
HTTP/1.1 200 OK Date: Tue, 24 May 2005 11:27:16 GMT Content-Type: image/png Content-Length: 2108 [Image Data]
Microphones
All microphones
URI: /microphones
Version: 1.2
MIME-types: application/json
, application/xml
Methods: GET
List all microphones available at server.
JSON representation — objects array microphone
.
XML – representation:
Single microphone in JSON representation:
{ "uri": /* string */, "name": /* string */, "audio-uri": /* string */, "camera-uri": /* string */ }
Single microphone in XML representation:
Example for resource’s interaction:
GET /microphones HTTP/1.1 Host: 127.0.0.1 Accept: application/json
HTTP/1.1 200 OK Date: Mon, 23 May 2005 21:07:53 GMT Content-Type: application/json [ { "uri": "http://127.0.0.1/6Hjk9l4dudlf", "name": "Newton", "audio-uri": "http://127.0.0.1/Ogei7uquahbohyae", "camera-uri": "http://127.0.0.1/pamua8Eif4moh6ae" }, { "uri": "http://127.0.0.1/Pqja954nfrdqcb", "name": "Microphone1", "audio-uri": "http://127.0.0.1/ethieSho5ching4e", "camera-uri": "http://127.0.0.1/cee9rahtoo4uRooh" }, { "uri": "http://127.0.0.1/Q57mak8maogk", "name": "Hallway", "audio-uri": "http://127.0.0.1/xohpai8jeQuohm6f", "camera-uri": "http://127.0.0.1/euDaiheejiaGae3s" } ]
Audio
Audio Stream
URI:
Version: 1.1
MIME-types: audio/x-wav
, audio/mpeg
Methods: GET
Request parameters:
- sample_rate — signal sampling rate. Valid values in [8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000] Hz. If is not set. then using value equal 22050.
- bit_rate — bitrate, e.g. 128. If is not set, using 64 kbps for audio/mpeg and 22050 * 16 bps (22.05 kHz * 16 bit) for audio/x-wav.
Example for resource’s interaction:
GET /ethieSho5ching4e?sample_rate=44100&bit_rate=128 HTTP/1.1 Host: 127.0.0.1 Accept: audio/mpeg
HTTP/1.1 200 OK Date: Mon, 23 May 2005 23:15:27 GMT Content-Type: audio/mpeg [Audio data]
Audio broadcasting lasts until disconnect by any side.
OSD (on-screen display)
Creating OSD
URI:
Version: 1.5
MIME-types: application/json
, application/xml
Methods: POST
Request body in JSON representation:
{ "name": /* string */, "left": /* number */, "top": /* number */, "font-size": /* number */, "font-color": /* string */, "line-count": /* number */, "draw-background": /* number */ }
Request body in XML representation:
Output coordinates and font size set in % related to frame sizes.
Parameter
set with link like #RGB, where R, G, B – value of color parts at hex-form in interval [0..255].
Example: #FF0000, #0A5B4F.
Parameter set text background notation (blacking-out or clarification depends from luminance of text color): 0 – no notation, 1 – notate.
Success server answer on this request:
HTTP/1.1 201 Created Location: <URI OSD>
Example for resource’s interaction:
POST <osd-uri объекта Camera> HTTP/1.1 Host: 127.0.0.1 Content-Type: application/json { "name": "xyz", "left": 10, "top": 20, "font-size": 10, "font-color": "#00FF00", "line-count": 10, "draw-background": 1 }
HTTP/1.1 201 Created Date: Mon, 23 May 2005 23:15:27 GMT Location: <osd-uri объекта Camera>/xyz
Removing OSD-object
URI:
Version: 1.2
Methods: DELETE
Example for resource’s interaction:
DELETE <URI OSD-object> HTTP/1.1 Host: 127.0.0.1
HTTP/1.1 204 No content Date: Mon, 23 May 2005 23:15:27 GMT
Adding content to OSD-object
URI:
Version: 1.2
MIME-types: text/plain
Methods: POST
Example for resource’s interaction:
POST <URI OSD-объекта> HTTP/1.1 Host: 127.0.0.1 Content-Type: text/plain Content-Length: 15 Hello, world!!!
HTTP/1.1 201 Created Date: Mon, 23 May 2005 23:15:27 GMT
Removing content from OSD-object
URI:
Version: 1.2
MIME-types: text/plain
Methods: PUT
Example for resource’s interaction:
PUT <URI OSD-объекта>/clear HTTP/1.1 Host: 127.0.0.1
HTTP/1.1 204 No content Date: Mon, 23 May 2005 23:15:27 GMT
Archive Event
Create Archive Event
URI: /events
MIME-types: application/json, application/xml
Methods: POST
JSON request format:
{ "time" : /*string*/, "source" : /*string*/, "name" : /*string*/, "device": /*number*/, "data" : /*string*/ }
Parameters:
time – Archive Event start time in ISO 8601 format. Optional. Default value is the present time on the server.
source – Archive Event source. Optional. Default value is an empty string.
name – Archive Event name. Optional. Default value is an empty string.
device – Ordinal number of the camera. Optional. Default value is -1 indicating the event is not tied to any camera.
data – Archive Event data. Optional. Default value is an empty string.
Server response:
HTTP/1.1 201 Created Location: <URI Archive Event object>
JSON response example:
POST /events HTTP/1.1 Host: localhost:9786 Content-Type: application/json { "time" : "2005-08-09T18:31:42.201", "source" : "test source", "name" : "test name", "device": 0, "data" : "test data" } HTTP/1.1 201 Created Date: Mon, 23 May 2009 23:15:27 GMT Location: events/gds2w8sd1w
Location header contains the address of the Archive Event object which can be accessed later.
RPC (Remote Procedure Call)
URI: /rpc
MIME types: application/json, application/x-msgpack
Methods: POST
The resource provides easy access to the capabilities of full-blown Line server communication protocol. This protocol is used, for example, by “Observer” application. Developers should not implement the network part of the interaction and can use HTTP as transport protocol.
Data formats
Request can be transmitted using JSON (version 7.1.1 or higher) or MessagePack (version 7.0 or higher) formats. Formats of request and reply are always the same. Text encoding is UTF-8. In order to get maximal performance it is recommended to use MessagePack. All examples are presented in JSON format.
Time
Time is represented as an array of integers. Its elements represent year, month, day, hour, minute, seconds, and milliseconds respectively. If some element in the end of the array equals to zero, it can be omitted. For example, “October 30, 2016, 15:00” could not only be presented as [2016, 11, 30, 15, 0, 0, 0] but also as [2016, 11, 30, 15].
Timeline of playback
Timeline is used to determine (and represent) whether a record for a certain time period exists in acrhive or not. The minimal time period used by timeline is called timeline resolution. It is possible to get timelines with any partifular resolution starting from 1 second. Resolution may be arbitrary, for example, 10 seconds, 16 seconds, 2 minutes, 30 minutes, 7 days, etc.
Timeline examples:
- [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0] – This timeline starts on the 1st of January, 2016 and ends on the 1st of January, 2017. Its resolution is 1 month. In this case it is clear that there are records for February and March only;
- [1, 0] – This timeline starts on the 1st of January, 2016 and ends on the 1st of January, 2017. Its resolution is 6 months. In this case there are records for the first half of 2016;
- [0, 1, 0] – This timeline starts on the 1st of January, 2015 and ends on the 1st of January, 2018. In this case there are records for the year 2016;
- [0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0 , 0, 0, 0, 0, 0, 0] – This timeline represents February, 2016. There are records for the 5th and the 17th of February. Please remember that timeline for any given month always contains 31 days. So the timeline for May, June and July will contain 93 elements, where the element corresponding to the 31th of June will always be equal to zero, because such day does not exist.
- [0, 0, 0, 0, 0, 0, 1, 1, 0, 0] – This timeline starts at 00:30 March 10, 2016 and ends at 00:41 March 10, 2016. There are records for 00:36 and 00:37.
Request structure
In the case of a single request, it is an object with one required field:
- method – a method name.
and optional fields:
- params – an object with the parameters;
- id – an integer ID, which will be included in the response;
Request sample:
1{ 2 "id" : 42, 3 "method" : "some_method", 4 "params" : 5 { 6 "some_param" : "some_value" 7 } 8}
Response structure
Response also is an object, a set of fields that depends on a success of a inquiry processing:
- id – an integer ID that was contained in the request;
- result – an object with the result; It is contained in a response only in case of successful processing command;
- error – an object with information about the error.
Response sample for successful request processing:
POST /rpc HTTP/1.1 Host: 127.0.0.1 Content-Type: application/json { "method" : "sum_two_numbers", "params" : { "first" : 30, "second" : 12 } }
HTTP/1.1 200 OK Date: Tue, 07 Jun 2016 07:52:46 GMT Content-Type: application/json { "result" : { "sum" : 42 } }
Response sample where errors occurred during request processing:
POST /rpc HTTP/1.1 Host: 127.0.0.1 Content-Type: application/json { "method" : "sum_two_numbers", "params" : { "second" : 30 } }
HTTP/1.1 200 OK Date: Tue, 07 Jun 2016 07:52:46 GMT Content-Type: application/json { "error" : { "type" : "invalid_param", "message" : "first" } }
Batch requests
Server supports execution of a list of commands transmitted simultaneously. In this case, the commands should be represented as an array of single requests. Response to such request will be represented as an array of single responses, the order of which will correspond to the order of requests:
POST /rpc HTTP/1.1
Host: 127.0.0.1
Content-Type: application/json
[
{
"method" : "mul_two_numbers",
"params" :
{
"first" : 7,
"second" : 6
}
},
{
"method" : "sub_two_numbers",
"params" :
{
"first" : 30
}
}
]
HTTP/1.1 200 OK
Date: Tue, 07 Jun 2016 07:52:46 GMT
Content-Type: application/json
[
{
"result" :
{
"mul" : 42
}
},
{
"error" :
{
"type" : "invalid_param",
"message" : "second"
}
}
]
Methods list
archive.get_frames_timeline
Gets timeline.
Request parameters:
- channel – optional channel identifier; if not set, all available channels are used;
- stream – stream identifier (“video”, “video2”, “video3”, “audio”);
- start_time – begin of a timeline interval;
- end_time – end of a timeline interval;
- unit_len – a scale of a timeline unit(seconds).
Response content:
- timeline – requested timeline (see description in “Data formats” section).
Request sample for the list of days in February, 2016 where a record for at least one camera is available:
1{ 2 "method" : "archive.get_frames_timeline", 3 "params" : 4 { 5 "start_time" : [2016, 2, 1], 6 "end_time" : [2016, 3, 1], 7 "unit_len" : 86400 //the number of seconds per day 8 } 9}
Response sample:
1{ 2 "result" : 3 { 4 "timeline" : [0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0] 5 } 6}
Request sample for the list of minutes for substream archive of camera 0 on the 1st of February, 2016:
1{ 2 "method" : "archive.get_frames_timeline", 3 "params" : 4 { 5 "channel" : 0, 6 "stream" : "video2", 7 "start_time" : [2016, 2, 1], 8 "end_time" : [2016, 2, 2], 9 "unit_len" : 60 10 } 11}
Response sample:
1{ 2 "result" : 3 { 4 "timeline" : [0, 0, 1, ... , 0, 0, 1] //the array consists of 1440 elements 5 } 6}
archive.get_motions_timeline
Gets a timeline by a customised filter: by zone/s of motion detection, object size, object colors(videoanalytics at playback)
Request parameters:
- channel – optional channel identifier(if not set, all available channels are used);
- start_time – begin of time interval;
- end_time – end of time interval (duration of a time interval mustn’t be longer than 5 minuties);
- unit_len -a scale of a timeline unit(seconds);
- filter – an object contains of customized filter parameters.
Filter parameters(all parameters are optional):
- min_area – minimal size of detected object( from all size of a frame). Value(float number) from 0.0 to 1.0, for example – 0.1 for detected object not less than 10% from a size of a frame;
- max_area – maximum size of detected object;
- mask64 – 64-bit matrix 8х8 which contains 64 cells of a frame and represented as a string of 64 symbols each of them could be “0” or “1”. For example “0000000000010000000000000000000000000000000000000000000000000000”, it is requested of an existing of motion detection at the 4th cell at the 2nd row of a frame;
- colors – an array, where each elements consist of an array of 3 numbers, corresponding to RGB-elements of searching color(range [0, 255]).
Response sample:
- timeline – requested timeline (see description in “Data formats” section).
Request sample:
1{ 2 "method" : "archive.get_motions_timeline", 3 "params" : 4 { 5 "start_time" : [2016, 2, 1, 18, 0, 0], 6 "end_time" : [2016, 2, 1, 18, 5, 0], 7 "unit_len" : 60, 8 "filter" : 9 { 10 "min_area" : 0.03, 11 "colors" : [[120, 16, 23], [43, 55, 233]] 12 } 13 } 14}
Response sample:
1{ 2 "result" : 3 { 4 "timeline" : [0, 1, 0, 0, 1] 5 } 6}
archive.get_channels_list
Gets list of cameras, records for which are available in archive, for particular time interval.
Request parameters:
- start_time – begin of time interval;
- end_time – end of time interval.
Response content:
- channels – array of channels, where each element corresponds to one channel.
Every element of “channels” array contains the following fields:
- channel – channel identifier.
Request sample:
1{ 2 "method" : "archive.get_channels_list", 3 "params" : 4 { 5 "start_time" : [2016, 1, 6], 6 "end_time" : [2016, 1, 7] 7 } 8}
Response sample:
1{ 2 "result" : 3 { 4 "channels" : 5 [ 6 { 7 "channel" : 0 8 }, 9 { 10 "channel" : 1 11 } 12 ] 13 } 14}
archive.get_streams_list
Gets streams for particular camera and for particular time interval that are available in archive.
Request parameters:
- channel – channel identifier;
- start_time – begin of time interval;
- end_time – end of time interval.
Response content:
- streams – array of streams, where each elements corresponds to one stream.
Every element of “streams” array contains the following fields:
- stream – stream identifier.
Request sample:
1{ 2 "method" : "archive.get_streams_list", 3 "params" : 4 { 5 "channel" : 0, 6 "start_time" : [2016, 1, 6], 7 "end_time" : [2016, 1, 7] 8 } 9}
Response sample:
1{ 2 "result" : 3 { 4 "streams" : 5 [ 6 { 7 "stream" : "video" 8 }, 9 { 10 "stream" : "video2" 11 }, 12 { 13 "stream" : "video3" 14 }, 15 { 16 "stream" : "audio" 17 }, 18 ] 19 } 20}
archive.get_frames_list
Gets a list of frames.
Request sample:
- channel – channel identifier;
- stream – stream identifier;
- start_time – begin of time interval;
- end_time – end of time interval.
Response content:
- frames_list – array of frames, where each elements corresponds to one frame.
Every element of “frames_list” array contains the following fields:
- id – frame identifier;
- gop_index – ordinal number of a frame at GOP, 0 – I-frame;
- timestamp – frame time.
Request sample: getting list of frames for type “video” and camera 0 at 13:00 on the 1st of March 2016:
1{ 2 "method" : "archive.get_frames_list", 3 "params" : 4 { 5 "channel" : 0, 6 "stream" : "video", 7 "start_time" : [2016, 3, 1, 13, 0], 8 "end_time" : [2016, 3, 1, 14, 0] 9 } 10}
Response sample:
1{ 2 "result" : 3 { 4 "frames_list" : 5 [ 6 { 7 "id" : "f9lk3jfs42df41fsdj4", 8 "gop_index" : 12, 9 "timestamp" : [2016, 3, 1, 13, 11, 43, 543] 10 }, 11 { 12 "id" : "kdj48dh2n", 13 "gop_index" : 13, 14 "timestamp" : [2016, 3, 1, 13, 11, 43, 659] 15 }, 16 ... , 17 { 18 "id" : "ja4wds94dk34", 19 "gop_index" : 2, 20 "timestamp" : [2016, 3, 1, 13, 58, 12, 78] 21 } 22 ] 23 } 24}
archive.get_frame
Gets information about particular frame. This method supports only “application/x-msgpack” format.
Request sample:
- channel – channel identifier;
- stream – stream identifier;
- id – frame identifier.
Response content:
- frame – an object with metadata and information about a frame.
“Frame” object contains the following fields:
- info – object with information about a frame;
- raw_bytes – raw frame data.
Content of an object “info”- video request :
- timestamp – frame timestamp;
- gop_index – ordinal number of a frame at GOP;
- width (might be omited) – frame width;
- height (might be omited) – frame height;
- codec – one of the following values: “h264”, “mpeg4”, “mjpeg”.
Content of an object “info”- audio request:
- timestamp – frame timestamp;
- codec – currently the only possible value is “pcm”;
- channels – number of audio channels;
- sps – numbers of samples per second;
- bps – number of bits per second.
Request sample:
1{ 2 "method" : "archive.get_frame", 3 "params" : 4 { 5 "channel" : 0, 6 "stream" : "video", 7 "id" : "deadbeef" 8 } 9}
Response sample:
1{ 2 "result" : 3 { 4 "frame" : 5 { 6 "info" : 7 { 8 "timestamp" : [2016, 12, 23, 12, 54, 26, 943], 9 "gop_index" : 21, 10 "codec" : "h264" 11 }, 12 "raw_bytes" : ... 13 } 14 } 15}
Other
Protocol version
URI: /version
Version: 1.1
MIME-types: application/json
, application/xml
Methods: GET
Protocol version, that will support by this server. Applicable only GET method without parameters of request.
Protocol version in JSON representation:
{ "major": /* number */, "minor": /* number */ }
Protocol version in XML representation:
Example for resource’s interaction:
GET /version HTTP/1.1 Host: 127.0.0.1 Accept: application/xml
HTTP/1.1 200 OK Date: Mon, 23 May 2005 22:38:34 GMT Content-Type: application/xml xml version="1.0" encoding="utf-8"?>2 37
Change history
Version 1.0
- Names in XML representation was uniformed — lower case symbols, symbol “-” as word splitter.
- Camera’s parameters (resolution, color etc.) don’t show in camera representation.
- Determined default values for image request’s parameters (resolution, quality etc.).
- Protocol version 0.0 doesn’t support now.
Version 1.1
- Added support for “Microphone” object.
- Fixed error of describing tag name like
(in previous version was
).
Version 1.2
- Added field
into Camera object. - Added field
into Microphone object. - Added support for “OSD” object (on-screen display).
- Added field
into Camera object.
Version 1.3
- Added text color (field
) into OSD object.
Version 1.4
- Added fields
and
into Camera object. - Added parameter
keep_aspect_ratio
into Image object.
Version 1.5
- Added field
into OSD object.