@camera.ui/sdk 0.0.3 → 0.0.4

package/dist/sensor/audio.js

@@ -1,118 +1,140 @@
-import { Sensor } from './base.js';
-import { SensorCategory, SensorType } from './types.js';
+import { Sensor, SensorType, SensorCategory } from './base.js';
+/** Built-in audio label types recognized across the system. */
+export const BASE_AUDIO_LABELS = [
+    'doorbell',
+    'glass_break',
+    'siren',
+    'speaking',
+    'gunshot',
+    'dog_bark',
+    'baby_cry',
+    'alarm',
+    'scream',
+    'cat',
+    'car_alarm',
+    'smoke_alarm',
+];
 /**
- * Audio sensor property keys
+ * Property names of an audio detection sensor.
+ *
+ * @internal
  */
 export var AudioProperty;
 (function (AudioProperty) {
+    /** Whether an audio event is currently detected. */
     AudioProperty["Detected"] = "detected";
+    /** List of detected audio events (e.g. glass break, scream). */
     AudioProperty["Detections"] = "detections";
+    /** Current audio level in decibels. */
     AudioProperty["Decibels"] = "decibels";
+    /** Timestamp in milliseconds of the last detection trigger, set by the backend. */
+    AudioProperty["LastTriggered"] = "lastTriggered";
 })(AudioProperty || (AudioProperty = {}));
 /**
- * Audio Sensor
- *
- * Base class for external audio detection (Ring, ONVIF events, etc.)
- * Properties can be set directly: `sensor.detected = true`
+ * Audio sensor that reports audio events and decibel levels.
  *
- * For audio-stream-based detection, use `AudioDetectorSensor` instead.
+ * Plugin authors call `reportDetections(list)` to push detected audio events
+ * (auto-derives `detected`) and `setDecibels(value)` to update the audio level.
  */
 export class AudioSensor extends Sensor {
     type = SensorType.Audio;
     category = SensorCategory.Sensor;
-    name;
-    /**
-     * External audio sensors don't require audio frames.
-     * They receive detection events from external sources (APIs, ONVIF, etc.)
-     */
     _requiresFrames = false;
     constructor(name = 'Audio Sensor') {
-        super();
-        this.name = name;
-        // Initialize defaults
-        this.props.detected = false;
-        this.props.detections = [];
-        this.props.decibels = 0;
+        super(name);
+        this._writeState({
+            [AudioProperty.Detected]: false,
+            [AudioProperty.Detections]: [],
+            [AudioProperty.Decibels]: 0,
+        });
     }
-    /** Whether audio event is currently detected */
+    /** Whether an audio event is currently detected. */
     get detected() {
-        return this.rawProps.detected;
+        return this.props.detected;
     }
-    /** Set audio detected state */
-    set detected(value) {
-        this.props.detected = value;
-    }
-    /** Current audio detections */
+    /** Current detection list. */
     get detections() {
-        return this.rawProps.detections;
-    }
-    /** Set audio detections */
-    set detections(value) {
-        this.props.detections = value;
+        return this.props.detections;
     }
-    /** Current decibel level */
+    /** Current audio level in decibels. */
     get decibels() {
-        return this.rawProps.decibels;
+        return this.props.decibels;
     }
-    /** Set decibel level */
-    set decibels(value) {
-        this.props.decibels = value;
+    /**
+     * Report detected audio events.
+     *
+     * - `reportDetections(true)` — audio detected without specifics. The SDK
+     *   synthesizes a single full-frame `'audio'` detection.
+     * - `reportDetections(true, [...])` — audio detected with explicit detections.
+     * - `reportDetections(false)` — clear.
+     *
+     * @param detected - Whether an audio event is currently detected.
+     *
+     * @param detections - Optional explicit detections produced for this event.
+     *
+     * @example
+     * ```ts
+     * import type { Detection } from '@camera.ui/sdk';
+     * sensor.reportDetections(true, [
+     *   { label: 'glass_break', confidence: 0.91, box: { x: 0, y: 0, width: 1, height: 1 } } satisfies Detection,
+     * ]);
+     * sensor.reportDetections(false);
+     * ```
+     */
+    reportDetections(detected, detections) {
+        const list = this._normalizeReportedDetections(detected, detections, 'audio');
+        this._writeState({
+            [AudioProperty.Detected]: detected,
+            [AudioProperty.Detections]: list,
+        });
     }
     /**
-     * Update audio detection state
+     * Explicitly clear audio detection state (detected = false, detections = []).
      *
-     * @param detected - Whether audio event is currently detected
+     * @example
+     * ```ts
+     * sensor.clearDetections();
+     * ```
+     */
+    clearDetections() {
+        this.reportDetections(false);
+    }
+    /**
+     * Update the current audio level (in decibels).
      *
-     * @param detections - Array of detection events
+     * @param value - Audio level in decibels.
      *
-     * @param decibels - Current decibel level
+     * @example
+     * ```ts
+     * sensor.setDecibels(72);
+     * ```
      */
-    setAudio(detected, detections = [], decibels) {
-        this.props.detected = detected;
-        this.props.detections = detections;
-        if (decibels !== undefined) {
-            this.props.decibels = decibels;
-        }
+    setDecibels(value) {
+        this._writeState({ [AudioProperty.Decibels]: value });
     }
-    /** Clear audio detection state */
-    clearAudio() {
-        this.props.detected = false;
-        this.props.detections = [];
-        this.props.decibels = 0;
+    /**
+     * Read-only sensor: external writes are ignored. State is reported via `reportDetections`/`setDecibels`.
+     *
+     * Called by the cross-process plugin host when a generic property write is received.
+     * Audio sensors have no externally writable properties, so the parameters are
+     * unused (underscore-prefixed) and the call is a no-op.
+     *
+     * @param _property - Unused — audio sensors expose no writable properties.
+     *
+     * @param _value - Unused — audio sensors expose no writable properties.
+     *
+     * @internal
+     */
+    updateValue(_property, _value) {
+        // No-op — audio state is reported by the plugin, not set externally.
     }
 }
 /**
- * Audio Detector Sensor (Active Detection)
- *
- * Use this class for audio-based event detection (glass break, screams, etc.)
- * The `inputProperties` getter specifies the required audio input format.
- *
- * @example
- * ```typescript
- * class GlassBreakDetector extends AudioDetectorSensor {
- *   get inputProperties(): AudioInputProperties {
- *     return { sampleRate: 16000, channels: 1, format: 'pcm16' };
- *   }
- *
- *   async detectAudio(audio: AudioData): Promise<AudioResult> {
- *     const events = await this.classifier.classify(audio.data);
- *     return {
- *       detected: events.some(e => e.label === 'glass_break'),
- *       detections: events.map(e => ({
- *         label: e.label,
- *         confidence: e.score,
- *         box: { x: 0, y: 0, width: 1, height: 1 },
- *       })),
- *       decibels: audio.decibels,
- *     };
- *   }
- * }
- * ```
+ * Audio detector that receives audio frames from the backend pipeline.
+ * Extend this class and implement {@link detectAudio} to classify audio events.
+ * The backend resamples and buffers audio to match {@link modelSpec} before
+ * each call.
  */
 export class AudioDetectorSensor extends AudioSensor {
-    /**
-     * Indicates this sensor requires audio frames for detection.
-     * Used by the backend to determine streaming requirements.
-     */
     _requiresFrames = true;
 }