Our software > SecuritySpy > Help > Web Server Specification
SecuritySpy 
Multi-camera CCTV software for the Mac
Web Server Specification
This document describes the web server interface of the latest version of SecuritySpy 6. Both HTTP and RTSP services run from the same port (which by default is 8000 for HTTP/RTSP and 8001 for HTTPS/RTSPS). All below requests use the HTTP protocol unless otherwise specified. This is an advanced document and knowledge of HTTP and HTML is assumed. Parameters in [square brackets] are optional.
▸ Live video
Note: you can use the URL Generator function, available from the Window menu in SecuritySpy, to easily create media URLs.
HTTP multipart "server push" video stream
Request format
video?cameraNum=X[&width=X][&height=X][&quality=X][&fps=X][&vcodec=X]
Parameters
cameraNum - the number of the camera, as displayed in the Camera Info window
width - the width of the image in pixels
height - the height of the image in pixels
quality - the compression quality in the range 1 to 100
fps - the FPS of video that SecuritySpy will attempt to send
vcodec - the video codec:
• jpeg (default; the only codec that works in HTML img tags)
• h264
• h265
• h26x (the server chooses between H.264 and H.265)
Example
video?cameraNum=0&width=640&height=480&quality=50&fps=10
Returned data
A multipart-mixed-replace video-only 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, with JPEG codec, works in all major browsers, using an HTML <img> tag. The H.264/H.265 variants are custom formats without standard browser support. The full specification that describes this stream can be found in the document SecuritySpy Video Stream Specification.
RTSP video/audio stream
Request format
stream?cameraNum=X[&width=X][&height=X][&fps=X][&vcodec=X][&acodec=X]
Parameters
cameraNum - the number of the camera, as displayed in the Camera Info window
width - the width of the image in pixels
height - the height of the image in pixels
fps - the frame rate of the video that SecuritySpy will attempt to send
vcodec - the video codec:
• h264 (default)
• h265
• h26x (the server chooses between H.264 and H.265)
acodec - the audio codec
• aac (default)
• ulaw
• pcm
• none (to disable audio)
Example
stream?cameraNum=0
Returned data
An RTSP video/audio stream, which can be received by any RTSP player, such as VLC.
Note
SecuritySpy supports TCP Interleaved transport only (not UDP).
When using a client like VLC, make sure to use a URL that starts with the protocol specifier rtsp://
HTTP Live Streaming video/audio stream
Request format
hls?cameraNum=X
hls_mediaplaylist?&cameraNum=X&quality=X
The hls stream is an adaptive stream, where the client can switch between different quality settings depending on current bandwidth conditions, whereas the hls_mediaplaylist stream is of a fixed quality.
Parameters
cameraNum - the number of the camera, as displayed in the Camera Info window
quality - stream resolution/bandwidth (0 - low, 1 - medium, 2 - high)
Examples
hls?cameraNum=0
hls_mediaplaylist?cameraNum=0&quality=2
Returned data
An H.264 HTTP Live Streaming video/audio stream, which can be used in Safari within an HTML <video> tag.
Still JPEG image
Request format
image?cameraNum=X[&width=X][&height=X][&quality=X]
Parameters
cameraNum - the number of the camera, as displayed in the Camera Info window
width - the width of the image in pixels
height - the height of the image in pixels
quality - 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 from the specified camera.
HTML page containing a grid of live cameras
Request format
multiplex?cameras=X[&cropMode=X][&format=X][&fps=X][&border=X][&camInfo=X][&hiRes=X]
Parameters
cameras: a comma-separated list of cameras to include
cropMode: 0 - black bars, 1 - crop, 2 - stretch
format: 0 - JPEG, 1 - H.264/H.265
fps: maximum frame rate to be used of each video stream
border: width in pixels of black border around the whole page
camInfo: 1 to include a camera information bar at the top of each feed
hiRes: 1 for double-resolution feeds (useful for retina screens)
Example
multiplex?cameras=4,5,6,9&cropMode=1&format=0&border=10
Returned data
A HTML page containing a grid of live video feeds from the cameras you specify.
▸ Live audio
Audio GET
Request format
audio?cameraNum=X
Parameters
cameraNum - 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
Request format
audio?cameraNum=X
Parameters
cameraNum - 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.
▸ Captured footage
HTML/XML page containing links to captured footage
Request format
download?cameraNum=X[&cameraNum=X][&ccFilesCheck=X][&mcFilesCheck=X][&imageFilesCheck=X][&ageText=X][&date1Text=X][&date2Text=X][&format=X][&results=X][&continuation=X]
Parameters
cameraNum - the camera number(s) (more than one can be specified)
ccFilesCheck - specify 1 to include continuous-capture files
mcFilesCheck - specify 1 to include motion-capture files
imageFilesCheck - specify 1 to include still (JPEG) image files
ageText - the maximum age of files to list, in days
date1Text, date2Text - A date range (format corresponds to the setting in SecuritySpy's General Settings)
format - the format of the returned data: "list", "grid" or "xml"
results - the maximum number of files to return (if not specified, up to 200 files will be returned)
continuation - the continuation value specified in the data returned by the last call to download (see below)
Using the continuation parameter (XML only)
There is a limit of the number of files that will be returned with each call to download (this limit can specified via the results parameter described above). If there are more files available that meet the specified search criteria, a <bsl:continuation> value will be included in the head of the returned XML page. Subsequently, to obtain the next batch of files matching the search criteria, make the same request again, but this time include this continuation value as a parameter to the download call. You can repeat this process until there are no further files to obtain, which will be indicated when the returned XML page does not contain a continuation value.
Example
download?cameraNum=0&cameraNum=2&ccFilesCheck=1&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.
Download a file
Request format
getfile?cameraNum/date/filename (default download)
getfilehb?cameraNum/date/filename (high-bandwidth download)
getfilelb?cameraNum/date/filename (low-bandwidth download)
Parameters
cameraNum - the number of the camera
date - the date in the format YYYY-MM-DD
fileName - the URL-encoded name of the file
In reality, you would not construct these parameters from scratch: the data returned by the download request contains full requests for each file.
Example
getfile/1/2019-01-22/22-01-2019+13-13-36+M+Street.m4v
Returned data
The requested file.
▸ PTZ
PTZ controls HTML page
Request format
ptz/controls?cameraNum=X
Parameters
cameraNum - 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
Request format
ptz/command?cameraNum=X&command=X[&speed=X]
Parameters
cameraNum - the number of the camera, as displayed in the Camera Info window
speed - the speed of movement, from 1-100
command - 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.
Note
Command 99 is only applicable to cameras that support continuous movement. For cameras that support movement in individual steps, this command does nothing.
PTZ capabilities
Request format
getptzcapabilities?cameraNum=X
Parameters
cameraNum - the number of the camera
Example
getptzcapabilities?cameraNum=0
Returned data
A text page containing a single number that indicates which PTZ capabilities the camera supports. To interpret this number, convert it to binary (most calculators have this feature). Each binary digit represents a capability, where 1 means supported and 0 means not supported:
| Binary digit | Value | Capability |
|---|---|---|
| 1st (rightmost) | 1 | Pan/Tilt |
| 2nd | 2 | Home |
| 3rd | 4 | Zoom |
| 4th | 8 | Presets |
| 5th | 16 | Speed control |
| 6th | 32 | Continuous movement |
For example, if the returned number is 37, converting to binary gives 100101. Reading from right to left: the 1st, 3rd, and 6th digits are 1, meaning the camera supports Pan/Tilt, Zoom, and Continuous movement.
Note on continuous movement: If the 6th digit is 1, you must issue a "Stop movement" command (99) after any move or zoom command (1-11 in the PTZ command table above).
▸ Scheduling
Set a schedule and/or schedule override for a camera
Request format
setSchedule?cameraNum=X&schedule=X&override=X&mode=X
Parameters
cameraNum - the number of the camera, or -1 for all cameras
schedule - which schedule to set, as follows:
| 0 | Unarmed 24/7 |
| 1 | Armed 24/7 |
| 2 | Armed Sunrise To Sunset |
| 3 | Armed Sunset To Sunrise |
| Custom schedule IDs can be obtained from the System Information data (see below) | |
| 0 | No override |
| 1 | Unarmed Until Next Scheduled Event |
| 2 | Armed Until Next Scheduled Event |
| 3 | Unarmed For 1 Hour |
| 4 | Armed For 1 Hour |
| 5 | Unarmed For 2 Hours |
| 6 | Armed For 2 Hours |
| 7 | Unarmed For 3 Hours |
| 8 | Armed For 3 Hours |
| 9 | Unarmed For 4 Hours |
| 10 | Armed For 4 Hours |
| 11 | Unarmed For 5 Hours |
| 12 | Armed For 5 Hours |
| 13 | Unarmed For 6 Hours |
| 14 | Armed For 6 Hours |
mode - the mode(s) to set the schedule for, as follows:
| C | Continuous-capture mode |
| M | Motion-capture mode |
| A | Actions mode |
Example
setSchedule?cameraNum=0&schedule=1&override=0&mode=CA
Returned data
"OK" as text if the command was accepted.
Invoke a schedule preset
Request format
setPreset?id=X
Parameters
id - the schedule preset to invoke, as obtained from the System Information data (see below)
Example
setPreset?id=100
Returned data
"OK" as text if the command was accepted.
Get Camera Modes
Request format
cameramodes?cameraNum=X
Parameters
cameraNum - 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.
▸ Settings
Settings are split into the following sections, each with its own separate request. All strings are UTF-8 unless otherwise specified.
- Settings are changed with an HTTP POST whose body is application/x-www-form-urlencoded (key=value pairs separated by &, with each value URL-encoded).
- Only the parameters that are included are changed; everything else keeps its current value.
- A successful POST returns the JSON {"result":"OK"}, except where noted below (settings-web and settings-cameras).
- Boolean parameters accept 1, yes or true (lower case) for true; any other value means false.
- A GET of each section with format=json returns the same keys that the POST accepts (plus a few read-only ones, which the POST ignores), so a client can GET the settings, modify them and POST them back (see Obtaining Current Settings below).
- All settings requests require an Administrator account (or no web accounts to be set up). The one exception is a single camera's settings: the POST to settings-cameras, and its GET with cameraNum and format, are also allowed for an account that has the Set camera settings permission for that camera.
- Requests authenticated with an API key can't POST to settings-web. They also can't set the setPass, fsPass and quitPass passwords or a camera's aShellCommand text, which are silently left unchanged, and the shell command text is returned empty on GET.
- If the Use legacy web interface option is enabled, prefix these requests with /v6/, for example /v6/settings-general.
Lists
Groups, schedules, schedule presets, upload destinations and web accounts are lists of items. Each list is set by posting one key per item (group, sched, preset, upload or account), each holding one item as a JSON object, for example group={...}&group={...}.
- The posted items replace the whole list. To add, change or remove one item, GET the list, modify it, and post back every item that should remain.
- If the key is left out, the list is unchanged.
- Posting the key once with an empty value (for example group=) deletes all items.
- Each item has an ID (groupId, scheduleId, presetId, serverId or accountId), which identifies an existing item to keep or modify. For a new item, use an ID of 0 (or leave it out) and SecuritySpy assigns a new unique one; GET the list afterwards to find it.
- IDs must be unique within a list: SecuritySpy assigns new IDs only for 0 or missing IDs, and doesn't fix duplicates.
- A GET with format=json returns each list as a JSON array, under groups, schedules, presets, uploads or accounts. To post a list back, send each array element as its own group= (etc.) parameter, URL-encoded.
- Each item is rebuilt from what is posted: any key left out of an item takes its default value (0, false or empty), so always post complete items.
- Passwords are never returned by GET. An item posted without a password, or with the placeholder value **************** (16 asterisks), keeps its existing password.
- Items that aren't valid JSON objects are ignored.
The list examples below are shown before URL-encoding, for readability.
General
Request format
HTTP POST to settings-general with any of the following parameters:
| sysName | System name |
| autoReopen | Restart automatically after a crash (0/1) |
| allowSleep | Allow automatic computer sleep (0/1) |
| dismissAlerts | Dismiss alert messages after one minute (0/1) |
| sendDiagnostics | Share diagnostic information with developer (0/1) |
| suspendDecoding | Suspend video decoding when not needed (0/1) |
| errPopup | Pop-up messages for important errors (0/1) |
| msgPopup | Pop-up messages for features and licensing (0/1) |
| updatePopup | Pop-up messages for software updates (0/1) |
| smartSearch | Enable Smart Search (0/1); requires an Apple Silicon Mac with 16 GB of memory and macOS 14 or later |
| dateFormat | Date format (0 - Day/Month/Year, 1 - Month/Day/Year, 2 - Year/Month/Day, 3 - Year/Day/Month, 4 - Day-Month-Year, 5 - Month-Day-Year, 6 - Year-Month-Day, 7 - Year-Day-Month) |
| timeFormat | Time format (0 - 24-hour, 1 - 12-hour) |
| thumbCrop | Motion thumbnail crop (0-100, where 0 is tightest and 100 is widest) |
| setPass | Password to open the Settings window in SecuritySpy on the Mac (empty for none; POST only) |
| fsPass | Password to exit full-screen mode (empty for none; POST only) |
| quitPass | Password to quit the application (empty for none; POST only) |
Example
sysName=Home+CCTV&autoReopen=1&dateFormat=6&timeFormat=0
Audio
Request format
HTTP POST to settings-audio with any of the following parameters:
| previewAudioDevice | Output device for playing live audio from cameras: the UID of a macOS audio output device, or empty for the system default |
| previewVolSetType | Set device volume before playing live audio (0 - don't set, 1 - set to previewVolSetVal) |
| previewVolSetVal | Volume to set before playing live audio (1-100) |
| hissReduction | Hiss reduction (mute low-level audio) (0/1) |
| twoWayAudioDevice | Input device for sending live audio to cameras: the UID of a macOS audio input device, or empty for the system default |
| twoWayAudioVol | Volume for sending live audio to cameras (1-250, where 100 is full volume) |
| muteIncoming | Mute incoming audio when sending (0/1) |
| actionsAudioDevice | Output device for Actions alert sounds: the UID of a macOS audio output device, or empty for the system default |
| actionsVolSetType | Set device volume before playing alert sounds (0 - don't set, 1 - set to actionsVolSetVal) |
| actionsVolSetVal | Volume to set before playing alert sounds (1-100) |
| actionsVolResetType | Reset device volume after playing alert sounds (0 - don't reset, 1 - reset to actionsVolResetVal, 2 - reset to original value) |
| actionsVolResetVal | Volume to reset to after playing alert sounds (0-100) |
Example
actionsVolSetType=1&actionsVolSetVal=80&actionsVolResetType=2&hissReduction=1
Display
Request format
HTTP POST to settings-display with any of the following parameters:
| floatVideo | Float video windows over other applications (0/1) |
| kioskMode | Go full screen at launch and after inactivity (kiosk mode) (0/1) |
| lowRate | Reduce live video display frame rate (0/1) |
| highlight | Highlight motion in video windows (0/1) |
| highlightColour | Video highlight colour (0 - yellow, 1 - red, 2 - orange, 3 - pink, 4 - blue, 5 - purple, 6 - white) |
| infoBar | Info bar in video windows (0 - none, 1 - small, 2 - medium, 3 - large, 4 - jumbo) |
| infoName | Show camera name in the info bar (0/1) |
| infoFps1 | Show incoming frame rate in the info bar (0/1) |
| infoFps2 | Show display frame rate in the info bar (0/1) |
| infoAudio | Show audio controls in the info bar (0/1) |
| infoStatus | Show arming/recording status in the info bar (0/1) |
| autoClose | Auto-close windows (0 - none, 1 - video windows, 2 - video and Camera Control windows, 3 - all non-video windows, 9 - all windows) |
| autoCloseMins | Minutes after last user activity to auto-close windows |
| cropMode | Framing (0 - draw black bars around images, 1 - crop images to fill, 2 - stretch images to fill) |
| displayQuality | Display quality (0 - auto, 1 - low, 2 - medium, 3 - high, 4 - best) |
| divThickness | Divider line thickness in pixels |
| replaySeconds | Instant video replay duration in seconds |
| group | A camera group (a list; see Lists above), up to 32 groups |
Each group item is a JSON object with the following keys:
| groupId | Group ID (1-255; 0 for a new group) |
| name | Group name |
| displayType | Display type (0 - cameras in a grid, 1 - cycle between each camera, 2 - cycle between groups of four cameras) |
| cycleSeconds | Cycle time in seconds, for the cycle display types |
| cameras | Array of the camera numbers in the group |
A GET also returns each group's columnCount and visible values, which are read-only.
Example
highlight=1&highlightColour=1&autoClose=1&autoCloseMins=10
group={"groupId":1,"name":"Outside","displayType":0,"cycleSeconds":10,"cameras":[0,2,3]}&group={"groupId":0,"name":"Inside","displayType":1,"cycleSeconds":5,"cameras":[1,4]}
Scheduling
Request format
HTTP POST to settings-sched with any of the following parameters:
| sunriseOffset1 | Sunrise offset in minutes for the Armed Sunrise To Sunset schedule (may be negative) |
| sunsetOffset1 | Sunset offset in minutes for the Armed Sunrise To Sunset schedule (may be negative) |
| sunriseOffset2 | Sunrise offset in minutes for the Armed Sunset To Sunrise schedule (may be negative) |
| sunsetOffset2 | Sunset offset in minutes for the Armed Sunset To Sunrise schedule (may be negative) |
| sched | A custom schedule (a list; see Lists above) |
| preset | A schedule preset (a list; see Lists above) |
Each sched item is a JSON object with the following keys:
| scheduleId | Schedule ID (5-65535; 0 for a new schedule). IDs 0-4 are reserved for the built-in schedules (see below) |
| name | Schedule name |
| objects | Array of armed time periods, each a [start, end] pair in minutes from Monday 00:00 (0-10080). A mode is armed from start up to end; a period whose start is after its end wraps around from Sunday to Monday |
A GET also returns each schedule's objectCount, which is read-only.
Each preset item is a JSON object with the following keys:
| presetId | Preset ID (0 for a new custom preset). IDs 1-4 are the security-mode presets Home, Away, Night and Off, whose names are fixed (a posted name is ignored); these can also be applied from the Apple Home app. IDs 5-16 are reserved, and custom presets have IDs of 17 or above |
| name | Preset name (custom presets only) |
| clearOverrides | Clear schedule overrides when applying this preset (true/false) |
| homeTrigger | ID of a HomeKit trigger that applies this preset (via HomeHelper), or 0 for none |
| cameras | Array of objects, one per camera that the preset changes, each with these keys: |
| cameraNum | The camera number |
| ccScheduleId | Schedule to apply to Continuous Capture |
| mcScheduleId | Schedule to apply to Motion Capture |
| aScheduleId | Schedule to apply to Actions |
Each schedule ID in a preset is one of the following, or the ID of a custom schedule. -1 (or leaving the key out) means that the preset doesn't change that mode.
| 0 | Disarmed 24/7 |
| 1 | Armed 24/7 |
| 2 | Armed Sunrise To Sunset |
| 3 | Armed Sunset To Sunrise |
A GET also returns a whichEnabledFlag value for each preset camera, which is read-only. To apply a preset, see Invoke a schedule preset under Scheduling above.
Example
This replaces all schedules with two: an existing one, and a new one that is armed 09:00-17:00 Monday to Friday. It also replaces all presets with a single Night preset, which arms Motion Capture and Actions for camera 0, and Actions only for camera 1.
sched={"scheduleId":2817,"name":"Weekends","objects":[[7200,10080]]}&sched={"scheduleId":0,"name":"Office Hours","objects":[[540,1020],[1980,2460],[3420,3900],[4860,5340],[6300,6780]]}&preset={"presetId":3,"clearOverrides":true,"homeTrigger":0,"cameras":[{"cameraNum":0,"ccScheduleId":-1,"mcScheduleId":1,"aScheduleId":1},{"cameraNum":1,"aScheduleId":1}]}
Storage
Request format
HTTP POST to settings-storage with any of the following parameters:
| primaryStorage | Path to the primary storage location (an existing folder), or empty for the default location |
| archiveStorage | Path to the archive storage location (an existing folder), or empty for none |
| archiveMode | Archive mode (0 - move files when primary is full, 1 - copy files immediately when complete, 2 - fallback only (no archiving)) |
| removeBySpace | Remove old files below free space threshold (0/1) |
| removeGbSys | Free space threshold on the system volume in GB (0 for automatic) |
| removeGbNonSys | Free space threshold on other volumes in GB (0 for automatic) |
| removeByAge | Permanently delete files after specified age (0/1) |
| removeAgeSys | Age in days after which to delete files on the system volume |
| removeAgeNonSys | Age in days after which to delete files on other volumes |
| tag-N | Exclude files with Finder tag colour N from deletion (0/1), where N is 1 - grey, 2 - green, 3 - purple, 4 - blue, 5 - yellow, 6 - red, 7 - orange |
| diskWaitTime | Volume mount timeout in seconds |
| usageWarningGb | Usage warning threshold in GB |
Example
primaryStorage=/Volumes/Cameras&removeBySpace=1&removeGbSys=0&removeGbNonSys=0&removeByAge=1&removeAgeSys=30&removeAgeNonSys=90&tag-6=1
Compression
Request format
HTTP POST to settings-compression with any of the following parameters:
| videoCodec | Video codec for movie files, for cameras set to recompress video (0 - ProRes 422 HQ, 1 - ProRes 422, 2 - ProRes 422 LT, 3 - ProRes 422 Proxy, 4 - JPEG, 5 - H.264, 6 - H.265) |
| videoQuality | Video quality (1-100) |
| audioCodec | Audio codec for movie files, for cameras set to recompress audio (0 - none, 1 - Apple Lossless, 2 - μ-Law, 3 - AAC) |
| audioQuality | Audio quality (1-100) |
| jpegQuality | Quality for still images, email attachments and web streams (1-100) |
Example
videoCodec=5&videoQuality=50&audioCodec=3&jpegQuality=60
Uploads
Request format
HTTP POST to settings-uploads with the following parameter:
| upload | An upload destination (a list; see Lists above) |
Each upload item is a JSON object with the following keys:
| serverId | Destination ID (0 for a new destination); cameras refer to destinations by this ID |
| name | Destination name |
| protocol | Protocol (0 - FTP, 1 - FTPS (FTP with TLS), 2 - SFTP, 3 - Amazon S3, 4 - local file system copy) |
| address | Server address (FTP/FTPS/SFTP), or optional endpoint (S3) |
| username | Username (FTP/FTPS/SFTP), or access key ID (S3) |
| password | Password (FTP/FTPS/SFTP), or secret access key (S3); not returned by GET |
| bucket | Bucket name (S3 only) |
| path | Path on the server, empty for the server's default location (all protocols); for a local copy, the path of the destination folder on this Mac |
| appendCamName | Append camera name to path (true/false) |
| appendDirName | Append day folder name to path (true/false) |
Example
upload={"serverId":0,"name":"Backup NAS","protocol":2,"address":"nas.local","username":"cctv","password":"secret","path":"backup","appendCamName":true,"appendDirName":true}
Request format
HTTP POST to settings-email with any of the following parameters:
| subject | Subject text for motion-triggered emails, or empty for automatic (placeholders: +s system name, +n camera name, +t trigger description, +d date) |
| mediaType | Media attachment (0 - still image files, 1 - movie file) |
| maxRes | Maximum resolution, in tenths of a megapixel (0 - unlimited, 80 - 8 MP, 70, 60, 50, 40, 30, 20, 10, 5, 3 - 0.3 MP) |
| imageCount | Number of frames per email |
| fps | Frame capture rate in frames per second |
| highlightMotion | Highlight motion in first frame (0/1) |
| preferMotion | Prefer frames with motion (0/1) |
| sysEmail | Recipients of system emails (comma-separated addresses) |
| errEmailLevel | Error reports (0 - none, 1 - all errors and warnings, 2 - all errors, 3 - critical errors only) |
| statsEmail | Summaries of daily activity (0/1) |
| downtimeEmail | Alerts when this system goes offline (0/1) |
| sendingMethod | Send emails using (0 - email relay service, 1 - SMTP server) |
| address | SMTP server address |
| fromName | SMTP 'From' name |
| fromEmail | SMTP 'From' email |
| username | SMTP username |
| password | SMTP password (not returned by GET; the placeholder **************** leaves it unchanged) |
| encryption | SMTP encryption (0 - none, 1 - implicit, 2 - explicit) |
Example
sysEmail=me@example.com&errEmailLevel=3&sendingMethod=1&address=smtp.example.com&fromName=CCTV&fromEmail=cctv@example.com&username=cctv@example.com&password=secret&encryption=2
Web
Request format
HTTP POST to settings-web with any of the following parameters (not available to requests authenticated with an API key):
| http | HTTP enabled (0/1) |
| portHttp | HTTP port (1024 or above) |
| https | HTTPS enabled (0/1) |
| portHttps | HTTPS port (1024 or above, different from the HTTP port) |
| autoNatHttp | Auto-configure router for HTTP Internet access (0/1) |
| autoNatHttps | Auto-configure router for HTTPS Internet access (0/1) |
| ddnsName | Dynamic DNS name: the name part of name.viewcam.me (3-15 characters), or empty for none |
| log | Write log file of all connections (0/1) |
| bonjour | Advertise this web server via Bonjour (0/1) |
| sessionLen | Login session duration in seconds (0 - until web browser is quit, 900, 1800, 3600, 10800, 21600, 43200, 86400, 172800, 432000, 604800, 864000, 1296000, 2592000) |
| hlsMaxFps | HLS maximum frame rate (0 for no limit) |
| hlsMaxRes | HLS maximum resolution, in tenths of a megapixel (0 - unlimited, 80 - 8 MP, 70, 60, 50, 40, 30, 20, 10, 5, 3 - 0.3 MP) |
| geoblockType | Geoblock (0 - off, 1 - allow listed locations only, 2 - block listed locations) |
| geoblockList | Geoblock locations: two-letter ISO country codes run together without separators, e.g. GBFRDE; continents are XA - Asia, XE - Europe, XF - Africa, XM - North America, XO - Oceania, XS - South America |
| account | A web account (a list; see Lists above) |
Each account item is a JSON object with the following keys:
| accountId | Account ID (0 for a new account) |
| username | Username |
| password | Password (not returned by GET; can't begin with API_) |
| permissionType | Permission type (0 - per-camera custom permissions, 1 - Live, 2 - Live, Captures, 3 - Live, Captures, Control, 4 - Administrator, 5 - per-group custom permissions) |
| permissions | For permission types 0 and 5 only: array of permission bitmasks (see below). Element 0 applies to all cameras. For type 0, element N+1 applies to camera number N; for type 5, element N applies to the group with groupId N. Missing elements mean no permissions |
| maxSeconds | Live duration limit in seconds (0 for no limit) |
| maxFps | Live frame rate limit (0 for no limit) |
| maxRes | Live resolution limit, in tenths of a megapixel (0 - unlimited, 80 - 8 MP, 70, 60, 50, 40, 30, 20, 10, 5, 3 - 0.3 MP) |
| maxAge | Captures age limit in days (0 for no limit) |
| timedAccess | Restrict access to a daily time range (true/false) |
| startTime | Start of the daily access period, as "hh:mm" (24-hour, server's local time) |
| endTime | End of the daily access period, as "hh:mm"; must be later than startTime |
| apiKey | API key: API_ followed by exactly 32 letters and digits to set a key, or empty to remove it; any other value, or leaving it out, keeps the existing key (not returned by GET) |
Each permission bitmask is the sum of any of the following:
| 1 | Get live video and images |
| 4 | Get captured footage |
| 8 | Delete captured footage |
| 16 | Set camera settings |
| 64 | Camera Control (PTZ) |
| 128 | Change schedules |
| 256 | Set PTZ preset positions |
| 512 | Get live audio |
| 1024 | Trigger motion detection |
| 2048 | Send live audio (two-way audio) |
| 4096 | Hide download options |
A GET returns hasApiKey for each account, which says whether it has an API key; the key itself is never returned.
Important: as the posted accounts replace all existing accounts, always include the account you are using. A successful POST returns {"result":"OK","reload":1}, and connections for any account that was changed or removed are closed.
Example
This keeps an existing Administrator account (with its password and API key unchanged), and adds an account that can view camera 0 (live video), and camera 1 (live video and audio):
https=1&portHttps=8001&autoNatHttps=1&sessionLen=86400&account={"accountId":1846262,"username":"admin","password":"****************","permissionType":4,"maxSeconds":0,"maxFps":0,"maxRes":0,"maxAge":0,"timedAccess":false,"startTime":"00:00","endTime":"00:00"}&account={"accountId":0,"username":"guest","password":"secret","apiKey":"","permissionType":0,"permissions":[0,1,513],"maxSeconds":0,"maxFps":0,"maxRes":0,"maxAge":0,"timedAccess":false,"startTime":"00:00","endTime":"00:00"}
Cameras
Request format
HTTP POST to settings-cameras with cameraNum and any of the following parameters. A successful POST returns the camera's number and (possibly updated) name, as JSON, for example {"camUpdate":{"num":"3","name":"Front Door"}}. A camera number that isn't in use returns a 404 error.
| cameraNum | The camera number (REQUIRED) |
| deviceType | The camera's device type (0 - local device, 1 - network camera, 3 - video file, 4 - screen capture); GET only, as the device type can't be changed with this request |
| Device (network cameras) | |
| address | Address (IP address or hostname) |
| portHttp | HTTP port (0 for the default) |
| sslHttp | Use SSL for HTTP connections (0/1) |
| portRtsp | RTSP port (0 for the default) |
| sslRtsp | Use SSL for RTSP connections (0/1) |
| username | Username |
| password | Password (returned by GET) |
| format | Streaming format (0 - JPEG HTTP, 1 - JPEG RTSP, 2 - JPEG RTSP-over-HTTP, 3 - MPEG-4 HTTP, 4 - MPEG-4 RTSP, 5 - MPEG-4 RTSP-over-HTTP, 6 - H.265 RTSP, 7 - H.264 RTSP, 8 - H.264 RTSP-over-HTTP, 9 - HTTP, 10 - RTSP, 11 - RTSP-over-HTTP, 12 - MxPEG HTTP, 13 - RTSP UDP, 14 - H.265 RTSP-over-HTTP, 15 - H.264 HTTP, 16 - H.265 HTTP, 17 - raw stream); which formats are available depends on the camera's make and model, chosen in the camera's settings |
| quality | Quality (0 - default, 1-10 where 1 is lowest and 10 is highest) |
| width | Video width (0 for the default) |
| height | Video height (0 for the default) |
| fps | Frame rate (0 for the default) |
| inputNum | Input/stream, as an index starting from 0 |
| request | Manual profile path: the path of the video stream, for a camera set up as Manual Configuration in the camera's settings |
| recompressVideo | Recompress video data (0/1) |
| recompressAudio | Recompress audio data (0/1) |
| setTime | Set device date and time (0/1; ONVIF cameras) |
| Device (local devices, video files, screen capture) | |
| widthL | Video width (0 for the default) |
| heightL | Video height (0 for the default) |
| fpsL | Frame rate (0 for the default) |
| Setup | |
| enabled | Enable this camera (0/1) |
| name | Camera name |
| overlayText | Text overlay, or empty for none (placeholders: +s system name, +n camera name, +d date, +w day of week, +t timestamp, \n new line) |
| overlaySize | Text overlay font size |
| overlayPos | Text overlay position (0 - top left, 1 - top right, 2 - bottom left, 3 - bottom right) |
| audioDevice | Audio input (x - none, n - the network camera's own audio, otherwise the UID of a macOS audio input device) |
| audioGain | Audio input volume (1-200, where 100 is unchanged) |
| ccAudio | Record audio with Continuous Capture movies (0/1) |
| mcAudio | Record audio with Motion Capture movies (0/1) |
| transformation | Transformation (0 - none, 1 - rotate 180°, 2 - rotate 90° right, 3 - rotate 90° left, 4 - flip horizontal, 5 - flip vertical) |
| brightness | Brightness (-50 to 50, where 0 is unchanged) |
| contrast | Contrast (-50 to 50, where 0 is unchanged) |
| storage | Camera-specific storage location: the path of an existing folder, or empty to use the primary storage location |
| viewOnly | Operate in view-only mode (don't count towards license limit) (0/1) |
| suppressErr | Suppress email error notifications (0/1) |
| Detection | |
| mdType | Motion detection method (0 - automatic, 1 - standard, 2 - AI-powered) |
| motionSensitivity | Motion sensitivity (1-100) |
| humanSensitivity | Human sensitivity (1-100) |
| vehicleSensitivity | Vehicle sensitivity (1-100) |
| animalSensitivity | Animal sensitivity (1-100) |
| audioSensitivity | Audio sensitivity (1-100) |
| Continuous Capture | |
| ccMovie | Capture movie continuously (0/1) |
| ccMovieFps | Movie capture rate in frames per second (0 for full rate) |
| ccMoviePlaybackFps | Movie playback rate in frames per second, for time-lapse movies (0 for real time) |
| ccFreq | New file (1 - when Continuous Capture is armed, 0 - daily at midnight, 3 - hourly on the hour, or every N minutes, as N+10: 11 - every minute, 12, 13, 14, 15, 16, 20, 25, 30, 40, 70 - every hour, 130, 190, 250, 370, 490, 730 - every 12 hours) |
| ccMovieFtp | Upload movies to (see Upload destinations below) |
| ccImage | Capture images continuously (0/1) |
| ccImageInterval | Seconds between image captures |
| ccImageFtp | Upload images to (see Upload destinations below) |
| webcamName | Webcam image file name |
| webcamFreq | Seconds between webcam image uploads |
| webcamFtp | Upload webcam image to (see Upload destinations below) |
| ccRemoveAge | Delete old Continuous Capture files after this many days (0 to use the Storage settings) |
| Motion Capture | |
| mcTriggers | Motion Capture triggers (see Triggers below) |
| mcMovie | Capture movie in response to triggers (0/1) |
| mcMovieFps | Movie capture rate in frames per second (0 for full rate) |
| mcMoviePre | Movie pre-capture seconds |
| mcMoviePost | Movie post-capture seconds |
| mcMovieFtp | Upload movies to (see Upload destinations below) |
| mcDaily | Capture all motion into one day-long movie (0/1; not recommended) |
| mcImage | Capture images in response to triggers (0/1) |
| mcImageInterval | Seconds between image captures |
| mcImagePost | Image post-capture seconds |
| mcImageFtp | Upload images to (see Upload destinations below) |
| mcRemoveAge | Delete old Motion Capture files after this many days (0 to use the Storage settings) |
| Actions | |
| aTriggers | Actions triggers (see Triggers below) |
| aSoundMac | Sound to play on the Mac: a sound file name such as Glass.aiff (from the SecuritySpy or macOS Sounds folders), or empty for none |
| aSoundDurationMac | Mac sound duration in seconds |
| aSoundVolMac | Mac sound volume (1-100) |
| aSoundCam | Sound to play on the camera (as aSoundMac), or empty for none |
| aSoundDurationCam | Camera sound duration in seconds |
| aSoundVolCam | Camera sound volume (1-100) |
| aScriptName | AppleScript to run: a file name from SecuritySpy's Scripts folder, or empty for none |
| aEmail | Send email to (comma-separated addresses, or empty for none) |
| aShellCommand | Shell command to run, or empty for none (can't be set, or read, using an API key) |
| aOtherCamN | Trigger camera number N (0/1) |
| aComeFront | Come to the front and open this camera's video window (0/1) |
| aWakeScreen | Wake the screen and dismiss the screensaver (0/1) |
| aHighlight | Highlight camera (0/1) |
| aHighlightDuration | Highlight duration in seconds |
| aNotification | Generate a notification on the Mac running SecuritySpy (0/1) |
| aDelay | Delay Actions for this many seconds after a trigger |
| aReset | Reset period: after an Action fires, it is suppressed for this many seconds (this applies to each Action separately) |
| aResetType | Which triggers are suppressed during the reset period (0 - only repeats of a trigger type that has already fired, 1 - any trigger) |
Upload destinations
The ccMovieFtp, ccImageFtp, webcamFtp, mcMovieFtp and mcImageFtp parameters each take the serverId of an upload destination (see Uploads above), or 0 for Don't Upload.
Triggers
The mcTriggers and aTriggers parameters each take a list of trigger tokens separated by semicolons, or an empty value for no triggers. Each token has the form type:objects:homeId:exclude.
| type | The trigger type: motion (motion detection), arrives (object arrives), departs (object departs), audio (audio detection), p1 (camera port 1), p2 (camera port 2), pir (camera PIR sensor), md (camera motion detection), home (HomeKit trigger, via HomeHelper). Camera inputs are only available on cameras that support them. Motion, arrives, departs and home tokens can appear more than once (with up to 8 repeats in total per mode); the other types once each |
| objects | For motion, arrives and departs: the sum of the objects to detect: 1 - human, 2 - vehicle, 4 - animal, 8 - package (arrives/departs only). For motion, 0 means any motion; arrives and departs need at least one object. 0 for the other types |
| homeId | For home: the ID of the HomeKit trigger. 0 for the other types |
| exclude | The sum of the outputs that this token does NOT fire (0 fires them all), as follows. A token that excludes every output is removed |
Output values for mcTriggers:
| 1 | Movie capture |
| 2 | Image capture |
Output values for aTriggers:
| 1 | Play sound on Mac |
| 2 | Play sound on camera |
| 4 | Run script |
| 8 | Home action |
| 16 | Send email |
| 32 | Run shell command |
| 64 | Trigger other cameras |
| 128 | Video display (come to front, wake screen, highlight) |
| 256 | macOS notification |
| 512 | Push notifications to the SecuritySpy iOS app |
For example, aTriggers=motion:1:0:0;arrives:10:0:16;audio:0:0:512 sets three Actions triggers: a human moving fires every action; a vehicle or package arriving fires every action except email; and audio fires every action except push notifications.
Example
cameraNum=3&name=Front+Door&enabled=1&mcTriggers=motion:3:0:0;arrives:8:0:0&mcMovie=1&mcMoviePre=3&mcMoviePost=10&mcMovieFtp=0&aOtherCam2=1
Deleting Cameras
Request format
settings-cameras?deleteCams=X
Parameters
deleteCams - a comma-separated list of the numbers of the cameras to delete
Example
settings-cameras?deleteCams=1,2&format=json
Returned data
With format=json, {"result":"OK"}; otherwise an HTML page, which can be ignored.
Camera Order
Request format
HTTP POST to settings-order with an order parameter: a comma-separated list of camera numbers, in display order. Any cameras that aren't listed follow in numerical order.
Example
order=2,0,1,3
Obtaining Current Settings
Issue a GET to the request for the settings you want to obtain, with a format parameter of either json or xml. JSON is the more convenient, as list items are posted back as JSON. This works with the following requests:
settings-general
settings-audio
settings-display
settings-sched
settings-storage
settings-compression
settings-uploads
settings-email
settings-web
settings-cameras (also requires a cameraNum parameter; a camera number that isn't in use returns a 404 error)
The numbers of all cameras can be obtained from the System Information data (see below).
Example
settings-cameras?cameraNum=4&format=json
settings-storage?format=xml
▸ Event Stream
Request format
eventStream?version=3[&format=multipart]
Returned data
A stream of events, in either plain text or as a multipart/mixed stream (if the "format" parameter is specified as above), that provides live events for all cameras. Each line is as follows:
[TIME] [EVENT NUMBER] [CAMERA NUMBER] [EVENT] [INFO]
[TIME] is specified in the order year, month, day, hour, minute, second and is always 14 characters long
[EVENT NUMBER] increments for each subsequent event
[CAMERA NUMBER] specifies the camera number, or X if the event does not refer to a specific camera
[INFO] is event-specific information
[EVENT] describes the event, as follows:
ARM_C
The camera's Continuous Capture mode has been armed
DISARM_C
The camera's Continuous Capture mode has been disarmed
ARM_M
The camera's Motion Capture mode has been armed
DISARM_M
The camera's Motion Capture mode has been disarmed
ARM_A
The camera's Actions mode has been armed
DISARM_A
The camera's Actions mode has been disarmed
ERROR
An error has been generated for the specified camera
INFO: error codes and error description
CONFIGCHANGE
There has been a configuration change for the specified camera
OFFLINE
The specified camera has just gone offline
ONLINE
The specified camera has just come online
MOTION
Motion has been detected in the specified camera
INFO: the position and size of the bounding box of the motion, in the format X Y W H, with the origin being the top left of the camera's image
MOTION_END
Motion has stopped in the specified camera - only issued after a MOTION event
CLASSIFY
AI classification results for the specified camera
INFO: the prediction percentages for humans, vehicles and animals
TRIGGER_M
Motion Capture has been triggered for the specified camera
INFO: trigger reason code (see below)
TRIGGER_A
Actions have been triggered for the specified camera
INFO: trigger reason code (see below)
FILE
For images, this happens immediately when an image file is created; for movie files, this happens when a recording has finished and the file has been completed (which may be some time after it was actually created).
INFO: the full path to the file
NULL
This "heartbeat" event is sent every 10 seconds to confirm that the stream is still active
Trigger reason code
This is a number provided with the TRIGGER_M and TRIGGER_A events. When interpreted in binary, each digit indicates a specific trigger reason - from LSB (bit 0) upwards, this list is as follows:
- Video motion detection
- Audio detection
- AppleScript
- Camera event
- Web server event
- Triggered by another camera
- Manual trigger
- Human movement
- Vehicle movement
- HomeKit event
- Animal movement
- Human arrival
- Human departure
- Vehicle arrival
- Vehicle departure
- Animal arrival
- Animal departure
Example (plain text)
20140927091955 1 3 ARM_C 20190927091955 2 3 ARM_M 20190927092026 3 3 MOTION 760 423 320 296 20190927092026 4 3 CLASSIFY HUMAN 99 20190927092026 5 3 TRIGGER_M 9 20190927092036 6 3 MOTION 0 432 260 198 20190927092036 7 3 CLASSIFY HUMAN 5 VEHICLE 95 ANIMAL 0 20190927092040 8 X NULL 20190927092050 9 3 FILE /Volumes/VolName/Cam/2019-07-26/26-07-2019 15-52-00 C Cam.m4v 20190927092055 10 3 DISARM_M 20190927092056 11 3 OFFLINE
Notes
- INFO may or may not be supplied; your parser must not require its presence or absence.
- New EVENT types may be added in the future; your parser should ignore unknown event types.
▸ System Information
Request format
systemInfo[?format=X]
Parameters
format - the format of the returned data: "xml" or "json" (if omitted altogether, a legacy XML version of this document is returned for backwards-compatibility)
Returned data
An document listing details of the system, including general information, scheduling, and available cameras.
<?xml version="1.0" encoding="utf-8"?>
<system>
<server>
<name>SecuritySpy</name>
<version>6.13</version>
</server>
<camera-list>
<camera>
<number>0</number>
<name>ComputerCam</name>
<connected>yes</connected>
<video-width>1920</video-width>
<video-height>1080</video-height>
<cc-mode>armed</cc-mode>
<mc-mode>armed</mc-mode>
<a-mode>disarmed</a-mode>
<has-audio>no</has-audio>
<ptzcapabilities>0</ptz-capabilities>
<device-name>FaceTime</device-name>
<device-type>Local</device-type>
</camera>
<camera>
<number>1</number>
<name>Front Door</name>
<connected>yes</connected>
<video-width>1200</video-width>
<video-height>800</video-height>
<cc-mode>armed</cc-mode>
<mc-mode>armed</mc-mode>
<a-mode>armed</a-mode>
<has-audio>yes</has-audio>
<ptz-capabilities>11</ptz-capabilities>
<device-name>Axis Network Camera</device-name>
<device-type>Network</device-type>
<address>192.168.1.10</address>
<port>80</port>
</camera>
</camera-list>
</system>
▸ Authentication in URL
NOTE: the below methods are insecure because the username/password can be extracted from the URL. For improved security, you should use the URL Generator function, available from the Window menu in SecuritySpy, to generate URLs that contain secure authentication tokens.
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¶m2=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
Privacy & Data Retention Policy
© Ben Software Ltd