Follow us @bensoftware

SecuritySpy

Multi-camera video surveillance software for the Mac

Back to help


Web Server Specification

This document describes the web server interface of SecuritySpy version 4. Both HTTP and RTSP services run from the same port (which by default is 8000 for HTTP/RTSP and 8001 for HTTPS/RTSPS) This is an advanced document and basic knowledge of HTTP and RTSP is assumed. Parameters in [square brackets] are optional.


HTML page containing live video or still images (HTTP)

Request format
++live?cameraNum=<camera1>[&cameraNum=<camera2>][&imageSize=<size>][&req_fps=<fps>][&viewMethod=<method>]

Parameters
<camera1>, <camera2> etc. are the numbers of the cameras to display
<size> is the size of the images, either in format "640x480" or "scale2" (double size) or "scale0.5" (half size)
<fps> the requested frame rate of the video streams
<method> the viewing method of images on the page, one of the following numbers:

0
Auto - SecuritySpy will try to detect the browser's capabilities and will choose a viewing method to suit
3
JavaScript JPEG (works on all web browsers; audio only)
4
Server-push JPEG stream (works on most web browsers; audio only)
5
Still JPEG images (works on all web browsers)
7
HTTP Live Streaming (works in Safari only; audio and video)

Example
++view?cameraNum=0&cameraNum=2&cameraNum=3&imageSize=640x480&method=0

Returned data
A HTML page containing live images from the cameras you specify.


Still JPEG image (HTTP)

Request format
++image?cameraNum=<camera>[&width=<width>][&height=<height>][&quality=<quality>]

Parameters
<camera>
is the number of the camera, as displayed in the Camera Info window
<width> is the width of the image in pixels
<height> is the height of the image in pixels
<quality> is the compression quality in the range 1 to 100

Example
++image?cameraNum=0&width=640&height=480&quality=50

Returned data
A single JPEG image for the specified camera.


Multipart JPEG "server push" video stream (HTTP)

Request format
++video?cameraNum=<camera>[&width=<width>][&height=<height>][&quality=<quality>][&req_fps=<fps>]

Parameters
<camera>
is the number of the camera, as displayed in the Camera Info window
<width> is the width of the image in pixels
<height> is the height of the image in pixels
<quality> is the compression quality in the range 1 to 100
<fps> is the FPS of video that SecuritySpy will attempt to send

Example
++video?cameraNum=0&width=640&height=480&quality=50&req_fps=10

Returned data
A multipart-mixed-replace JPEG stream, as follows:

HTTP/1.1 200 OK\r\n
Server: BBVS\r\n
Content-Type: multipart/x-mixed-replace;boundary=ssBoundary8345\r\n
\r\n
--ssBoundary8345\r\n
Content-Type: image/jpeg\r\n
Content-Length: 21325\r\n
\r\n
<JPEG image data>\r\n
--ssBoundary8345\r\n
Content-Type: image/jpeg\r\n
Content-Length: 22128\r\n
\r\n
<JPEG image data>\r\n
........

Note
This method currently doesn't work in Internet Explorer but is supported by most other browsers.


H.264 stream (RTSP)

Request format
++stream?cameraNum=<camera>&codec=<codec>[&width=<width>][&height=<height>][&req_fps=<fps>]

Parameters
<codec> video compression codec - currently the only supported value is h264
<camera> is the number of the camera, as displayed in the Camera Info window
<width> is the width of the image in pixels
<height> is the height of the image in pixels
<fps> is the FPS of video that SecuritySpy will attempt to send

Example
++stream?cameraNum=0&codec=h264

Returned data
An H.264 RTSP video stream, which can be received by any player that supports RTSP streams, such as VLC.


Audio GET (HTTP)

Request format
++audio?cameraNum=<camera>

Parameters
<camera>
is the number of the camera, as displayed in the Camera Info window

Example
++audio?cameraNum=0

Returned data
A G.711 μ-law 8000kHz mono audio stream, as follows:

HTTP/1.1 200 OK\r\n
Server: BBVS\r\n
Content-Type: audio/basic\r\n
\r\n
<audio data>


Audio POST for two-way audio (HTTP)

Request format
++audio?cameraNum=<camera>

Parameters
<camera>
is the number of the camera, as displayed in the Camera Info window

Example
++audio?cameraNum=0

POST data
A G.711 μ-law 8000kHz mono audio stream, which SecuritySpy will forward to the specified camera.


PTZ controls HTML page (HTTP)

Request format
++ptz/controls?cameraNum=<camera>

Parameters
<camera>
is the number of the camera, as displayed in the Camera Info window

Example
++ptz/controls?cameraNum=0

Returned data
An HTML page with buttons to control the PTZ of the specified camera.


PTZ command (HTTP)

Request format
++ptz/command?cameraNum=<camera>&command=<command>[&speed=<speed>]

Parameters
<camera>
is the number of the camera, as displayed in the Camera Info window
<speed> is the speed of movement, from 1-100 (supported in SecuritySpy 4.0.11 and later)
<command> is the command to execute, which is a number as follows:

1
Left   12 Preset 1   112 Save preset 1
2
Right   13 Preset 2   113 Save preset 2
3
Up   14 Preset 3   114 Save preset 3
4
Down   15 Preset 4   115 Save preset 4
5
Zoom in   16 Preset 5   116 Save preset 5
6
Zoom out   17 Preset 6   117 Save preset 6
7
Home   18 Preset 7   118 Save preset 7
8
Up-left   19 Preset 8   119 Save preset 8
9
Up-right            
10
Down-left            
11
Down-right   99 Stop movement      

Example
++ptz/command?cameraNum=0&command=7

Returned data
"OK" as text if the command was accepted by SecuritySpy.

Note
Command 99 to stop movement is only applicable to cameras that support continuous-motion PTZ and require this additional command to stop the movement after it is started. For other cameras that support movement in individual steps, this command does nothing.


Arm or Disarm Continuous Capture (HTTP)

Request format
++ssControlContinuousCapture?cameraNum=<camera>&arm=<armFlag>

Parameters
<camera>
is the number of the camera
<armFlag> 1 to arm or 0 to disaram

Example
++ssControlContinuousCapture?cameraNum=0&arm=1

Returned data
HTTP 303 redirect to the referer page, or if no referer page, the text "The control message was received OK".


Arm or Disarm Motion Capture (HTTP)

Request format
++ssControlMotionCapture?cameraNum=<camera>&arm=<armFlag>

Parameters
<camera>
is the number of the camera
<armFlag> 1 to arm or 0 to disaram

Example
++ssControlContinuousCapture?cameraNum=0&arm=1

Returned data
HTTP 303 redirect to the referer page, or if no referer page, the text "The control message was received OK".


Arm or Disarm Actions (HTTP)

Request format
++ssControlActions?cameraNum=<camera>&arm=<armFlag>

Parameters
<camera>
is the number of the camera
<armFlag> 1 to arm or 0 to disaram

Example
++ssControlContinuousCapture?cameraNum=0&arm=1

Returned data
HTTP 303 redirect to the referer page, or if no referer page, the text "The control message was received OK".


Get Camera Modes (HTTP)

Request format
++cameramodes?cameraNum=<camera>

Parameters
<camera>
is the number of the camera

Example
++cameramodes?cameraNum=0

Returned data
Three lines of plain text that specifies the armed status of Continuous Capture, Motion Capture and Actions respectively. For example:

C:ARMED
M:DISARMED
A:ARMED

NOTE: Depending on the version, SecuritySpy may use either a Line Feed (10) or Carriage Return (13) between lines.


Trigger motion-detection for a camera (HTTP)

Request format
++triggermd?cameraNum=<camera>

Parameters
<camera>
is the number of the camera

Example
++triggermd?cameraNum=0


HTML/XML page containing links to captured video footage (HTTP)

Request format
++download?cameraNum=<camera1>[&cameraNum=<camera2>][&fileTypeMenu=<type>][&ageText=<age>]
[&date1Text=<date1>][&date2Text=<date2>][&format=<format>]

Parameters
<camera1>
, <camera2> etc are the numbers of the cameras to be included in the list of footage
<type> a one-character indicator of what kinds of files to list:

m
Movie files only
i
Image files only
b
Both movie files and image files

<age> The maximum age of files to list, in days
<date1>, <date2> A date range for files to list, in the format "DD/MM/YY"
<format> The format of the returned data: "html" or "xml"

Example
++download?cameraNum=0&cameraNum=2&fileTypeMenu=b&ageText=5

Returned data
An HTML or XML page containing a list of files that match the search criteria, with download links to the the files themselves.


HTML/XML page containing list of sounds (HTTP)

Request format
++sounds[?format=<format>]

Parameters
<format> The format of the returned data: "html" or "xml"

Returned data
An HTML or XML page with a list of sounds installed in the SecuritySpy server with links. Clicking on a link will play the sound on the server computer.


HTML/XML page containing list of scripts (HTTP)

Request format
++scripts[?format=<format>]

Parameters
<format> The format of the returned data: "html" or "xml"

Returned data
An HTML or XML page with a list of scripts installed in the SecuritySpy server with links. Clicking on a link will run the script on the server computer.


PTZ capabilities (HTTP)

Request format
++getptzcapabilities?cameraNum=<camera>

Parameters
<camera>
is the number of the camera

Example
++getptzcapabilities?cameraNum=0

Returned data
A text page containing a single number, which is the sum of the following constants:

1 Pan and Tilt
2 Home
4 Zoom
8 Presets

So for example if the number returned is 9, this means the camera support Pan, Tilt, and Presets, but not Home or Zoom.


System Information (HTTP)

Request format
++systemInfo

Returned data
An XML document listing details of available cameras (all cameras that the client has authentication to view).

Example
<?xml version="1.0" encoding="utf-8"?>
<system>
    <server>
            <name>SecuritySpy</name>
            <version>4.0</version>
    </server>
    <cameralist>
        <camera>
            <number>0</number>
            <name>ComputerCam</name>
            <connected>yes</connected>
            <width>640</width>
            <height>480</height>
            <mode-c>armed</mode-c>
            <mode-m>armed</mode-m>
            <mode-a>disarmed</mode-a>
            <hasaudio>no</hasaudio>
            <ptzcapabilities>0</ptzcapabilities>
            <devicename>iSight</devicename>
            <devicetype>Local</devicetype>
        </camera>
        <camera>
            <number>1</number>
            <name>Front Door</name>
            <connected>yes</connected>
            <width>1200</width>
            <height>800</height>
            <mode-c>armed</mode-c>
            <mode-m>armed</mode-m>
            <mode-a>armed</mode-a>
            <hasaudio>yes</hasaudio>
            <ptzcapabilities>11</ptzcapabilities>
            <devicename>Axis Network Camera</devicename>
            <devicetype>Network</devicetype>
            <address>192.168.1.10</address>
            <port>80</port>
        </camera>
    </cameralist>
</system>

Camera parameters
<number> the camera number
<name> the camera name
<connected> whether this camera is connected (yes or no)
<width> the pixel with of this camera's video
<height> the pixel height of this camera's video
<mode-c> whether Continuous Capture mode is armed
<mode-m> whether Motion Capture mode is armed
<mode-a> whether Actions mode is armed
<hasaudio> whether the camera is associated with an active audio input (yes or no)
<ptzcapabilities> a constant describing the PTZ capabilities of the camera - see the "PTZ capabilities" request above
<devicename> the name of the underlying video device
<devicetype> the type of device this is: Network, Local or DV
<address> the network address (network devices only)
<port> the network port (network devices only)


Event Stream (HTTP)

Request format
++eventStream

Returned data
A stream of plain text lines, each terminated by a carriage return, that provides live events for all cameras. Each line is as follows:

[TIME] [EVENT NUMBER] [CAMERA NUMBER] [EVENT]

[TIME] is specified in the order year, month, day, hour, minute, second and is always 14 characters long
[EVENT NUMBER] increases by 1 for each subsequent event
[CAMERA NUMBER] specifies the camera that this event relates to, for example CAM15 for camera number 15
[EVENT] describes the event: ARM_C, DISARM_C, ARM_M, DISARM_M, ARM_A, DISARM_A, ERROR, CONFIGCHANGE, MOTION, OFFLINE, ONLINE

Example
20140927091955 10 CAM0 ARM_C
20140927091955 11 CAM15 ARM_M
20140927092026 12 CAM0 MOTION
20140927091955 13 CAM0 DISARM_M
20140927092031 14 CAM17 OFFLINE