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

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

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class CameraFrameWorkerSettings(TypedDict):
+    """Frame worker (decoder) settings."""
+
+    fps: int
+    """Target frames per second for detection."""
+
+
+class SnapshotSettings(TypedDict):
+    """Snapshot settings for a camera."""
+
+    autoRefresh: bool
+    """Enable automatic snapshot refresh."""
+    ttl: int
+    """Cache TTL in seconds (how long a snapshot is valid)."""
+    interval: int
+    """Auto-refresh interval in seconds (min: 10, max: 60)."""

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

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from typing import Literal, NotRequired, TypedDict
+
+from .enums import (
+    AudioCodec,
+    AudioFFmpegCodec,
+    ProbeAudioCodec,
+    RTSPAudioCodec,
+    StreamDirection,
+    VideoCodec,
+    VideoFFmpegCodec,
+)
+
+
+class Go2RtcWSSource(TypedDict):
+    """WebSocket streaming URLs from go2rtc."""
+
+    webrtc: str
+    """WebRTC signaling endpoint."""
+    mse: str
+    """MSE streaming endpoint."""
+
+
+class Go2RtcRTSPSource(TypedDict):
+    """RTSP streaming URLs from go2rtc."""
+
+    base: str
+    """Base RTSP URL."""
+    default: str
+    """Default stream (video + audio)."""
+    muted: str
+    """Video only (muted)."""
+    audioOnly: str
+    """Audio only (no video)."""
+    aac: str
+    """Stream with AAC audio URL."""
+    opus: str
+    """Stream with Opus audio URL."""
+    pcma: str
+    """Stream with PCMA audio URL."""
+    onvif: str
+    """ONVIF URL."""
+    prebuffered: str
+    """Prebuffered stream URL."""
+    noGop: str
+    """Stream URL with GOP cache disabled."""
+
+
+class Go2RtcSnapshotSource(TypedDict):
+    """Snapshot/image URLs from go2rtc."""
+
+    mp4: str
+    """MP4 single-frame video URL."""
+    jpeg: str
+    """JPEG snapshot URL."""
+    mjpeg: str
+    """MJPEG stream URL."""
+
+
+class StreamUrls(TypedDict):
+    """Collection of all streaming URLs for a camera source."""
+
+    ws: Go2RtcWSSource
+    """WebSocket URLs."""
+    rtsp: Go2RtcRTSPSource
+    """RTSP URLs."""
+    snapshot: Go2RtcSnapshotSource
+    """Snapshot URLs."""
+
+
+class ProbeConfig(TypedDict, total=False):
+    """Configuration for stream probing."""
+
+    video: bool
+    """Include video track info."""
+    audio: bool | Literal["all"] | list[ProbeAudioCodec]
+    """Include audio track info (true, 'all', or specific codecs)."""
+    microphone: bool
+    """Include microphone/backchannel info."""
+
+
+class FMTPInfo(TypedDict):
+    """Format parameters (fmtp) from SDP."""
+
+    payload: int
+    """RTP payload type number."""
+    config: str
+    """Codec-specific configuration string."""
+
+
+class AudioCodecProperties(TypedDict):
+    """Audio codec properties from stream probe."""
+
+    sampleRate: int
+    """Audio sample rate in Hz."""
+    channels: int
+    """Number of audio channels."""
+    payloadType: int
+    """RTP payload type."""
+    fmtpInfo: NotRequired[FMTPInfo]
+    """Optional format parameters."""
+
+
+class VideoCodecProperties(TypedDict):
+    """Video codec properties from stream probe."""
+
+    clockRate: int
+    """Video clock rate."""
+    payloadType: int
+    """RTP payload type."""
+    fmtpInfo: NotRequired[FMTPInfo]
+    """Optional format parameters."""
+
+
+class AudioStreamInfo(TypedDict):
+    """Audio stream information from probe."""
+
+    codec: AudioCodec
+    """Audio codec."""
+    ffmpegCodec: AudioFFmpegCodec
+    """FFmpeg codec name."""
+    properties: AudioCodecProperties
+    """Codec properties."""
+    direction: StreamDirection
+    """Stream direction."""
+
+
+class VideoStreamInfo(TypedDict):
+    """Video stream information from probe."""
+
+    codec: VideoCodec
+    """Video codec."""
+    ffmpegCodec: VideoFFmpegCodec
+    """FFmpeg codec name."""
+    properties: VideoCodecProperties
+    """Codec properties."""
+    direction: StreamDirection
+    """Stream direction."""
+
+
+class ProbeStream(TypedDict):
+    """Stream probe result containing SDP and track information."""
+
+    sdp: str
+    """Raw SDP string."""
+    audio: list[AudioStreamInfo]
+    """Available audio tracks."""
+    video: list[VideoStreamInfo]
+    """Available video tracks."""
+
+
+class RTSPUrlOptions(TypedDict, total=False):
+    """Options for generating RTSP URLs."""
+
+    video: bool
+    """Include video track."""
+    audio: bool | RTSPAudioCodec | list[RTSPAudioCodec]
+    """Include audio track(s)."""
+    gop: bool
+    """Request keyframe at start (GOP)."""
+    prebuffer: bool
+    """Use prebuffered stream."""
+    audioSingleTrack: bool
+    """Combine audio tracks into single track."""
+    backchannel: bool
+    """Enable backchannel (two-way audio)."""
+    timeout: int
+    """Connection timeout in s."""
+
+
+class SnapshotUrlOptions(TypedDict, total=False):
+    """Options for generating snapshot URLs."""
+
+    width: int
+    """Output width in pixels."""
+    height: int
+    """Output height in pixels."""
+    rotate: Literal[90, 180, 270, -90]
+    """Rotation in degrees."""
+    cache: str
+    """Cache key/strategy."""
+    hw: Literal["vaapi", "v4l2m2m", "cuda", "dxva2", "videotoolbox", "rkmpp"]
+    """Hardware acceleration backend."""
+    gop: bool
+    """Request keyframe at start (GOP)."""
+    prebuffer: bool
+    """Use prebuffered stream."""

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

@@ -0,0 +1,92 @@
+"""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
+
+if TYPE_CHECKING:
+    from .camera_config_internal import CameraConfigPartial, CameraInputSettings
+    from .camera_enums import CameraFrameWorkerDecoder, FrameType
+    from .camera_wire import DetectionEventMessage
+    from .event_emitter import AsyncEventEmitter
+    from .manager_rpc import ConnectionStatus, DiscoveredCameraWithState
+    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
+    "AsyncEventEmitter",
+    # Manager
+    "ConnectionStatus",
+    "DiscoveredCameraWithState",
+    # Sensor wire-format / RPC
+    "SensorJSON",
+    "PropertyChangedEvent",
+    "PropertyChangeListener",
+    "PropertyUpdateFn",
+    "CapabilityUpdateFn",
+    # Camera wire-format
+    "DetectionEventMessage",
+    # Sensor triggers
+    "SENSOR_TRIGGER_TYPES",
+    # Streaming
+    "IceServer",
+    # Camera enums
+    "FrameType",
+    "CameraFrameWorkerDecoder",
+    # Camera config
+    "CameraInputSettings",
+    "CameraConfigPartial",
+    # Utils
+    "is_equal",
+]
+
+# Map of public name -> (submodule, attribute_name) for lazy loading.
+_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"),
+    "CameraInputSettings": (".camera_config_internal", "CameraInputSettings"),
+    "CameraConfigPartial": (".camera_config_internal", "CameraConfigPartial"),
+    "is_equal": (".shared_utils", "is_equal"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    target = _LAZY.get(name)
+    if target is None:
+        raise AttributeError(f"module 'camera_ui_sdk.internal' has no attribute {name!r}")
+    submodule_path, attr_name = target
+    from importlib import import_module
+
+    module = import_module(submodule_path, __name__)
+    value = getattr(module, attr_name)
+    globals()[name] = value
+    return value

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

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import NotRequired, TypedDict
+
+from ..camera.config import CameraConfigInputSettings, CameraInformation
+from ..camera.enums import CameraRole
+
+
+class CameraInputSettings(TypedDict):
+    """Camera input settings (user configuration)."""
+
+    _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: list[str]
+    """User-provided stream URLs."""
+    childSourceId: NotRequired[str]
+    """Child source ID (for snapshot fallback)."""
+
+
+class CameraConfigPartial(TypedDict, total=False):
+    """Camera configuration subset for partial updates."""
+
+    name: str
+    """Camera display name."""
+    nativeId: str
+    """Native device ID from plugin."""
+    isCloud: bool
+    """Whether camera streams from cloud."""
+    disabled: bool
+    """Disable this camera."""
+    info: CameraInformation
+    """Camera hardware information."""
+    sources: list[CameraConfigInputSettings]
+    """Video input sources."""

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

@@ -0,0 +1,9 @@
+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."""

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

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+from ..camera.enums import DetectionEventType
+from ..camera.events import DetectionEvent
+
+
+class DetectionEventMessage(TypedDict):
+    """Detection event message published via NATS."""
+
+    type: DetectionEventType
+    """Event lifecycle type."""
+    data: DetectionEvent
+    """Full event data."""

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

@@ -0,0 +1,102 @@
+"""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
+from collections import OrderedDict
+from collections.abc import Callable
+from typing import Any
+
+
+class AsyncEventEmitter:
+    """Generic 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`.
+    """
+
+    @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()
+
+    def on(self, event: str, f: Callable[..., Any]) -> Callable[..., Any]:
+        """Register a listener (sync or async) that is invoked for every emission of *event*."""
+        event = self._normalize_event(event)
+        listeners = self._events.get(event)
+        if listeners is None:
+            listeners = OrderedDict[Callable[..., Any], Callable[..., Any]]()
+            self._events[event] = listeners
+        listeners[f] = f
+        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."""
+        event = self._normalize_event(event)
+
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            self.remove_listener(event, f)
+            return f(*args, **kwargs)
+
+        listeners = self._events.get(event)
+        if listeners is None:
+            listeners = OrderedDict[Callable[..., Any], Callable[..., Any]]()
+            self._events[event] = listeners
+        listeners[f] = wrapper
+        return f
+
+    def emit(self, event: str, *args: Any, **kwargs: Any) -> bool:
+        """Invoke every listener registered for *event* with the given arguments.
+
+        Returns ``True`` if *event* had listeners, ``False`` otherwise.
+        Async handlers are scheduled as fire-and-forget tasks.
+        """
+        event = self._normalize_event(event)
+        listeners = self._events.get(event)
+        if not listeners:
+            return False
+
+        for handler in list(listeners.values()):
+            result = handler(*args, **kwargs)
+            if asyncio.iscoroutine(result):
+                future = asyncio.ensure_future(result)
+                self._waiting.add(future)
+                future.add_done_callback(self._waiting.discard)
+
+        return True
+
+    def remove_listener(self, event: str, f: Callable[..., Any]) -> None:
+        """Remove a previously registered listener *f* from *event*. No-op if it is not registered."""
+        event = self._normalize_event(event)
+        listeners = self._events.get(event)
+        if listeners is not None:
+            listeners.pop(f, None)
+            if not listeners:
+                del self._events[event]
+
+    def remove_all_listeners(self, event: str | None = None) -> None:
+        """Remove every listener for *event*, or every listener for every event when *event* is ``None``."""
+        if event is not None:
+            self._events.pop(self._normalize_event(event), None)
+        else:
+            self._events.clear()
+
+    def cancel(self) -> None:
+        """Cancel all pending async tasks."""
+        for future in self._waiting:
+            future.cancel()
+        self._waiting.clear()

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

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from typing import Literal, NotRequired
+
+from ..manager import DiscoveredCamera
+
+ConnectionStatus = Literal["idle", "connecting", "connected", "error"]
+"""Connection status for discovered cameras."""
+
+
+class DiscoveredCameraWithState(DiscoveredCamera):
+    """
+    Discovered camera with provider and 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.
+    """
+
+    provider: str
+    """Name of the provider plugin that discovered this camera."""
+
+    connectionStatus: ConnectionStatus
+    """Current connection status reported by the provider."""
+
+    errorMessage: NotRequired[str]
+    """Last error message when ``connectionStatus`` is ``error``."""

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

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, NotRequired, TypeAlias, TypedDict
+
+if TYPE_CHECKING:
+    from ..sensor.audio import AudioProperty
+    from ..sensor.base import SensorCategory, SensorType
+    from ..sensor.battery import BatteryCapability, BatteryProperty
+    from ..sensor.classifier import ClassifierProperty
+    from ..sensor.contact import ContactProperty
+    from ..sensor.doorbell import DoorbellProperty
+    from ..sensor.face import FaceProperty
+    from ..sensor.garage import GarageProperty
+    from ..sensor.humidity import HumidityProperty
+    from ..sensor.leak import LeakProperty
+    from ..sensor.license_plate import LicensePlateProperty
+    from ..sensor.light import LightCapability, LightProperty
+    from ..sensor.motion import MotionProperty
+    from ..sensor.object import ObjectProperty
+    from ..sensor.occupancy import OccupancyProperty
+    from ..sensor.ptz import PTZCapability, PTZProperty
+    from ..sensor.security_system import SecuritySystemProperty
+    from ..sensor.siren import SirenCapability, SirenProperty
+    from ..sensor.smoke import SmokeProperty
+    from ..sensor.spec import ModelSpec
+    from ..sensor.switch import SwitchProperty
+    from ..sensor.temperature import TemperatureProperty
+
+    SensorPropertyType: TypeAlias = (
+        AudioProperty
+        | BatteryProperty
+        | ClassifierProperty
+        | ContactProperty
+        | DoorbellProperty
+        | FaceProperty
+        | GarageProperty
+        | HumidityProperty
+        | LeakProperty
+        | LicensePlateProperty
+        | LightProperty
+        | MotionProperty
+        | ObjectProperty
+        | OccupancyProperty
+        | PTZProperty
+        | SecuritySystemProperty
+        | SirenProperty
+        | SmokeProperty
+        | SwitchProperty
+        | TemperatureProperty
+    )
+
+    SensorCapability: TypeAlias = PTZCapability | LightCapability | SirenCapability | BatteryCapability
+
+
+class PropertyChangedEvent(TypedDict):
+    """Emitted when a sensor property value changes."""
+
+    cameraId: str
+    sensorId: str
+    sensorType: SensorType
+    property: str
+    value: object
+    previousValue: NotRequired[object]
+    timestamp: int
+
+
+# @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]
+CapabilityUpdateFn = Callable[[list[str]], None]
+
+
+class SensorJSON(TypedDict):
+    """JSON-serializable representation of a sensor for RPC transport."""
+
+    id: str
+    type: SensorType
+    name: str
+    displayName: str
+    category: SensorCategory
+    cameraId: str
+    pluginId: NotRequired[str]
+    properties: dict[str, Any]
+    capabilities: NotRequired[list[str]]
+    requiresFrames: NotRequired[bool]
+    modelSpec: NotRequired[ModelSpec]

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

@@ -0,0 +1,4 @@
+from __future__ import annotations
+
+SENSOR_TRIGGER_TYPES: tuple[str, ...] = ("contact", "doorbell", "switch", "light", "siren", "security_system")
+"""Sensor trigger types — the subset of trigger types that originate from configurable sensors (excludes motion/audio)."""

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

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+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.
+
+    Args:
+        first: First value to compare.
+        second: Second value to compare.
+        ignore_order: If ``True``, lists are compared ignoring element order.
+
+    Returns:
+        ``True`` if the values are deeply equal.
+    """
+    # 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
+        if ignore_order:
+            second_copy = list(second)
+            for item in first:  # pyright: ignore[reportUnknownVariableType]
+                found = False
+                for i, second_item in enumerate(second_copy):
+                    if is_equal(item, second_item, ignore_order):
+                        second_copy.pop(i)
+                        found = True
+                        break
+                if not found:
+                    return False
+            return True
+        else:
+            return all(
+                is_equal(item, second[i], ignore_order)
+                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
+        for key in first:  # pyright: ignore[reportUnknownVariableType]
+            if key not in second:
+                return False
+            if not is_equal(first[key], second[key], ignore_order):
+                return False
+        return True
+
+    # Primitive comparison (fallback)
+    return bool(first == second)