@camera.ui/sdk 0.0.20 → 0.0.22

package/dist/index.d.ts

@@ -6,7 +6,7 @@
 type CameraType = 'camera' | 'doorbell';
 /**
  * Detection zone intersection type.
- * - `intersect`: Trigger when object touches the zone boundary
+ * - `intersect`: Trigger when object overlaps the zone at all
  * - `contain`: Trigger only when object is fully inside the zone
  */
 type ZoneType = 'intersect' | 'contain';
@@ -108,7 +108,7 @@ interface CameraInputSettings {
     useForSnapshot: boolean;
     /** Keep connection always active */
     hotMode: boolean;
-    /** Preload stream on startup */
+    /** Keep a keyframe cache for this source, so the view opens faster. Use `hotMode` to keep the stream connected. */
     preload: boolean;
     /** Strip the audio track from this source (defaults to false) */
     muted?: boolean;
@@ -469,7 +469,7 @@ interface JsonBaseSchemaWithoutCallbacks<T extends string | string[] | number |
 interface JsonBaseSchema<T extends string | string[] | number | number[] | boolean | boolean[] = any> extends JsonBaseSchemaWithoutCallbacks<T> {
     /** Whether to persist this field to storage */
     store?: boolean;
-    /** Callback when value changes */
+    /** Callback after a write. `setValue` fires it whether or not the value changed; `setConfig` fires it only for keys that changed. */
     onSet?: (newValue: any, oldValue: any) => Promise<void>;
     /** Callback to get computed value */
     onGet?: () => Promise<any>;
@@ -707,8 +707,9 @@ interface DeviceStorage<T extends Record<string, any> = Record<string, any>> {
     /**
      * Get a configuration value.
      *
-     * Resolves in order: the schema's `onGet` callback (if any), then the stored
-     * value, then the schema default, then the provided default.
+     * If the schema declares an `onGet` callback, its result is returned as-is,
+     * with no fallback. Otherwise resolves in order: the stored value, then the
+     * schema default, then the provided default.
      *
      * @param key - Configuration key
      *
@@ -924,7 +925,7 @@ interface ModelSpec {
     input: VideoInputSpec;
     /** Labels emitted by an upstream object detector that activate this detector (e.g. `['person']` for face detection). */
     triggerLabels: DetectionLabel[];
-    /** Embedding model identifier for face recognition. */
+    /** Embedding model identifier. Required for face recognition and for CLIP: embeddings are stored and matched under this id. */
     embeddingModel?: string;
 }
 /**
@@ -1461,8 +1462,9 @@ declare abstract class FaceDetectorSensor<TStorage extends object = Record<strin
     /** Declares the expected input dimensions and trigger labels. The backend scales frames to match. */
     abstract get modelSpec(): ModelSpec;
     /**
-     * Detect faces in batch. Each frame is a pre-cropped, pre-scaled person
-     * region produced by the upstream object detector. Must return exactly one
+     * Detect faces in batch. Each frame is pre-scaled to `modelSpec.input`:
+     * normally a person region cropped by the upstream object detector, but the
+     * whole scene when no decoded frame is available. Must return exactly one
      * FaceResult per input frame, in the same order.
      */
     abstract detectFaces(frames: VideoFrameData[]): Promise<FaceResult[]>;
@@ -2114,7 +2116,7 @@ declare class MotionSensor<TStorage extends object = Record<string, any>> extend
 }
 /** Return type for {@link MotionDetectorSensor.detectMotion}. */
 interface MotionResult {
-    /** Whether motion is detected in this frame. */
+    /** Whether motion is detected in this frame. Ignored by the backend, which re-derives it from the detections. */
     detected: boolean;
     /** Detections emitted for this frame. */
     detections: Detection[];
@@ -2123,7 +2125,9 @@ interface MotionResult {
  * Motion detector that receives video frames from the backend pipeline.
  * Extend this class and implement {@link detectMotion} to analyze frames
  * for motion. The backend calls `detectMotion()` at the configured frame
- * interval and applies the returned result to the sensor.
+ * interval, zone-filters the returned detections and applies them.
+ * `detected` is re-derived from the surviving detections, so a result with
+ * no detections reports no motion.
  */
 declare abstract class MotionDetectorSensor<TStorage extends object = Record<string, any>> extends MotionSensor<TStorage> {
     _requiresFrames: boolean;
@@ -2339,7 +2343,13 @@ declare enum PTZCapability {
     /** Camera supports named position presets */
     Presets = "presets",
     /** Camera supports a home position */
-    Home = "home"
+    Home = "home",
+    /** Camera executes relative displacement moves */
+    RelativeMove = "relativeMove",
+    /** Camera accepts absolute position writes via `setPosition()` */
+    AbsolutePosition = "absolutePosition",
+    /** Camera accepts continuous-move commands via `setVelocity()` */
+    VelocityControl = "velocityControl"
 }
 /**
  * Properties for PTZ controls
@@ -2356,7 +2366,9 @@ declare enum PTZProperty {
     /** Current movement velocity (continuous move) */
     Velocity = "velocity",
     /** Target preset to move to */
-    TargetPreset = "targetPreset"
+    TargetPreset = "targetPreset",
+    /** Relative displacement move command (write-only) */
+    RelativeMove = "relativeMove"
 }
 /** Absolute PTZ position */
 interface PTZPosition {
@@ -2381,6 +2393,20 @@ interface PTZDirection {
     tiltSpeed: number;
     zoomSpeed: number;
 }
+/**
+ * Relative displacement for a single PTZ move.
+ *
+ * Deltas are normalized to the camera's field of view: `panDelta: 1` moves the
+ * view by one full frame width, `tiltDelta: 1` by one full frame height.
+ * Conventions match {@link PTZDirection}: positive `panDelta` = right,
+ * positive `tiltDelta` = up, positive `zoomDelta` = zoom in. Plugins map the
+ * deltas to hardware-specific translation spaces (e.g. ONVIF RelativeMove).
+ */
+interface PTZRelativeMove {
+    panDelta: number;
+    tiltDelta: number;
+    zoomDelta: number;
+}
 /**
  * Property value map for PTZ controls.
  *
@@ -2392,6 +2418,7 @@ interface PTZControlProperties {
     [PTZProperty.Presets]: string[];
     [PTZProperty.Velocity]?: PTZDirection;
     [PTZProperty.TargetPreset]?: string;
+    [PTZProperty.RelativeMove]?: PTZRelativeMove;
 }
 /** Read-only proxy interface for a PTZ control */
 interface PTZControlLike extends SensorLike {
@@ -2403,6 +2430,7 @@ interface PTZControlLike extends SensorLike {
     getValue(property: PTZProperty.Presets): string[] | undefined;
     getValue(property: PTZProperty.Velocity): PTZDirection | undefined;
     getValue(property: PTZProperty.TargetPreset): string | undefined;
+    getValue(property: PTZProperty.RelativeMove): PTZRelativeMove | undefined;
     getValue(property: string): unknown;
 }
 /**
@@ -2440,20 +2468,37 @@ declare class PTZControl<TStorage extends object = Record<string, any>> extends
      * Continuous-move command. Override to drive hardware and call
      * `await super.setVelocity(value)` after success to sync the SDK state.
      *
-     * @param value - Per-axis speeds in `[-1, 1]`, or `undefined` to stop.
+     * @param value - Per-axis speeds in `[-1, 1]`. Stop is zero on every axis.
+     * `undefined` is ignored and the published `velocity` keeps its last value.
      *
      * @example
      * ```ts
      * await ptz.setVelocity({ panSpeed: 0.5, tiltSpeed: 0, zoomSpeed: 0 });
-     * await ptz.setVelocity(undefined); // stop
+     * await ptz.setVelocity({ panSpeed: 0, tiltSpeed: 0, zoomSpeed: 0 }); // stop
      * ```
      */
     setVelocity(value: PTZDirection | undefined): Promise<void>;
+    /**
+     * Relative displacement move. Override to drive hardware (e.g. ONVIF
+     * RelativeMove in a translation space) and call
+     * `await super.setRelativeMove(value)` after success to sync the SDK state.
+     * Advertise {@link PTZCapability.RelativeMove} when the camera supports it.
+     *
+     * @param value - Per-axis displacement, normalized to the field of view.
+     *
+     * @example
+     * ```ts
+     * // move the view a third of a frame to the right, a tenth down
+     * await ptz.setRelativeMove({ panDelta: 0.33, tiltDelta: -0.1, zoomDelta: 0 });
+     * ```
+     */
+    setRelativeMove(value: PTZRelativeMove): Promise<void>;
     /**
      * Preset-move command. Override to drive hardware and call
      * `await super.setTargetPreset(value)` after success to sync the SDK state.
      *
-     * @param value - Preset name to move to, or `undefined` to clear.
+     * @param value - Preset name to move to. `undefined` is ignored and the
+     * published `targetPreset` keeps its last value.
      *
      * @example
      * ```ts
@@ -2496,7 +2541,7 @@ declare class PTZControl<TStorage extends object = Record<string, any>> extends
      * Cross-process consumer entry point. Dispatches writable properties
      * to semantic methods so plugin overrides (hardware actions) are honored.
      * `moving` and `presets` are observed/discovered state and not externally writable;
-     * only `Position`, `Velocity`, and `TargetPreset` may be set.
+     * only `Position`, `Velocity`, `TargetPreset`, and `RelativeMove` may be set.
      *
      * @param property - Property name to write.
      *
@@ -3094,7 +3139,7 @@ declare abstract class Sensor<TProperties extends object, TStorage extends objec
     /**
      * Get a read-only snapshot of all property values.
      *
-     * @returns Frozen view of every property currently held by the sensor.
+     * @returns Shallow copy of every property currently held by the sensor.
      *
      * @example
      * ```ts
@@ -3175,8 +3220,9 @@ declare abstract class Sensor<TProperties extends object, TStorage extends objec
      * override can safely access `this.cameraId`, `this.storage`, and publish
      * properties via the semantic helper methods.
      *
-     * Errors thrown here are caught and logged — they will NOT break assignment
-     * bookkeeping. If your work can fail, handle it inside the override.
+     * Errors thrown here are caught and swallowed, not logged. They will NOT
+     * break assignment bookkeeping, but nothing surfaces them either. If your
+     * work can fail, handle it inside the override.
      *
      * Paired 1:1 with `onDeassigned` — for every `onAssigned` call there is
      * exactly one matching `onDeassigned` later (on deassignment or cleanup).
@@ -3317,7 +3363,7 @@ interface DetectionLine {
 }
 /**
  * Detection zone configuration.
- * Defines areas for detection filtering or privacy masking.
+ * Defines areas that restrict or drop detections.
  */
 interface DetectionZone {
     /** Zone display name */
@@ -3330,7 +3376,7 @@ interface DetectionZone {
     filter: ZoneFilter;
     /** Labels to filter (empty = all labels) */
     labels: DetectionLabel[];
-    /** Whether this is a privacy mask (blur/block area) */
+    /** Whether this is an ignore zone: detections fully inside it are dropped. */
     isPrivacyMask: boolean;
     /** Zone display color (hex) */
     color: string;
@@ -3348,7 +3394,7 @@ interface MotionDetectionSettings {
  * Object detection settings.
  */
 interface ObjectDetectionSettings {
-    /** Minimum confidence threshold (0-1) */
+    /** Minimum confidence threshold (0.3 - 1.0) */
     confidence: number;
     /** Suppress events from objects that stay stationary across events (e.g. parked cars). Defaults to true. */
     suppressStatic?: boolean;
@@ -3383,11 +3429,11 @@ interface PtzAutotrackSettings {
      */
     trackingSpeed: number;
     /**
-     * Motion prediction: aim this many detection-frames ahead along the target's
-     * measured velocity so a moving target is followed without lag. 0 disables
-     * prediction. Range 0 - 6.
+     * Motion prediction: aim this many milliseconds ahead along the target's
+     * measured velocity, covering the time the camera needs to move and settle.
+     * 0 disables prediction. Range 0 - 4000.
      */
-    leadFrames: number;
+    leadMs: number;
     /**
      * Camera pan-rate calibration — assumed pan travel at full motor speed, in
      * normalized frame-widths per second. Lower it if the camera stops short of
@@ -3880,7 +3926,7 @@ interface CameraInput {
     useForSnapshot: boolean;
     /** Keep connection always active */
     hotMode: boolean;
-    /** Preload stream on startup */
+    /** Keep a keyframe cache for this source, so the view opens faster. Use `hotMode` to keep the stream connected. */
     preload: boolean;
     /** Strip the audio track from this source (defaults to false) */
     muted?: boolean;
@@ -4050,7 +4096,6 @@ interface Camera extends BaseCamera {
  * the host) and emits a log entry at the corresponding severity:
  *
  *   - log:       general informational message (default level).
- *   - info:      same as log; informational message.
  *   - warn:      potential problem that does not stop execution.
  *   - error:     a failure or unexpected condition.
  *   - success:   confirmation of a completed operation.
@@ -4122,7 +4167,7 @@ interface EventDetection {
     maxCount: number;
     /** Bounding box of the highest-confidence detection (normalized 0–1) */
     box?: BoundingBox;
-    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    /** Best-selected JPEG thumbnail crop. Only present on 'segment-start' and 'segment-end' messages, and omitted when it is the same image as the segment thumbnail. */
     thumbnail?: Uint8Array;
     /** Object tracker ID (links this detection across frames) */
     trackId?: number;
@@ -4139,7 +4184,7 @@ interface EventAttribute {
     label: string;
     /** Detection confidence (0-1) */
     confidence?: number;
-    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    /** Best-selected JPEG thumbnail crop. Present on 'segment-start' and 'segment-end' messages, and on 'segment-update' for unknown faces. */
     thumbnail?: Uint8Array;
     /** Face embedding vector for unknown face persistence. Only present for face attributes. */
     embedding?: number[];
@@ -4160,7 +4205,7 @@ interface EventSegment {
     firstSeen: number;
     /** Segment end time (Unix ms) */
     lastSeen: number;
-    /** Best-selected JPEG scene thumbnail for this segment. Only present on 'end' events. */
+    /** Best-selected JPEG scene thumbnail for this segment. Only present on 'segment-start' and 'segment-end' messages, plus once on a 'segment-update' if the start message had none. */
     thumbnail?: Uint8Array;
     /** Object detections in this segment */
     detections: EventDetection[];
@@ -4416,17 +4461,17 @@ interface CameraDevice {
      * @param sensorId - ID of sensor to remove
      */
     removeSensor(sensorId: string): Promise<void>;
-    /** Observable for sensor additions. Emits { sensorId, sensorType } when a sensor from another plugin is added. */
+    /** Observable for sensor additions. Emits for this plugin's own sensors and for other plugins' sensors whose type is listed in `contract.consumes`, also when such a sensor is activated for this camera. */
     readonly onSensorAdded: Observable<{
         sensorId: string;
         sensorType: SensorType;
     }>;
-    /** Observable for sensor removals. Emits { sensorId, sensorType } when a sensor from another plugin is removed. */
+    /** Observable for sensor removals. Emits for this plugin's own sensors and for other plugins' sensors on this camera, also when a sensor is deactivated for this camera. */
     readonly onSensorRemoved: Observable<{
         sensorId: string;
         sensorType: SensorType;
     }>;
-    /** Observable for detection events (start/update/end). Thumbnails in segments are only populated on 'end' events. */
+    /** Observable for detection events (start/update/end/segment-*). Segments are only present on 'segment-*' messages; thumbnails are populated on 'segment-start' and 'segment-end'. */
     readonly onDetectionEvent: Observable<{
         type: DetectionEventType;
         event: DetectionEvent;
@@ -4952,9 +4997,10 @@ interface Notification {
      */
     severity?: Severity;
     /**
-     * Collapse-key for dedup at both manager and notifier level (e.g.
-     * 'motion:cam-1' — multiple events with the same tag inside the throttle
-     * window collapse into one notification on the device).
+     * Collapse-key (e.g. 'motion:cam-1'). The host uses it to replace an older
+     * entry with the same tag in the in-app notification list. Delivery is not
+     * throttled: every publish is sent. Notifiers may map it to a platform
+     * collapse-id.
      */
     tag?: string;
     /** Optional inline JPEG attached to the notification. */
@@ -5285,9 +5331,8 @@ type PluginInterfaces = Partial<MotionDetectionInterface & ObjectDetectionInterf
 
 /**
  * Core manager event payload.
- * Emitted when a core system event occurs (e.g. cloud account changes,
- * remote-server availability, plugin lifecycle changes). Subscribe via
- * `coreManager.onEvent` to react to system-level state changes.
+ * The host currently publishes one event type, 'cloudAccountChanged'.
+ * Subscribe via `coreManager.onEvent` to react to it.
  */
 interface CoreManagerEvent {
     /** Event type identifier (e.g. 'cloudAccountChanged'). */
@@ -5299,8 +5344,8 @@ interface CoreManagerEvent {
  * Core manager interface for system-level operations.
  *
  * Provides access to cross-cutting services like the FFmpeg binary path,
- * server addresses, HMAC signing for cloud requests, inter-plugin lookup,
- * and a stream of core system events.
+ * server addresses, the cloud server id, inter-plugin lookup, and a stream
+ * of core system events.
  *
  * Accessed via `api.coreManager` in plugins.
  *
@@ -5347,7 +5392,9 @@ interface CoreManager {
      */
     getCloudServerId(): Promise<string>;
     /**
-     * Get all active plugins that implement a specific interface.
+     * Get all installed, enabled plugins that implement a specific interface.
+     * Plugins the admin disabled are excluded. A returned plugin may still be
+     * starting up or may have crashed, so a call into one can fail.
      *
      * @param interfaceName - Name of the plugin interface (e.g., 'ClipDetection')
      *
@@ -5796,4 +5843,4 @@ interface OAuthClientCredentialsCapable extends OAuthCapable {
 }
 
 export { API_EVENT, AudioDetectorSensor, AudioProperty, AudioSensor, BASE_AUDIO_LABELS, BasePlugin, BatteryCapability, BatteryInfo, BatteryProperty, BehaviorSubject, ChargingState, ClassifierDetectorSensor, ClassifierProperty, ClassifierSensor, ClipDetectorSensor, ContactProperty, ContactSensor, DETECTION_ATTRIBUTES, DETECTION_LABELS, Disposable, DoorbellProperty, DoorbellTrigger, EVENT_TRIGGER_TYPES, FaceDetectorSensor, FaceProperty, FaceSensor, GarageControl, GarageProperty, GarageState, HumidityInfo, HumidityProperty, LeakProperty, LeakSensor, LicensePlateDetectorSensor, LicensePlateProperty, LicensePlateSensor, LightCapability, LightControl, LightProperty, LockControl, LockProperty, LockState, MotionDetectorSensor, MotionProperty, MotionSensor, ObjectDetectorSensor, ObjectProperty, ObjectSensor, Observable, OccupancyProperty, OccupancySensor, PTZCapability, PTZControl, PTZProperty, PluginCapability, PluginInterface, PluginRole, RING_AUTO_RESET_MS, ReplaySubject, RtpPacket, SecuritySystem, SecuritySystemProperty, SecuritySystemState, Sensor, SensorCategory, SensorType, Severity, SirenCapability, SirenControl, SirenProperty, SmokeProperty, SmokeSensor, Subject, SwitchControl, SwitchProperty, TemperatureInfo, TemperatureProperty, canCreateCameras, canProvideSensorsToAnyCameras, distinctUntilChanged, filter, firstValueFrom, getContractValidationErrors, hasCapability, hasInterface, isHub, map, mergeMap, pairwise, share, validateContractConsistency };
-export type { AssignedPlugin, AudioCodec, AudioCodecProperties, AudioDetectionInterface, AudioDetectionPluginResponse, AudioDetectionSettings, AudioFFmpegCodec, AudioFrameData, AudioInputSpec, AudioLabel, AudioMetadata, AudioModelSpec, AudioResult, AudioSensorLike, AudioSensorProperties, AudioStreamInfo, BaseAudioLabel, BaseCamera, BaseCameraConfig, BatteryInfoLike, BatteryInfoProperties, BoundingBox, Camera, CameraAspectRatio, CameraConfig, CameraConfigInputSettings, CameraDetectionSettings, CameraDevice, CameraDeviceSource, CameraFrameWorkerSettings, CameraImplementation, CameraInformation, CameraInput, CameraPluginInfo, CameraRole, CameraSource, CameraType, CameraUiSettings, ClassifierDetection, ClassifierDetectionInterface, ClassifierDetectionPluginResponse, ClassifierResult, ClassifierSensorLike, ClassifierSensorProperties, ClipDetectionInterface, ClipDetectionPluginResponse, ClipEmbedding, ClipResult, ClipTextEmbeddingResult, ContactSensorLike, ContactSensorProperties, CoreManager, CoreManagerEvent, CreateDownloadOptions, CreateStreamDownloadOptions, Detection, DetectionAttribute, DetectionEvent, DetectionEventState, DetectionEventType, DetectionLabel, DetectionLine, DetectionZone, DeviceManager, DeviceStorage, DiscoveredCamera, DiscoveryProvider, DoorbellTriggerLike, DoorbellTriggerProperties, DownloadCleanup, DownloadManager, DownloadToken, EventAttribute, EventDescription, EventDetection, EventSegment, EventTrigger, EventTriggerType, FMTPInfo, FaceDetection, FaceDetectionInterface, FaceDetectionPluginResponse, FaceResult, FaceSensorLike, FaceSensorProperties, Fmp4Session, Fmp4SessionOptions, FormSubmitResponse, FormSubmitSchema, GarageControlLike, GarageControlProperties, Go2RtcRTSPSource, Go2RtcSnapshotSource, Go2RtcWSSource, HardwareAcceleration, HumidityInfoLike, HumidityInfoProperties, ImageMetadata, JsonArraySchema, JsonBaseSchema, JsonBaseSchemaWithoutCallbacks, JsonBooleanSchema, JsonEnumSchema, JsonFactorySchema, JsonNumberSchema, JsonSchema, JsonSchemaArray, JsonSchemaArrayWithoutCallbacks, JsonSchemaBoolean, JsonSchemaBooleanWithoutCallbacks, JsonSchemaButton, JsonSchemaEnum, JsonSchemaEnumWithoutCallbacks, JsonSchemaNumber, JsonSchemaNumberWithoutCallbacks, JsonSchemaString, JsonSchemaStringWithoutCallbacks, JsonSchemaSubmit, JsonSchemaType, JsonSchemaWithoutCallbacks, JsonSchemaWithoutKey, JsonStringSchema, LeakSensorLike, LeakSensorProperties, LicensePlateDetection, LicensePlateDetectionInterface, LicensePlateDetectionPluginResponse, LicensePlateResult, LicensePlateSensorLike, LicensePlateSensorProperties, LightControlLike, LightControlProperties, LineDirection, LockControlLike, LockControlProperties, LoggerService, ModelSpec, MotionDetectionInterface, MotionDetectionPluginResponse, MotionDetectionSettings, MotionResolution, MotionResult, MotionSensorLike, MotionSensorProperties, Notification, NotificationManager, NotifierDevice, NotifierInterface, OAuthAuthCodeFlowCapable, OAuthCapable, OAuthClientCredentialsCapable, OAuthDeviceFlowCapable, OAuthMetadata, OAuthProviderConfig, OAuthProviderDeclaration, OAuthState, OAuthStatus, ObjectDetectionInterface, ObjectDetectionPluginResponse, ObjectDetectionSettings, ObjectModelSpec, ObjectResult, ObjectSensorLike, ObjectSensorProperties, OccupancySensorLike, OccupancySensorProperties, OperatorFn, PTZControlLike, PTZControlProperties, PTZDirection, PTZPosition, PluginAPI, PluginAssignments, PluginConfig, PluginContract, PluginInfo, PluginInterfaces, Point, ProbeAudioCodec, ProbeConfig, ProbeStream, PropertyChangeOf, PtzAutotrackSettings, PythonVersion, RTPInfo, RTSPAudioCodec, RTSPUrlOptions, RtpSession, RtpSessionBackchannelOptions, RtpSessionOptions, SchemaCondition, SchemaConditionOperator, SchemaConfig, SecuritySystemLike, SecuritySystemProperties, SensorCapability, SensorLike, SensorPropertyType, SensorTriggerRef, SensorTriggerSettings, SirenControlLike, SirenControlProperties, SmokeSensorLike, SmokeSensorProperties, SnapshotInterface, SnapshotSettings, SnapshotUrlOptions, StreamDirection, StreamUrls, StreamingInterface, StreamingRole, SwitchControlLike, SwitchControlProperties, TemperatureInfoLike, TemperatureInfoProperties, ToastMessage, TrackedDetection, VideoCodec, VideoCodecProperties, VideoFFmpegCodec, VideoFrameData, VideoInputSpec, VideoStreamInfo, VideoStreamingMode, ZoneFilter, ZoneType };
+export type { AssignedPlugin, AudioCodec, AudioCodecProperties, AudioDetectionInterface, AudioDetectionPluginResponse, AudioDetectionSettings, AudioFFmpegCodec, AudioFrameData, AudioInputSpec, AudioLabel, AudioMetadata, AudioModelSpec, AudioResult, AudioSensorLike, AudioSensorProperties, AudioStreamInfo, BaseAudioLabel, BaseCamera, BaseCameraConfig, BatteryInfoLike, BatteryInfoProperties, BoundingBox, Camera, CameraAspectRatio, CameraConfig, CameraConfigInputSettings, CameraDetectionSettings, CameraDevice, CameraDeviceSource, CameraFrameWorkerSettings, CameraImplementation, CameraInformation, CameraInput, CameraPluginInfo, CameraRole, CameraSource, CameraType, CameraUiSettings, ClassifierDetection, ClassifierDetectionInterface, ClassifierDetectionPluginResponse, ClassifierResult, ClassifierSensorLike, ClassifierSensorProperties, ClipDetectionInterface, ClipDetectionPluginResponse, ClipEmbedding, ClipResult, ClipTextEmbeddingResult, ContactSensorLike, ContactSensorProperties, CoreManager, CoreManagerEvent, CreateDownloadOptions, CreateStreamDownloadOptions, Detection, DetectionAttribute, DetectionEvent, DetectionEventState, DetectionEventType, DetectionLabel, DetectionLine, DetectionZone, DeviceManager, DeviceStorage, DiscoveredCamera, DiscoveryProvider, DoorbellTriggerLike, DoorbellTriggerProperties, DownloadCleanup, DownloadManager, DownloadToken, EventAttribute, EventDescription, EventDetection, EventSegment, EventTrigger, EventTriggerType, FMTPInfo, FaceDetection, FaceDetectionInterface, FaceDetectionPluginResponse, FaceResult, FaceSensorLike, FaceSensorProperties, Fmp4Session, Fmp4SessionOptions, FormSubmitResponse, FormSubmitSchema, GarageControlLike, GarageControlProperties, Go2RtcRTSPSource, Go2RtcSnapshotSource, Go2RtcWSSource, HardwareAcceleration, HumidityInfoLike, HumidityInfoProperties, ImageMetadata, JsonArraySchema, JsonBaseSchema, JsonBaseSchemaWithoutCallbacks, JsonBooleanSchema, JsonEnumSchema, JsonFactorySchema, JsonNumberSchema, JsonSchema, JsonSchemaArray, JsonSchemaArrayWithoutCallbacks, JsonSchemaBoolean, JsonSchemaBooleanWithoutCallbacks, JsonSchemaButton, JsonSchemaEnum, JsonSchemaEnumWithoutCallbacks, JsonSchemaNumber, JsonSchemaNumberWithoutCallbacks, JsonSchemaString, JsonSchemaStringWithoutCallbacks, JsonSchemaSubmit, JsonSchemaType, JsonSchemaWithoutCallbacks, JsonSchemaWithoutKey, JsonStringSchema, LeakSensorLike, LeakSensorProperties, LicensePlateDetection, LicensePlateDetectionInterface, LicensePlateDetectionPluginResponse, LicensePlateResult, LicensePlateSensorLike, LicensePlateSensorProperties, LightControlLike, LightControlProperties, LineDirection, LockControlLike, LockControlProperties, LoggerService, ModelSpec, MotionDetectionInterface, MotionDetectionPluginResponse, MotionDetectionSettings, MotionResolution, MotionResult, MotionSensorLike, MotionSensorProperties, Notification, NotificationManager, NotifierDevice, NotifierInterface, OAuthAuthCodeFlowCapable, OAuthCapable, OAuthClientCredentialsCapable, OAuthDeviceFlowCapable, OAuthMetadata, OAuthProviderConfig, OAuthProviderDeclaration, OAuthState, OAuthStatus, ObjectDetectionInterface, ObjectDetectionPluginResponse, ObjectDetectionSettings, ObjectModelSpec, ObjectResult, ObjectSensorLike, ObjectSensorProperties, OccupancySensorLike, OccupancySensorProperties, OperatorFn, PTZControlLike, PTZControlProperties, PTZDirection, PTZPosition, PTZRelativeMove, PluginAPI, PluginAssignments, PluginConfig, PluginContract, PluginInfo, PluginInterfaces, Point, ProbeAudioCodec, ProbeConfig, ProbeStream, PropertyChangeOf, PtzAutotrackSettings, PythonVersion, RTPInfo, RTSPAudioCodec, RTSPUrlOptions, RtpSession, RtpSessionBackchannelOptions, RtpSessionOptions, SchemaCondition, SchemaConditionOperator, SchemaConfig, SecuritySystemLike, SecuritySystemProperties, SensorCapability, SensorLike, SensorPropertyType, SensorTriggerRef, SensorTriggerSettings, SirenControlLike, SirenControlProperties, SmokeSensorLike, SmokeSensorProperties, SnapshotInterface, SnapshotSettings, SnapshotUrlOptions, StreamDirection, StreamUrls, StreamingInterface, StreamingRole, SwitchControlLike, SwitchControlProperties, TemperatureInfoLike, TemperatureInfoProperties, ToastMessage, TrackedDetection, VideoCodec, VideoCodecProperties, VideoFFmpegCodec, VideoFrameData, VideoInputSpec, VideoStreamInfo, VideoStreamingMode, ZoneFilter, ZoneType };

package/dist/internal/index.d.ts

@@ -45,7 +45,7 @@ interface ModelSpec {
     input: VideoInputSpec;
     /** Labels emitted by an upstream object detector that activate this detector (e.g. `['person']` for face detection). */
     triggerLabels: DetectionLabel[];
-    /** Embedding model identifier for face recognition. */
+    /** Embedding model identifier. Required for face recognition and for CLIP: embeddings are stored and matched under this id. */
     embeddingModel?: string;
 }
 
@@ -236,7 +236,9 @@ declare enum PTZProperty {
     /** Current movement velocity (continuous move) */
     Velocity = "velocity",
     /** Target preset to move to */
-    TargetPreset = "targetPreset"
+    TargetPreset = "targetPreset",
+    /** Relative displacement move command (write-only) */
+    RelativeMove = "relativeMove"
 }
 
 /**
@@ -606,7 +608,7 @@ interface CameraInputSettings {
     useForSnapshot: boolean;
     /** Keep connection always active */
     hotMode: boolean;
-    /** Preload stream on startup */
+    /** Keep a keyframe cache for this source, so the view opens faster. Use `hotMode` to keep the stream connected. */
     preload: boolean;
     /** Strip the audio track from this source (defaults to false) */
     muted?: boolean;
@@ -730,7 +732,7 @@ interface EventDetection {
     maxCount: number;
     /** Bounding box of the highest-confidence detection (normalized 0–1) */
     box?: BoundingBox;
-    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    /** Best-selected JPEG thumbnail crop. Only present on 'segment-start' and 'segment-end' messages, and omitted when it is the same image as the segment thumbnail. */
     thumbnail?: Uint8Array;
     /** Object tracker ID (links this detection across frames) */
     trackId?: number;
@@ -747,7 +749,7 @@ interface EventAttribute {
     label: string;
     /** Detection confidence (0-1) */
     confidence?: number;
-    /** Best-selected JPEG thumbnail crop. Only present on 'end' events. */
+    /** Best-selected JPEG thumbnail crop. Present on 'segment-start' and 'segment-end' messages, and on 'segment-update' for unknown faces. */
     thumbnail?: Uint8Array;
     /** Face embedding vector for unknown face persistence. Only present for face attributes. */
     embedding?: number[];
@@ -768,7 +770,7 @@ interface EventSegment {
     firstSeen: number;
     /** Segment end time (Unix ms) */
     lastSeen: number;
-    /** Best-selected JPEG scene thumbnail for this segment. Only present on 'end' events. */
+    /** Best-selected JPEG scene thumbnail for this segment. Only present on 'segment-start' and 'segment-end' messages, plus once on a 'segment-update' if the start message had none. */
     thumbnail?: Uint8Array;
     /** Object detections in this segment */
     detections: EventDetection[];

package/dist/sensor/base.js

@@ -179,7 +179,7 @@ export class Sensor {
     /**
      * Get a read-only snapshot of all property values.
      *
-     * @returns Frozen view of every property currently held by the sensor.
+     * @returns Shallow copy of every property currently held by the sensor.
      *
      * @example
      * ```ts
@@ -305,8 +305,9 @@ export class Sensor {
      * override can safely access `this.cameraId`, `this.storage`, and publish
      * properties via the semantic helper methods.
      *
-     * Errors thrown here are caught and logged — they will NOT break assignment
-     * bookkeeping. If your work can fail, handle it inside the override.
+     * Errors thrown here are caught and swallowed, not logged. They will NOT
+     * break assignment bookkeeping, but nothing surfaces them either. If your
+     * work can fail, handle it inside the override.
      *
      * Paired 1:1 with `onDeassigned` — for every `onAssigned` call there is
      * exactly one matching `onDeassigned` later (on deassignment or cleanup).

package/dist/sensor/motion.js

@@ -111,7 +111,9 @@ export class MotionSensor extends Sensor {
  * Motion detector that receives video frames from the backend pipeline.
  * Extend this class and implement {@link detectMotion} to analyze frames
  * for motion. The backend calls `detectMotion()` at the configured frame
- * interval and applies the returned result to the sensor.
+ * interval, zone-filters the returned detections and applies them.
+ * `detected` is re-derived from the surviving detections, so a result with
+ * no detections reports no motion.
  */
 export class MotionDetectorSensor extends MotionSensor {
     _requiresFrames = true;

package/dist/sensor/ptz.js

@@ -1,4 +1,4 @@
-import { Sensor, SensorType, SensorCategory } from './base.js';
+import { Sensor, SensorCategory, SensorType } from './base.js';
 /** Optional capabilities for PTZ controls. Add to `capabilities` to enable features. */
 export var PTZCapability;
 (function (PTZCapability) {
@@ -9,6 +9,12 @@ export var PTZCapability;
     PTZCapability["Presets"] = "presets";
     /** Camera supports a home position */
     PTZCapability["Home"] = "home";
+    /** Camera executes relative displacement moves */
+    PTZCapability["RelativeMove"] = "relativeMove";
+    /** Camera accepts absolute position writes via `setPosition()` */
+    PTZCapability["AbsolutePosition"] = "absolutePosition";
+    /** Camera accepts continuous-move commands via `setVelocity()` */
+    PTZCapability["VelocityControl"] = "velocityControl";
 })(PTZCapability || (PTZCapability = {}));
 /**
  * Properties for PTZ controls
@@ -27,6 +33,8 @@ export var PTZProperty;
     PTZProperty["Velocity"] = "velocity";
     /** Target preset to move to */
     PTZProperty["TargetPreset"] = "targetPreset";
+    /** Relative displacement move command (write-only) */
+    PTZProperty["RelativeMove"] = "relativeMove";
 })(PTZProperty || (PTZProperty = {}));
 /**
  * Pan-tilt-zoom camera control. Override `setPosition()` / `setVelocity()` /
@@ -82,22 +90,41 @@ export class PTZControl extends Sensor {
      * Continuous-move command. Override to drive hardware and call
      * `await super.setVelocity(value)` after success to sync the SDK state.
      *
-     * @param value - Per-axis speeds in `[-1, 1]`, or `undefined` to stop.
+     * @param value - Per-axis speeds in `[-1, 1]`. Stop is zero on every axis.
+     * `undefined` is ignored and the published `velocity` keeps its last value.
      *
      * @example
      * ```ts
      * await ptz.setVelocity({ panSpeed: 0.5, tiltSpeed: 0, zoomSpeed: 0 });
-     * await ptz.setVelocity(undefined); // stop
+     * await ptz.setVelocity({ panSpeed: 0, tiltSpeed: 0, zoomSpeed: 0 }); // stop
      * ```
      */
     async setVelocity(value) {
         this._writeState({ [PTZProperty.Velocity]: value });
     }
+    /**
+     * Relative displacement move. Override to drive hardware (e.g. ONVIF
+     * RelativeMove in a translation space) and call
+     * `await super.setRelativeMove(value)` after success to sync the SDK state.
+     * Advertise {@link PTZCapability.RelativeMove} when the camera supports it.
+     *
+     * @param value - Per-axis displacement, normalized to the field of view.
+     *
+     * @example
+     * ```ts
+     * // move the view a third of a frame to the right, a tenth down
+     * await ptz.setRelativeMove({ panDelta: 0.33, tiltDelta: -0.1, zoomDelta: 0 });
+     * ```
+     */
+    async setRelativeMove(value) {
+        this._writeState({ [PTZProperty.RelativeMove]: value });
+    }
     /**
      * Preset-move command. Override to drive hardware and call
      * `await super.setTargetPreset(value)` after success to sync the SDK state.
      *
-     * @param value - Preset name to move to, or `undefined` to clear.
+     * @param value - Preset name to move to. `undefined` is ignored and the
+     * published `targetPreset` keeps its last value.
      *
      * @example
      * ```ts
@@ -148,7 +175,7 @@ export class PTZControl extends Sensor {
      * Cross-process consumer entry point. Dispatches writable properties
      * to semantic methods so plugin overrides (hardware actions) are honored.
      * `moving` and `presets` are observed/discovered state and not externally writable;
-     * only `Position`, `Velocity`, and `TargetPreset` may be set.
+     * only `Position`, `Velocity`, `TargetPreset`, and `RelativeMove` may be set.
      *
      * @param property - Property name to write.
      *
@@ -167,6 +194,9 @@ export class PTZControl extends Sensor {
             case PTZProperty.TargetPreset:
                 await this.setTargetPreset(value);
                 return;
+            case PTZProperty.RelativeMove:
+                await this.setRelativeMove(value);
+                return;
         }
         // Unknown / non-writable property (incl. moving, presets) — ignored.
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camera.ui/sdk",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "camera.ui sdk",
   "exports": {
     ".": {