@camstack/types 1.2.42 → 1.2.43

package/dist/ffmpeg/invocation.d.ts

@@ -21,7 +21,7 @@
  * `-i`; everything that configures an OUTPUT comes after. `__tests__/
  * ffmpeg-invocation.spec.ts` asserts INDEXES, never membership.
  */
-import type { EncodeProfile, AudioEncode } from '../encode-profile.js';
+import type { AudioEncode, EncodeProfile } from '../encode-profile.js';
 /** Everything that configures the ffmpeg INPUT. Emitted strictly before `-i`. */
 export interface FfmpegInputPlan {
     /** An RTSP url, a `pipe:0` stdin feed, or a file path. */
@@ -34,6 +34,25 @@ export interface FfmpegInputPlan {
     readonly rtspTransport?: 'tcp' | 'udp' | null;
     /** `-fflags` values, e.g. `['+discardcorrupt']`, `['+genpts']`. */
     readonly fflags?: readonly string[];
+    /**
+     * `-analyzeduration` (microseconds) and `-probesize` (bytes): how long ffmpeg
+     * inspects the input before it emits ANYTHING.
+     *
+     * Unset means ffmpeg's defaults — 5 s and 5 MB — and on a live egress pull
+     * that is a five-second stall before the first packet, paid by whoever is
+     * staring at the player. Measured on the live hub: a HomeKit session on a
+     * 9 fps slot took 9 s from `stream started` to the first packet out of
+     * ffmpeg and 12.2 s to the first key frame. The SLOWER the slot, the longer
+     * the wait, because the default budget is wall-clock over an input that
+     * delivers few frames per second — which is why the 25 fps slot looked fine
+     * and the 9 fps one looked broken.
+     *
+     * Safe to shrink on RTSP specifically: the SDP already declares the codec,
+     * so there is nothing for the probe to discover. Leave unset for inputs that
+     * genuinely need discovery (a file of unknown provenance, a raw pipe).
+     */
+    readonly analyzeDurationUs?: number;
+    readonly probeSizeBytes?: number;
     /** Caller-supplied input options (an `EncodeProfile.inputArgs`, probe flags). */
     readonly extraArgs?: readonly string[];
 }
@@ -82,6 +101,21 @@ export interface FfmpegVideoEncodePlan {
     readonly pixelFormat?: string;
     readonly fps?: number;
     readonly gopFrames?: number;
+    /**
+     * `-force_key_frames expr:gte(t,n_forced*<sec>)` — an IDR every `<sec>`
+     * seconds of OUTPUT time, regardless of what the source does.
+     *
+     * Only a fragmented-MP4 consumer needs this today, and it needs it for a
+     * structural reason rather than a quality one: an fMP4 fragment written with
+     * `frag_keyframe` is cut at a key frame, so the key-frame cadence IS the
+     * fragment cadence. `-g` bounds the GOP the encoder would choose anyway;
+     * this pins the boundary to a wall-clock grid the muxer can meet.
+     *
+     * Structurally absent from {@link FfmpegVideoCopyPlan}: a copy has no
+     * encoder to instruct, and ffmpeg accepts the flag there, warns, and ignores
+     * it — the silent-no-op shape this file exists to prevent.
+     */
+    readonly forceKeyFramesSeconds?: number;
     readonly bf?: number;
     readonly bitrateKbps?: number;
     readonly rateControl?: FfmpegRateControl;
@@ -136,13 +170,46 @@ export interface FfmpegRtpOutput {
     /** Path ffmpeg writes this output's SDP to (`-sdp_file`). */
     readonly sdpFile?: string;
 }
+/**
+ * A fragmented-MP4 bytestream on stdout: `ftyp`+`moov` once, then a
+ * `moof`+`mdat` per fragment. The shape HomeKit Secure Video's recording
+ * delegate consumes, and the shape a CamStack clip source can consume from the
+ * same child (D67's primitive, one fragmenter, two consumers).
+ *
+ * ## Why `frag_keyframe` + `min_frag_duration`, and NOT `frag_duration`
+ *
+ * HKSV requires every media fragment to START on a sync sample. `frag_keyframe`
+ * cuts a fragment at each key frame, which satisfies that by construction.
+ * `-frag_duration` cuts at a wall-clock boundary *whether or not* a key frame
+ * has arrived, so a source whose IDR is late produces a fragment that opens on
+ * a delta frame — accepted by the muxer, rejected by the consumer, and
+ * invisible in an argv test. `-min_frag_duration` is the safe half of the pair:
+ * it only ever DELAYS a cut, so the boundary stays a key frame and a source
+ * with a 1 s GOP does not emit four fragments where one was negotiated.
+ *
+ * The consequence, stated because it decides what the caller must do: the
+ * fragment length is the key-frame cadence, so a caller that wants ~N-second
+ * fragments must also pin {@link FfmpegVideoEncodePlan.forceKeyFramesSeconds}.
+ * On a `copy` plan it cannot, and the fragment length is then whatever the
+ * SOURCE's GOP makes it — `fragmentMs` becomes a floor, not a target.
+ */
+export interface FfmpegFmp4Sink {
+    readonly kind: 'stdout';
+    readonly container: 'mp4';
+    /**
+     * The negotiated fragment length in milliseconds. Emitted as
+     * `-min_frag_duration` (microseconds): no fragment is cut before this much
+     * media has accumulated, and the cut itself still lands on a key frame.
+     */
+    readonly fragmentMs: number;
+}
 export type FfmpegSink = {
     readonly kind: 'rtsp-listen';
     readonly url: string;
 } | {
     readonly kind: 'stdout';
     readonly container: 'h264' | 'hevc' | 'mpegts';
-}
+} | FfmpegFmp4Sink
 /**
  * Two independent mapped RTP outputs. Generic ffmpeg RTP vocabulary — the
  * SRTP encryption, the port allocation and the payload-type numbers stay
@@ -235,6 +302,37 @@ export interface EncodeProfileInvocationInput {
     readonly logLevel?: 'error' | 'warning' | 'info';
     readonly threadCount?: number;
     readonly audioSidecar?: FfmpegAudioSidecar | null;
+    /**
+     * How the encoder is bounded. `EncodeProfile` carries a bitrate but not the
+     * WINDOW it is enforced over, and the window is the difference between a
+     * HomeKit stream that fits its per-second budget and one that overshoots on
+     * every key frame. Absent ⇒ the relaxed two-second default a browser wants.
+     *
+     * The three overlays below are on the INVOCATION rather than on
+     * `EncodeProfile` on purpose: they are consumer-protocol facts
+     * (`acquireEgressTranscode` exposes each as its own named request field),
+     * while `EncodeProfile` is the operator-facing shape a derived-stream editor
+     * writes. Folding them into the profile would put ffmpeg detail in front of
+     * an operator who has no way to judge it.
+     */
+    readonly rateControl?: FfmpegRateControl;
+    /** `-bsf:v` — `dump_extra` for a consumer that negotiates its own SDP. */
+    readonly bitstreamFilter?: string;
+    /** `-pix_fmt`. */
+    readonly pixelFormat?: string;
+    /**
+     * `-force_key_frames` on a fixed grid — see
+     * {@link FfmpegVideoEncodePlan.forceKeyFramesSeconds}. An overlay like the
+     * three above rather than an `EncodeProfile` field: it is a CONSUMER-protocol
+     * fact (an fMP4 fragment length the consumer negotiated), not something an
+     * operator authoring a derived stream can judge.
+     *
+     * Applies only to the encode branch. On a smart COPY there is no encoder to
+     * instruct, and the caller — not this adapter — has to decide whether a
+     * source-dictated GOP is acceptable, because only the caller knows what it
+     * promised its consumer.
+     */
+    readonly forceKeyFramesSeconds?: number;
 }
 /**
  * Adapt an `EncodeProfile` (the operator/consumer-facing shape) into an

package/dist/ffmpeg/sharing-key.d.ts

@@ -7,10 +7,62 @@ import type { EgressTranscodeRequest } from '../capabilities/stream-broker.cap.j
  *   object either way (`substituteRtspHost`), so folding it in would fork the
  *   child once per consuming node;
  * - `tag` is attribution for the broker panel.
+ *
+ * `publishLocally` is INSIDE the shape, and it is not a delivery detail like
+ * `hostname`. A push child emits MPEG-TS and its demuxed packets go straight
+ * into a published cam stream; a dial child emits an elementary Annex-B
+ * bytestream into a restreamer a consumer dials. Same encode parameters,
+ * completely different transports — so with it excluded, whoever acquired
+ * FIRST decided the transport for every later sharer, and the loser received a
+ * handle whose transport its consumer cannot use.
+ */
+/**
+ * How the encoded bytes REACH the consumer. Three transports, three containers,
+ * three delivery mechanisms — and a child can serve exactly one of them, which
+ * is why this is in the key and `hostname` is not.
+ *
+ * - `dial` — elementary Annex-B into a restreamer the consumer dials.
+ * - `push` — MPEG-TS demuxed straight into a locally published cam stream.
+ * - `fragments` — a fragmented-MP4 byte stream split into an initialisation
+ *   segment plus `moof`+`mdat` units, delivered IN-PROCESS on a subscribable
+ *   plane. No url and no cam stream: the consumer holds an object, not an
+ *   address. Not reachable from `EgressTranscodeRequest` today — see
+ *   {@link egressTransportFromRequest}.
+ */
+export type EgressTransport = 'dial' | 'push' | 'fragments';
+/**
+ * Everything about DELIVERY that decides which child a request lands on.
+ *
+ * It is a second argument rather than fields on `EgressTranscodeRequest`
+ * because the `fragments` transport has no cap surface yet: HKSV's delegate and
+ * the clip source that will share its fragmenter are both in-process consumers,
+ * and putting `fragmentMs` on the request schema now would mean a codegen run
+ * and a `@camstack/system` train for a field nothing off-node can call. When
+ * that changes, {@link egressTransportFromRequest} is the ONE place that learns
+ * to read it, and every sharing decision follows automatically.
+ */
+export interface EgressTransportPlan {
+    readonly transport: EgressTransport;
+    /**
+     * Negotiated fragment length, `fragments` only. In the key: two consumers
+     * that negotiated different fragment lengths are asking for differently-cut
+     * media out of differently-configured muxers, so they cannot share a child.
+     */
+    readonly fragmentMs?: number;
+}
+/**
+ * The transport a CAP request describes. `fragments` is deliberately
+ * unreachable from here — the request schema has no way to ask for it, so the
+ * cap path can never be handed a fragment child by accident.
  */
+export declare function egressTransportFromRequest(request: EgressTranscodeRequest): EgressTransportPlan;
 interface CanonicalEgressPlan {
     readonly deviceId: number;
     readonly source: string;
+    /** See {@link EgressTransport}. */
+    readonly transport: EgressTransport;
+    /** The negotiated fragment length, or `-1` for a transport without one. */
+    readonly fragmentMs: number;
     readonly video: Readonly<Record<string, string | number>>;
     readonly audio: Readonly<Record<string, string | number>>;
     readonly rateControl: string;
@@ -23,7 +75,7 @@ interface CanonicalEgressPlan {
  * future operator-facing "why are these two not sharing?" surface — can diff
  * two requests without reversing a hash.
  */
-export declare function canonicalEgressPlan(request: EgressTranscodeRequest): CanonicalEgressPlan;
+export declare function canonicalEgressPlan(request: EgressTranscodeRequest, delivery?: EgressTransportPlan): CanonicalEgressPlan;
 /**
  * The refcount / dedup key. `canonicalHash` sorts object keys at every depth,
  * so a request built with a different field order produces the same digest.
@@ -35,5 +87,5 @@ export declare function canonicalEgressPlan(request: EgressTranscodeRequest): Ca
  * exactly a mutable shared object, where one consumer's downgrade dragged
  * every other consumer to 360p.
  */
-export declare function egressTranscodeSharingKey(request: EgressTranscodeRequest): string;
+export declare function egressTranscodeSharingKey(request: EgressTranscodeRequest, delivery?: EgressTransportPlan): string;
 export {};

package/dist/generated/addon-api.d.ts

@@ -5746,6 +5746,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof privacyMaskCapability.methods.setMask.output>;
             meta: object;
         }>;
+        setAudioEnabled: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof privacyMaskCapability.methods.setAudioEnabled.input>;
+            output: z.infer<typeof privacyMaskCapability.methods.setAudioEnabled.output>;
+            meta: object;
+        }>;
     }>>;
     ptz: TRPCBuiltRouter<{
         ctx: TrpcContext;
@@ -5970,6 +5977,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof recordingCapability.methods.readSegmentBytes.output>;
             meta: object;
         }>;
+        readGopBytes: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof recordingCapability.methods.readGopBytes.input>;
+            output: z.infer<typeof recordingCapability.methods.readGopBytes.output>;
+            meta: object;
+        }>;
         setDeviceConfig: TRPCMutationProcedure<{
             input: {
                 [x: string]: unknown;
@@ -8834,6 +8848,15 @@ export type AppRouter = TrpcCoreRouter<{
         errorShape: AugmentedErrorShape;
         transformer: true;
     }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+        repairNodeAddons: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                nodeId: string;
+            };
+            output: {
+                success: boolean;
+            };
+            meta: object;
+        }>;
         forgetNode: import("@trpc/server").TRPCMutationProcedure<{
             input: {
                 nodeId: string;
@@ -8844,6 +8867,15 @@ export type AppRouter = TrpcCoreRouter<{
             meta: object;
         }>;
     }>> & import("@trpc/server").TRPCDecorateCreateRouterOptions<{
+        repairNodeAddons: import("@trpc/server").TRPCMutationProcedure<{
+            input: {
+                nodeId: string;
+            };
+            output: {
+                success: boolean;
+            };
+            meta: object;
+        }>;
         forgetNode: import("@trpc/server").TRPCMutationProcedure<{
             input: {
                 nodeId: string;

package/dist/generated/device-proxy.d.ts

@@ -276,7 +276,7 @@ export interface DeviceProxy {
     readonly pipelineOrchestrator: Pick<InferDeviceProxyCap<typeof pipelineOrchestratorCapability>, 'assignPipeline' | 'unassignPipeline' | 'setPipelineDevicePin' | 'getPipelineDevicePin' | 'getPipelineAssignment' | 'getCameraMetrics' | 'assignAudio' | 'unassignAudio' | 'getAudioAssignment' | 'getAudioAssignments' | 'getCameraSettings' | 'setCameraStepToggle' | 'getCameraStepOverrides' | 'setCameraStepOverride' | 'setCameraPipelineForAgent' | 'resolvePipeline' | 'getCameraSwitches' | 'setCameraSwitch' | 'getCameraStatus' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
     readonly pipelineRunner: Pick<InferDeviceProxyCap<typeof pipelineRunnerCapability>, 'detachCamera' | 'getCameraMetrics' | 'runDetailSubtree'>;
     readonly plateGallery: Pick<InferDeviceProxyCap<typeof plateGalleryCapability>, 'listPlates' | 'getPlateByTrack'>;
-    readonly recording: Pick<InferDeviceProxyCap<typeof recordingCapability>, 'getAvailability' | 'getDaysWithRecordings' | 'getPlaybackManifest' | 'getDeviceConfig' | 'locateSegment' | 'readSegmentBytes' | 'setDeviceConfig' | 'rescanStorage' | 'pruneFootage' | 'deleteFootprint' | 'renderGif' | 'renderClip' | 'getStatus' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
+    readonly recording: Pick<InferDeviceProxyCap<typeof recordingCapability>, 'getAvailability' | 'getDaysWithRecordings' | 'getPlaybackManifest' | 'getDeviceConfig' | 'locateSegment' | 'readSegmentBytes' | 'readGopBytes' | 'setDeviceConfig' | 'rescanStorage' | 'pruneFootage' | 'deleteFootprint' | 'renderGif' | 'renderClip' | 'getStatus' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
     readonly recordingExport: Pick<InferDeviceProxyCap<typeof recordingExportCapability>, 'createExport' | 'listExports'>;
     readonly streamBroker: Pick<InferDeviceProxyCap<typeof streamBrokerCapability>, 'publishCameraStream' | 'retractCameraStream' | 'assignProfile' | 'unassignProfile' | 'renderPreBufferClip' | 'restartProfile' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
 }

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 874 method paths across 120 capabilities.
+ * Coverage: 876 method paths across 120 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {

package/dist/index.d.ts

@@ -188,6 +188,7 @@ export type { CameraDetectionCapabilities, CameraMotionConfig, CameraNativeDetec
 export { DEVICE_TYPE_INFO, type DeviceTypeInfo } from './types/device-type.js';
 export * from './units/index.js';
 export { bestLocationMatch, locationSimilarity } from './util/location-match.js';
+export { bareAddonId, isSameAddonId } from './utils/addon-id.js';
 export { cosineSimilarity } from './utils/cosine-similarity.js';
 export { ElementConfigStore } from './utils/element-config-store.js';
 export { errMsg } from './utils/err-msg.js';
@@ -204,6 +205,7 @@ export { sleep, sleepCancellable } from './utils/sleep.js';
 export { decodeVectorBase64, encodeVectorBase64, vectorDimFromBase64, } from './utils/vector-codec.js';
 export { evaluateZoneRules, type ZoneRuleEvalResult } from './utils/zone-rule-eval.js';
 export { DEFAULT_DETAIL_CROP_CONVENTION, DETAIL_CROP_PADDING_FIELD, DETAIL_CROP_PADDING_KEY, DETAIL_CROP_SECTION_ID, DETAIL_CROP_SQUARE_KEY, type DetailCropConvention, DetailCropConventionSchema, type DetailCropRect, deriveDetailCropRect, type HydratedSettingsSection, type HydratedSettingsView, pickDetailCropConvention, readDetailCropConvention, } from './pipeline/detail-crop.js';
+export { DEFAULT_NATIVE_LEASE_SETTINGS, NATIVE_LEASE_ACTIVITY_FIELD, NATIVE_LEASE_ACTIVITY_KEY, NATIVE_LEASE_ADMISSION_FIELD, NATIVE_LEASE_ADMISSION_KEY, NATIVE_LEASE_BUDGET_FIELD, NATIVE_LEASE_BUDGET_KEY, NATIVE_LEASE_SECTION_ID, NATIVE_LEASE_TTL_FIELD, NATIVE_LEASE_TTL_KEY, type NativeLeaseAdmission, NativeLeaseAdmissionSchema, type NativeLeaseKnob, type NativeLeaseNumberKnob, type NativeLeaseSettings, NativeLeaseSettingsSchema, type NativeLeaseSettingsOverride, pickNativeLeaseOverride, readNativeLeaseOverride, } from './pipeline/native-lease.js';
 export { bindAddonActions } from './helpers/bind-addon-actions.js';
 export type { DeviceOption, InferenceDeviceDescriptor, RuntimeId, } from './inference/runtime-capabilities.js';
 export { defaultDeviceFor, enumerateInferenceDevices, modelFormatForRuntime, runtimeDevices, scoreRuntimes, supportedRuntimes, } from './inference/runtime-capabilities.js';