@camstack/addon-post-analysis 1.2.220 → 1.2.222

package/dist/{dist-DWXR9KNe.mjs → dist-CxPGPwcy.mjs}

@@ -5344,6 +5344,86 @@ var ZodIssueCode = {
 /** @deprecated Do not use. Stub definition, only included for zod-to-json-schema compatibility. */
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
+//#endregion
+//#region ../types/dist/sleep-BnujYGPe.mjs
+/**
+* The audio chunk plane's byte format, and the ONE expansion from a coded
+* window to float samples (D455).
+*
+* ## Why a format at all
+*
+* D450 took the plane off its 8 → 16 kHz upsample: it carries the SOURCE
+* RATE, and the one consumer that needs 16 kHz resamples next to the model.
+* It left the FORMAT alone — the broker still turned each G.711 byte into a
+* 4-byte f32le sample before the bytes entered the transport, so every leg of
+* the plane carried four times the source. The plane crosses hub-main twice on
+* the way to the analyzer, and the fleet's G.711 cameras are ~79 % of it.
+*
+* So the plane carries the source BYTES too, and whoever needs floats expands
+* them where it needs them. That is the same argument D450 made for the rate,
+* one step further along the same wire.
+*
+* ## Why the expansion lives here
+*
+* Two packages need it and they must never disagree: `addon-pipeline`'s broker
+* (which still has to serve a subscriber that did NOT ask for coded bytes —
+* `AudioChunkPlane` expands per subscription) and
+* `addon-pipeline-orchestrator`'s `AudioWindowAccumulator` (which flushes an
+* f32le window to the analyzer cap, whose `AudioChunkInput` contract is
+* unchanged and stays f32le). Both bundle the bare `@camstack/types` entry
+* into their own dist (`self-contained` externals), so this travels with a
+* `camstack deploy` and needs no published server.
+*
+* A second μ-law table anywhere else is the defect this module exists to
+* prevent. (`stream-broker.ts`'s `mulawToPcm` / `alawToPcm` are the ENCODE
+* direction for the WebRTC egress — a different transform, not a copy.)
+*
+* ## Absent means f32le
+*
+* `format` is optional on the wire and its absence means `f32le` — today's
+* bytes, byte for byte. A peer that never heard of the field is served what it
+* has always been served, because the broker only emits a coded window to a
+* subscription that DECLARED it accepts one (`AudioSubscribeOptions.accept`).
+* That is the D448 `rawForward` negotiation, and it is what makes this
+* deployable one addon at a time across three nodes.
+*/
+/** Every byte format the audio chunk plane can carry. `f32le` is the default. */
+var AUDIO_CHUNK_FORMATS = [
+	"f32le",
+	"pcmu",
+	"pcma"
+];
+/**
+* Build the μ-law decode table (ITU-T G.711). Each of the 256 byte values maps
+* to a 16-bit PCM sample, normalised to [-1.0, 1.0] for f32le output.
+*
+* Moved here verbatim from `audio-rtp-decoder.ts`, which no longer decodes:
+* it buffers the coded bytes and the plane's consumers expand.
+*/
+function buildUlawTable() {
+	const table = new Float32Array(256);
+	for (let i = 0; i < 256; i++) {
+		const complemented = ~i & 255;
+		const sign = (complemented & 128) !== 0 ? -1 : 1;
+		const exponent = complemented >> 4 & 7;
+		table[i] = sign * ((8 * (complemented & 15) + 132 << exponent) - 132) / 32768;
+	}
+	return table;
+}
+/** Build the A-law decode table (ITU-T G.711). */
+function buildAlawTable() {
+	const table = new Float32Array(256);
+	for (let i = 0; i < 256; i++) {
+		const xored = i ^ 85;
+		const sign = (xored & 128) !== 0 ? 1 : -1;
+		const exponent = xored >> 4 & 7;
+		const mantissa = xored & 15;
+		table[i] = sign * (exponent === 0 ? 16 * mantissa + 8 : 16 * mantissa + 264 << exponent - 1) / 32768;
+	}
+	return table;
+}
+buildUlawTable();
+buildAlawTable();
 Object.fromEntries([
 	{
 		id: "overview",
@@ -6636,11 +6716,20 @@ var SubscribeFramesResultSchema = object({
 * (the wire-serialisable supertype of `Buffer`) to match `DecodedFrameSchema`
 * / `EncodedPacketSchema`'s precedent; a `Buffer` is assignable to it.
 */
+var AudioChunkFormatSchema = _enum(AUDIO_CHUNK_FORMATS);
 var DecodedAudioChunkSchema = object({
 	data: _instanceof(Uint8Array),
 	sampleRate: number().int().positive(),
 	channels: number().int().positive(),
-	timestamp: number()
+	timestamp: number(),
+	/**
+	* Byte format of `data`. ABSENT MEANS `f32le` — today's bytes, byte for
+	* byte, for any peer that never heard of this field. A coded window
+	* (`pcmu` / `pcma`, one byte per sample) is only ever emitted to a
+	* subscription that DECLARED it accepts one, so absence can never mean
+	* "coded bytes a consumer will read as floats" (D455).
+	*/
+	format: AudioChunkFormatSchema.optional()
 });
 /**
 * Input for `stream-broker.subscribeAudioChunks` (Phase 5 / D9). The
@@ -6652,7 +6741,18 @@ var DecodedAudioChunkSchema = object({
 var SubscribeAudioChunksInputSchema = object({
 	brokerId: string(),
 	/** Short caller-identity tag (`audio-analyzer`, …) for `listClients`. */
-	tag: string().optional()
+	tag: string().optional(),
+	/**
+	* Byte formats this subscriber can READ, best first. The broker serves the
+	* chunk's own format when it is in this list and expands to `f32le`
+	* otherwise, so a subscriber is never handed bytes it cannot interpret.
+	*
+	* Absent (or without the source format) means `f32le` — the behaviour every
+	* subscriber had before D455, unchanged. This is the negotiation half of
+	* the source-bytes lever: it is what lets the broker and its consumers
+	* deploy one at a time across three nodes.
+	*/
+	accept: array(AudioChunkFormatSchema).readonly().optional()
 });
 /** Result of `stream-broker.subscribeAudioChunks`. */
 var SubscribeAudioChunksResultSchema = object({ 
@@ -11208,6 +11308,51 @@ var AudioAnalysisSettingsSchema = object({
 	minConfidence: number().min(0).max(1).default(.3),
 	allowedClasses: array(string()).default([])
 });
+/**
+* `attachDevice` — the analyzer PULLS a camera's audio from the broker (D461).
+*
+* Until D461 the orchestrator drained the broker's chunk plane, accumulated
+* ~1 s windows and pushed them back out as `analyseChunk`. It neither produced
+* nor consumed the audio: the PCM crossed hub-main twice for a process that
+* only buffered it. `attachDevice` inverts the direction — the analyzer opens
+* its own `subscribeAudioChunks` against the broker and the subscriber IS the
+* decoder, so the coded G.711 bytes D455 put on the plane stay coded all the
+* way to the one expansion that feeds the model.
+*
+* The orchestrator still owns the POLICY (the `audioMode` gate, the on-motion
+* window, the per-device node assignment, the settings read) and therefore
+* still owns the attach/detach pair. It no longer owns the bytes.
+*/
+var AudioAttachDeviceInputSchema = object({
+	deviceId: number(),
+	/** Broker id (`<deviceId>/<camStreamId>`) carrying this camera's audio. */
+	brokerId: string(),
+	/**
+	* `clusterRoles.ingestNode` — the node whose broker owns the source dial.
+	* Every `streamBroker` call the attachment makes is pinned to it, exactly as
+	* the orchestrator's poller pinned them before the move.
+	*/
+	ingestNodeId: string(),
+	/**
+	* Resolved once by the orchestrator at attach time, exactly as it was read
+	* once per subscription before D461. The analyzer does NOT re-resolve per
+	* window: a settings change re-attaches, which is what always happened.
+	*/
+	settings: AudioAnalysisSettingsSchema
+});
+var AudioAttachDeviceResultSchema = object({
+	/** False only when the analyzer is shutting down and refused to attach. */
+	attached: boolean(),
+	/**
+	* True when the attachment replaced a live one for the same device. An
+	* attach is idempotent by REPLACEMENT — two pollers on one camera would
+	* double the broker's fanout and neither would know about the other.
+	*/
+	replaced: boolean()
+});
+var AudioDetachDeviceResultSchema = object({ 
+/** False when no attachment existed — detach is idempotent. */
+detached: boolean() });
 var AudioClassificationResultSchema = object({
 	labels: array(AudioClassificationLabelSchema).readonly(),
 	rawLabels: array(AudioClassificationLabelSchema).readonly().optional(),
@@ -11216,7 +11361,7 @@ var AudioClassificationResultSchema = object({
 method(object({
 	chunk: AudioChunkInputSchema,
 	settings: AudioAnalysisSettingsSchema
-}), AudioAnalysisResultSchema.nullable(), { kind: "mutation" }), method(AudioChunkInputSchema, AudioClassificationResultSchema, { timeoutMs: 3e4 }), method(_void(), boolean()), method(_void(), _void(), { kind: "mutation" }), method(_void(), object({ backend: string() }), {
+}), AudioAnalysisResultSchema.nullable(), { kind: "mutation" }), method(AudioChunkInputSchema, AudioClassificationResultSchema, { timeoutMs: 3e4 }), method(AudioAttachDeviceInputSchema, AudioAttachDeviceResultSchema, { kind: "mutation" }), method(object({ deviceId: number() }), AudioDetachDeviceResultSchema, { kind: "mutation" }), method(_void(), boolean()), method(_void(), _void(), { kind: "mutation" }), method(_void(), object({ backend: string() }), {
 	kind: "mutation",
 	auth: "admin"
 });
@@ -22327,6 +22472,14 @@ var NativeCropResultSchema = object({
 	* set `encodeJpeg: true`; `bytes` is then absent.
 	*/
 	jpeg: string().optional(),
+	/**
+	* The SAME compressed JPEG as `jpeg`, as bytes (D462). Present instead of
+	* `jpeg` when the request set `acceptJpegBytes`; a request that did not gets
+	* `jpeg` exactly as before. MsgPack and the mesh leg both carry binary —
+	* `bytes` above has crossed this boundary as a `Uint8Array` all along — so
+	* base64 was buying nothing but a multi-megabyte string in the relay's heap.
+	*/
+	jpegBytes: _instanceof(Uint8Array).optional(),
 	width: number().int().positive(),
 	height: number().int().positive(),
 	/**
@@ -22393,7 +22546,14 @@ var ParkTrackFrameResultSchema = discriminatedUnion("parked", [object({
 })]);
 /** A retrieved parcel — the runner's own JPEG, base64 for the wire. */
 var ParkedTrackFrameSchema = object({
-	jpeg: string(),
+	/**
+	* Base64 JPEG — the pre-D462 wire. OPTIONAL since D462: a request that set
+	* `acceptJpegBytes` is answered in `jpegBytes` and this is then absent.
+	* Exactly one of the two is present.
+	*/
+	jpeg: string().optional(),
+	/** The same JPEG as bytes, for a caller that declared it reads them (D462). */
+	jpegBytes: _instanceof(Uint8Array).optional(),
 	width: number().int().positive(),
 	height: number().int().positive(),
 	/** The frame instant the parcel shows (the caller's clock, echoed back). */
@@ -22980,6 +23140,13 @@ method(RunnerCameraConfigSchema, object({ success: literal(true) }), { kind: "mu
 	bbox: NativeCropBboxSchema,
 	maxWidth: number().int().positive().optional(),
 	/**
+	* The caller reads a `Uint8Array` (D462). When set, a JPEG answer comes
+	* back in `jpegBytes` instead of base64 `jpeg`. Absent means the old
+	* wire — never assume consent: a pre-D462 caller parses the field as
+	* base64 and bytes would decode to garbage rather than fail.
+	*/
+	acceptJpegBytes: boolean().optional(),
+	/**
 	* When `true`, the runner encodes the resolved crop to JPEG ON THE
 	* OWNING NODE and returns it in `jpeg` (base64) INSTEAD of raw `bytes`.
 	* Callers set this for CROSS-NODE fetches (`handle.nodeId` is a remote
@@ -23047,7 +23214,14 @@ method(RunnerCameraConfigSchema, object({ success: literal(true) }), { kind: "mu
 }), ParkTrackFrameResultSchema, { kind: "mutation" }), method(object({
 	deviceId: number(),
 	trackId: string(),
-	kind: ParkedFrameKindSchema
+	kind: ParkedFrameKindSchema,
+	/**
+	* The caller reads a `Uint8Array` (D462). When set, a JPEG answer comes
+	* back in `jpegBytes` instead of base64 `jpeg`. Absent means the old
+	* wire — never assume consent: a pre-D462 caller parses the field as
+	* base64 and bytes would decode to garbage rather than fail.
+	*/
+	acceptJpegBytes: boolean().optional()
 }), ParkedTrackFrameSchema.nullable()), method(object({
 	deviceId: number(),
 	trackId: string()
@@ -36620,12 +36794,24 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"audioAnalyzer.attachDevice": {
+		capName: "audio-analyzer",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"audioAnalyzer.classify": {
 		capName: "audio-analyzer",
 		capScope: "system",
 		addonId: null,
 		access: "view"
 	},
+	"audioAnalyzer.detachDevice": {
+		capName: "audio-analyzer",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"audioAnalyzer.dispose": {
 		capName: "audio-analyzer",
 		capScope: "system",
@@ -42469,11 +42655,21 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"audioAnalyzer.attachDevice": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"audioAnalyzer.classify": [{
 		name: "deviceId",
 		form: "single",
 		optional: true
 	}],
+	"audioAnalyzer.detachDevice": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"audioMetrics.getCurrentSnapshot": [{
 		name: "deviceId",
 		form: "single",
@@ -44325,6 +44521,52 @@ Object.freeze({
 	"network-access": "ingress",
 	"smtp-provider": "email"
 });
+var G711_SCALE_CORRECTION_DB = {
+	PCMU: 20 * Math.log10(4),
+	PCMA: 20 * Math.log10(8)
+};
+/**
+* Restate a dBFS number that was MEASURED through the pre-epoch decoder as the
+* same intent on the ITU-T scale (D460).
+*
+* ## When this applies, and when it is the wrong thing to reach for
+*
+* An absolute-dBFS number in this repo is one of two things, and only one of
+* them converts:
+*
+*  - **A statement about the scale** — "-55 dBFS is near silence", "-25 dBFS
+*    is loud". It was true on the ITU-T scale before the epoch and it is true
+*    after. The defect was never in the number; it was that 19 of this hub's
+*    25 cameras did not obey it. Converting such a number takes something
+*    correct and makes it wrong, in order to preserve a bug.
+*  - **A measurement taken through the old decoder** — a value someone read
+*    off a meter that under-reported by exactly 4× (PCMU) or 8× (PCMA). It
+*    describes a sound that was really {@link G711_SCALE_CORRECTION_DB} dB
+*    louder. That is what this function is for.
+*
+* Telling the two apart is a question about PROVENANCE, not about arithmetic,
+* and it cannot be answered from the number. It is answered by the comment the
+* author left — which is why `scripts/check-dbfs-era.mts` makes leaving one
+* mandatory.
+*
+* ## Why a function and not a typed-in number
+*
+* `-55 + 12.04` written into a source file is, six months later, completely
+* indistinguishable from a threshold somebody simply preferred. Calling this
+* keeps the derivation, the law, and the original measurement all visible at
+* the call site, so a future reader can disagree with the *premise* instead of
+* having to reverse-engineer the sum.
+*
+* **This is not a runtime gain.** It converts an authored CONSTANT once, where
+* it is declared. It must never be applied to a live sample or a stored
+* `AudioEvent.dbfs`: the decoder is correct now, and a second authority
+* adjusting numbers the decoder already got right is the original defect with
+* an extra place to argue with (D459).
+*/
+function ituDbfsFromPreEpoch(law, authoredDbfs) {
+	return authoredDbfs + G711_SCALE_CORRECTION_DB[law];
+}
+Math.round(ituDbfsFromPreEpoch("PCMU", -55));
 /** Schema defaults — an untouched sub-field must author exactly these. */
 var NC_AUDIO_DEFAULTS = {
 	hitPercent: 60,