Skip to content

CCTV and video

A camera is a data source in FACE. It can be an IP camera or NVR over RTSPS, an ONVIF device over HTTPS, an HTTPS feed, a video file, or the operator’s own device camera pushing frames. You add it in Settings › Integrations › Systems. Its card on Ask then opens Surveillance, the live feed, with that camera already chosen.

The connector’s job is reachability and description. Frame analysis happens in FACE’s vision pipeline (see /docs/analysis/).

Type spellings

WhereSpellings
Connector registry (Test, Explore)cctv, videostream (video_stream, the “Video Stream” card), camera
Fetch routingcctv, video_stream, videostream, camera, webcam

Settings (CctvConnectionConfig)

SettingMeaning
endpoint_urlrtsps:// or https://, or a file path readable on the processing node. rtsp:// and http:// are refused, because they are unencrypted. Do not put credentials in the URL.
usernameCamera username (a setting)
max_framesFrames sampled per extraction. 0 means the server default, not “none”.
transportRTSP transport: tcp (default) or udp
device_captureMarks a push source: the operator’s device records frames and sends them to FACE. endpoint_url stays empty.

Credential: password. It answers RTSP Digest (preferred) or Basic challenges, and ONVIF WS-Security UsernameToken with a password digest. It is never echoed, logged or written into lineage.

Cameras live on site networks. Set allow_internal_network to control whether a connection may reach internal addresses.

Test

Test on a camera connection, from Settings › Integrations › Systems, uses this probe:

EndpointWhat Test does
rtsps://TCP connect to the camera (5 s)
https://One HEAD request with the credentials. 401/403 is reported as feed rejected the credentials (HTTP …).
File pathChecks that the file exists and is not a directory
Device captureValidates the configuration. There is no server-side endpoint to dial. device_capture together with an endpoint_url is refused.

A successful probe says the camera accepted a connection. It does not say that video is being published or that a frame will decode.

Explore: asking the camera what it is

EndpointExplore reads
rtsps://Native RTSP OPTIONS + DESCRIBE (Accept: application/sdp). There is one dataset per media track, with codec, clock rate, packetisation and profile, plus resolution and frame rate where the camera states them, including from the H.264 parameter sets.
https:// (ONVIF)ONVIF over SOAP 1.2: GetSystemDateAndTime, GetDeviceInformation, GetServices/GetCapabilities, GetProfiles, GetVideoSourceConfigurations and GetStreamUri. Each returned stream URI is then described over RTSP in the same call. You type a host and a credential, and FACE finds the streams.
File path, device capturesupported=false, with the reason

CCTVService.DescribeSource returns the same description for an ad-hoc endpoint. Each reason repeats what a DESCRIBE does not establish:

  • that video is being published (an NVR describes a channel whose camera is unplugged)
  • that the codec will decode on this deployment
  • that the scene is what you expect
  • that playback (SETUP/PLAY) will be allowed

ONVIF uses Media ver10. A device that serves profiles only on Media2 reports zero profiles, and the reason says so. FACE does not multicast-probe your LAN (WS-Discovery) and does not subscribe to events. Each camera is added by address.

Snapshots

When a camera supports ONVIF GetSnapshotUri, FACE can fetch a still with one authenticated GET instead of decoding video. Only the path and query from the device’s answer are used. The host and port stay the ones on your connection, so a device cannot redirect FACE to another address. The response must validate as an image.

Frames: two paths

PathRPCWhat it doesWhat it leaves behind
GradedSurveillanceService.IngestSurveillanceFeed (and a fetch’s camera branch)Samples or receives frames, then runs the vision tier: object grading, material, damage, and evidence framesOne lineage record per ingest, evidence artefacts, observations
LiveSurveillanceService.DetectLiveFrameOne validated frame through the deployment’s local detector only. It never reaches the vision model or the network.Shown on Surveillance; not stored as an observation or evidence

A live answer carries box_origin = BOX_ORIGIN_LOCAL_DETECTOR, the detector’s own label, and no grade, material or damage fields. Its detection_note is never empty and says whether a local detector is present in this deployment. That note describes the deployment, not the camera.

Frame limits

  • Accepted formats: JPEG and PNG (unsupported image format "…" (only jpeg/png accepted))
  • At most 12 MiB per frame, and 40 million pixels
  • Frames sampled from a feed per sweep are set by the operator setting VISION_SWEEP_FRAMES.

A camera connection’s Execute has no tabular result and says so. Frames reach analysis through the ingest path, not through SqlService.