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
date format: YYYY-MM-DD ; default – current date
time format: hh:mm:ss ; default – current time
This time using as start point for archive playback.
If you set this option while -p (port) equal observer work port (kernel.exe), but not playback work port (oopnet.exe), it will be ignored.

WEB-Server specification

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//streaming/
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 () and stream name (), which can have two values:

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:

Version: 1.0 MIME-types: 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

http://127.0.0.1/OhX7iet9aithoofu

http://127.0.0.1/doo3ree1aef8Vudo

http://127.0.0.1/eer7vei9thoa4Eik

http://127.0.0.1/keenoo3IthoP4zai

http://127.0.0.1/xee9uz7Aich4tuga

http://127.0.0.1/gool9hieR3iu5hoh

http://127.0.0.1/ingae4ooCh8ahb4a

http://127.0.0.1/ohxuof4Su7ekiuDi

Tri

http://127.0.0.1/Uosuu4aivuuchei4

http://127.0.0.1/Atejae1baeD6Ku4A

http://127.0.0.1/Sheip2ooXohd1Phe

http://127.0.0.1/haurieP9chosaif4

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:

Version: 1.0 MIME-types: 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:

Version: 1.0 MIME-types: 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: /clear
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.

Installation

Working with observer.exe from command line

Common format

Comments

Options

Modes

Init

WEB-Server specification

Data format

Authentication

Resources

Cameras

All cameras

Image

Single frame

M-JPEG stream

H.264-stream

RTSP stream

PTZ

Camera’s PTZ-control

Camera’s focus control

Work with Camera’s On-Screen Menu

All Cameras’ PTZ-presets.

Single Camera’s PTZ-preset

PTZ-preset’s image preview

Microphones

All microphones

Audio

Audio Stream

OSD (on-screen display)

Creating OSD

Removing OSD-object

Adding content to OSD-object

Removing content from OSD-object

Archive Event

Create Archive Event

RPC (Remote Procedure Call)

Data formats

Time

Timeline of playback

Request structure

Response structure

Batch requests

Methods list

archive.get_frames_timeline

archive.get_motions_timeline

archive.get_channels_list

archive.get_streams_list

archive.get_frames_list

archive.get_frame

Other

Protocol version

Change history

Version 1.0

Version 1.1

Version 1.2

Version 1.3

Version 1.4

Version 1.5

Supports