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

Authentication in URL

It is possible to encode a username and password into the URL itself, so that when it's used, the web browser won't ask for login details. This can be useful, for example, if you want to password-protect your SecuritySpy server, but then make a particular camera publicly available. With SecuritySpy there are two way to do this:

The standard way to encode the username and password into the URL is like this:

http://username:password@address/resource

SecuritySpy also supports the use of an auth parameter on any resource, like this:

http://address/resource?auth=xyz

Parameters to HTML requests go after a question mark character after the resource name, and if there are multiple parameter=value pairs, they are separated by ampersand characters, for example:

http://address/resource?param1=value1&param2=value2&auth=xyz

The value of the auth parameter is the Base64-encoded version of the string username:password. So for example, to request a video stream for camera 1, where the username is user and the password is pass, the URL would be as follows:

http://address/++video?cameraNum=1&auth=dXNlcjpwYXNz