RTSP Camera Agent

This OCS Agent which grabs screenshots and records video from IP cameras supporting the RTSP streaming protocol.

usage: python3 agent.py [-h] [--mode {acq,test}] --directory DIRECTORY
                        --address ADDRESS --user USER --password PASSWORD
                        [--motion_start MOTION_START]
                        [--motion_stop MOTION_STOP]
                        [--snapshot_seconds SNAPSHOT_SECONDS] [--port PORT]
                        [--urlpath URLPATH] [--jpeg_quality JPEG_QUALITY]
                        [--max_snapshot_files MAX_SNAPSHOT_FILES]
                        [--record_fps RECORD_FPS]
                        [--record_duration RECORD_DURATION]
                        [--max_record_files MAX_RECORD_FILES] [--fake]
                        [--disable_motion]

Agent Options

--mode

Possible choices: acq, test

Starting action for the Agent.

Default: “acq”

--directory

Directory for media buffers (snapshots and recordings)

--address

Hostname or IP address of camera

--user

User name for camera access

--password

Password for camera access

--motion_start

ISO 8601 time (HH:MM:SS+-zz:zz) to begin motion detection

--motion_stop

ISO 8601 time (HH:MM:SS+-zz:zz) to end motion detection

--snapshot_seconds

Number of seconds between snapshots for motion detection

Default: 10

--port

The RTSP port number

Default: 554

--urlpath

The path portion of the URL. Default will use values for Dahua cameras.

--jpeg_quality

The JPEG quality (0-100)

Default: 20

--max_snapshot_files

Maximum number of images to keep in the circular buffer

Default: 17280

--record_fps

The frames per second for video recording

Default: 20.0

--record_duration

The length in seconds to record video.

Default: 60

--max_record_files

Maximum number of images to keep in the circular buffer

Default: 120

--fake

Use an internal fake camera for acquisition

Default: False

--disable_motion

Disable motion detection

Default: False

Configuration File Examples

Below are configuration examples for the ocs config file and for running the Agent in a docker container.

OCS Site Config

To configure the RTSP Camera Agent we need to add a RTSPCameraAgent block to our ocs configuration file. Here is an example configuration block using all of the common arguments. Many options do not normally need to be changed:

{'agent-class': 'RTSPCameraAgent',
 'instance-id': 'camera-c3',
 'arguments': ['--mode', 'acq',
               '--directory', '/camera',
               '--address', 'camera-c3.example.org',
               '--user', 'ocs',
               '--password', '<password>',
               '--motion_start', '19:00:00-04:00',
               '--motion_stop', '07:00:00-04:00',
               '--snapshot_seconds', '10',
               '--record_duration', '120']},

Docker Compose

The RTSP camera Agent should be configured to run in a Docker container. An example docker-compose service configuration is shown here:

ocs-camera-c3:
  image: simonsobs/socs:latest
  hostname: ocs-docker
  environment:
    - INSTANCE_ID=camera-c3
    - SITE_HUB=ws://127.0.0.1:8001/ws
    - SITE_HTTP=http://127.0.0.1:8001/call
    - LOGLEVEL=info
  volumes:
    - ${OCS_CONFIG_DIR}:/config:ro
    - /so/cameras/c3:/camera
  user: 9000:9000

The LOGLEVEL environment variable can be used to set the log level for debugging. The default level is “info”. The volume must mount to whatever location inside the container that you specified in the config file. The user must have permissions to write to the mounted local directory.

Description

The indoor IP cameras at the site support the RTSP protocol. These cameras are mainly for security monitoring. The directory specified in the configuration is the top level directory for storing files. Two subdirectories, “snapshots” and “recordings” are created below this. Snapshots are saved every 10 seconds and a couple days worth are kept in a circular buffer on disk. A symlink (“latest.jpg”) is kept for the latest snapshot acquired, and this can be displayed in a Grafana text panel using an HTML image tag.

By default, these snapshots are processed for motion detection. If motion is detected, a 20fps video recording is triggered. During recording, further motion detection is disabled. After the recording stops, motion detection resumes. These recordings are also kept in a circular disk buffer in the “recordings” subdirectory. These full video files are for manual download and viewing after a security event. All image and video files contain the ISO timestamp when they were acquired.

Agent API

class socs.agents.rtsp_camera.agent.RTSPCameraAgent(agent, directory, address, user, password, seconds=10, port=554, urlpath=None, jpeg_quality=20, max_snapshot_files=10000, record_fps=20.0, record_duration=60, max_record_files=100, motion_start=None, motion_stop=None, disable_motion=False, fake=False)[source]

Agent to support image capture from RTSP cameras.

This Agent captures images and writes them to a feed, as well as saving frames to disk. The camera can also be triggered to record….

Parameters:

agent (OCSAgent) – OCSAgent object from ocs.ocs_agent.init_site_agent().
directory (str) – The path to image storage for this camera.
address (str) – The hostname or IP address of the camera.
user (str) – The user name for camera access.
password (str) – The password for camera access.
seconds (int) – The seconds between snapshots.
port (int) – The RTSP port to use (default is standard 554).
urlpath (str) – The remaining URL for the camera, which might include options like channel and subtype. This will depend on the manufacturer.
jpeg_quality (int) – The JPEG quality for snapshot images (0-100).
max_snapshot_files (int) – The maximum number of snapshots to keep.
record_fps (float) – The frames per second for recorded video.
record_duration (int) – The number of seconds for each recorded video.
max_record_files (int) – The maximum number of recordings to keep.
motion_start (str) – ISO time (HH:MM:SS+-zz:zz) to start motion detection.
motion_stop (str) – ISO time (HH:MM:SS+-zz:zz) to stop motion detection.
disable_motion (bool) – If True, disable motion detection.
fake (bool) – If True, ignore camera settings and generate fake video for testing.

agent

OCSAgent object from ocs.ocs_agent.init_site_agent().

Type:: OCSAgent

log

Logger object used to log events within the Agent.

Type:: txaio.tx.Logger

lock

TimeoutLock object used to prevent simultaneous commands being sent to hardware.

Type:: TimeoutLock

acq(test_mode=False)[source]

Process - Capture frames from an RTSP camera.

Parameters:: test_mode (bool) – Run the Process loop only once. Meant only for testing. Default is False.

Notes

Individual frames are written to a circular disk buffer. Metadata about the captured images is stored in the session data. The format of this is:

>>> response.session['data']
{
    'address': 'camera-c1.example.org',
    'timestamp': 1701983575.123456,
    'path': '/ocs/cameras_rtsp/c1/img_2023-12-29T02:44:47+00:00.jpg',
}

record(session, params=None)[source]

Record video stream.

Task - Record video for fixed timespan.

Parameters:: None