@camstack/types 1.2.42 → 1.2.44

package/dist/interfaces/camera-switches.d.ts

@@ -5,7 +5,7 @@
  * ## This file adds no state
  *
  * Every switch here is a VIEW onto an authority that already existed
- * ([D61](../../../../docs/decisions/adr-0062.md)). The whole point of the
+ * ([D62](../../../../docs/decisions/adr-0062.md)). The whole point of the
  * group is that there is exactly one place each function is turned off, and
  * the group routes to it:
  *
@@ -16,6 +16,53 @@
  * | `audio-analysis` | `deviceManager.setWrapperActive('audio-analysis')` | `AudioSubscriptionController.subscribeAudioStream` returns `null` before opening the stream |
  * | `recording` | `recording.setDeviceConfig` → `RecordingConfig.enabled` | `band-decision.shouldRecord` returns false; the controller detaches the device |
  * | `notifications` | `notificationRules.setDeviceMuted` | `NotificationCenter.evaluateAndEnqueue` returns before any rule is evaluated |
+ * | `privacy-mask` | `privacyMask.setMask({ enabled })` → the CAMERA | the camera blanks the masked regions itself; every stream and recording carries the black boxes |
+ * | `device-audio` | `privacyMask.setAudioEnabled` → the CAMERA | the camera stops encoding an audio track at all; every consumer sees silent video |
+ * | `broker-audio` | `streamBroker.setDeviceAudioMute` → `DeviceOverride.audioMuted` | `StreamBroker.setAudioMuted` drops the audio plane at the source: no `type:'audio'` packet leaves `fanOutEncoded`, no RTP reaches the restreamer, and the restreamer serves the video-only SDP |
+ *
+ * ## `device-audio` and `broker-audio` are two functions, not two knobs
+ *
+ * They look adjacent and they are not the same control ([D83](../../../../docs/decisions/adr-0083.md)):
+ * `device-audio` writes the CAMERA, so it is hardware privacy — the microphone
+ * genuinely stops, it survives CamStack entirely, and it costs a multi-second
+ * encoder restart on every flip. `broker-audio` writes THIS server, so it is
+ * instant, vendor-independent and reversible without touching the camera, and
+ * a camera that ignores or lacks the ISAPI/Reolink control is still silenced.
+ * D62 forbids a second switch that *disagrees* with the first; these two
+ * cannot disagree, because neither reads the other's store — the camera holds
+ * one, the broker holds the other, and each reports its own fact.
+ *
+ * ## The two switches whose authority is not on this server
+ *
+ * `privacy-mask` and `device-audio` write the CAMERA. That is not a loophole
+ * in "the group stores nothing" — it is the purest form of it: the camera
+ * holds the fact, every read is a read-through, and there is no server-side
+ * copy that could drift. Their availability therefore cannot come from
+ * `listBindableCapsForDeviceType` (a device-NATIVE cap carries no wrappers and
+ * is filtered out there); it comes from the cap's own camera-probed
+ * `privacyMask.getOptions()`, which is strictly more honest — it answers for
+ * THIS camera rather than for the device type
+ * ([D74](../../../../docs/decisions/adr-0074.md)).
+ *
+ * ## `privacy-mask` is the one row whose ON is not "the function is working"
+ *
+ * Every other switch means *this camera's function is doing its job*, so
+ * `enabled: false` is a thing an operator took away. `privacy-mask` means **the
+ * MASK is active** — `enabled: true` is video deliberately obscured. The
+ * polarity is not a choice made here: `addon-export-hap`'s privacy `Switch`
+ * (`builders/privacy-switch.ts`) already mirrors `patch.enabled` verbatim, and
+ * a HomeKit toggle that disagreed with the app's toggle for the same camera is
+ * worse than either surface not having one.
+ *
+ * Two consequences follow and both are load-bearing:
+ *
+ * - **It never counts as `switchedOff`.** `countsAsSwitchedOff` is `false` for
+ *   exactly this row. With the polarity above, every camera that has NOT drawn
+ *   a privacy mask would otherwise report `switchedOff: ['privacy-mask']` — the
+ *   normal, healthy state of most cameras rendered as an operator disablement.
+ * - **Its cost line names BOTH directions.** `costWhenOff` is rendered
+ *   unconditionally by both clients, so for this row it has to read correctly
+ *   whichever way the switch is sitting.
  *
  * The wrapper-binding pair is not a new idea: `legacy-migrations.ts` already
  * migrated the legacy `audioEnabled` / `pipelineEnabled` /
@@ -35,20 +82,39 @@
  */
 import { z } from 'zod';
 /**
- * The five functions the operator named (2026-08-05). Deliberately NOT one id
- * per pipeline step: face recognition and plate/LPR are per-step toggles on
+ * The functions the operator named — five on 2026-08-05, plus the camera's own
+ * microphone on 2026-08-07. Deliberately NOT one id per pipeline step: face
+ * recognition and plate/LPR are per-step toggles on
  * `pipelineOrchestrator.setCameraStepToggle` and belong in the pipeline
- * editor, not in a five-button safety group.
+ * editor, not in a safety group.
  */
 export declare const CameraSwitchIdSchema: z.ZodEnum<{
+    "privacy-mask": "privacy-mask";
     "audio-analysis": "audio-analysis";
     recording: "recording";
     "stream-broker": "stream-broker";
     notifications: "notifications";
     "object-detection": "object-detection";
+    "device-audio": "device-audio";
+    "broker-audio": "broker-audio";
 }>;
 export type CameraSwitchId = z.infer<typeof CameraSwitchIdSchema>;
-/** Stable render order — broadest blast radius first. */
+/**
+ * Stable render order — broadest blast radius first, and a source before the
+ * thing that consumes it. `device-audio` sits ABOVE `audio-analysis` because
+ * turning the microphone off leaves the analyzer with nothing to analyse; the
+ * reverse is not true.
+ *
+ * `privacy-mask` sits directly ABOVE `device-audio` because they are literal
+ * siblings — one cap, one device plane, video then audio — and NOT above
+ * `object-detection` despite feeding it: a mask blanks REGIONS, so its blast
+ * radius is partial, and the "broadest first" rule does not rank a partial
+ * control above a whole-function one.
+ *
+ * `broker-audio` sits directly BELOW `device-audio` by the same source-first
+ * rule: the camera's microphone feeds the broker, so silencing the camera
+ * leaves the broker's mute with nothing to suppress; the reverse is not true.
+ */
 export declare const CAMERA_SWITCH_ORDER: readonly CameraSwitchId[];
 /**
  * WHERE the switch's state actually lives. A discriminated union rather than a
@@ -65,6 +131,14 @@ export declare const CameraSwitchAuthoritySchema: z.ZodDiscriminatedUnion<[z.Zod
     kind: z.ZodLiteral<"recording-config">;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"notification-mute">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"camera-audio">;
+    capName: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"camera-mask">;
+    capName: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"broker-audio-mute">;
 }, z.core.$strip>], "kind">;
 export type CameraSwitchAuthority = z.infer<typeof CameraSwitchAuthoritySchema>;
 /**
@@ -75,6 +149,7 @@ export type CameraSwitchAuthority = z.infer<typeof CameraSwitchAuthoritySchema>;
 export declare const CameraSwitchUnavailableReasonSchema: z.ZodEnum<{
     "no-provider": "no-provider";
     "source-unreachable": "source-unreachable";
+    "not-configured": "not-configured";
 }>;
 export type CameraSwitchUnavailableReason = z.infer<typeof CameraSwitchUnavailableReasonSchema>;
 /**
@@ -87,11 +162,14 @@ export type CameraSwitchUnavailableReason = z.infer<typeof CameraSwitchUnavailab
  */
 export declare const CameraSwitchSchema: z.ZodObject<{
     id: z.ZodEnum<{
+        "privacy-mask": "privacy-mask";
         "audio-analysis": "audio-analysis";
         recording: "recording";
         "stream-broker": "stream-broker";
         notifications: "notifications";
         "object-detection": "object-detection";
+        "device-audio": "device-audio";
+        "broker-audio": "broker-audio";
     }>;
     label: z.ZodString;
     costWhenOff: z.ZodString;
@@ -99,6 +177,7 @@ export declare const CameraSwitchSchema: z.ZodObject<{
     unavailableReason: z.ZodOptional<z.ZodEnum<{
         "no-provider": "no-provider";
         "source-unreachable": "source-unreachable";
+        "not-configured": "not-configured";
     }>>;
     enabled: z.ZodBoolean;
     authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -110,6 +189,14 @@ export declare const CameraSwitchSchema: z.ZodObject<{
         kind: z.ZodLiteral<"recording-config">;
     }, z.core.$strip>, z.ZodObject<{
         kind: z.ZodLiteral<"notification-mute">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"camera-audio">;
+        capName: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"camera-mask">;
+        capName: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"broker-audio-mute">;
     }, z.core.$strip>], "kind">;
 }, z.core.$strip>;
 export type CameraSwitch = z.infer<typeof CameraSwitchSchema>;
@@ -118,11 +205,14 @@ export declare const CameraSwitchGroupSchema: z.ZodObject<{
     deviceId: z.ZodNumber;
     switches: z.ZodReadonly<z.ZodArray<z.ZodObject<{
         id: z.ZodEnum<{
+            "privacy-mask": "privacy-mask";
             "audio-analysis": "audio-analysis";
             recording: "recording";
             "stream-broker": "stream-broker";
             notifications: "notifications";
             "object-detection": "object-detection";
+            "device-audio": "device-audio";
+            "broker-audio": "broker-audio";
         }>;
         label: z.ZodString;
         costWhenOff: z.ZodString;
@@ -130,6 +220,7 @@ export declare const CameraSwitchGroupSchema: z.ZodObject<{
         unavailableReason: z.ZodOptional<z.ZodEnum<{
             "no-provider": "no-provider";
             "source-unreachable": "source-unreachable";
+            "not-configured": "not-configured";
         }>>;
         enabled: z.ZodBoolean;
         authority: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -141,6 +232,14 @@ export declare const CameraSwitchGroupSchema: z.ZodObject<{
             kind: z.ZodLiteral<"recording-config">;
         }, z.core.$strip>, z.ZodObject<{
             kind: z.ZodLiteral<"notification-mute">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"camera-audio">;
+            capName: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"camera-mask">;
+            capName: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"broker-audio-mute">;
         }, z.core.$strip>], "kind">;
     }, z.core.$strip>>>;
     fetchedAt: z.ZodNumber;
@@ -154,12 +253,32 @@ export type CameraSwitchGroup = z.infer<typeof CameraSwitchGroupSchema>;
  */
 export declare const DETECTION_PIPELINE_CAP_NAME = "detection-pipeline";
 export declare const AUDIO_ANALYSIS_CAP_NAME = "audio-analysis";
+/**
+ * The device-NATIVE cap that owns what the camera does not capture — masked
+ * video regions and, since 2026-08-07, the microphone. Named here because the
+ * `camera-audio` authority, the orchestrator's gather and the fake harness all
+ * have to agree on it.
+ */
+export declare const PRIVACY_MASK_CAP_NAME = "privacy-mask";
 /** Static half of a switch: everything that does not depend on a device. */
 export interface CameraSwitchDescriptor {
     readonly id: CameraSwitchId;
     readonly label: string;
     readonly costWhenOff: string;
     readonly authority: CameraSwitchAuthority;
+    /**
+     * May `enabled: false` on this row appear in {@link switchedOffIds}?
+     *
+     * `true` for every switch that means "this camera's function is doing its
+     * job", where OFF is something a person took away and a status surface must
+     * render as disabled rather than broken.
+     *
+     * `false` for `privacy-mask` alone, and only because its polarity is
+     * inverted: OFF there means the mask is not obscuring anything, which is the
+     * ordinary state of nearly every camera. Reporting it would put a
+     * `switchedOff` badge on healthy cameras and drown the badge that matters.
+     */
+    readonly countsAsSwitchedOff: boolean;
 }
 /**
  * THE catalog. One entry per switch; the cost lines are the operator-facing
@@ -195,6 +314,87 @@ export interface CameraSwitchDerivationInput {
     readonly recordingEnabled: boolean | null;
     /** `notificationRules` per-camera mute; `null` when the cap did not answer. */
     readonly notificationsMuted: boolean | null;
+    /**
+     * The camera's own microphone, read through the `privacy-mask` native cap.
+     * `null` = the cap is bound to this camera but did not answer.
+     *
+     * A camera with no `privacy-mask` provider at all is `{ supported: false }`,
+     * not `null` — "this camera has no such control" and "we could not read it"
+     * are different answers and the operator is shown different copy for each.
+     */
+    readonly deviceAudio: DeviceAudioSwitchState | null;
+    /**
+     * The camera's own VIDEO privacy mask, read through the same `privacy-mask`
+     * native cap and the same pair of round trips as {@link deviceAudio} — one
+     * `getOptions` + one `getStatus` answer both, so the second switch is free.
+     *
+     * `null` = the cap is bound to this camera but did not answer.
+     */
+    readonly privacyMask: PrivacyMaskSwitchState | null;
+    /**
+     * The BROKER's audio-plane policy for this camera, read from the
+     * stream-broker on the device's source-owner node. `null` = the broker did
+     * not answer, which renders no control rather than a control defaulted to
+     * "audio flows".
+     */
+    readonly brokerAudio: BrokerAudioSwitchState | null;
+}
+/** What the stream-broker reported about its audio plane for one camera. */
+export interface BrokerAudioSwitchState {
+    /**
+     * `DeviceOverride.audioMuted` — the broker's own persisted policy. `true`
+     * means the broker drops this camera's audio on every plane it serves.
+     *
+     * There is no `supported` companion, deliberately. Muting a camera that is
+     * currently silent is not a dead control: the policy governs what happens
+     * when sound DOES appear (a camera unmuted at the device, a stream that
+     * only carries audio at night), so it is meaningful to set in advance.
+     * That is the opposite of the privacy mask with zero zones, where flipping
+     * the master enable is provably a no-op until something else changes.
+     */
+    readonly muted: boolean;
+}
+/** What the camera-probed audio switch reported for one camera. */
+export interface DeviceAudioSwitchState {
+    /**
+     * `privacyMask.getOptions().supportsAudioMute` — camera-probed, never a
+     * device-type guess. A camera that does not expose the control renders no
+     * switch rather than a toggle that silently does nothing.
+     */
+    readonly supported: boolean;
+    /**
+     * `privacyMask.getStatus().audioEnabled` — the camera's current answer.
+     * `null` when unsupported, or when supported but unreadable; the second
+     * case yields `source-unreachable`, never a control defaulted to "on".
+     */
+    readonly enabled: boolean | null;
+}
+/** What the camera-probed VIDEO privacy mask reported for one camera. */
+export interface PrivacyMaskSwitchState {
+    /**
+     * Can this camera store privacy zones at all? Derived from the probed
+     * `getOptions()`: `maxRegions > 0` AND at least one supported shape kind.
+     * Reolink answers `maxNum: 0` / `supportedShapes: []` honestly on models
+     * that cannot, and that must render no control rather than a toggle whose
+     * write the camera discards.
+     */
+    readonly supported: boolean;
+    /**
+     * How many zones are actually drawn on the camera right now
+     * (`getStatus().regions.length`). `null` = supported, but the status could
+     * not be read.
+     *
+     * **Zero is not "off", it is "nothing to switch".** Toggling the master
+     * enable with no zones changes not one pixel — the dead control D62 exists
+     * to remove — so it resolves to `not-configured`, which tells the operator
+     * to go and draw one instead of leaving them pressing a button.
+     */
+    readonly configuredRegions: number | null;
+    /**
+     * `getStatus().enabled` — the camera's master mask flag, `true` when the
+     * zones are being blanked. `null` when unreadable; never defaulted.
+     */
+    readonly enabled: boolean | null;
 }
 /**
  * Pure derivation of the whole group. No I/O — the orchestrator gathers, this
@@ -213,5 +413,11 @@ export declare function deriveCameraSwitches(input: CameraSwitchDerivationInput)
  * `switchedOff: ['object-detection']` was turned off; the same camera with an
  * empty list is broken. Unavailable switches never appear — a function nobody
  * provides was not switched off by anyone.
+ *
+ * `privacy-mask` never appears either, whichever way it is sitting, because its
+ * ON means "the mask is active" rather than "the function works"
+ * ({@link CameraSwitchDescriptor.countsAsSwitchedOff}). Without that filter the
+ * ordinary state of every camera nobody has masked would carry a
+ * "switched off" badge, and the badge that matters would be lost in it.
  */
 export declare function switchedOffIds(switches: readonly CameraSwitch[]): readonly CameraSwitchId[];

package/dist/interfaces/inference-engine.d.ts

@@ -16,16 +16,36 @@ import type { RawFrameFormat } from '../types/io.js';
  * raw buffer to JPEG internally rather than throwing — `infer()` must
  * always succeed for either kind.
  */
-export type InferenceInput = {
+/**
+ * Fields every `InferenceInput` variant carries regardless of pixel transport.
+ */
+interface InferenceInputCommon {
+    /**
+     * The camera this frame belongs to — **diagnostic only**. It changes no
+     * dispatch decision, no deadline and no shed rule; it exists so an inference
+     * failure inside a SHARED pool can name the camera that paid for it.
+     *
+     * A `SharedInferencePool` serves every camera on its
+     * `(node, runtime, device)`, so its `inference request timed out` and
+     * `worker saturated` lines could describe the pool and nothing else — and
+     * "why is 617 worse than 615?" is the question those lines always get asked.
+     *
+     * Omitted by callers with no camera (commands, model loads, the benchmark);
+     * the failure line then carries no `deviceId` tag rather than a fabricated
+     * one.
+     */
+    readonly deviceId?: number;
+}
+export type InferenceInput = ({
     readonly kind: 'jpeg';
     readonly data: Buffer;
-} | {
+} & InferenceInputCommon) | ({
     readonly kind: 'raw';
     readonly data: Buffer;
     readonly width: number;
     readonly height: number;
     readonly format: RawFrameFormat;
-};
+} & InferenceInputCommon);
 export interface IInferenceEngine {
     readonly runtime: DetectionRuntime;
     readonly device: DetectionDevice;
@@ -34,3 +54,4 @@ export interface IInferenceEngine {
     run?(input: Float32Array, inputShape: readonly number[]): Promise<Float32Array>;
     dispose(): Promise<void>;
 }
+export {};

package/dist/interfaces/stream-broker.d.ts

@@ -208,6 +208,24 @@ export interface BrokerStats {
         readonly channels: number;
         readonly supported: boolean;
     } | null;
+    /**
+     * BROKER-SIDE AUDIO MUTE ([D83](../../../../docs/decisions/adr-0083.md)).
+     * `true` = this broker is deliberately distributing none of the device's
+     * audio, live or recorded. It is what tells a silent camera apart from a
+     * broken one on the stream panel: a broker holding an `audio` descriptor
+     * with `audioMuted: true` is doing exactly what it was asked.
+     *
+     * `audioMutedDropped` counts the audio units the mute threw away since the
+     * current dial — the proof the mute is on the packet path and not merely
+     * persisted.
+     *
+     * NOTE: this interface is the hand-written twin of `BrokerStatsSchema` in
+     * `capabilities/schemas/streaming-shared.ts`. They are not generated from
+     * each other; a field added to one and not the other compiles and then
+     * silently disappears on the wire.
+     */
+    readonly audioMuted?: boolean;
+    readonly audioMutedDropped?: number;
 }
 export interface IStreamBroker {
     readonly deviceId: string;

package/dist/node.d.ts

@@ -8,3 +8,7 @@ export { canonicalDeviceFingerprint, diffExportTargets, resolveExportFingerprint
 export type { DeviceExportShape, ExportDelta, ExportTargetEntry, } from './utils/export-reconciler.js';
 export { FfmpegProcess } from './ffmpeg/process.js';
 export type { FfmpegProcessOptions, FfmpegExit, FfmpegExitClass } from './ffmpeg/process.js';
+export { Fmp4FragmentPlane } from './ffmpeg/fmp4-fragment-plane.js';
+export type { Fmp4CloseReason, Fmp4Packet, Fmp4PrebufferOptions, Fmp4PrebufferStats, Fmp4SubscribeInput, Fmp4SubscriberInfo, Fmp4Subscription, } from './ffmpeg/fmp4-fragment-plane.js';
+export { Fmp4FragmentChild } from './ffmpeg/fmp4-fragment-child.js';
+export type { Fmp4FragmentChildArgs, Fmp4FragmentChildDeps, } from './ffmpeg/fmp4-fragment-child.js';