@camera.ui/server 0.0.70 → 0.0.71-dev.0

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/camera/device.py

@@ -0,0 +1,432 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Protocol, TypeAlias, runtime_checkable
+
+if TYPE_CHECKING:
+    from ..observable import Disposable, Observable
+    from ..sensor.base import Sensor, SensorLike, SensorType
+    from ..storage import DeviceStorage, JsonSchema
+    from ..types import LoggerService
+
+from .config import (
+    CameraInformation,
+    CameraPluginInfo,
+    CameraPropertyObservableObject,
+    CameraPublicProperties,
+    CameraUiSettings,
+    SensorEventData,
+)
+from .detection import CameraDetectionSettings, DetectionLine, DetectionZone, PtzAutotrackSettings
+from .enums import CameraRole, CameraType
+from .events import DetectionEventPayload
+from .frames import CameraFrameWorkerSettings, SnapshotSettings
+from .streaming import (
+    ProbeConfig,
+    ProbeStream,
+    RTSPUrlOptions,
+    SnapshotUrlOptions,
+    StreamUrls,
+)
+
+
+@runtime_checkable
+class CameraSource(Protocol):
+    """Camera source with snapshot and probe capabilities."""
+
+    _id: str
+    """Unique source ID."""
+    name: str
+    """Source display name."""
+    role: CameraRole
+    """Resolution role."""
+    useForSnapshot: bool
+    """Use this source for snapshots."""
+    hotMode: bool
+    """Keep connection always active."""
+    preload: bool
+    """Preload stream on startup."""
+    prebuffer: bool
+    """Enable stream prebuffering."""
+    urls: StreamUrls
+    """Generated streaming URLs."""
+    childSourceId: str | None
+    """Child source ID (for snapshot fallback)."""
+
+    async def snapshot(self, forceNew: bool = False) -> bytes | None:
+        """
+        Get camera snapshot image.
+
+        Args:
+            forceNew: Force fresh snapshot (ignore cache).
+
+        Returns:
+            JPEG image data or None if unavailable.
+        """
+        ...
+
+    async def probeStream(
+        self, probeConfig: ProbeConfig | None = None, refresh: bool = False
+    ) -> ProbeStream | None:
+        """
+        Probe stream for codec and track information.
+
+        Args:
+            probeConfig: What to probe for.
+            refresh: Force fresh probe (ignore cache).
+
+        Returns:
+            Stream information or None if unavailable.
+        """
+        ...
+
+    async def getStreamStatus(self) -> str:
+        """
+        Get the current stream connection status.
+
+        Returns:
+            Status string: 'connected', 'connecting', 'error', or 'idle'.
+        """
+        ...
+
+    def generateSnapshotUrl(self, options: SnapshotUrlOptions | None = None) -> str:
+        """
+        Generate Snapshot URL with specified options.
+
+        Args:
+            options: URL generation options.
+
+        Returns:
+            Snapshot URL string.
+        """
+        ...
+
+
+@runtime_checkable
+class CameraDeviceSource(CameraSource, Protocol):
+    """Camera source with full streaming capabilities."""
+
+    def generateRTSPUrl(self, options: RTSPUrlOptions | None = None) -> str:
+        """
+        Generate RTSP URL with specified options.
+
+        Args:
+            options: URL generation options.
+
+        Returns:
+            RTSP URL string.
+        """
+        ...
+
+
+@runtime_checkable
+class CameraDevice(Protocol):
+    """
+    Main camera device interface.
+    Provides access to camera streams, sensors, and services.
+    """
+
+    @property
+    def id(self) -> str:
+        """Unique camera ID."""
+        ...
+
+    @property
+    def nativeId(self) -> str | None:
+        """Native device ID from plugin."""
+        ...
+
+    @property
+    def pluginInfo(self) -> CameraPluginInfo | None:
+        """Source plugin information."""
+        ...
+
+    @property
+    def disabled(self) -> bool:
+        """Whether camera is disabled."""
+        ...
+
+    @property
+    def name(self) -> str:
+        """Camera display name."""
+        ...
+
+    @property
+    def room(self) -> str:
+        """Room this camera belongs to."""
+        ...
+
+    @property
+    def type(self) -> CameraType:
+        """Camera type (camera/doorbell)."""
+        ...
+
+    @property
+    def snapshotSettings(self) -> SnapshotSettings:
+        """Snapshot settings."""
+        ...
+
+    @property
+    def info(self) -> CameraInformation:
+        """Camera hardware information."""
+        ...
+
+    @property
+    def isCloud(self) -> bool:
+        """Whether camera streams from cloud."""
+        ...
+
+    @property
+    def detectionZones(self) -> list[DetectionZone]:
+        """Detection zone configurations."""
+        ...
+
+    @property
+    def detectionLines(self) -> list[DetectionLine]:
+        """Detection line configurations (virtual tripwires)."""
+        ...
+
+    @property
+    def detectionSettings(self) -> CameraDetectionSettings:
+        """Detection settings."""
+        ...
+
+    @property
+    def ptzAutotrack(self) -> PtzAutotrackSettings:
+        """PTZ autotracking settings."""
+        ...
+
+    @property
+    def snooze(self) -> bool:
+        """Whether detections are snoozed (paused)."""
+        ...
+
+    @property
+    def frameWorkerSettings(self) -> CameraFrameWorkerSettings:
+        """Frame worker settings."""
+        ...
+
+    @property
+    def interfaceSettings(self) -> CameraUiSettings:
+        """UI display settings."""
+        ...
+
+    @property
+    def sources(self) -> list[CameraDeviceSource]:
+        """All video sources."""
+        ...
+
+    @property
+    def streamSource(self) -> CameraDeviceSource:
+        """Primary streaming source."""
+        ...
+
+    @property
+    def highResolutionSource(self) -> CameraDeviceSource | None:
+        """High resolution source (if available)."""
+        ...
+
+    @property
+    def midResolutionSource(self) -> CameraDeviceSource | None:
+        """Mid resolution source (if available)."""
+        ...
+
+    @property
+    def lowResolutionSource(self) -> CameraDeviceSource | None:
+        """Low resolution source (if available)."""
+        ...
+
+    @property
+    def snapshotSource(self) -> CameraSource | None:
+        """Snapshot source (if available)."""
+        ...
+
+    def getSourceById(self, id: str) -> CameraDeviceSource | None:
+        """
+        Get a source by its ID.
+
+        Args:
+            id: The source ID.
+
+        Returns:
+            The matching source, or None if not found.
+        """
+        ...
+
+    @property
+    def connected(self) -> bool:
+        """Whether camera is connected."""
+        ...
+
+    @property
+    def frameWorkerConnected(self) -> bool:
+        """Whether frame worker is connected."""
+        ...
+
+    @property
+    def onConnected(self) -> Observable[bool]:
+        """Observable for connection state changes."""
+        ...
+
+    @property
+    def onFrameWorkerConnected(self) -> Observable[bool]:
+        """Observable for frame worker state changes."""
+        ...
+
+    @property
+    def logger(self) -> LoggerService:
+        """Logger service for this camera."""
+        ...
+
+    async def connect(self) -> None:
+        """
+        Tell the server this camera is online.
+
+        Only the plugin that owns this camera (via pluginInfo) may connect it.
+        """
+        ...
+
+    async def disconnect(self) -> None:
+        """
+        Tell the server this camera is offline.
+
+        Only the plugin that owns this camera (via pluginInfo) may disconnect it.
+        """
+        ...
+
+    def onPropertyChange(
+        self, property: CameraPublicProperties | list[CameraPublicProperties]
+    ) -> Observable[CameraPropertyObservableObject]:
+        """
+        Observe camera property changes.
+
+        Args:
+            property: Property name(s) to observe.
+
+        Returns:
+            Observable emitting old and new values.
+        """
+        ...
+
+    def getSensors(self) -> list[SensorLike]:
+        """Get all sensors attached to this camera (owned + foreign)."""
+        ...
+
+    def getSensor(self, sensorId: str) -> SensorLike | None:
+        """Get sensor by ID (checks owned and foreign sensors)."""
+        ...
+
+    def getSensorsByType(self, sensorType: SensorType) -> list[SensorLike]:
+        """Get all sensors of a specific type (owned + foreign)."""
+        ...
+
+    def onSensorProperty(
+        self,
+        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.
+
+        Args:
+            sensor_type: The sensor type to watch.
+            property: The property name to observe.
+            callback: Called with (value, timestamp_ms, sensor) when the property changes.
+
+        Returns:
+            Disposable to stop all subscriptions.
+        """
+        ...
+
+    async def addSensor(self, sensor: Sensor[Any, Any, Any]) -> None:
+        """
+        Add a sensor to this camera.
+
+        Args:
+            sensor: Sensor instance to add.
+        """
+        ...
+
+    async def removeSensor(self, sensorId: str) -> None:
+        """
+        Remove a sensor from this camera.
+
+        Args:
+            sensorId: ID of sensor to remove.
+        """
+        ...
+
+    @property
+    def onSensorAdded(self) -> Observable[SensorEventData]:
+        """Observable for sensor additions. Emits SensorEventData when a sensor from another plugin is added."""
+        ...
+
+    @property
+    def onSensorRemoved(self) -> Observable[SensorEventData]:
+        """Observable for sensor removals. Emits SensorEventData when a sensor from another plugin is removed."""
+        ...
+
+    @property
+    def onDetectionEvent(self) -> Observable[DetectionEventPayload]:
+        """Observable for detection events (start/update/end). Thumbnails in segments are only populated on 'end' events."""
+        ...
+
+    async def implement(self, impl: CameraImplementation) -> None:
+        """
+        Register a camera implementation for streaming and/or snapshot.
+
+        The impl value should implement StreamingInterface, SnapshotInterface,
+        or both.
+
+        Args:
+            impl: Object or class implementing camera interfaces
+        """
+        ...
+
+    def createStorage(self, schemas: list[JsonSchema]) -> DeviceStorage:
+        """
+        Create storage for plugin-specific camera configuration.
+
+        Args:
+            schemas: Schema definitions for the storage
+
+        Returns:
+            Typed device storage instance
+        """
+        ...
+
+
+@runtime_checkable
+class StreamingInterface(Protocol):
+    async def streamUrl(self, source_id: str) -> str:
+        """
+        Get the streaming URL for a source.
+
+        Args:
+            source_id: The ID of the source
+
+        Returns:
+            The streaming URL (e.g., rtsp://, rtmp://, or custom protocol)
+        """
+        ...
+
+
+@runtime_checkable
+class SnapshotInterface(Protocol):
+    async def snapshot(self, source_id: str, force_new: bool = False) -> bytes | None:
+        """
+        Get a snapshot image from the camera.
+
+        Args:
+            source_id: The source ID to get the snapshot from
+            force_new: If True, bypass cache and get a fresh snapshot
+
+        Returns:
+            Image data as bytes, or None if unavailable
+        """
+        ...
+
+
+CameraImplementation: TypeAlias = StreamingInterface | SnapshotInterface

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/camera/enums.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Literal
+
+CameraType = Literal["camera", "doorbell"]
+"""
+Camera device type.
+- `camera`: Standard surveillance camera
+- `doorbell`: Doorbell camera
+"""
+
+ZoneType = Literal["intersect", "contain"]
+"""
+Detection zone intersection type.
+- `intersect`: Trigger when object touches the zone boundary
+- `contain`: Trigger only when object is fully inside the zone
+"""
+
+ZoneFilter = Literal["include", "exclude"]
+"""
+Detection zone filter mode.
+- `include`: Only consider detections inside this zone
+- `exclude`: Only consider detections outside this zone
+"""
+
+CameraRole = Literal["high-resolution", "mid-resolution", "low-resolution", "snapshot"]
+"""
+Camera stream resolution role.
+Used to identify different quality streams from the same camera.
+"""
+
+StreamingRole = Literal["high-resolution", "mid-resolution", "low-resolution"]
+"""Streaming roles (excludes snapshot)."""
+
+MotionResolution = Literal["low", "medium", "high"]
+"""
+Motion detection resolution setting.
+Higher resolution = more accurate but slower.
+"""
+
+AudioCodec = Literal[
+    "PCMU", "PCMA", "MPEG4-GENERIC", "opus", "G722", "G726", "MPA", "PCM", "FLAC", "ELD", "PCML", "L16"
+]
+"""Supported audio codecs (RTP/SDP format names)."""
+
+AudioFFmpegCodec = Literal[
+    "pcm_mulaw", "pcm_alaw", "aac", "libopus", "g722", "g726", "mp3", "pcm_s16be", "pcm_s16le", "flac"
+]
+"""FFmpeg audio codec names for transcoding."""
+
+VideoCodec = Literal["H264", "H265", "VP8", "VP9", "AV1", "JPEG", "RAW"]
+"""Supported video codecs (RTP/SDP format names)."""
+
+VideoFFmpegCodec = Literal["h264", "hevc", "vp8", "vp9", "av1", "mjpeg", "rawvideo"]
+"""FFmpeg video codec names for transcoding."""
+
+RTSPAudioCodec = Literal["aac", "opus", "pcma"]
+"""Audio codecs supported for RTSP streaming."""
+
+ProbeAudioCodec = Literal["aac", "opus", "pcma"]
+"""Audio codecs supported for stream probing."""
+
+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)
+"""
+
+CameraAspectRatio = Literal["16:9", "9:16", "8:3", "4:3", "1:1"]
+"""Camera aspect ratio for UI display."""
+
+Point = tuple[float, float]
+"""Zone polygon coordinate as [x, y] tuple (0-100 percentage)."""
+
+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
+"""
+
+StreamDirection = Literal["sendonly", "recvonly", "sendrecv", "inactive"]
+"""Stream direction (from SDP)."""
+
+DetectionEventState = Literal["active", "ended"]
+"""Event lifecycle state."""
+
+EventTriggerType = Literal[
+    "motion", "audio", "contact", "doorbell", "switch", "light", "siren", "security_system", "line-crossing"
+]
+"""Event trigger type."""
+
+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."""
+
+DetectionEventType = Literal["start", "end", "update", "segment-start", "segment-update", "segment-end"]
+"""Detection event message type (lifecycle phase)."""

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/camera/events.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import Literal, NotRequired, TypedDict
+
+from ..sensor.detection import BoundingBox
+from .enums import DetectionEventType, EventTriggerType
+
+
+class EventDetection(TypedDict):
+    """Aggregated object detection within a segment."""
+
+    label: str
+    """Detection label (e.g. "person", "car")."""
+    score: float
+    """Best confidence score."""
+    maxCount: int
+    """Maximum simultaneous count in a single frame."""
+    box: NotRequired[BoundingBox]
+    """Bounding box of the highest-confidence detection (normalized 0-1)."""
+    thumbnail: NotRequired[bytes]
+    """Best-selected JPEG thumbnail crop. Only present on 'end' events."""
+    trackId: NotRequired[int]
+    """Object tracker ID (links this detection across frames)."""
+    moving: NotRequired[bool]
+    """Whether the object was moving (True) or stationary (False)."""
+
+
+class EventAttribute(TypedDict):
+    """Unified attribute within a segment (face identity, license plate, classifier result)."""
+
+    type: str
+    """Attribute type ('face', 'license_plate', or classifier-specific like 'bird')."""
+    label: str
+    """Identity name, plate text, or classification label."""
+    confidence: NotRequired[float]
+    """Detection confidence (0-1)."""
+    thumbnail: NotRequired[bytes]
+    """Best-selected JPEG thumbnail crop. Only present on 'end' events."""
+    embedding: NotRequired[list[float]]
+    """Face embedding vector for unknown face persistence. Only present for face attributes."""
+    embeddingModel: NotRequired[str]
+    """Embedding model identifier. Only present for face attributes with embedding."""
+    clipEmbedding: NotRequired[list[float]]
+    """CLIP embedding vector for semantic search. Only present for clip attributes."""
+    clipEmbeddingModel: NotRequired[str]
+    """CLIP embedding model identifier. Only present for clip attributes with embedding."""
+    parentTrackId: NotRequired[int]
+    """Parent object's tracker ID (links this attribute to its parent detection)."""
+
+
+class EventTrigger(TypedDict):
+    """Event trigger (motion, audio, sensor, or line-crossing)."""
+
+    type: EventTriggerType
+    """Trigger type."""
+    label: NotRequired[str]
+    """Audio label (e.g. "doorbell", "glass_break")."""
+    score: NotRequired[float]
+    """Best confidence score."""
+    firstSeen: int
+    """First detection time (Unix ms)."""
+    lastSeen: int
+    """Last detection time (Unix ms)."""
+    lineName: NotRequired[str]
+    """Name of the crossed line (only for line-crossing triggers)."""
+    crossingDirection: NotRequired[str]
+    """Crossing direction (only for line-crossing triggers)."""
+    trackId: NotRequired[int]
+    """Track ID of the object that crossed (only for line-crossing triggers)."""
+
+
+class EventDescription(TypedDict):
+    """AI-generated event description."""
+
+    title: str
+    """Brief title of what occurred."""
+    description: str
+    """Chronological narrative of the scene."""
+    summary: str
+    """Two-sentence notification-friendly summary."""
+    threatLevel: int
+    """Threat level: 0 = normal, 1 = suspicious, 2 = threat."""
+
+
+class EventSegment(TypedDict):
+    """A contiguous object detection phase within an event."""
+
+    firstSeen: int
+    """Segment start time (Unix ms)."""
+    lastSeen: int
+    """Segment end time (Unix ms)."""
+    thumbnail: NotRequired[bytes]
+    """Best-selected JPEG scene thumbnail for this segment. Only present on 'end' events."""
+    detections: list[EventDetection]
+    """Object detections in this segment."""
+    attributes: list[EventAttribute]
+    """Unified attributes (faces, plates, classifications)."""
+    zones: NotRequired[list[str]]
+    """Names of detection zones any detection in this segment overlapped (deduplicated)."""
+    description: NotRequired[EventDescription]
+    """AI-generated description for this segment."""
+
+
+class DetectionEvent(TypedDict):
+    """Aggregated detection event with lifecycle (start -> update -> end).
+    Groups individual sensor detections into structured events."""
+
+    id: str
+    """Unique event ID."""
+    cameraId: str
+    """Camera that produced this event."""
+    state: Literal["active", "ended"]
+    """Event lifecycle state."""
+    startTime: int
+    """Event start time (Unix ms)."""
+    endTime: NotRequired[int]
+    """Event end time (Unix ms, only when ended)."""
+    lastUpdate: int
+    """Last activity timestamp (Unix ms)."""
+    types: list[str]
+    """Detection types present in this event (for filtering)."""
+    triggers: list[EventTrigger]
+    """Event triggers (motion/audio)."""
+    segments: list[EventSegment]
+    """Detection segments (object detection phases).
+    For segment-* messages: contains only the current segment.
+    For start/end messages: empty."""
+    segmentIndex: NotRequired[int]
+    """Index of the segment in segments[0] for segment-* messages."""
+    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."""
+    thumbnail: NotRequired[bytes]
+    """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."""
+
+
+class DetectionEventPayload(TypedDict):
+    """Emitted for detection events (start/update/end)."""
+
+    type: DetectionEventType
+    """Event lifecycle type."""
+    event: DetectionEvent
+    """Full event data."""