Camera¶
Camera config, frames, streaming sessions, detection events, runtime device API.
camera_ui_sdk.camera ¶
CameraPublicProperties
module-attribute
¶
CameraPublicProperties = Literal['_id', 'nativeId', 'pluginInfo', 'name', 'disabled', 'isCloud', 'info', 'type', 'snapshotSettings', 'detectionZones', 'detectionSettings', 'ptzAutotrack', 'frameWorkerSettings', 'interfaceSettings', 'recording', 'plugins', 'assignments', 'sources']
Camera public property names for observation.
EVENT_TRIGGER_TYPES
module-attribute
¶
EVENT_TRIGGER_TYPES: tuple[str, ...] = ('motion', 'audio', 'contact', 'doorbell', 'switch', 'light', 'siren', 'security_system', 'line-crossing')
All event trigger types as a runtime-accessible tuple.
AudioCodec
module-attribute
¶
AudioCodec = Literal['PCMU', 'PCMA', 'MPEG4-GENERIC', 'opus', 'G722', 'G726', 'MPA', 'PCM', 'FLAC', 'ELD', 'PCML', 'L16']
Supported audio codecs (RTP/SDP format names).
AudioFFmpegCodec
module-attribute
¶
AudioFFmpegCodec = Literal['pcm_mulaw', 'pcm_alaw', 'aac', 'libopus', 'g722', 'g726', 'mp3', 'pcm_s16be', 'pcm_s16le', 'flac']
FFmpeg audio codec names for transcoding.
CameraAspectRatio
module-attribute
¶
Camera aspect ratio for UI display.
CameraRole
module-attribute
¶
Camera stream resolution role. Used to identify different quality streams from the same camera.
CameraType
module-attribute
¶
Camera device type.
- camera: Standard surveillance camera
- doorbell: Doorbell camera
DetectionEventState
module-attribute
¶
Event lifecycle state.
DetectionEventType
module-attribute
¶
DetectionEventType = Literal['start', 'end', 'update', 'segment-start', 'segment-update', 'segment-end']
Detection event message type (lifecycle phase).
EventTriggerType
module-attribute
¶
EventTriggerType = Literal['motion', 'audio', 'contact', 'doorbell', 'switch', 'light', 'siren', 'security_system', 'line-crossing']
Event trigger type.
LineDirection
module-attribute
¶
Line crossing direction filter.
- both: Trigger on crossings in either direction
- a-to-b: Trigger only when crossing from A side to B side
- b-to-a: Trigger only when crossing from B side to A side
MotionResolution
module-attribute
¶
Motion detection resolution setting. Higher resolution = more accurate but slower.
Point
module-attribute
¶
Zone polygon coordinate as [x, y] tuple (0-100 percentage).
ProbeAudioCodec
module-attribute
¶
Audio codecs supported for stream probing.
RTSPAudioCodec
module-attribute
¶
Audio codecs supported for RTSP streaming.
StreamDirection
module-attribute
¶
Stream direction (from SDP).
StreamingRole
module-attribute
¶
Streaming roles (excludes snapshot).
VideoCodec
module-attribute
¶
Supported video codecs (RTP/SDP format names).
VideoFFmpegCodec
module-attribute
¶
FFmpeg video codec names for transcoding.
VideoStreamingMode
module-attribute
¶
Video streaming mode for UI playback.
- auto: Automatically select best method
- webrtc: WebRTC with UDP (lowest latency)
- webrtc/tcp: WebRTC with TCP fallback
- mse: Media Source Extensions (browser native)
ZoneFilter
module-attribute
¶
Detection zone filter mode.
- include: Only consider detections inside this zone
- exclude: Only consider detections outside this zone
ZoneType
module-attribute
¶
Detection zone intersection type.
- intersect: Trigger when object touches the zone boundary
- contain: Trigger only when object is fully inside the zone
AssignedPlugin ¶
BaseCamera ¶
Bases: TypedDict
Base camera data structure (stored in database).
BaseCameraConfig ¶
Bases: TypedDict
Base camera configuration (shared fields).
Camera ¶
CameraConfig ¶
CameraConfigInputSettings ¶
Bases: TypedDict
Camera input settings for config.
childSourceId
instance-attribute
¶
Child source ID (for snapshot fallback).
CameraInformation ¶
Bases: TypedDict
Camera hardware/firmware information.
CameraInput ¶
Bases: TypedDict
Camera video input/source with resolved URLs.
childSourceId
instance-attribute
¶
Child source ID (for snapshot fallback).
CameraPluginInfo ¶
CameraPropertyObservableObject ¶
CameraUiSettings ¶
Bases: TypedDict
UI display settings for a camera.
PluginAssignments ¶
Bases: TypedDict
Plugin assignments for camera sensors/features. Maps sensor types to their assigned plugin(s).
SensorEventData ¶
AudioDetectionSettings ¶
CameraDetectionSettings ¶
DetectionLine ¶
Bases: TypedDict
Detection line configuration. Defines a virtual tripwire for line crossing detection. The two points define grab-handle positions; the actual crossing line is perpendicular through their midpoint.
points
instance-attribute
¶
Grab-handle positions (0-100%). Crossing line is perpendicular through midpoint.
DetectionZone ¶
Bases: TypedDict
Detection zone configuration. Defines areas for detection filtering or privacy masking.
isPrivacyMask
instance-attribute
¶
Whether this is a privacy mask (blur/block area).
MotionDetectionSettings ¶
ObjectDetectionSettings ¶
Bases: TypedDict
Object detection settings.
PtzAutotrackSettings ¶
Bases: TypedDict
PTZ autotracking settings — automatically follow detected objects.
targetLabels
instance-attribute
¶
Object labels to track (e.g. 'person', 'vehicle').
minConfidence
instance-attribute
¶
Minimum detection confidence to track (0.3 - 1.0).
triggerDeadZone
instance-attribute
¶
Dead zone around frame center (0 - 0.3). No motor command while the target is inside this zone.
returnToHome
instance-attribute
¶
Return to home position when no target is found for homeWaitMs.
homeWaitMs
instance-attribute
¶
How long to wait (ms) without a target before returning home.
SensorTriggerRef ¶
Bases: TypedDict
Stable reference to a sensor for cascade trigger configuration. Uses composite key (sensorType + sensorName + pluginId) instead of UUID so references survive plugin restarts.
SensorTriggerSettings ¶
Bases: TypedDict
Sensor trigger settings (contact, doorbell, switch, light, etc.).
CameraDevice ¶
Bases: Protocol
Main camera device interface. Provides access to camera streams, sensors, and services.
detectionLines
property
¶
Detection line configurations (virtual tripwires).
frameWorkerSettings
property
¶
Frame worker settings.
highResolutionSource
property
¶
High resolution source (if available).
midResolutionSource
property
¶
Mid resolution source (if available).
lowResolutionSource
property
¶
Low resolution source (if available).
onFrameWorkerConnected
property
¶
Observable for frame worker state changes.
onSensorAdded
property
¶
Observable for sensor additions. Emits SensorEventData when a sensor from another plugin is added.
onSensorRemoved
property
¶
Observable for sensor removals. Emits SensorEventData when a sensor from another plugin is removed.
onDetectionEvent
property
¶
Observable for detection events (start/update/end). Thumbnails in segments are only populated on 'end' events.
getSourceById ¶
Get a source by its ID.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id
|
str
|
The source ID. |
required |
Returns:
| Type | Description |
|---|---|
CameraDeviceSource | None
|
The matching source, or None if not found. |
connect
async
¶
Tell the server this camera is online.
Only the plugin that owns this camera (via pluginInfo) may connect it.
disconnect
async
¶
Tell the server this camera is offline.
Only the plugin that owns this camera (via pluginInfo) may disconnect it.
onPropertyChange ¶
onPropertyChange(property: CameraPublicProperties | list[CameraPublicProperties]) -> Observable[CameraPropertyObservableObject]
Observe camera property changes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
property
|
CameraPublicProperties | list[CameraPublicProperties]
|
Property name(s) to observe. |
required |
Returns:
| Type | Description |
|---|---|
Observable[CameraPropertyObservableObject]
|
Observable emitting old and new values. |
getSensors ¶
Get all sensors attached to this camera (owned + foreign).
getSensor ¶
Get sensor by ID (checks owned and foreign sensors).
getSensorsByType ¶
Get all sensors of a specific type (owned + foreign).
onSensorProperty ¶
onSensorProperty(sensor_type: SensorType, property: str, callback: Callable[[Any, int, SensorLike], None]) -> Disposable
Subscribe to a specific property on a sensor type with full lifecycle management. Automatically subscribes/unsubscribes when sensors of the given type are added/removed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sensor_type
|
SensorType
|
The sensor type to watch. |
required |
property
|
str
|
The property name to observe. |
required |
callback
|
Callable[[Any, int, SensorLike], None]
|
Called with (value, timestamp_ms, sensor) when the property changes. |
required |
Returns:
| Type | Description |
|---|---|
Disposable
|
Disposable to stop all subscriptions. |
addSensor
async
¶
Add a sensor to this camera.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sensor
|
Sensor[Any, Any, Any]
|
Sensor instance to add. |
required |
removeSensor
async
¶
Remove a sensor from this camera.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sensorId
|
str
|
ID of sensor to remove. |
required |
implement
async
¶
Register a camera implementation for streaming and/or snapshot.
The impl value should implement StreamingInterface, SnapshotInterface, or both.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
impl
|
CameraImplementation
|
Object or class implementing camera interfaces |
required |
createStorage ¶
Create storage for plugin-specific camera configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
schemas
|
list[JsonSchema]
|
Schema definitions for the storage |
required |
Returns:
| Type | Description |
|---|---|
DeviceStorage
|
Typed device storage instance |
CameraDeviceSource ¶
Bases: CameraSource, Protocol
Camera source with full streaming capabilities.
generateRTSPUrl ¶
Generate RTSP URL with specified options.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options
|
RTSPUrlOptions | None
|
URL generation options. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
RTSP URL string. |
CameraSource ¶
Bases: Protocol
Camera source with snapshot and probe capabilities.
childSourceId
instance-attribute
¶
Child source ID (for snapshot fallback).
snapshot
async
¶
Get camera snapshot image.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
forceNew
|
bool
|
Force fresh snapshot (ignore cache). |
False
|
Returns:
| Type | Description |
|---|---|
bytes | None
|
JPEG image data or None if unavailable. |
probeStream
async
¶
Probe stream for codec and track information.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
probeConfig
|
ProbeConfig | None
|
What to probe for. |
None
|
refresh
|
bool
|
Force fresh probe (ignore cache). |
False
|
Returns:
| Type | Description |
|---|---|
ProbeStream | None
|
Stream information or None if unavailable. |
getStreamStatus
async
¶
Get the current stream connection status.
Returns:
| Type | Description |
|---|---|
str
|
Status string: 'connected', 'connecting', 'error', or 'idle'. |
generateSnapshotUrl ¶
Generate Snapshot URL with specified options.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options
|
SnapshotUrlOptions | None
|
URL generation options. |
None
|
Returns:
| Type | Description |
|---|---|
str
|
Snapshot URL string. |
SnapshotInterface ¶
Bases: Protocol
snapshot
async
¶
Get a snapshot image from the camera.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source_id
|
str
|
The source ID to get the snapshot from |
required |
force_new
|
bool
|
If True, bypass cache and get a fresh snapshot |
False
|
Returns:
| Type | Description |
|---|---|
bytes | None
|
Image data as bytes, or None if unavailable |
StreamingInterface ¶
Bases: Protocol
streamUrl
async
¶
Get the streaming URL for a source.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source_id
|
str
|
The ID of the source |
required |
Returns:
| Type | Description |
|---|---|
str
|
The streaming URL (e.g., rtsp://, rtmp://, or custom protocol) |
DetectionEvent ¶
Bases: TypedDict
Aggregated detection event with lifecycle (start -> update -> end). Groups individual sensor detections into structured events.
segments
instance-attribute
¶
Detection segments (object detection phases). For segment-* messages: contains only the current segment. For start/end messages: empty.
segmentIndex
instance-attribute
¶
Index of the segment in segments[0] for segment-* messages.
expectedEndTime
instance-attribute
¶
Expected event end time (Unix ms) — the latest dwell expiry across all
currently-active triggers. Monotonically non-decreasing during the event
lifetime. Updated on each update / segment-* message.
thumbnail
instance-attribute
¶
Full-frame downscaled JPEG captured at event start. Inline only on the first message that delivers it (start or the first update); the NVR plugin persists it and clients fetch it on demand via getEventThumbnails.
DetectionEventPayload ¶
EventAttribute ¶
Bases: TypedDict
Unified attribute within a segment (face identity, license plate, classifier result).
type
instance-attribute
¶
Attribute type ('face', 'license_plate', or classifier-specific like 'bird').
thumbnail
instance-attribute
¶
Best-selected JPEG thumbnail crop. Only present on 'end' events.
embedding
instance-attribute
¶
Face embedding vector for unknown face persistence. Only present for face attributes.
embeddingModel
instance-attribute
¶
Embedding model identifier. Only present for face attributes with embedding.
clipEmbedding
instance-attribute
¶
CLIP embedding vector for semantic search. Only present for clip attributes.
clipEmbeddingModel
instance-attribute
¶
CLIP embedding model identifier. Only present for clip attributes with embedding.
parentTrackId
instance-attribute
¶
Parent object's tracker ID (links this attribute to its parent detection).
EventDescription ¶
Bases: TypedDict
AI-generated event description.
threatLevel
instance-attribute
¶
Threat level: 0 = normal, 1 = suspicious, 2 = threat.
EventDetection ¶
Bases: TypedDict
Aggregated object detection within a segment.
box
instance-attribute
¶
Bounding box of the highest-confidence detection (normalized 0-1).
thumbnail
instance-attribute
¶
Best-selected JPEG thumbnail crop. Only present on 'end' events.
trackId
instance-attribute
¶
Object tracker ID (links this detection across frames).
moving
instance-attribute
¶
Whether the object was moving (True) or stationary (False).
EventSegment ¶
Bases: TypedDict
A contiguous object detection phase within an event.
thumbnail
instance-attribute
¶
Best-selected JPEG scene thumbnail for this segment. Only present on 'end' events.
attributes
instance-attribute
¶
Unified attributes (faces, plates, classifications).
zones
instance-attribute
¶
Names of detection zones any detection in this segment overlapped (deduplicated).
description
instance-attribute
¶
AI-generated description for this segment.
EventTrigger ¶
Bases: TypedDict
Event trigger (motion, audio, sensor, or line-crossing).
CameraFrameWorkerSettings ¶
SnapshotSettings ¶
Bases: TypedDict
Snapshot settings for a camera.
AudioCodecProperties ¶
Bases: TypedDict
Audio codec properties from stream probe.
AudioStreamInfo ¶
Bases: TypedDict
Audio stream information from probe.
FMTPInfo ¶
Go2RtcRTSPSource ¶
Bases: TypedDict
RTSP streaming URLs from go2rtc.
Go2RtcSnapshotSource ¶
Go2RtcWSSource ¶
ProbeConfig ¶
Bases: TypedDict
Configuration for stream probing.
ProbeStream ¶
RTSPUrlOptions ¶
SnapshotUrlOptions ¶
Bases: TypedDict
Options for generating snapshot URLs.
hw
instance-attribute
¶
Hardware acceleration backend.
StreamUrls ¶
VideoCodecProperties ¶
VideoStreamInfo ¶
Bases: TypedDict
Video stream information from probe.