@camstack/types 1.2.225 → 1.2.227

package/dist/addon.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-VlZxDyXq.js");
+const require_sleep = require("./sleep-D7DPSeiv.js");
 const require_event_category = require("./event-category-BVfsrBYA.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 //#region src/generated/cap-input-defaults.ts

package/dist/addon.mjs

@@ -1,4 +1,4 @@
-import { A as DeviceType, Et as normalizeAddonInitResult, G as ReadinessRegistry, H as nodePin, I as expandCapMethods, K as ReadinessTimeoutError, S as DEVICE_CHILDREN_BATCH_MAX, St as DATAPLANE_SECRET_HEADER, T as describeCustomActions, Tt as BaseAddon, U as readNodePin, Y as scopeKey, a as asJsonObject, b as deviceOpsCapability, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, j as adminUiCapability, kt as emitReadiness, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, wt as DisposerChain, x as viewerUiCapability } from "./sleep-GU_us3DG.mjs";
+import { A as DeviceType, At as emitReadiness, Ct as DATAPLANE_SECRET_HEADER, Dt as normalizeAddonInitResult, Et as BaseAddon, G as ReadinessRegistry, H as nodePin, I as expandCapMethods, K as ReadinessTimeoutError, S as DEVICE_CHILDREN_BATCH_MAX, T as describeCustomActions, Tt as DisposerChain, U as readNodePin, Y as scopeKey, a as asJsonObject, b as deviceOpsCapability, d as BOOT_RECOVERY_BACKOFF_MS, f as DEVICE_SCOPED_CAPS, h as createEventBusSliceSource, j as adminUiCapability, m as createDeviceProxy, p as isDeviceScopedCap, s as asString, t as sleep, u as parseJsonUnknown, x as viewerUiCapability } from "./sleep-CiR4z7r9.mjs";
 import { t as EventCategory } from "./event-category-BVDXG4tB.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 //#region src/generated/cap-input-defaults.ts

package/dist/{canonical-hash-CvL03d3i.mjs → canonical-hash-CPK2Dy60.mjs}

@@ -100,16 +100,29 @@ function resolveStreamMaps(selection) {
 	};
 }
 /** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
-function buildVideoFilterArgs(scale, outputArgs, filterGraph) {
+function buildVideoFilterArgs(scale, outputArgs, filterGraph, hwUpload) {
 	if (filterGraph) {
 		if (scale) throw new Error("FfmpegInvocation: video.scale cannot be combined with a filter graph — scale inside the graph instead (the -vf would feed an output the graph already feeds)");
 		if (outputArgs.some((a) => a === "-vf")) throw new Error("FfmpegInvocation: outputArgs carries a -vf while a filter graph feeds the same output — fold the filter into the graph");
 		return [];
 	}
-	if (!scale) return [];
 	if (outputArgs.some((a) => a === "-vf")) return [];
-	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}`];
-	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2`];
+	if (!scale) return hwUpload.length > 0 ? ["-vf", hwUpload] : [];
+	const suffix = hwUpload.length > 0 ? `,${hwUpload}` : "";
+	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}${suffix}`];
+	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2${suffix}`];
+}
+/**
+* The upload filter a hardware encode needs, or `''`.
+*
+* Nothing is uploaded when the DECODE already left the frames on the GPU
+* (`-hwaccel vaapi`): they are surfaces already, and uploading a surface is an
+* error rather than a no-op.
+*/
+function resolveHwUpload(device, decodeHwAccel) {
+	if (device === void 0) return "";
+	if (!isSoftwareDecode(decodeHwAccel)) return "";
+	return "format=nv12,hwupload";
 }
 /** Rate-control args for an encode plan. */
 function buildRateControlArgs(video) {
@@ -129,7 +142,7 @@ function buildRateControlArgs(video) {
 	];
 }
 /** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
-function buildVideoArgs(video, outputArgs, filterGraph) {
+function buildVideoArgs(video, outputArgs, filterGraph, hwEncode) {
 	if (video.kind === "raw") {
 		if (filterGraph && video.filter !== void 0) throw new Error("FfmpegInvocation: video.filter cannot be combined with a filter graph — fold the filter into the graph");
 		return [
@@ -149,8 +162,10 @@ function buildVideoArgs(video, outputArgs, filterGraph) {
 			...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
 		];
 	}
+	const hwUpload = hwEncode === void 0 ? "" : resolveHwUpload(hwEncode.device, hwEncode.decodeHwAccel);
+	if (hwEncode !== void 0 && filterGraph) throw new Error("FfmpegInvocation: a hardware encode fed by a filter graph must upload INSIDE the graph — hwEncodeDevice cannot be combined with filterGraph");
 	const args = [
-		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph),
+		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph, hwUpload),
 		"-c:v",
 		video.encoder
 	];
@@ -320,10 +335,18 @@ function buildAudioSidecarArgs(sidecar) {
 * (`0:a:0?`): the sidecar is defined as the SOURCE's microphone on its own RTP
 * output, not as whatever the main output happens to carry.
 */
+/** The hardware-encode context for this invocation, or `undefined`. */
+function hwEncodeFor(inv) {
+	return inv.hwEncodeDevice === void 0 ? void 0 : {
+		device: inv.hwEncodeDevice,
+		decodeHwAccel: inv.decodeHwAccel
+	};
+}
 function buildFfmpegArgs(inv) {
 	const graph = inv.filterGraph ?? null;
 	const head = [
 		...logBannerArgs(inv.logLevel),
+		...inv.hwEncodeDevice !== void 0 ? ["-vaapi_device", inv.hwEncodeDevice.renderNode] : [],
 		...buildInputArgs(inv.input, inv.decodeHwAccel),
 		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
 		...graph ? ["-filter_complex", graph.graph] : []
@@ -337,7 +360,7 @@ function buildFfmpegArgs(inv) {
 			"-an",
 			"-map",
 			maps.video ?? "0:v:0",
-			...buildVideoArgs(inv.video, inv.outputArgs, graph),
+			...buildVideoArgs(inv.video, inv.outputArgs, graph, hwEncodeFor(inv)),
 			...threadArgs,
 			...inv.outputArgs,
 			...buildRtpOutputArgs(inv.sink.video)
@@ -360,7 +383,7 @@ function buildFfmpegArgs(inv) {
 	return [
 		...head,
 		...videoMapArgs,
-		...buildVideoArgs(inv.video, inv.outputArgs, graph),
+		...buildVideoArgs(inv.video, inv.outputArgs, graph, hwEncodeFor(inv)),
 		...threadArgs,
 		...mutedAudio ? [] : audioMapArgs,
 		...audioArgs,

package/dist/{canonical-hash-DYsYm8is.js → canonical-hash-CSE4ioRi.js}

@@ -100,16 +100,29 @@ function resolveStreamMaps(selection) {
 	};
 }
 /** The `-vf` filter args, or `[]` when a consumer `-vf` already claims the slot. */
-function buildVideoFilterArgs(scale, outputArgs, filterGraph) {
+function buildVideoFilterArgs(scale, outputArgs, filterGraph, hwUpload) {
 	if (filterGraph) {
 		if (scale) throw new Error("FfmpegInvocation: video.scale cannot be combined with a filter graph — scale inside the graph instead (the -vf would feed an output the graph already feeds)");
 		if (outputArgs.some((a) => a === "-vf")) throw new Error("FfmpegInvocation: outputArgs carries a -vf while a filter graph feeds the same output — fold the filter into the graph");
 		return [];
 	}
-	if (!scale) return [];
 	if (outputArgs.some((a) => a === "-vf")) return [];
-	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}`];
-	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2`];
+	if (!scale) return hwUpload.length > 0 ? ["-vf", hwUpload] : [];
+	const suffix = hwUpload.length > 0 ? `,${hwUpload}` : "";
+	if (scale.mode === "exact") return ["-vf", `scale=${scale.width}:${scale.height}${suffix}`];
+	return ["-vf", `scale='min(${scale.width},iw)':'min(${scale.height},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2${suffix}`];
+}
+/**
+* The upload filter a hardware encode needs, or `''`.
+*
+* Nothing is uploaded when the DECODE already left the frames on the GPU
+* (`-hwaccel vaapi`): they are surfaces already, and uploading a surface is an
+* error rather than a no-op.
+*/
+function resolveHwUpload(device, decodeHwAccel) {
+	if (device === void 0) return "";
+	if (!isSoftwareDecode(decodeHwAccel)) return "";
+	return "format=nv12,hwupload";
 }
 /** Rate-control args for an encode plan. */
 function buildRateControlArgs(video) {
@@ -129,7 +142,7 @@ function buildRateControlArgs(video) {
 	];
 }
 /** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
-function buildVideoArgs(video, outputArgs, filterGraph) {
+function buildVideoArgs(video, outputArgs, filterGraph, hwEncode) {
 	if (video.kind === "raw") {
 		if (filterGraph && video.filter !== void 0) throw new Error("FfmpegInvocation: video.filter cannot be combined with a filter graph — fold the filter into the graph");
 		return [
@@ -149,8 +162,10 @@ function buildVideoArgs(video, outputArgs, filterGraph) {
 			...video.bitstreamFilter ? ["-bsf:v", video.bitstreamFilter] : []
 		];
 	}
+	const hwUpload = hwEncode === void 0 ? "" : resolveHwUpload(hwEncode.device, hwEncode.decodeHwAccel);
+	if (hwEncode !== void 0 && filterGraph) throw new Error("FfmpegInvocation: a hardware encode fed by a filter graph must upload INSIDE the graph — hwEncodeDevice cannot be combined with filterGraph");
 	const args = [
-		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph),
+		...buildVideoFilterArgs(video.scale, outputArgs, filterGraph, hwUpload),
 		"-c:v",
 		video.encoder
 	];
@@ -320,10 +335,18 @@ function buildAudioSidecarArgs(sidecar) {
 * (`0:a:0?`): the sidecar is defined as the SOURCE's microphone on its own RTP
 * output, not as whatever the main output happens to carry.
 */
+/** The hardware-encode context for this invocation, or `undefined`. */
+function hwEncodeFor(inv) {
+	return inv.hwEncodeDevice === void 0 ? void 0 : {
+		device: inv.hwEncodeDevice,
+		decodeHwAccel: inv.decodeHwAccel
+	};
+}
 function buildFfmpegArgs(inv) {
 	const graph = inv.filterGraph ?? null;
 	const head = [
 		...logBannerArgs(inv.logLevel),
+		...inv.hwEncodeDevice !== void 0 ? ["-vaapi_device", inv.hwEncodeDevice.renderNode] : [],
 		...buildInputArgs(inv.input, inv.decodeHwAccel),
 		...(inv.extraInputs ?? []).flatMap((extra) => buildInputArgs(extra, inv.decodeHwAccel)),
 		...graph ? ["-filter_complex", graph.graph] : []
@@ -337,7 +360,7 @@ function buildFfmpegArgs(inv) {
 			"-an",
 			"-map",
 			maps.video ?? "0:v:0",
-			...buildVideoArgs(inv.video, inv.outputArgs, graph),
+			...buildVideoArgs(inv.video, inv.outputArgs, graph, hwEncodeFor(inv)),
 			...threadArgs,
 			...inv.outputArgs,
 			...buildRtpOutputArgs(inv.sink.video)
@@ -360,7 +383,7 @@ function buildFfmpegArgs(inv) {
 	return [
 		...head,
 		...videoMapArgs,
-		...buildVideoArgs(inv.video, inv.outputArgs, graph),
+		...buildVideoArgs(inv.video, inv.outputArgs, graph, hwEncodeFor(inv)),
 		...threadArgs,
 		...mutedAudio ? [] : audioMapArgs,
 		...audioArgs,

package/dist/capabilities/index.d.ts

@@ -92,8 +92,8 @@ export type { DetailParent, DetailResult, MotionSource, MotionSources, ParkedFra
 export { FrameLazyCountersSchema, FrameLazyMetricsSchema, MotionSourceEnum, type DetectionSources, DetectionSourcesSchema, MotionSourcesSchema, type NativeCropBbox, NativeCropBboxSchema, NativeCropResultSchema, OccupancyBurstRefusalSchema, ParkedFrameKindSchema, ParkedTrackFrameSchema, ParkRefusalSchema, ParkTrackFrameResultSchema, pipelineRunnerCapability, ReportMotionInputSchema, RunnerCameraConfigSchema, RunnerCameraDeviceUIFields, RunnerFrameSourceSchema, RunnerInferenceDeviceSchema, RunnerLocalLoadSchema, RunnerLocalMetricsSchema, } from './pipeline-runner.cap.js';
 export { AudioChunkInputSchema, AudioClassificationLabelSchema, AudioLevelSchema, BoundingBoxSchema, FrameInputSchema, SpatialDetectionSchema, } from './schemas/detection-shared.js';
 export { CameraMetricsSchema, CameraMetricsWithDeviceIdSchema, OrchestratorMetricsSchema, } from './schemas/orchestrator-metrics.js';
-export type { CameraStream, CamProfile, CamStreamKind, DecodedAudioChunkWire, FrameHandleFormat, ProfileRtspEntry, ProfileSlot, ProfileSlotStatus, SubscribeAudioChunksInput, SubscribeAudioChunksResult, SubscribeFramesInput, SubscribeFramesResult, } from './schemas/streaming-shared.js';
-export { AudioChunkFormatSchema, BrokerStatsSchema, BrokerStatusSchema, CAM_PROFILE_ORDER, CameraStreamSchema, CamProfileSchema, CamStreamKindSchema, CamStreamResolutionSchema, DecodedAudioChunkSchema, DecodedFrameSchema, EncodedPacketSchema, FrameHandleFormatSchema, FrameHandleSchema, makeProfileBrokerId, makeSourceBrokerId, ProfileRtspEntrySchema, ProfileSlotSchema, ProfileSlotStatusSchema, parseProfileBrokerId, StreamSourceEntrySchema, StreamSourceSchema, SubscribeAudioChunksInputSchema, SubscribeAudioChunksResultSchema, SubscribeFramesInputSchema, SubscribeFramesResultSchema, selectAssignedProfileSlots, } from './schemas/streaming-shared.js';
+export type { CameraStream, CamProfile, CamStreamKind, DecodedAudioChunkWire, FrameHandleFormat, ProfileRtspEntry, ProfileSlot, AudioStreamPick, ProfileSlotStatus, SubscribeAudioChunksInput, SubscribeAudioChunksResult, SubscribeFramesInput, SubscribeFramesResult, } from './schemas/streaming-shared.js';
+export { AudioChunkFormatSchema, AudioStreamPickSchema, BrokerStatsSchema, BrokerStatusSchema, CAM_PROFILE_ORDER, CameraStreamSchema, CamProfileSchema, CamStreamKindSchema, CamStreamResolutionSchema, DecodedAudioChunkSchema, DecodedFrameSchema, EncodedPacketSchema, FrameHandleFormatSchema, FrameHandleSchema, makeProfileBrokerId, makeSourceBrokerId, ProfileRtspEntrySchema, ProfileSlotSchema, ProfileSlotStatusSchema, parseProfileBrokerId, StreamSourceEntrySchema, StreamSourceSchema, SubscribeAudioChunksInputSchema, SubscribeAudioChunksResultSchema, SubscribeFramesInputSchema, SubscribeFramesResultSchema, selectAssignedProfileSlots, } from './schemas/streaming-shared.js';
 export { buildEventKindDescriptor, EVENT_KIND_BY_CAP, EVENTFUL_CAP_NAMES, type SensorEventKindDescriptor, } from './sensor-event-kinds.js';
 export { type ImageContract, ImageContractSchema, type ImageContractState, ImageContractStateSchema, type IServerManagementProvider, type ServerBootMode, ServerBootModeSchema, type ServerPackageStatus, ServerPackageStatusSchema, type ServerRollbackInfo, ServerRollbackInfoSchema, type ServerUpdateActionResult, ServerUpdateActionResultSchema, type ServerUpdateCheckResult, ServerUpdateCheckResultSchema, type ServerUpdateState, ServerUpdateStateSchema, serverManagementCapability, type WrapperEvidence, WrapperEvidenceSchema, type WrapperIdentity, WrapperIdentitySchema, type WrapperKind, WrapperKindSchema, } from './server-management.cap.js';
 export { type BulkRecord, BulkRecordSchema, type CollectionColumn, CollectionColumnSchema, type CollectionIndex, CollectionIndexSchema, type ISettingsStoreProvider, type MutationFilter, MutationFilterSchema, QueryFilterSchema, SettingsRecordSchema, type SettingsStoreClient, settingsStoreCapability, } from './settings-store.cap.js';
@@ -120,7 +120,7 @@ export type { Clip, ClipPlayback, IVideoclipsProvider } from './videoclips.cap.j
 export { ClipPlaybackSchema, ClipSchema, MAX_CLIP_EVENT_IDS, MAX_CLIP_LABELS, videoclipsCapability, } from './videoclips.cap.js';
 export type { IViewerUiProvider } from './viewer-ui.cap.js';
 export { viewerUiCapability } from './viewer-ui.cap.js';
-export { type IWebrtcSessionProvider, type WebrtcClientHints, type WebrtcStreamChoice, WebrtcStreamChoiceSchema, type WebrtcStreamTarget, WebrtcStreamTargetSchema, webrtcClientHintsSchema, webrtcSessionCapability, } from './webrtc-session.cap.js';
+export { type IWebrtcSessionProvider, type WebrtcClientHints, type WebrtcLadderDecision, WebrtcLadderDecisionSchema, type WebrtcSessionDebug, WebrtcSessionDebugSchema, type WebrtcStreamChoice, WebrtcStreamChoiceSchema, type WebrtcStreamTarget, WebrtcStreamTargetSchema, type WebrtcTierFailure, WebrtcTierFailureSchema, webrtcClientHintsSchema, webrtcSessionCapability, } from './webrtc-session.cap.js';
 export { type AccessoriesStatus, AccessoriesStatusSchema, accessoriesCapability, type IAccessoriesProvider, } from './accessories.cap.js';
 export { AddonAutoUpdateSchema, AddonListItemSchema, AutoUpdateSettingsSchema, addonsCapability, type BulkUpdateItem, type BulkUpdateItemStatus, type BulkUpdatePhase, type BulkUpdateState, CustomActionInputSchema, type IAddonsProvider, InstalledPackageSchema, LogStreamEntrySchema, PackageUpdateSchema, PackageVersionInfoSchema, SearchResultSchema, } from './addons.cap.js';
 export { type AirQualitySensorStatus, AirQualitySensorStatusSchema, airQualitySensorCapability, type IAirQualitySensorProvider, } from './air-quality-sensor.cap.js';

package/dist/capabilities/pipeline-analytics.cap.d.ts

@@ -726,6 +726,7 @@ declare const MediaFileKindEnum: z.ZodEnum<{
     keyFrameSmall: "keyFrameSmall";
     thumbnailSmall: "thumbnailSmall";
     confirmationCrop: "confirmationCrop";
+    debugCrop: "debugCrop";
     sceneFrame: "sceneFrame";
 }>;
 export type MediaFileKind = z.infer<typeof MediaFileKindEnum>;
@@ -754,6 +755,7 @@ declare const MediaFileRefSchema: z.ZodObject<{
         keyFrameSmall: "keyFrameSmall";
         thumbnailSmall: "thumbnailSmall";
         confirmationCrop: "confirmationCrop";
+        debugCrop: "debugCrop";
         sceneFrame: "sceneFrame";
     }>;
     sizeBytes: z.ZodNumber;
@@ -829,6 +831,7 @@ declare const MediaFileSchema: z.ZodObject<{
         keyFrameSmall: "keyFrameSmall";
         thumbnailSmall: "thumbnailSmall";
         confirmationCrop: "confirmationCrop";
+        debugCrop: "debugCrop";
         sceneFrame: "sceneFrame";
     }>;
     sizeBytes: z.ZodNumber;
@@ -867,6 +870,7 @@ declare const MediaFileInfoSchema: z.ZodObject<{
         keyFrameSmall: "keyFrameSmall";
         thumbnailSmall: "thumbnailSmall";
         confirmationCrop: "confirmationCrop";
+        debugCrop: "debugCrop";
         sceneFrame: "sceneFrame";
     }>;
     url: z.ZodString;
@@ -1008,6 +1012,7 @@ export declare const RetrainFrameCandidateSchema: z.ZodObject<{
         keyFrameSmall: "keyFrameSmall";
         thumbnailSmall: "thumbnailSmall";
         confirmationCrop: "confirmationCrop";
+        debugCrop: "debugCrop";
         sceneFrame: "sceneFrame";
     }>;
     timestamp: z.ZodNumber;
@@ -1035,6 +1040,7 @@ export declare const RetrainFrameSchema: z.ZodObject<{
         keyFrameSmall: "keyFrameSmall";
         thumbnailSmall: "thumbnailSmall";
         confirmationCrop: "confirmationCrop";
+        debugCrop: "debugCrop";
         sceneFrame: "sceneFrame";
     }>;
     sizeBytes: z.ZodNumber;
@@ -1069,6 +1075,7 @@ export declare const RetrainFrameSelectionSchema: z.ZodObject<{
             keyFrameSmall: "keyFrameSmall";
             thumbnailSmall: "thumbnailSmall";
             confirmationCrop: "confirmationCrop";
+            debugCrop: "debugCrop";
             sceneFrame: "sceneFrame";
         }>;
         sizeBytes: z.ZodNumber;
@@ -1103,6 +1110,7 @@ export declare const RetrainFrameListSchema: z.ZodObject<{
             keyFrameSmall: "keyFrameSmall";
             thumbnailSmall: "thumbnailSmall";
             confirmationCrop: "confirmationCrop";
+            debugCrop: "debugCrop";
             sceneFrame: "sceneFrame";
         }>;
         timestamp: z.ZodNumber;
@@ -1128,6 +1136,7 @@ export declare const RetrainFrameListSchema: z.ZodObject<{
             keyFrameSmall: "keyFrameSmall";
             thumbnailSmall: "thumbnailSmall";
             confirmationCrop: "confirmationCrop";
+            debugCrop: "debugCrop";
             sceneFrame: "sceneFrame";
         }>;
         sizeBytes: z.ZodNumber;
@@ -1730,6 +1739,7 @@ declare const EventMediaKindFootprintSchema: z.ZodObject<{
         keyFrameSmall: "keyFrameSmall";
         thumbnailSmall: "thumbnailSmall";
         confirmationCrop: "confirmationCrop";
+        debugCrop: "debugCrop";
         sceneFrame: "sceneFrame";
     }>;
     rows: z.ZodNumber;
@@ -1778,6 +1788,7 @@ declare const EventMediaKindBreakdownSchema: z.ZodObject<{
             keyFrameSmall: "keyFrameSmall";
             thumbnailSmall: "thumbnailSmall";
             confirmationCrop: "confirmationCrop";
+            debugCrop: "debugCrop";
             sceneFrame: "sceneFrame";
         }>;
         rows: z.ZodNumber;
@@ -3207,6 +3218,7 @@ export declare const pipelineAnalyticsCapability: {
                     keyFrameSmall: "keyFrameSmall";
                     thumbnailSmall: "thumbnailSmall";
                     confirmationCrop: "confirmationCrop";
+                    debugCrop: "debugCrop";
                     sceneFrame: "sceneFrame";
                 }>;
                 rows: z.ZodNumber;
@@ -3600,6 +3612,7 @@ export declare const pipelineAnalyticsCapability: {
                     keyFrameSmall: "keyFrameSmall";
                     thumbnailSmall: "thumbnailSmall";
                     confirmationCrop: "confirmationCrop";
+                    debugCrop: "debugCrop";
                     sceneFrame: "sceneFrame";
                 }>;
                 timestamp: z.ZodNumber;
@@ -3625,6 +3638,7 @@ export declare const pipelineAnalyticsCapability: {
                     keyFrameSmall: "keyFrameSmall";
                     thumbnailSmall: "thumbnailSmall";
                     confirmationCrop: "confirmationCrop";
+                    debugCrop: "debugCrop";
                     sceneFrame: "sceneFrame";
                 }>;
                 sizeBytes: z.ZodNumber;
@@ -3672,6 +3686,7 @@ export declare const pipelineAnalyticsCapability: {
                     keyFrameSmall: "keyFrameSmall";
                     thumbnailSmall: "thumbnailSmall";
                     confirmationCrop: "confirmationCrop";
+                    debugCrop: "debugCrop";
                     sceneFrame: "sceneFrame";
                 }>;
                 sizeBytes: z.ZodNumber;
@@ -4083,6 +4098,7 @@ export declare const pipelineAnalyticsCapability: {
                 keyFrameSmall: "keyFrameSmall";
                 thumbnailSmall: "thumbnailSmall";
                 confirmationCrop: "confirmationCrop";
+                debugCrop: "debugCrop";
                 sceneFrame: "sceneFrame";
             }>>;
             deviceId: z.ZodNumber;
@@ -4102,6 +4118,7 @@ export declare const pipelineAnalyticsCapability: {
                 keyFrameSmall: "keyFrameSmall";
                 thumbnailSmall: "thumbnailSmall";
                 confirmationCrop: "confirmationCrop";
+                debugCrop: "debugCrop";
                 sceneFrame: "sceneFrame";
             }>;
             sizeBytes: z.ZodNumber;
@@ -4129,6 +4146,7 @@ export declare const pipelineAnalyticsCapability: {
                 keyFrameSmall: "keyFrameSmall";
                 thumbnailSmall: "thumbnailSmall";
                 confirmationCrop: "confirmationCrop";
+                debugCrop: "debugCrop";
                 sceneFrame: "sceneFrame";
             }>>>;
             deviceId: z.ZodNumber;
@@ -4148,6 +4166,7 @@ export declare const pipelineAnalyticsCapability: {
                 keyFrameSmall: "keyFrameSmall";
                 thumbnailSmall: "thumbnailSmall";
                 confirmationCrop: "confirmationCrop";
+                debugCrop: "debugCrop";
                 sceneFrame: "sceneFrame";
             }>;
             sizeBytes: z.ZodNumber;
@@ -4189,6 +4208,7 @@ export declare const pipelineAnalyticsCapability: {
                 keyFrameSmall: "keyFrameSmall";
                 thumbnailSmall: "thumbnailSmall";
                 confirmationCrop: "confirmationCrop";
+                debugCrop: "debugCrop";
                 sceneFrame: "sceneFrame";
             }>;
             url: z.ZodString;
@@ -4237,6 +4257,7 @@ export declare const pipelineAnalyticsCapability: {
                 keyFrameSmall: "keyFrameSmall";
                 thumbnailSmall: "thumbnailSmall";
                 confirmationCrop: "confirmationCrop";
+                debugCrop: "debugCrop";
                 sceneFrame: "sceneFrame";
             }>;
             url: z.ZodString;

package/dist/capabilities/pipeline-runner.cap.d.ts

@@ -332,6 +332,11 @@ declare const RunnerCameraConfigSchema: z.ZodObject<{
     detectionFps: z.ZodDefault<z.ZodNumber>;
     motionStreamId: z.ZodString;
     detectionStreamId: z.ZodString;
+    audioStreamPick: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        high: "high";
+        mid: "mid";
+        low: "low";
+    }>, z.ZodLiteral<"auto">]>>;
     motionSources: z.ZodDefault<z.ZodArray<z.ZodEnum<{
         onboard: "onboard";
         analyzer: "analyzer";
@@ -611,6 +616,11 @@ export declare const pipelineRunnerCapability: {
             detectionFps: z.ZodDefault<z.ZodNumber>;
             motionStreamId: z.ZodString;
             detectionStreamId: z.ZodString;
+            audioStreamPick: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+                high: "high";
+                mid: "mid";
+                low: "low";
+            }>, z.ZodLiteral<"auto">]>>;
             motionSources: z.ZodDefault<z.ZodArray<z.ZodEnum<{
                 onboard: "onboard";
                 analyzer: "analyzer";

package/dist/capabilities/schemas/streaming-shared.d.ts

@@ -8,6 +8,22 @@ export declare const CamProfileSchema: z.ZodEnum<{
 export type CamProfile = z.infer<typeof CamProfileSchema>;
 /** Canonical ordering. Hard-coded; never sorted. */
 export declare const CAM_PROFILE_ORDER: readonly ["high", "mid", "low"];
+/**
+ * Which rung a per-camera consumer listens on: an explicit profile, or `auto`.
+ *
+ * `auto` is a REAL value, not an absent one — it means "resolve it by the rule
+ * that consumer owns". It lives beside `CamProfile` because a rung is the only
+ * operator-facing way to name a stream: a cam-stream id is broker-internal and
+ * moves when a slot is reassigned, so a stored id silently stops meaning what
+ * the operator picked. Today's one user is the audio analyser, whose rule is
+ * "the lowest AVAILABLE native rung" (D537).
+ */
+export declare const AudioStreamPickSchema: z.ZodUnion<readonly [z.ZodEnum<{
+    high: "high";
+    mid: "mid";
+    low: "low";
+}>, z.ZodLiteral<"auto">]>;
+export type AudioStreamPick = z.infer<typeof AudioStreamPickSchema>;
 export declare const CamStreamKindSchema: z.ZodEnum<{
     "pull-rtsp": "pull-rtsp";
     "pull-rtmp": "pull-rtmp";

package/dist/capabilities/webrtc-session.cap.d.ts

@@ -77,6 +77,112 @@ export declare const WebrtcStreamChoiceSchema: z.ZodObject<{
     bitrateKbps: z.ZodNullable<z.ZodNumber>;
 }, z.core.$strip>;
 export type WebrtcStreamChoice = z.infer<typeof WebrtcStreamChoiceSchema>;
+/**
+ * The last move the adaptive ladder made on this session, and the numbers it
+ * rested on. Mirrors `LadderDecision` in the stream-broker's
+ * `adaptive-controller.ts` — the log line's evidence, made readable.
+ *
+ * Nullability is load-bearing: `lossRatio: null` means the loss tracker had
+ * no window to report, which is NOT a link with zero loss.
+ */
+export declare const WebrtcLadderDecisionSchema: z.ZodObject<{
+    cause: z.ZodEnum<{
+        healthy: "healthy";
+        loss: "loss";
+        stall: "stall";
+    }>;
+    tier: z.ZodNullable<z.ZodEnum<{
+        high: "high";
+        mid: "mid";
+        low: "low";
+    }>>;
+    forcedTranscodeDown: z.ZodBoolean;
+    lossRatio: z.ZodNullable<z.ZodNumber>;
+    clientKbps: z.ZodNullable<z.ZodNumber>;
+    stalledForMs: z.ZodNullable<z.ZodNumber>;
+    serverSending: z.ZodNullable<z.ZodBoolean>;
+    at: z.ZodNumber;
+}, z.core.$strip>;
+export type WebrtcLadderDecision = z.infer<typeof WebrtcLadderDecisionSchema>;
+/** Per-tier count of MEASURED downgrades this viewer session has suffered. */
+export declare const WebrtcTierFailureSchema: z.ZodObject<{
+    tier: z.ZodEnum<{
+        high: "high";
+        mid: "mid";
+        low: "low";
+    }>;
+    failures: z.ZodNumber;
+}, z.core.$strip>;
+export type WebrtcTierFailure = z.infer<typeof WebrtcTierFailureSchema>;
+/**
+ * What the SERVER decided for one WebRTC session — the half the client cannot
+ * measure. See `getSessionDebug`.
+ */
+export declare const WebrtcSessionDebugSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    alive: z.ZodBoolean;
+    observedAt: z.ZodNumber;
+    brokerId: z.ZodNullable<z.ZodString>;
+    camStreamId: z.ZodNullable<z.ZodString>;
+    sourceKind: z.ZodEnum<{
+        unknown: "unknown";
+        derived: "derived";
+        native: "native";
+    }>;
+    adaptive: z.ZodBoolean;
+    servedTier: z.ZodNullable<z.ZodEnum<{
+        high: "high";
+        mid: "mid";
+        low: "low";
+    }>>;
+    ingestNodeId: z.ZodNullable<z.ZodString>;
+    ingestIsRemote: z.ZodNullable<z.ZodBoolean>;
+    sourceCodec: z.ZodNullable<z.ZodString>;
+    negotiatedCodec: z.ZodNullable<z.ZodString>;
+    egressLeg: z.ZodEnum<{
+        unknown: "unknown";
+        copy: "copy";
+        transcode: "transcode";
+    }>;
+    brokerStatus: z.ZodNullable<z.ZodString>;
+    brokerCodec: z.ZodNullable<z.ZodString>;
+    brokerBitrateKbps: z.ZodNullable<z.ZodNumber>;
+    brokerInputFps: z.ZodNullable<z.ZodNumber>;
+    brokerUptimeMs: z.ZodNullable<z.ZodNumber>;
+    rtpPacketsSent: z.ZodNullable<z.ZodNumber>;
+    trackMode: z.ZodNullable<z.ZodEnum<{
+        live: "live";
+        recorded: "recorded";
+    }>>;
+    lastDecision: z.ZodNullable<z.ZodObject<{
+        cause: z.ZodEnum<{
+            healthy: "healthy";
+            loss: "loss";
+            stall: "stall";
+        }>;
+        tier: z.ZodNullable<z.ZodEnum<{
+            high: "high";
+            mid: "mid";
+            low: "low";
+        }>>;
+        forcedTranscodeDown: z.ZodBoolean;
+        lossRatio: z.ZodNullable<z.ZodNumber>;
+        clientKbps: z.ZodNullable<z.ZodNumber>;
+        stalledForMs: z.ZodNullable<z.ZodNumber>;
+        serverSending: z.ZodNullable<z.ZodBoolean>;
+        at: z.ZodNumber;
+    }, z.core.$strip>>;
+    tierFailures: z.ZodArray<z.ZodObject<{
+        tier: z.ZodEnum<{
+            high: "high";
+            mid: "mid";
+            low: "low";
+        }>;
+        failures: z.ZodNumber;
+    }, z.core.$strip>>;
+    upgradeCount: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type WebrtcSessionDebug = z.infer<typeof WebrtcSessionDebugSchema>;
 /**
  * WebRTC session — device-scoped facade over the system `webrtc` cap.
  *
@@ -361,6 +467,89 @@ export declare const webrtcSessionCapability: {
             }, z.core.$strip>>;
             alive: z.ZodBoolean;
         }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * The SERVER's half of the stream-debug overlay, for one live session.
+         *
+         * The client can measure its own transport (`getStats()`); it cannot see
+         * which rung `auto` actually resolved to, why the ladder last moved, or
+         * whether the rung it is being served is the camera's own encode or
+         * something this hub built. That asymmetry is why "quality is stuck on
+         * low" reports have historically been unanswerable from the viewer alone.
+         *
+         * EVERY measurement here is nullable and `null` means UNKNOWN, never zero
+         * (D393): a session whose ladder has never moved reports
+         * `lastDecision: null`, which is a different fact from a ladder that moved
+         * for `healthy` with a 0 loss ratio.
+         *
+         * Read-only, ~1 Hz, polled by the overlay only while it is visible.
+         */
+        readonly getSessionDebug: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            sessionId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            sessionId: z.ZodString;
+            alive: z.ZodBoolean;
+            observedAt: z.ZodNumber;
+            brokerId: z.ZodNullable<z.ZodString>;
+            camStreamId: z.ZodNullable<z.ZodString>;
+            sourceKind: z.ZodEnum<{
+                unknown: "unknown";
+                derived: "derived";
+                native: "native";
+            }>;
+            adaptive: z.ZodBoolean;
+            servedTier: z.ZodNullable<z.ZodEnum<{
+                high: "high";
+                mid: "mid";
+                low: "low";
+            }>>;
+            ingestNodeId: z.ZodNullable<z.ZodString>;
+            ingestIsRemote: z.ZodNullable<z.ZodBoolean>;
+            sourceCodec: z.ZodNullable<z.ZodString>;
+            negotiatedCodec: z.ZodNullable<z.ZodString>;
+            egressLeg: z.ZodEnum<{
+                unknown: "unknown";
+                copy: "copy";
+                transcode: "transcode";
+            }>;
+            brokerStatus: z.ZodNullable<z.ZodString>;
+            brokerCodec: z.ZodNullable<z.ZodString>;
+            brokerBitrateKbps: z.ZodNullable<z.ZodNumber>;
+            brokerInputFps: z.ZodNullable<z.ZodNumber>;
+            brokerUptimeMs: z.ZodNullable<z.ZodNumber>;
+            rtpPacketsSent: z.ZodNullable<z.ZodNumber>;
+            trackMode: z.ZodNullable<z.ZodEnum<{
+                live: "live";
+                recorded: "recorded";
+            }>>;
+            lastDecision: z.ZodNullable<z.ZodObject<{
+                cause: z.ZodEnum<{
+                    healthy: "healthy";
+                    loss: "loss";
+                    stall: "stall";
+                }>;
+                tier: z.ZodNullable<z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>>;
+                forcedTranscodeDown: z.ZodBoolean;
+                lossRatio: z.ZodNullable<z.ZodNumber>;
+                clientKbps: z.ZodNullable<z.ZodNumber>;
+                stalledForMs: z.ZodNullable<z.ZodNumber>;
+                serverSending: z.ZodNullable<z.ZodBoolean>;
+                at: z.ZodNumber;
+            }, z.core.$strip>>;
+            tierFailures: z.ZodArray<z.ZodObject<{
+                tier: z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>;
+                failures: z.ZodNumber;
+            }, z.core.$strip>>;
+            upgradeCount: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strip>, "query">;
     };
     /** BIG PLAN 2: declarative mount hint — read by `@camstack/system` `buildCapRouters`. */
     readonly mount: {