@camera.ui/server 2.0.22 → 2.0.23

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

@@ -1,11 +1,10 @@
 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 ..observable import Observable
+    from ..sensor.base import Sensor
     from ..storage import DeviceStorage, JsonSchema
     from ..types import LoggerService
 
@@ -15,7 +14,6 @@ from .config import (
     CameraPropertyObservableObject,
     CameraPublicProperties,
     CameraUiSettings,
-    SensorEventData,
 )
 from .detection import CameraDetectionSettings, DetectionLine, DetectionZone, PtzAutotrackSettings
 from .enums import CameraRole, CameraType
@@ -247,18 +245,6 @@ class CameraDevice(Protocol):
         """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."""
@@ -280,117 +266,98 @@ class CameraDevice(Protocol):
         ...
 
     @property
-    def logger(self) -> LoggerService:
-        """Logger service for this camera."""
-        ...
-
-    async def connect(self) -> None:
+    def onDetectionEvent(self) -> Observable[DetectionEventPayload]:
         """
-        Tell the server this camera is online.
+        Observable for detection events.
 
-        Only the plugin that owns this camera (via pluginInfo) may connect it.
+        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'.
         """
         ...
 
-    async def disconnect(self) -> None:
-        """
-        Tell the server this camera is offline.
-
-        Only the plugin that owns this camera (via pluginInfo) may disconnect it.
-        """
+    @property
+    def logger(self) -> LoggerService:
+        """Logger service for this camera."""
         ...
 
-    def onPropertyChange(
-        self, property: CameraPublicProperties | list[CameraPublicProperties]
-    ) -> Observable[CameraPropertyObservableObject]:
+    def getSourceById(self, id: str) -> CameraDeviceSource | None:
         """
-        Observe camera property changes.
+        Get a source by its ID.
 
         Args:
-            property: Property name(s) to observe.
+            id: The source ID.
 
         Returns:
-            Observable emitting old and new values.
+            The matching source, or None if not found.
         """
         ...
 
-    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:
+    def createStorage(self, schemas: list[JsonSchema]) -> DeviceStorage:
         """
-        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.
+        Create storage for plugin-specific camera configuration.
 
         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.
+            schemas: Schema definitions for the storage.
 
         Returns:
-            Disposable to stop all subscriptions.
+            Typed device storage instance.
         """
         ...
 
-    async def addSensor(self, sensor: Sensor[Any, Any, Any]) -> None:
+    async def connect(self) -> None:
         """
-        Add a sensor to this camera.
+        Tell the server this camera is online.
 
-        Args:
-            sensor: Sensor instance to add.
+        Only the plugin that owns this camera (via pluginInfo) may connect it.
         """
         ...
 
-    async def removeSensor(self, sensorId: str) -> None:
+    async def disconnect(self) -> None:
         """
-        Remove a sensor from this camera.
+        Tell the server this camera is offline.
 
-        Args:
-            sensorId: ID of sensor to remove.
+        Only the plugin that owns this camera (via pluginInfo) may disconnect it.
         """
         ...
 
-    @property
-    def onSensorAdded(self) -> Observable[SensorEventData]:
+    def onPropertyChange(
+        self, property: CameraPublicProperties | list[CameraPublicProperties]
+    ) -> Observable[CameraPropertyObservableObject]:
         """
-        Observable for sensor additions.
+        Observe camera property changes.
 
-        Emits for this plugin's own sensors and for other plugins' sensors whose type is
-        listed in contract.consumes. Also emits when such a sensor is activated for this camera.
+        Args:
+            property: Property name(s) to observe.
+
+        Returns:
+            Observable emitting old and new values.
         """
         ...
 
-    @property
-    def onSensorRemoved(self) -> Observable[SensorEventData]:
+    async def addSensor(self, sensor: Sensor[Any, Any, Any]) -> None:
         """
-        Observable for sensor removals.
+        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.
 
-        Emits for this plugin's own sensors and for other plugins' sensors on this camera.
-        Also emits when a sensor is deactivated for this camera.
+        Args:
+            sensor: Sensor instance to register.
         """
         ...
 
-    @property
-    def onDetectionEvent(self) -> Observable[DetectionEventPayload]:
+    async def removeSensor(self, sensorId: str) -> None:
         """
-        Observable for detection events.
+        Unregister a sensor this plugin registered on this camera. The
+        persisted entity stays (shows disconnected) unless the user deletes it.
 
-        Emits 'start', 'update', 'end', 'segment-start', 'segment-update' and 'segment-end'.
-        Segments only ride on the segment-* events, start/update/end carry an empty segment list.
+        Args:
+            sensorId: ID of sensor to unregister.
         """
         ...
 
@@ -402,52 +369,45 @@ class CameraDevice(Protocol):
         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
+            impl: Object or class implementing camera interfaces.
         """
         ...
 
 
 @runtime_checkable
 class StreamingInterface(Protocol):
+    """Optional implementation that provides stream URLs."""
+
     async def streamUrl(self, source_id: str) -> str:
         """
         Get the streaming URL for a source.
 
         Args:
-            source_id: The ID of the source
+            source_id: The ID of the source.
 
         Returns:
-            The streaming URL (e.g., rtsp://, rtmp://, or custom protocol)
+            The streaming URL (e.g. rtsp://, rtmp://, or custom protocol).
         """
         ...
 
 
 @runtime_checkable
 class SnapshotInterface(Protocol):
+    """Optional implementation that provides snapshots."""
+
     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
+            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
+            Image data as bytes, or None if unavailable.
         """
         ...
 
 
 CameraImplementation: TypeAlias = StreamingInterface | SnapshotInterface
+"""Value accepted by CameraDevice.implement: streaming, snapshot, or both."""

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

@@ -92,7 +92,8 @@ class EventSegment(TypedDict):
     lastSeen: int
     """Segment end time (Unix ms)."""
     thumbnail: NotRequired[bytes]
-    """Best-selected JPEG scene thumbnail for this segment. Only present on 'segment-*' messages."""
+    """Best-selected JPEG scene thumbnail for this segment. Present on 'segment-start' and
+    'segment-end', plus once on a 'segment-update' if the start message had none."""
     detections: list[EventDetection]
     """Object detections in this segment."""
     attributes: list[EventAttribute]
@@ -130,7 +131,7 @@ class DetectionEvent(TypedDict):
     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
+    """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]

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

@@ -38,6 +38,8 @@ class CameraFrameWorkerSettings(TypedDict):
     """Capture event thumbnails from the highest-resolution source."""
     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: NotRequired[FrameWorkerDecoderSettings]
+    """Decoder hardware selection used instead of `decoder` while this camera decodes on its assigned worker. Falls back to `decoder` when omitted."""
 
 
 class SnapshotSettings(TypedDict):

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/internal/__init__.py

@@ -1,14 +1,3 @@
-"""Internal SDK symbols.
-
-This subpackage exposes symbols used by the camera.ui server runtime and
-SDK internals but NOT part of the public plugin API. Plugin authors should
-not import from ``camera_ui_sdk.internal``; the contents may change without
-deprecation.
-
-Symbols are re-exported lazily via ``__getattr__`` to avoid circular imports
-during SDK bootstrap. Consumers can still ``from camera_ui_sdk.internal import X``.
-"""
-
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
@@ -22,16 +11,14 @@ if TYPE_CHECKING:
     from .sensor_rpc import (
         CapabilityUpdateFn,
         PropertyChangedEvent,
-        PropertyChangeListener,
         PropertyUpdateFn,
         SensorJSON,
     )
-    from .sensor_triggers import SENSOR_TRIGGER_TYPES
     from .shared_utils import is_equal
     from .streaming_internal import IceServer
 
 __all__ = [
-    # AsyncEventEmitter
+    # Events
     "AsyncEventEmitter",
     # Manager
     "ConnectionStatus",
@@ -39,13 +26,10 @@ __all__ = [
     # Sensor wire-format / RPC
     "SensorJSON",
     "PropertyChangedEvent",
-    "PropertyChangeListener",
     "PropertyUpdateFn",
     "CapabilityUpdateFn",
     # Camera wire-format
     "DetectionEventMessage",
-    # Sensor triggers
-    "SENSOR_TRIGGER_TYPES",
     # Streaming
     "IceServer",
     # Camera enums
@@ -58,18 +42,16 @@ __all__ = [
     "is_equal",
 ]
 
-# Map of public name -> (submodule, attribute_name) for lazy loading.
+# public name → (submodule, attribute), resolved lazily to avoid circular imports during SDK bootstrap
 _LAZY: dict[str, tuple[str, str]] = {
     "AsyncEventEmitter": (".event_emitter", "AsyncEventEmitter"),
     "ConnectionStatus": (".manager_rpc", "ConnectionStatus"),
     "DiscoveredCameraWithState": (".manager_rpc", "DiscoveredCameraWithState"),
     "SensorJSON": (".sensor_rpc", "SensorJSON"),
     "PropertyChangedEvent": (".sensor_rpc", "PropertyChangedEvent"),
-    "PropertyChangeListener": (".sensor_rpc", "PropertyChangeListener"),
     "PropertyUpdateFn": (".sensor_rpc", "PropertyUpdateFn"),
     "CapabilityUpdateFn": (".sensor_rpc", "CapabilityUpdateFn"),
     "DetectionEventMessage": (".camera_wire", "DetectionEventMessage"),
-    "SENSOR_TRIGGER_TYPES": (".sensor_triggers", "SENSOR_TRIGGER_TYPES"),
     "IceServer": (".streaming_internal", "IceServer"),
     "FrameType": (".camera_enums", "FrameType"),
     "CameraFrameWorkerDecoder": (".camera_enums", "CameraFrameWorkerDecoder"),

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/internal/camera_config_internal.py

@@ -20,7 +20,7 @@ class CameraInputSettings(TypedDict):
     hotMode: bool
     """Keep connection always active."""
     preload: bool
-    """Buffer the last keyframe group so new viewers get a picture faster."""
+    """Keep a keyframe cache for this source, so the view opens faster. Use ``hotMode`` to keep the stream connected."""
     muted: NotRequired[bool]
     """Strip the audio track from this source (defaults to False)."""
     urls: list[str]

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/internal/camera_enums.py

@@ -2,8 +2,8 @@ from __future__ import annotations
 
 from typing import Literal
 
-CameraFrameWorkerDecoder = Literal["wasm", "rust"]
-"""Frame worker decoder implementation."""
-
 FrameType = Literal["stream", "motion"]
 """Frame type identifier for frame workers."""
+
+CameraFrameWorkerDecoder = Literal["wasm", "rust"]
+"""Frame worker decoder implementation."""

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/internal/event_emitter.py

@@ -1,14 +1,3 @@
-"""Generic event-listener registry for camera.ui.
-
-Provides :class:`AsyncEventEmitter`, an event-name keyed listener
-registry that supports both sync and async handlers. Handlers are
-registered via :meth:`AsyncEventEmitter.on` /
-:meth:`AsyncEventEmitter.once`, removed via
-:meth:`AsyncEventEmitter.remove_listener` /
-:meth:`AsyncEventEmitter.remove_all_listeners`, and invoked through
-:meth:`AsyncEventEmitter.emit`.
-"""
-
 from __future__ import annotations
 
 import asyncio
@@ -18,18 +7,12 @@ from typing import Any
 
 
 class AsyncEventEmitter:
-    """Generic event-listener registry that accepts sync and async handlers.
+    """Event-listener registry that accepts sync and async handlers.
 
-    Listeners are keyed by event name and invoked in registration order
-    by :meth:`emit`. Async handlers are scheduled via ``ensure_future``
-    (fire-and-forget) and tracked so they can be cancelled with
-    :meth:`cancel`.
+    Listeners are keyed by event name and invoked in registration order. Async
+    handlers are scheduled fire-and-forget and tracked so :meth:`cancel` can stop them.
     """
 
-    @staticmethod
-    def _normalize_event(event: Any) -> str:
-        return event.value if hasattr(event, "value") else str(event)
-
     def __init__(self) -> None:
         self._events: dict[str, OrderedDict[Callable[..., Any], Callable[..., Any]]] = {}
         self._waiting: set[asyncio.Future[Any]] = set()
@@ -45,7 +28,7 @@ class AsyncEventEmitter:
         return f
 
     def once(self, event: str, f: Callable[..., Any]) -> Callable[..., Any]:
-        """Register a one-shot listener that is invoked the next time *event* is emitted and then removed automatically."""
+        """Register a one-shot listener that runs on the next emission of *event*, then removes itself."""
         event = self._normalize_event(event)
 
         def wrapper(*args: Any, **kwargs: Any) -> Any:
@@ -89,11 +72,10 @@ class AsyncEventEmitter:
     ) -> bool:
         """Invoke every listener registered for *event* and wait for async handlers to settle.
 
-        Handler exceptions are passed to *on_error* instead of propagating,
-        so one failing listener never blocks the others. Returns ``True``
-        when every handler settled within *timeout* seconds, ``False`` if
-        some were still pending when the timeout elapsed (they keep running
-        and remain cancellable via :meth:`cancel`).
+        Handler exceptions go to *on_error* instead of propagating, so one failing
+        listener never blocks the others. Returns ``False`` if handlers were still
+        pending after *timeout* seconds, they keep running and stay cancellable
+        via :meth:`cancel`.
         """
         event = self._normalize_event(event)
         listeners = self._events.get(event)
@@ -145,3 +127,8 @@ class AsyncEventEmitter:
         for future in self._waiting:
             future.cancel()
         self._waiting.clear()
+
+    @staticmethod
+    def _normalize_event(event: Any) -> str:
+        """Accept both plain event names and enum members."""
+        return event.value if hasattr(event, "value") else str(event)

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/internal/manager_rpc.py

@@ -9,12 +9,9 @@ ConnectionStatus = Literal["idle", "connecting", "connected", "error"]
 
 
 class DiscoveredCameraWithState(DiscoveredCamera):
-    """
-    Discovered camera with provider and connection state.
+    """Discovered camera plus the provider that found it and its live connection state.
 
-    Extended version of ``DiscoveredCamera`` used by the UI to render the
-    adoption list — adds the provider plugin name and a live connection
-    status so users see whether the camera is currently reachable.
+    Used by the UI to render the adoption list.
     """
 
     provider: str

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/internal/sensor_rpc.py

@@ -56,34 +56,49 @@ if TYPE_CHECKING:
 class PropertyChangedEvent(TypedDict):
     """Emitted when a sensor property value changes."""
 
-    cameraId: str
     sensorId: str
+    """Sensor that changed."""
     sensorType: SensorType
+    """Type of the sensor that changed."""
     property: str
+    """Property key that changed."""
     value: object
+    """New value."""
     previousValue: NotRequired[object]
+    """Value before the change, absent on the first write."""
     timestamp: int
+    """Change time in epoch milliseconds."""
 
 
-# @internal Callback used to propagate property updates to the backend via RPC.
-# Receives a partial-state delta (only properties that actually changed). One callback
-# invocation per `_writeState` call — atomic from the receiver's perspective.
 PropertyUpdateFn = Callable[[dict[str, Any]], None]
-PropertyChangeListener = Callable[[PropertyChangedEvent], None]
+"""Receives a partial-state delta, one call per ``_write_state``."""
+
 CapabilityUpdateFn = Callable[[list[str]], None]
+"""Receives the full capability list whenever it changes."""
 
 
 class SensorJSON(TypedDict):
     """JSON-serializable representation of a sensor for RPC transport."""
 
     id: str
+    """Sensor ID."""
     type: SensorType
+    """Sensor type."""
     name: str
+    """Internal name."""
     displayName: str
+    """Name shown in the UI."""
     category: SensorCategory
-    cameraId: str
+    """Category the sensor belongs to."""
+    nativeId: NotRequired[str]
+    """Device ID assigned by the plugin."""
     pluginId: NotRequired[str]
+    """Plugin that owns the sensor."""
     properties: dict[str, Any]
+    """Current property values."""
     capabilities: NotRequired[list[str]]
+    """Capability keys the sensor reports."""
     requiresFrames: NotRequired[bool]
+    """Sensor needs a frame feed to work."""
     modelSpec: NotRequired[ModelSpec]
+    """Model the sensor runs, for ML-backed sensors."""

package/dist/server/src/_camera_ui_tools/camera_ui_sdk/internal/shared_utils.py

@@ -4,39 +4,30 @@ from typing import Any
 
 
 def is_equal(first: Any, second: Any, ignore_order: bool = False) -> bool:
-    """
-    Deep equality check for arbitrary values.
-
-    Recursively compares primitives, lists, and dicts. Dict comparison
-    ignores key declaration order (only key/value pairs matter). Set
-    ``ignore_order`` to ``True`` to compare lists as multisets, i.e.
-    ignoring element order.
-
-    Typically used for property-change detection on sensors: a property
-    update is only emitted when the new value is not deeply equal to the
-    previous value, which avoids redundant events for unchanged data.
+    """Deep equality for primitives, lists, and dicts. Dict key order never matters.
 
     Args:
         first: First value to compare.
         second: Second value to compare.
-        ignore_order: If ``True``, lists are compared ignoring element order.
+        ignore_order: Compare lists as multisets instead of position by position.
 
     Returns:
         ``True`` if the values are deeply equal.
+
+    Example:
+        ```python
+        is_equal({"a": 1, "b": 2}, {"b": 2, "a": 1})  # True
+        ```
     """
-    # Same reference or both primitive and equal
     if first is second:
         return True
 
-    # Handle None
     if first is None or second is None:
         return first is second
 
-    # Different types
     if type(first) is not type(second):
         return False
 
-    # List comparison
     if isinstance(first, list):
         if len(first) != len(second):  # pyright: ignore[reportUnknownArgumentType]
             return False
@@ -58,7 +49,6 @@ def is_equal(first: Any, second: Any, ignore_order: bool = False) -> bool:
                 for i, item in enumerate(first)  # pyright: ignore[reportUnknownArgumentType,reportUnknownVariableType]
             )
 
-    # Dict comparison
     if isinstance(first, dict):
         if len(first) != len(second):  # pyright: ignore[reportUnknownArgumentType]
             return False
@@ -69,5 +59,4 @@ def is_equal(first: Any, second: Any, ignore_order: bool = False) -> bool:
                 return False
         return True
 
-    # Primitive comparison (fallback)
     return bool(first == second)