Cameras
HSYCO implements video surveillance functions and supports several camera brands.
HSYCO is not a traditional NVR.
Its strength is not the raw video performance or storage capabilities, but its ability to seamlessy integrate camera management with other field systems and to create fully customized, web-based user interfaces for integrared camera control.
The key difference between HSYCO and a NVR is that HSYCO doesn't have dedicated CPU, memory and storage resources allocated to the video surveillance functions.
HSYCO's hardware resources are shared with other services, so the actual capacity in terms of frames per second, number of cameras, recording capacity etc. is not fixed, but heavily dependent on the specific application, as well as the HSYCO hardware.
For example, an HSYCO server could support hundreds of cameras, as far as you are viewing and recording from only some at the same time. The frame resolution, size, and the user interface design are all important factors that affect the video performance of HSYCO.
As a starting point, you should expect an overall capacity of handling about 70-100 frames per second for up to 800x600 resolution and about 40KB size frames on an HSYCO PRO server, but this is not guaranteed.
These figures apply to JPEG and MJPEG sources, where the load is dominated by HTTP requests and frame handling. RTSP cameras are bound by a different resource, the server's hardware video decoder, and are sized separately: see Capacity and load of RTSP cameras.
To define the storage requirements for video recording, consider that HSYCO saves full individual JPG frames, at the same size received from the camera; the frames of RTSP cameras are the JPEG images generated by decoding the H.264 or H.265 stream. So just multiply the size of a single frame, times the total number of frames you expect to have stored on HSYCO. Usually, most of the disk space on a typical installation is available for video recording. HSYCO tries not to fill its storage above 90%, and stops recording when there is less than 5% free space.
All the key features of a complete video surveillance system are available in HSYCO, with the additional benefits and flexibility of a fully integrated system.
The HSYCO Web based user interface for video cameras display and control is highly configurable, very effective and easy to use from any device running a Web browser. The video streams are optimized to guarantee performance even when connected through a basic 3G network.
Video recording can be triggered by camera-detected motion events as well as by any other event in the connected systems, including the anti intrusion, fire/gas detection and access control systems or door locks.
Recordings can be conveniently browsed using a scrollable pull down list in the video surveillance page.
HSYCO can send e-mails with live or recorded video frames.
HSYCO supports PTZ video cameras (i.e. with Pan - Tilt - Zoom functionality).
The control of orientation, zoom and focus can be smoothly performed by clicking on specific areas inside the camera image.
PTZ cameras pre-set positions can be controlled as well.
HSYCO can create grids of cameras, and display these grids on the web interface, on the display of Snom VoIP phones and digital signage panels.
In order to comply with privacy regulations, HSYCO can be configured to automatically delete all recorded videos after a predefined amount of time - which can be different for each camera.
The recording function can be individually disabled for any video camera.
An HSYCO server can also access remote cameras through intermediate HSYCO servers, creating a distributed hierarchical video surveillance and supervision architecture.
Cameras Configuration
HSYCO interacts with cameras in three ways:
- using a url defined in the hsyco.ini file, to acquire individual frames, only when necessary and with the required frequency, or to open an RTSP stream;
- receiving, in the form of HTTP request sent by the camera to HSYCO Web server, the motion detection events notifications;
- sending pan, tilt, zoom and focus commands to cameras with PTZ support.
To reduce the processing load on the cameras and network traffic, HSYCO acquires frames from each camera only in the following cases:
- after motion detection events;
- when the Web interface requests the live view of a camera;
- on recording requests by the JavaScript, Java or EVENTS API.
The Manager Settings Tool documentation describes all video surveillance configuration parameters.
Users Configuration
You should configure the cameras to allow anonymous or authenticated access.
User and password information for each camera are configured in the hsyco.ini file.
Frames Acquisition
The camera must be enabled to serve JPEG frames requests coming from the HSYCO server, or to serve an H.264/H.265 RTSP stream, as described in the RTSP Cameras section.
JPEG and MJPEG sources are acquired over HTTP, with anonymous, basic or digest authentication.
Motion Detection
To receive motion detection events notifications, HSYCO expects that cameras generate HTTP requests to the HSYCO Web Server, in the following format:
http://192.168.0.50/x/camerarec?camera=<name>
or:
http://192.168.0.50/x/camerarec?camera=<name>&zone=<id>
The camera and zone parameters can be separated by &, : or ;.
<name> is the camera name, corresponding to one of the cameras listed in the Cameras parameter in hsyco.ini.
<id> is an optional parameter that identifies the active zone of the motion area.
This parameter is optional and, if present, is passed as a parameter to the CameraMotionEvent() Java callback method associated to the motion detection events and can be used at the application level.
For example:
http://192.168.0.50/x/camerarec?camera=back
http://192.168.0.50/x/camerarec?camera=back&zone=1
PTZ Control
The camera must be configured to allow PTZ control from the HSYCO server.
The Camera.<id>.PTZ parameter selects the PTZ driver:
| Value | Driver |
|---|---|
axis | Axis cameras, native PTZ through the Axis PTZ CGI |
axis-vptz | Axis cameras, digital PTZ on a single view of a multi-view camera, selected with the camera= parameter in the camera URL |
mobotix | Mobotix cameras, native PTZ |
onvif | any camera supporting the ONVIF PTZ service, see the ONVIF PTZ section |
vptz | virtual PTZ, performed by HSYCO by cropping and scaling the acquired frames |
user | PTZ commands implemented at the application level |
Leave the parameter empty for cameras without PTZ support. Any other value is reported as an error in the log, and PTZ control is disabled for that camera.
Static Cameras
Static cameras are a special purpose type of camera feeds that, instead of the typical frame refresh rate of a normal video camera, present a much slower update of a still image. This is typical, for example, of weather satellite images available on line, or public webcams that are not refreshed as a live camera is.
Using this kind of camera feeds as a normal camera source would cause HSYCO to poll the source with the same frequency used for all other normal cameras, even when the source image only changes just a few times a day, causing unnecessary network and server load.
Static cameras are enabled with the Camera.<id>.Static boolean parameter, which replaces the Camera.<id>.Type = static attribute of previous HSYCO versions.
If Camera.<id>.Static is set to true, a single HTTP request is sent to acquire the image when a CAMERAREC action is executed. The live camerapanel display will not trigger HTTP requests to the source, but show the last recorded image. Events are grouped per day. For static cameras only, a variable name (starting with $) can be set in the configuration instead of the URL in order to allow dynamic URLs.
RTSP Cameras
In addition to JPEG/MJPEG sources, HSYCO supports RTSP streams encoded in H.264 or H.265, decoded through the ffmpeg service.
To use an RTSP source, simply set the camera URL to an rtsp:// or rtsps:// address; HSYCO automatically detects the scheme. For example:
Camera.cam1.URL = rtsp://CAMERAIPADDRESS:554/stream1
The optional thumbnail URL supports RTSP as well, so that a camera can use the main stream for the full size view, and a lower resolution substream for the thumbnails:
Camera.cam1.URL = rtsp://CAMERAIPADDRESS:554/h264Preview_01_main
Camera.cam1.URL.Small = rtsp://CAMERAIPADDRESS:554/h264Preview_01_sub
Credentials are taken from the Camera.<id>.User and Camera.<id>.Password parameters, or can be embedded in the URL, as in rtsp://user:password@CAMERAIPADDRESS:554/stream1.
HSYCO opens the stream over RTSP/TCP and converts it to a sequence of JPEG frames, at the rate set by the CamerasRefreshMillis parameter, 1000 ms by default, so the acquisition rate doesn't depend on the frame rate of the source stream. As with all other cameras, the stream is only opened when the camera is actually in use, for live view or recording, and is closed as soon as the camera goes back to standby.
Once the frames are decoded, an RTSP camera is an ordinary HSYCO camera: same live view, same recording and retention rules, same events, grids, e-mail notifications and API. Only the way frames are acquired is different. The audio track of the stream, if any, is discarded.
Hardware Decoding Requirement
RTSP is only available on servers that can decode H.264 or H.265 in hardware.
Decoding a 1080p stream in software costs more CPU than the rest of HSYCO put together, and on the small servers HSYCO typically runs on it starves every other service, so software decoding is not used as a fallback. A camera whose codec has no hardware path on that server is stopped, and the reason is written once in the log:
CamerasClient ffmpeg [entrance] - RTSP stream disabled: no hardware decoding available for H264 on this server
At startup HSYCO probes the ffmpeg installation to find out what the server can really do. The probe takes a few seconds and reports the outcome in the log:
Hardware decoding available on this server (/usr/bin/ffmpeg) - H.264: h264_v4l2m2m, H.265: drm
The Cameras page of the Settings manager shows the same result as an RTSP indicator, with a green check when hardware decoding is available, a red mark when it is not, and a progress icon while the probe is still running.
The probe is an actual decode: each candidate method decodes a short test clip, and accelerators must hand the frames back in their own hardware pixel format.
Supported Servers
Hardware support is a property of the silicon, and it is not the same on machines that otherwise look identical. These are the results measured on the boards HSYCO is deployed on:
| Server | H.264 | H.265 / HEVC |
|---|---|---|
| HSYCO with Raspberry Pi 3 Model B+ (BCM2837) | yes, up to 1080p | no, the chip has no HEVC decoder |
| HSYCO with Raspberry Pi 4 Model B (BCM2711) | yes, rated 1080p60 | yes, rated 4Kp60 |
| HSYCO with Compute Module 4S (BCM2711) | yes, rated 1080p60 | yes at moderate resolutions; 4K is not stable |
| HSYCO with Compute Module 5 (BCM2712) | no, the chip has no H.264 decoder | yes, including 4K |
Two consequences are worth planning around:
- an HSYCO equipped with a Compute Module 5 will not take an H.264 camera at all, and no setting or driver update changes that - its cameras must be configured for H.265;
- the only codec the CM4S and the CM5 both accelerate is H.265, and on the CM4S only at moderate resolutions, so a 4K H.265 camera that runs on a CM5 should not be expected to run on a CM4S.
Selecting the Codec on the Camera
The stream path in the URL does not select the codec, even when it contains the name of one: the camera sends whatever its encoder is configured for, and the URL only selects which of its streams is used. The codec must therefore be set on the camera itself.
With verbose logging enabled, HSYCO reports the codec it detected, together with the quality factor and the frame rate it will use, once for each camera when the stream is opened:
CamerasClient ffmpeg [entrance] - H264 hardware decoding, JPEG quality 12, 1.0 fps
Use that line to confirm what the camera is really sending before troubleshooting anything else.
Camera Frame Rate
The number of frames HSYCO takes from the stream is set by the CamerasRefreshMillis parameter: one frame every 1000 ms by default, so one frame per second per camera. That is the rate of the JPEG frames coming out of the decoding process, and it is the same for RTSP and for all other cameras.
The camera, however, keeps sending its own frame rate, and the frames in excess are dropped after they have been decoded: every frame the camera sends is decoded and copied out of the decoder's buffers into system memory, and only then are the ones HSYCO does not need discarded. If the camera sends many more frames per second than HSYCO uses, most of the memory bandwidth of the server is spent on frames that are immediately thrown away, and at Full HD or 4K that alone can saturate a small server.
Lowering the frame rate on the camera, as close as practical to the rate HSYCO samples at, is therefore the single largest saving available, and it is what makes hardware decoding pay off. It costs nothing: HSYCO never needs more frames per second than CamerasRefreshMillis asks for.
Some cameras accept the frame rate as a parameter of the RTSP URL, which is the simplest option when it is available. On all others it has to be set in the camera's own encoder configuration.
JPEG Quality
Frames decoded from an RTSP stream are re-encoded as JPEG, at the quality set by the optional Camera.<id>.JPEGQualityFactor parameter. The value is the ffmpeg -q:v scale, from 2 for the best quality to 31 for the worst; the default is 12. In the Settings manager the field is a list of five values, from Highest (2) to Lowest (28), and only appears for RTSP cameras.
The quality factor sets the size of every frame HSYCO stores, so it has a direct effect on storage, bandwidth and page responsiveness. These are average sizes measured on live cameras:
| Stream | q:v 4 | q:v 8 | q:v 12 |
|---|---|---|---|
| 4K, 3840x2160 | 715 KB | 500 KB | 368 KB |
| Full HD, 1920x1080 | 102 KB | 71 KB | 30-70 KB |
| Substream, 640x360 | 5.5 KB |
Frame size depends on the scene as much as on the settings: at the same resolution and the same quality factor, a detailed or noisy image can be twice the size of a simple one, which is the range shown in the Full HD row above. Use these figures as orders of magnitude, and size storage on the larger end.
Capacity and Load of RTSP Cameras
An RTSP camera costs CPU in three places:
- decoding, done by the video hardware, which is the part that scales well;
- copying the decoded frames into system memory, paid for every frame the camera sends, whether HSYCO uses it or not;
- JPEG encoding of the frames that are actually used, at the rate set by
CamerasRefreshMillis.
Only the first is accelerated. This is why the resolution and the frame rate configured on the camera weigh more on the server than the number of cameras.
The figures below were measured with the cameras in live view, and are expressed in CPU cores, where 1.0 core means one processor core fully busy. They cover the whole HSYCO server, not the decoding alone:
| Server | Streams in use | Frames used | CPU |
|---|---|---|---|
| HSYCO with Raspberry Pi 3 Model B+ | 2 x Full HD H.264 | 1 fps | 1.5 cores |
| HSYCO with Compute Module 4S | 2 x Full HD H.264 + 1 x 640x360 H.264 | 1 fps | 0.9 cores |
| HSYCO with Compute Module 4S | the same three streams above | 3 to 7 fps | 2.5 cores |
| HSYCO with Compute Module 5 | 1 x 4K H.265 | 1 fps | 0.5 cores |
| HSYCO with Compute Module 5 | 1 x 4K H.265 + 1 x Full HD H.265 | 7 fps | 1.5 cores |
As a rule of thumb, on a server of this class:
- a Full HD stream in use at 1 frame per second costs between half and three quarters of a core;
- a 4K H.265 stream in use at 1 frame per second costs about half a core;
- taking more frames per second raises the copying and encoding cost roughly in proportion: the same three streams cost about three times as much at 3 to 7 frames per second as they do at 1;
- three or four simultaneous Full HD streams is a realistic ceiling, and using the cameras' substreams for the thumbnails is the cheapest way to raise the number of cameras that can be displayed at once;
- video should never be sized to use the whole server: HSYCO shares it with all the other integrations and services running on it.
Since the cameras of a typical installation are not all viewed at the same time, these limits apply to the cameras in use - shown live on a page, or recording - and not to the number of cameras configured. An HSYCO server can hold a large number of RTSP cameras in its configuration, provided only a few of them are streaming simultaneously.
Two limits are not linear, and cannot be extrapolated from the figures above. The hardware decoder has a finite number of decoding contexts and, on the smaller servers, allocates its buffers from a memory pool shared with the rest of the system: beyond a certain number of simultaneous streams a camera does not slow down, it fails to start or stops. And the resolution of a single stream can exceed what the decoder sustains no matter how few cameras there are.
Neither case is tolerated silently. Five decoding errors on a stream stop that camera, rather than letting HSYCO publish corrupted frames:
CamerasClient ffmpeg [entrance] - hardware decoding failed on this stream after 5 errors, stopping the camera
If this happens, reduce the resolution or the frame rate of the camera, use its substream, reduce the number of cameras streaming at the same time, or move the camera to a server whose decoder handles that codec and resolution.
Storage and Bandwidth
HSYCO stores full JPEG frames, so the storage needed is simply the frame size times the number of frames kept. With the sizes above:
- one Full HD camera recording at 1 frame per second, 8 hours a day, at quality 12: about 1.7 GB per day;
- one 4K camera in the same conditions: about 10 GB per day.
The retention time can be set per camera, and recording can be disabled per camera, so it is usually more effective to shorten the retention of the high resolution cameras than to lower their quality.
On the network side, the RTSP stream is pulled from the camera in full whenever the camera is in use, at the camera's own bitrate — typically 2 to 8 Mbit/s at Full HD, and 3 to 20 Mbit/s at 4K — regardless of how many frames HSYCO keeps. What reaches the browsers is instead the JPEG sequence, at the sampled frame rate: about 0.6 Mbit/s for a Full HD camera at 1 fps and quality 12, and about 3.4 Mbit/s for a 4K one.
Limitations
- Hardware decoding is mandatory: there is no software fallback, by design.
- The Motion Buffer, which keeps a few frames acquired before an event, is not available for RTSP cameras and the Settings manager disables the field for them: buffering would require keeping the stream and the hardware decoder open at all times, even while the camera is in standby.
ONVIF PTZ
Cameras supporting the ONVIF PTZ service can be controlled by setting Camera.<id>.PTZ to "onvif". This is the recommended driver for RTSP cameras, and for any camera that doesn't have a specific PTZ driver.
The camera user and password, either set with the Camera.<id>.User and Camera.<id>.Password parameters or embedded in the camera URL, are used for the ONVIF authentication.
The ONVIF device service port is set with the optional Camera.<id>.ONVIFPort parameter, and in the Settings manager with the ONVIF Port field, which only appears when the ONVIF driver is selected.
When the port is not set, HSYCO discovers it with WS-Discovery, which only reaches cameras that answer a probe on the local network. If nothing answers, PTZ control is disabled for that camera and the log says what to do:
Camera [entrance] - ONVIF WS-Discovery found no device service, set ONVIFPort to the camera's ONVIF port, PTZ control disabled
Setting the port explicitly always works, on local and remote cameras alike, and is the recommended configuration whenever the camera is not on the same network as the server.
The device service is contacted over HTTP first, then over HTTPS on the same port, accepting the self-signed certificates typically installed on cameras.
The driver supports pan, tilt and zoom, performed with ONVIF continuous move commands; zoom is only enabled when the camera declares support for it. The home position, when supported, is recalled with the focus near command.
Cameras URLs list
RTSP URLs
The stream paths of RTSP cameras depend on the model and firmware version; these are the most common formats:
| Brand | URL |
|---|---|
| Axis | rtsp://CAMERAIPADDRESS:554/axis-media/media.amp |
| Dahua | rtsp://CAMERAIPADDRESS:554/cam/realmonitor?channel=1&subtype=0 |
| Hikvision | rtsp://CAMERAIPADDRESS:554/Streaming/Channels/101 |
| Reolink | rtsp://CAMERAIPADDRESS:554/h264Preview_01_main |
| rtsp://CAMERAIPADDRESS:554/h265Preview_01_main | |
| rtsp://CAMERAIPADDRESS:554/h264Preview_01_sub |