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', 'zones', 'detectionSettings', 'ptzAutotrack', 'frameWorkerSettings', 'interfaceSettings', 'recordingSettings', 'plugins', 'assignments', 'sources']

Camera public property names for observation.

AlertZoneMatch module-attribute

AlertZoneMatch = Literal['anchor', 'intersect', 'contain']

When an object counts as inside an alert zone: where it stands, touching, or fully inside.

TimeWindow module-attribute

TimeWindow = TypedDict('TimeWindow', {'from': str, 'to': str, 'timezone': str})

A daily time window ("HH:mm"), read in the timezone it was configured in. A to before from wraps around midnight.

CameraImplementation module-attribute

CameraImplementation: TypeAlias = StreamingInterface | SnapshotInterface

Value accepted by CameraDevice.implement: streaming, snapshot, or both.

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.

CameraActivityMode module-attribute

CameraActivityMode = Literal['always-on', 'activity', 'standby']

When the live stream runs: continuously, only during activity, or on demand.

CameraAspectRatio module-attribute

CameraAspectRatio = CameraAspectRatioPreset | str

Camera aspect ratio for UI display: a preset or any custom width:height ratio.

CameraAspectRatioPreset module-attribute

CameraAspectRatioPreset = Literal['16:9', '9:16', '8:3', '4:3', '1:1']

Built-in aspect ratio presets offered as quick picks in the UI.

CameraRole module-attribute

CameraRole = Literal['high-resolution', 'mid-resolution', 'low-resolution', 'snapshot']

Camera stream resolution role. Used to identify different quality streams from the same camera.

CameraType module-attribute

CameraType = Literal['camera', 'doorbell']

Camera device type. - camera: Standard surveillance camera - doorbell: Doorbell camera

DetectionEventState module-attribute

DetectionEventState = Literal['active', 'ended']

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

LineDirection = Literal['both', 'a-to-b', 'b-to-a']

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

MotionResolution = Literal['low', 'medium', 'high']

Motion detection resolution setting. Higher resolution = more accurate but slower.

PlaybackSource module-attribute

PlaybackSource = Literal['auto', 'high', 'mid', 'low']

Recorded playback quality selection: a fixed tier, or automatic tier choice from the recorded coverage.

Point module-attribute

Point = tuple[float, float]

Zone polygon coordinate as [x, y] tuple (0-100 percentage).

ProbeAudioCodec module-attribute

ProbeAudioCodec = Literal['aac', 'opus', 'pcma']

Audio codecs supported for stream probing.

RTSPAudioCodec module-attribute

RTSPAudioCodec = Literal['aac', 'opus', 'pcma']

Audio codecs supported for RTSP streaming.

StreamDirection module-attribute

StreamDirection = Literal['sendonly', 'recvonly', 'sendrecv', 'inactive']

Stream direction (from SDP).

StreamingRole module-attribute

StreamingRole = Literal['high-resolution', 'mid-resolution', 'low-resolution']

Streaming roles (excludes snapshot).

VideoCodec module-attribute

VideoCodec = Literal['H264', 'H265', 'VP8', 'VP9', 'AV1', 'JPEG', 'RAW']

Supported video codecs (RTP/SDP format names).

VideoFFmpegCodec module-attribute

VideoFFmpegCodec = Literal['h264', 'hevc', 'vp8', 'vp9', 'av1', 'mjpeg', 'rawvideo']

FFmpeg video codec names for transcoding.

VideoStreamingMode module-attribute

VideoStreamingMode = Literal['auto', 'webrtc', 'mse', 'webrtc/tcp']

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)

ZoneType module-attribute

ZoneType = Literal['intersect', 'contain']

Detection zone intersection type. - intersect: Trigger when object overlaps the zone at all - contain: Trigger only when object is fully inside the zone

FrameWorkerDecoderHardware module-attribute

FrameWorkerDecoderHardware = Literal['auto', 'cpu', 'cuda', 'vaapi', 'qsv', 'videotoolbox', 'd3d11va', 'd3d12va', 'dxva2', 'vulkan', 'opencl', 'drm', 'rkmpp']

Hardware backend for the detection decoder. auto probes the platform order, cpu forces software decoding.

NotificationSpeed module-attribute

NotificationSpeed = Literal['immediate', 'balanced', 'best']

How long a push waits for a good picture. - immediate: send right away, with a picture only if one is ready - balanced: wait up to 2 seconds for the best picture - best: wait up to 4 seconds for the best picture

RecordingMode module-attribute

RecordingMode = Literal['continuous', 'event', 'adhoc']

How recordings are captured. - continuous: record around the clock - event: record only around detections, padded by the pre-buffer - adhoc: record only when started manually

RecordingSource module-attribute

RecordingSource = Literal['high', 'mid', 'low']

Stream tier to record.

AssignedPlugin

Bases: TypedDict

Plugin assignment info.

id instance-attribute

id: str

Plugin ID.

name instance-attribute

name: str

Plugin display name.

BaseCamera

Bases: TypedDict

Base camera data structure (stored in database).

nativeId instance-attribute

nativeId: str | None

Native device ID from plugin.

pluginInfo instance-attribute

pluginInfo: CameraPluginInfo | None

Source plugin information.

name instance-attribute

name: str

Camera display name.

room instance-attribute

room: str

Room this camera belongs to.

disabled instance-attribute

disabled: bool

Whether camera is disabled.

isCloud instance-attribute

isCloud: bool

Whether camera streams from cloud.

info instance-attribute

info: CameraInformation

Camera hardware information.

type instance-attribute

type: CameraType

Camera type (camera/doorbell).

snapshotSettings instance-attribute

snapshotSettings: SnapshotSettings

Snapshot settings.

zones instance-attribute

zones: NotRequired[CameraZones]

Zone configurations, one list per purpose.

detectionSettings instance-attribute

detectionSettings: CameraDetectionSettings

Detection settings.

ptzAutotrack instance-attribute

ptzAutotrack: PtzAutotrackSettings

PTZ autotracking settings.

recordingSettings instance-attribute

recordingSettings: CameraRecordingSettings

Recording settings.

notificationSettings instance-attribute

notificationSettings: CameraNotificationSettings

Push notification settings.

frameWorkerSettings instance-attribute

frameWorkerSettings: CameraFrameWorkerSettings

Frame worker settings.

interfaceSettings instance-attribute

interfaceSettings: CameraUiSettings

UI display settings.

plugins instance-attribute

plugins: list[AssignedPlugin]

Installed plugins.

assignments instance-attribute

assignments: PluginAssignments

Sensor-to-plugin assignments.

BaseCameraConfig

Bases: TypedDict

Base camera configuration (shared fields).

name instance-attribute

name: str

Camera display name.

nativeId instance-attribute

nativeId: NotRequired[str]

Native device ID from plugin.

isCloud instance-attribute

isCloud: NotRequired[bool]

Whether camera streams from cloud.

disabled instance-attribute

disabled: NotRequired[bool]

Disable this camera.

info instance-attribute

info: NotRequired[CameraInformation]

Camera hardware information.

Camera

Bases: BaseCamera

Camera with resolved video sources.

sources instance-attribute

sources: list[CameraInput]

Video input sources.

CameraConfig

Bases: BaseCameraConfig

Full camera configuration with sources.

sources instance-attribute

sources: list[CameraConfigInputSettings]

Video input sources.

CameraConfigInputSettings

Bases: TypedDict

Camera input settings for config.

name instance-attribute

name: str

Source display name.

role instance-attribute

role: CameraRole

Resolution role.

useForSnapshot instance-attribute

useForSnapshot: bool

Use this source for snapshots.

hotMode instance-attribute

hotMode: bool

Keep connection always active.

preload instance-attribute

preload: bool

Keep a keyframe cache for this source, so the view opens faster. Use hotMode to keep the stream connected.

muted instance-attribute

muted: NotRequired[bool]

Strip the audio track from this source (defaults to False).

childSourceId instance-attribute

childSourceId: NotRequired[str]

Child source ID (for snapshot fallback).

urls instance-attribute

urls: NotRequired[list[str]]

Raw source URLs, the server resolves them into streaming URLs.

CameraInformation

Bases: TypedDict

Camera hardware/firmware information.

model instance-attribute

model: str

Camera model name.

manufacturer instance-attribute

manufacturer: str

Manufacturer name.

hardware instance-attribute

hardware: str

Hardware version/revision.

serialNumber instance-attribute

serialNumber: str

Device serial number.

firmwareVersion instance-attribute

firmwareVersion: str

Current firmware version.

supportUrl instance-attribute

supportUrl: str

Manufacturer support URL.

CameraInput

Bases: TypedDict

Camera video input/source with resolved URLs.

name instance-attribute

name: str

Source display name.

role instance-attribute

role: CameraRole

Resolution role.

useForSnapshot instance-attribute

useForSnapshot: bool

Use this source for snapshots.

hotMode instance-attribute

hotMode: bool

Keep connection always active.

preload instance-attribute

preload: bool

Keep a keyframe cache for this source, so the view opens faster. Use hotMode to keep the stream connected.

muted instance-attribute

muted: NotRequired[bool]

Strip the audio track from this source (defaults to False).

urls instance-attribute

urls: StreamUrls

Generated streaming URLs.

videoCodec instance-attribute

videoCodec: NotRequired[VideoCodec]

Probed video codec of this source. Filled by the server once the stream has been probed; absent until then.

audioCodecs instance-attribute

audioCodecs: NotRequired[list[AudioCodec]]

Probed audio codecs of this source (camera to client, deduplicated, in track order). Filled by the server once the stream has been probed; absent until then.

backchannelAudioCodec instance-attribute

backchannelAudioCodec: NotRequired[AudioCodec]

Probed talkback audio codec (client to camera). Present only when the probed source has a backchannel.

childSourceId instance-attribute

childSourceId: NotRequired[str]

Child source ID (for snapshot fallback).

CameraPluginInfo

Bases: TypedDict

Camera source plugin information.

id instance-attribute

id: str

Plugin ID.

name instance-attribute

name: str

Plugin display name.

CameraPropertyObservableObject

Bases: TypedDict

Camera property change event.

property instance-attribute

property: str

Property name that changed.

old_state instance-attribute

old_state: Any

Previous value.

new_state instance-attribute

new_state: Any

New value.

CameraUiSettings

Bases: TypedDict

UI display settings for a camera.

streamingMode instance-attribute

streamingMode: VideoStreamingMode

Preferred streaming method.

streamingSource instance-attribute

streamingSource: StreamingRole

Preferred stream quality.

playbackSource instance-attribute

playbackSource: PlaybackSource

Recorded playback quality. Auto picks the best tier with footage and may switch at coverage edges.

activityMode instance-attribute

activityMode: CameraActivityMode

When the live stream runs: continuously, only during activity, or on demand.

aspectRatio instance-attribute

aspectRatio: CameraAspectRatio

Display aspect ratio.

PluginAssignments

Bases: TypedDict

Plugin assignments for a camera, keyed by sensor type.

Single-provider sensors and the camera controller hold one plugin; multi-provider sensors and the hub hold a list.

motion instance-attribute

motion: AssignedPlugin

Motion detection plugin.

object instance-attribute

object: AssignedPlugin

Object detection plugin.

audio instance-attribute

audio: AssignedPlugin

Audio detection plugin.

face instance-attribute

face: AssignedPlugin

Face detection plugin.

licensePlate instance-attribute

licensePlate: AssignedPlugin

License plate detection plugin.

ptz instance-attribute

ptz: AssignedPlugin

PTZ control plugin.

battery instance-attribute

battery: AssignedPlugin

Battery info plugin.

clip instance-attribute

clip: AssignedPlugin

CLIP embedding plugin.

objectAssist instance-attribute

objectAssist: AssignedPlugin

Object assist plugin for camera-side detections.

cameraController instance-attribute

cameraController: AssignedPlugin

Camera controller plugin.

light instance-attribute

light: list[AssignedPlugin]

Light control plugins.

siren instance-attribute

siren: list[AssignedPlugin]

Siren control plugins.

switch instance-attribute

switch: list[AssignedPlugin]

Switch control plugins.

securitySystem instance-attribute

securitySystem: list[AssignedPlugin]

Security system control plugins.

lock instance-attribute

lock: list[AssignedPlugin]

Lock control plugins.

garage instance-attribute

garage: list[AssignedPlugin]

Garage control plugins.

contact instance-attribute

contact: list[AssignedPlugin]

Contact sensor plugins.

occupancy instance-attribute

occupancy: list[AssignedPlugin]

Occupancy sensor plugins.

smoke instance-attribute

smoke: list[AssignedPlugin]

Smoke sensor plugins.

leak instance-attribute

leak: list[AssignedPlugin]

Leak sensor plugins.

gas instance-attribute

gas: list[AssignedPlugin]

Gas sensor plugins.

carbonMonoxide instance-attribute

carbonMonoxide: list[AssignedPlugin]

Carbon monoxide sensor plugins.

heat instance-attribute

heat: list[AssignedPlugin]

Heat sensor plugins.

cold instance-attribute

cold: list[AssignedPlugin]

Cold sensor plugins.

vibration instance-attribute

vibration: list[AssignedPlugin]

Vibration sensor plugins.

tamper instance-attribute

tamper: list[AssignedPlugin]

Tamper sensor plugins.

problem instance-attribute

problem: list[AssignedPlugin]

Problem sensor plugins.

power instance-attribute

power: list[AssignedPlugin]

Power sensor plugins.

doorbell instance-attribute

doorbell: list[AssignedPlugin]

Doorbell trigger plugins.

temperature instance-attribute

temperature: list[AssignedPlugin]

Temperature info plugins.

humidity instance-attribute

humidity: list[AssignedPlugin]

Humidity info plugins.

illuminance instance-attribute

illuminance: list[AssignedPlugin]

Illuminance info plugins.

carbonDioxide instance-attribute

carbonDioxide: list[AssignedPlugin]

Carbon dioxide info plugins.

classifier instance-attribute

classifier: list[AssignedPlugin]

Image classifier plugins.

hub instance-attribute

hub: list[AssignedPlugin]

Hub/bridge plugins.

AlertZone

Bases: TypedDict

Alert zone configuration. Never filters detections: a label selected here only sends push notifications while an object of that label is inside the zone.

name instance-attribute

name: str

Zone display name.

points instance-attribute

points: list[Point]

Polygon points (0-100 percentage coordinates).

labels instance-attribute

labels: list[DetectionLabel]

Labels that alert from inside this zone (empty = every label alerts here).

faces instance-attribute

faces: NotRequired[list[str]]

Faces that may push from inside this zone. Missing leaves faces out of the decision, an empty list lets every recognized face push, otherwise only the listed identities do. unknown covers everyone the recognition could not name, including people whose face was never captured.

plates instance-attribute

plates: NotRequired[list[str]]

Plates that may push from inside this zone, same rules as faces. Plates are OCR text, so the list is free-form rather than picked from a roster.

match instance-attribute

match: AlertZoneMatch

When an object counts as inside. Default: contain.

color instance-attribute

color: str

Zone display color (hex).

AudioDetectionSettings

Bases: TypedDict

Audio detection settings.

minDecibels instance-attribute

minDecibels: float

Minimum volume threshold in dBFS (-100 to 0). Audio below this level is skipped.

timeout instance-attribute

timeout: int

Audio dwell time in seconds.

confidence instance-attribute

confidence: NotRequired[float]

Minimum confidence threshold (0 - 1) for a labelled audio detection to count.

CameraDetectionSettings

Bases: TypedDict

Combined detection settings for a camera.

motion instance-attribute

motion: MotionDetectionSettings

Motion detection settings.

object instance-attribute

object: ObjectDetectionSettings

Object detection settings.

audio instance-attribute

audio: AudioDetectionSettings

Audio detection settings.

face instance-attribute

face: NotRequired[FaceDetectionSettings]

Face detection settings.

licensePlate instance-attribute

licensePlate: NotRequired[LicensePlateDetectionSettings]

License plate detection settings.

sensor instance-attribute

sensor: SensorTriggerSettings

Sensor trigger settings.

cascadeDetection instance-attribute

cascadeDetection: NotRequired[bool]

Whether the detection cascade is enabled.

cascadeTimeout instance-attribute

cascadeTimeout: NotRequired[int]

Cascade hold-open window in seconds.

snooze instance-attribute

snooze: NotRequired[bool]

Whether detections are snoozed (paused).

CameraZones

Bases: TypedDict

Everything the zone editor draws, one list per purpose. Motion decides where frame motion counts, object which types count where, privacy where nothing is looked at, alert which types notify from where, and lines report objects crossing them.

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.

name instance-attribute

name: str

Line display name.

points instance-attribute

points: list[Point]

Grab-handle positions (0-100%). Crossing line is perpendicular through midpoint.

direction instance-attribute

direction: LineDirection

Which crossing direction(s) trigger events.

labels instance-attribute

labels: list[DetectionLabel]

Labels to filter (empty = all labels).

color instance-attribute

color: str

Line display color (hex).

FaceDetectionSettings

Bases: TypedDict

Face detection settings.

confidence instance-attribute

confidence: NotRequired[float]

Minimum confidence threshold (0 - 1) for a face to count.

matchThreshold instance-attribute

matchThreshold: NotRequired[float]

Minimum similarity (0 - 1) for a face to be recognized as an enrolled person.

LicensePlateDetectionSettings

Bases: TypedDict

License plate detection settings.

confidence instance-attribute

confidence: NotRequired[float]

Minimum confidence threshold (0 - 1) for a plate to be found in the picture.

ocrConfidence instance-attribute

ocrConfidence: NotRequired[float]

Minimum text recognition confidence (0 - 1) for a plate read to count.

minLength instance-attribute

minLength: NotRequired[int]

Minimum plate text length, shorter reads are dropped as fragments.

MotionDetectionSettings

Bases: TypedDict

Motion detection settings.

resolution instance-attribute

resolution: MotionResolution

Detection resolution quality.

timeout instance-attribute

timeout: int

Motion dwell time in seconds.

MotionZone

Bases: TypedDict

Motion zone configuration. Motion carries no labels, so a motion zone only says where frame motion counts. No motion zone at all means motion counts everywhere.

name instance-attribute

name: str

Zone display name.

points instance-attribute

points: list[Point]

Polygon points (0-100 percentage coordinates).

color instance-attribute

color: str

Zone display color (hex).

ObjectDetectionSettings

Bases: TypedDict

Object detection settings.

confidences instance-attribute

confidences: dict[ObjectDetectionLabel, float]

Minimum confidence threshold (0.3 - 1.0) per object label.

suppressStatic instance-attribute

suppressStatic: NotRequired[bool]

Suppress events from objects that stay stationary across events (e.g. parked cars). Defaults to True.

timeout instance-attribute

timeout: NotRequired[int]

Object dwell time in seconds for camera-based object sensors that report a detection without a matching end report. Frame-based detection ignores this. Defaults to 15.

ObjectZone

Bases: TypedDict

Object zone configuration. With at least one include object zone, an object counts only inside such a zone and only when its label is listed there.

name instance-attribute

name: str

Zone display name.

points instance-attribute

points: list[Point]

Polygon points (0-100 percentage coordinates).

type instance-attribute

type: ZoneType

Intersection detection type.

labels instance-attribute

labels: list[ZoneLabel]

Labels that count in this zone. Besides the detection labels, face and license_plate decide whether an object here is identified at all, so a zone can watch a street without recognizing anyone on it.

color instance-attribute

color: str

Zone display color (hex).

PrivacyZone

Bases: TypedDict

Privacy zone configuration. camera.ui always covers the area in live view, playback and the pictures it generates; dropDetections decides whether detections inside are dropped too.

name instance-attribute

name: str

Zone display name.

points instance-attribute

points: list[Point]

Polygon points (0-100 percentage coordinates).

dropDetections instance-attribute

dropDetections: bool

Whether detections inside are dropped as well. Default: True.

PtzAutotrackSettings

Bases: TypedDict

PTZ autotracking settings: the camera follows detected objects automatically.

enabled instance-attribute

enabled: bool

Whether PTZ autotracking is enabled.

targetLabels instance-attribute

targetLabels: list[str]

Object labels to track (e.g. 'person', 'vehicle').

minConfidence instance-attribute

minConfidence: float

Minimum detection confidence to track (0.3 - 1.0).

triggerDeadZone instance-attribute

triggerDeadZone: float

Dead zone around frame center (0 - 0.3). No motor command while the target is inside this zone.

trackingSpeed instance-attribute

trackingSpeed: float

How aggressively the camera moves to re-center the target (1 - 5). Higher reaches full pan/tilt speed at a smaller off-center error.

leadMs instance-attribute

leadMs: float

Motion prediction (0 - 4000): aim this many milliseconds ahead along the target's measured velocity, covering the time the camera needs to move and settle. 0 disables prediction.

panRate instance-attribute

panRate: float

Camera pan-rate calibration (0.1 - 3): assumed pan travel at full motor speed in normalized frame-widths per second. Lower it if the camera stops short of the target, raise it if it overshoots.

returnToHome instance-attribute

returnToHome: bool

Return to home position when no target is found for homeWaitMs.

homeWaitMs instance-attribute

homeWaitMs: int

How long to wait (ms) without a target before returning home.

minTargetSize instance-attribute

minTargetSize: NotRequired[float]

Smallest target to start following, as a fraction of the frame height (0 - 0.5). 0 disables the limit.

maxTargetSize instance-attribute

maxTargetSize: NotRequired[float]

Largest target to keep following, as a fraction of the frame height (0 - 1). Above it the camera holds its position. 0 disables the limit.

activeHours instance-attribute

activeHours: NotRequired[TimeWindow]

Hours the camera is allowed to follow. Outside them autotracking rests.

SensorTriggerSettings

Bases: TypedDict

Sensor trigger settings (contact, doorbell, switch, light, etc.).

timeout instance-attribute

timeout: int

Sensor trigger timeout in seconds.

triggers instance-attribute

triggers: list[str]

Sensor entity ids that also trigger the detection cascade (in addition to motion/audio).

CameraDevice

Bases: Protocol

Main camera device interface. Provides access to camera streams, sensors, and services.

id property

id: str

Unique camera ID.

nativeId property

nativeId: str | None

Native device ID from plugin.

pluginInfo property

pluginInfo: CameraPluginInfo | None

Source plugin information.

disabled property

disabled: bool

Whether camera is disabled.

name property

name: str

Camera display name.

room property

room: str

Room this camera belongs to.

type property

type: CameraType

Camera type (camera/doorbell).

snapshotSettings property

snapshotSettings: SnapshotSettings

Snapshot settings.

info property

info: CameraInformation

Camera hardware information.

isCloud property

isCloud: bool

Whether camera streams from cloud.

zones property

zones: CameraZones

Zone configurations, one list per purpose.

detectionSettings property

detectionSettings: CameraDetectionSettings

Detection settings.

ptzAutotrack property

ptzAutotrack: PtzAutotrackSettings

PTZ autotracking settings.

recordingSettings property

recordingSettings: CameraRecordingSettings

Recording settings.

snooze property

snooze: bool

Whether detections are snoozed (paused).

frameWorkerSettings property

frameWorkerSettings: CameraFrameWorkerSettings

Frame worker settings.

interfaceSettings property

interfaceSettings: CameraUiSettings

UI display settings.

sources property

sources: list[CameraDeviceSource]

All video sources.

streamSource property

streamSource: CameraDeviceSource

Primary streaming source.

highResolutionSource property

highResolutionSource: CameraDeviceSource | None

High resolution source (if available).

midResolutionSource property

midResolutionSource: CameraDeviceSource | None

Mid resolution source (if available).

lowResolutionSource property

lowResolutionSource: CameraDeviceSource | None

Low resolution source (if available).

snapshotSource property

snapshotSource: CameraSource | None

Snapshot source (if available).

connected property

connected: bool

Whether camera is connected.

frameWorkerConnected property

frameWorkerConnected: bool

Whether frame worker is connected.

onConnected property

onConnected: Observable[bool]

Observable for connection state changes.

onFrameWorkerConnected property

onFrameWorkerConnected: Observable[bool]

Observable for frame worker state changes.

onDetectionEvent property

onDetectionEvent: Observable[DetectionEventPayload]

Observable for detection events.

Emits 'start', 'update', 'end', 'segment-start', 'segment-update' and 'segment-end'. Segments ride on the segment-* messages only, thumbnails on 'segment-start' and 'segment-end'.

logger property

logger: LoggerService

Logger service for this camera.

getSourceById

getSourceById(id: str) -> CameraDeviceSource | None

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.

createStorage

createStorage(schemas: list[JsonSchema]) -> DeviceStorage

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.

connect async

connect() -> None

Tell the server this camera is online.

Only the plugin that owns this camera (via pluginInfo) may connect it.

disconnect async

disconnect() -> None

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.

addSensor async

addSensor(sensor: Sensor[Any, Any, Any]) -> None

Register a sensor that belongs to this camera's hardware (spotlight, siren, PTZ, battery, ...). The host assigns it to this camera and reconciles it across restarts like a standalone sensor.

Registering here declares "this sensor belongs to this camera and no other": the assignment is locked, users cannot re-assign it. For sensors the user should assign freely, register via sensorManager.addSensor() instead.

Parameters:

Name	Type	Description	Default
sensor	Sensor[Any, Any, Any]	Sensor instance to register.	required

removeSensor async

removeSensor(sensorId: str) -> None

Unregister a sensor this plugin registered on this camera. The persisted entity stays (shows disconnected) unless the user deletes it.

Parameters:

Name	Type	Description	Default
sensorId	str	ID of sensor to unregister.	required

implement async

implement(impl: CameraImplementation) -> None

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

CameraDeviceSource

Bases: CameraSource, Protocol

Camera source with full streaming capabilities.

generateRTSPUrl

generateRTSPUrl(options: RTSPUrlOptions | None = None) -> str

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.

name instance-attribute

name: str

Source display name.

role instance-attribute

role: CameraRole

Resolution role.

useForSnapshot instance-attribute

useForSnapshot: bool

Use this source for snapshots.

hotMode instance-attribute

hotMode: bool

Keep connection always active.

preload instance-attribute

preload: bool

Keep a keyframe cache for this source, so the view opens faster. Use hotMode to keep the stream connected.

muted instance-attribute

muted: bool | None

Strip the audio track from this source (defaults to False).

urls instance-attribute

urls: StreamUrls

Generated streaming URLs.

childSourceId instance-attribute

childSourceId: str | None

Child source ID (for snapshot fallback).

snapshot async

snapshot(forceNew: bool = False) -> bytes | None

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

probeStream(probeConfig: ProbeConfig | None = None, refresh: bool = False) -> ProbeStream | None

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

getStreamStatus() -> str

Get the current stream connection status.

Returns:

Type	Description
str	Status string: 'connected', 'connecting', 'error', or 'idle'.

generateSnapshotUrl

generateSnapshotUrl(options: SnapshotUrlOptions | None = None) -> str

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

Optional implementation that provides snapshots.

snapshot async

snapshot(source_id: str, force_new: bool = False) -> bytes | None

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

Optional implementation that provides stream URLs.

streamUrl async

streamUrl(source_id: str) -> str

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.

id instance-attribute

id: str

Unique event ID.

cameraId instance-attribute

cameraId: str

Camera that produced this event.

state instance-attribute

state: Literal['active', 'ended']

Event lifecycle state.

startTime instance-attribute

startTime: int

Event start time (Unix ms).

endTime instance-attribute

endTime: NotRequired[int]

Event end time (Unix ms, only when ended).

lastUpdate instance-attribute

lastUpdate: int

Last activity timestamp (Unix ms).

types instance-attribute

types: list[str]

Detection types present in this event (for filtering).

triggers instance-attribute

triggers: list[EventTrigger]

Event triggers (motion/audio).

segments instance-attribute

segments: list[EventSegment]

Detection segments (object detection phases). For segment-* messages: contains only the current segment. For start/end messages: empty.

segmentIndex instance-attribute

segmentIndex: NotRequired[int]

Index of the segment in segments[0] for segment-* messages.

expectedEndTime instance-attribute

expectedEndTime: NotRequired[int]

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.

DetectionEventPayload

Bases: TypedDict

Emitted for detection events (start/update/end).

type instance-attribute

type: DetectionEventType

Event lifecycle type.

event instance-attribute

event: DetectionEvent

Full event data.

EventAttribute

Bases: TypedDict

Unified attribute within a segment (face identity, license plate, classifier result).

type instance-attribute

type: str

Attribute type ('face', 'license_plate', or classifier-specific like 'bird').

label instance-attribute

label: str

Identity name, plate text, or classification label.

confidence instance-attribute

confidence: NotRequired[float]

Detection confidence (0-1).

EventDetection

Bases: TypedDict

Aggregated object detection within a segment.

label instance-attribute

label: str

Detection label (e.g. "person", "car").

score instance-attribute

score: float

Best confidence score.

maxCount instance-attribute

maxCount: int

Maximum simultaneous count in a single frame.

moving instance-attribute

moving: NotRequired[bool]

Whether the object was moving (True) or stationary (False).

path instance-attribute

path: NotRequired[DetectionPath]

Where the tracked object entered and left the frame within this segment.

zones instance-attribute

zones: NotRequired[list[str]]

Names of detection/alert zones any object of this label overlapped during the segment.

alert instance-attribute

alert: NotRequired[bool]

Whether this detection may raise a notification. Alert zones decide it, the camera's own reports pass.

EventSegment

Bases: TypedDict

A contiguous object detection phase within an event.

firstSeen instance-attribute

firstSeen: int

Segment start time (Unix ms).

lastSeen instance-attribute

lastSeen: int

Segment end time (Unix ms).

detections instance-attribute

detections: list[EventDetection]

Object detections in this segment.

attributes instance-attribute

attributes: list[EventAttribute]

Unified attributes (faces, plates, classifications).

zones instance-attribute

zones: NotRequired[list[str]]

Names of detection zones any detection in this segment overlapped (deduplicated).

EventTrigger

Bases: TypedDict

Event trigger (motion, audio, sensor, or line-crossing).

type instance-attribute

type: EventTriggerType

Trigger type.

label instance-attribute

label: NotRequired[str]

Audio label (e.g. "doorbell", "glass_break").

score instance-attribute

score: NotRequired[float]

Best confidence score.

firstSeen instance-attribute

firstSeen: int

First detection time (Unix ms).

lastSeen instance-attribute

lastSeen: int

Last detection time (Unix ms).

lineName instance-attribute

lineName: NotRequired[str]

Name of the crossed line (only for line-crossing triggers).

crossingDirection instance-attribute

crossingDirection: NotRequired[str]

Crossing direction (only for line-crossing triggers).

trackId instance-attribute

trackId: NotRequired[int]

Track ID of the object that crossed (only for line-crossing triggers).

CameraFrameWorkerSettings

Bases: TypedDict

Frame worker (decoder) settings.

mainStreamAnalysis instance-attribute

mainStreamAnalysis: NotRequired[bool]

Analyse the main stream while something is detected, instead of the detection stream.

decoder instance-attribute

decoder: NotRequired[FrameWorkerDecoderSettings]

Decoder hardware selection. Applies on the machine that decodes this camera (master or assigned worker); an unusable selection falls back to auto.

workerDecoder instance-attribute

workerDecoder: NotRequired[FrameWorkerDecoderSettings]

Decoder hardware selection used instead of decoder while this camera decodes on its assigned worker. Falls back to decoder when omitted.

FrameWorkerDecoderSettings

Bases: TypedDict

Decoder hardware selection for the frame worker.

hardware instance-attribute

hardware: FrameWorkerDecoderHardware

Hardware backend to decode with.

device instance-attribute

device: NotRequired[str]

Device the backend opens (GPU index like 0, or a path like /dev/dri/renderD128). Backend default when omitted.

SnapshotSettings

Bases: TypedDict

Snapshot settings for a camera.

autoRefresh instance-attribute

autoRefresh: bool

Enable automatic snapshot refresh.

ttl instance-attribute

ttl: int

Cache TTL in seconds (how long a snapshot is valid).

interval instance-attribute

interval: int

Auto-refresh interval in seconds (min: 10, max: 60).

CameraNotificationSettings

Bases: TypedDict

Push notification settings for a camera.

enabled instance-attribute

enabled: bool

Whether detections on this camera send a push at all.

video instance-attribute

video: bool

Attach a short clip of the moment. Needs recording, uses the lowest recorded quality.

audio instance-attribute

audio: list[str]

Audio events that send a push. other covers custom audio labels.

sensors instance-attribute

sensors: list[str]

Sensor triggers that send a push, by sensor type.

cooldown instance-attribute

cooldown: float

Minimum seconds between pushes. Critical alerts bypass it and do not count toward it.

speed instance-attribute

speed: NotificationSpeed

How long a push waits for a good picture.

CameraRecordingSettings

Bases: TypedDict

Recording settings for a camera.

enabled instance-attribute

enabled: bool

Whether recording is enabled.

mode instance-attribute

mode: RecordingMode

Recording mode.

preBuffer instance-attribute

preBuffer: float

Seconds of video kept before an event (event mode, 0 - 60).

sources instance-attribute

sources: list[RecordingSource]

Stream tiers to record.

AudioCodecProperties

Bases: TypedDict

Audio codec properties from stream probe.

sampleRate instance-attribute

sampleRate: int

Audio sample rate in Hz.

channels instance-attribute

channels: int

Number of audio channels.

payloadType instance-attribute

payloadType: int

RTP payload type.

fmtpInfo instance-attribute

fmtpInfo: NotRequired[FMTPInfo]

Optional format parameters.

AudioStreamInfo

Bases: TypedDict

Audio stream information from probe.

codec instance-attribute

codec: AudioCodec

Audio codec.

ffmpegCodec instance-attribute

ffmpegCodec: AudioFFmpegCodec

FFmpeg codec name.

properties instance-attribute

properties: AudioCodecProperties

Codec properties.

direction instance-attribute

direction: StreamDirection

Stream direction.

FMTPInfo

Bases: TypedDict

Format parameters (fmtp) from SDP.

payload instance-attribute

payload: int

RTP payload type number.

config instance-attribute

config: str

Codec-specific configuration string.

Go2RtcRTSPSource

Bases: TypedDict

RTSP streaming URLs from go2rtc.

base instance-attribute

base: str

Base RTSP URL.

default instance-attribute

default: str

Default stream (video + audio).

muted instance-attribute

muted: str

Video only (muted).

audioOnly instance-attribute

audioOnly: str

Audio only (no video).

aac instance-attribute

aac: str

Stream with AAC audio URL.

opus instance-attribute

opus: str

Stream with Opus audio URL.

pcma instance-attribute

pcma: str

Stream with PCMA audio URL.

onvif instance-attribute

onvif: str

ONVIF URL.

noGop instance-attribute

noGop: str

Stream URL with GOP cache disabled.

Go2RtcSnapshotSource

Bases: TypedDict

Snapshot/image URLs from go2rtc.

mp4 instance-attribute

mp4: str

MP4 single-frame video URL.

jpeg instance-attribute

jpeg: str

JPEG snapshot URL.

mjpeg instance-attribute

mjpeg: str

MJPEG stream URL.

Go2RtcWSSource

Bases: TypedDict

WebSocket streaming URLs from go2rtc.

webrtc instance-attribute

webrtc: str

WebRTC signaling endpoint.

mse instance-attribute

mse: str

MSE streaming endpoint.

ProbeConfig

Bases: TypedDict

Configuration for stream probing.

video instance-attribute

video: bool

Include video track info.

audio instance-attribute

audio: bool | Literal['all'] | list[ProbeAudioCodec]

Include audio track info (true, 'all', or specific codecs).

microphone instance-attribute

microphone: bool

Include microphone/backchannel info.

ProbeStream

Bases: TypedDict

Stream probe result containing SDP and track information.

sdp instance-attribute

sdp: str

Raw SDP string.

audio instance-attribute

audio: list[AudioStreamInfo]

Available audio tracks.

video instance-attribute

video: list[VideoStreamInfo]

Available video tracks.

RTSPUrlOptions

Bases: TypedDict

Options for generating RTSP URLs.

video instance-attribute

video: bool

Include video track.

audio instance-attribute

audio: bool | RTSPAudioCodec | list[RTSPAudioCodec]

Include audio track(s).

gop instance-attribute

gop: bool

Request keyframe at start (GOP).

audioSingleTrack instance-attribute

audioSingleTrack: bool

Combine audio tracks into single track.

backchannel instance-attribute

backchannel: bool

Enable backchannel (two-way audio).

timeout instance-attribute

timeout: int

Connection timeout in s.

SnapshotUrlOptions

Bases: TypedDict

Options for generating snapshot URLs.

width instance-attribute

width: int

Output width in pixels.

height instance-attribute

height: int

Output height in pixels.

rotate instance-attribute

rotate: Literal[90, 180, 270, -90]

Rotation in degrees.

cache instance-attribute

cache: str

Cache key/strategy.

hw instance-attribute

hw: Literal['vaapi', 'v4l2m2m', 'cuda', 'dxva2', 'videotoolbox', 'rkmpp']

Hardware acceleration backend.

gop instance-attribute

gop: bool

Request keyframe at start (GOP).

StreamUrls

Bases: TypedDict

Collection of all streaming URLs for a camera source.

ws instance-attribute

ws: Go2RtcWSSource

WebSocket URLs.

rtsp instance-attribute

rtsp: Go2RtcRTSPSource

RTSP URLs.

snapshot instance-attribute

snapshot: Go2RtcSnapshotSource

Snapshot URLs.

VideoCodecProperties

Bases: TypedDict

Video codec properties from stream probe.

clockRate instance-attribute

clockRate: int

Video clock rate.

payloadType instance-attribute

payloadType: int

RTP payload type.

fmtpInfo instance-attribute

fmtpInfo: NotRequired[FMTPInfo]

Optional format parameters.

VideoStreamInfo

Bases: TypedDict

Video stream information from probe.

codec instance-attribute

codec: VideoCodec

Video codec.

ffmpegCodec instance-attribute

ffmpegCodec: VideoFFmpegCodec

FFmpeg codec name.

properties instance-attribute

properties: VideoCodecProperties

Codec properties.

direction instance-attribute

direction: StreamDirection

Stream direction.