@camstack/types 1.2.41 → 1.2.43

package/dist/capabilities/stream-broker.cap.d.ts

@@ -279,6 +279,181 @@ export declare const RtpSourceSchema: z.ZodObject<{
     pipelineKey: z.ZodString;
 }, z.core.$strip>;
 export type RtpSource = z.infer<typeof RtpSourceSchema>;
+/**
+ * The encode request — **structured and serialisable, with NO raw-flag escape
+ * hatch.** This is deliberate and it is the one lesson taken from
+ * `getStreamWithCodec`: that method's `outputArgs: string[]` is simultaneously
+ * its extensibility mechanism AND part of `pipelineKeyFor`'s sharing key, so
+ * adding a flag silently forks the shared child, and two consumers that mean
+ * the same thing but spell it differently never share. Here every knob is a
+ * NAMED field: a new requirement becomes a schema field (and a codegen run),
+ * never an opaque array.
+ *
+ * `inputArgs` / `outputArgs` are omitted from the profile for the same reason.
+ * The operator-facing derived-stream transform editor still has them — that is
+ * a different surface (`publishCameraStream({ kind: 'derived' })`) with a
+ * different purpose (reshaping a badly-behaved SOURCE), and it is unchanged.
+ */
+export declare const EgressEncodeSchema: z.ZodObject<{
+    audio: z.ZodUnion<readonly [z.ZodLiteral<"passthrough">, z.ZodObject<{
+        codec: z.ZodEnum<{
+            copy: "copy";
+            opus: "opus";
+            aac: "aac";
+            pcmu: "pcmu";
+            pcma: "pcma";
+        }>;
+        bitrateKbps: z.ZodOptional<z.ZodNumber>;
+        sampleRateHz: z.ZodOptional<z.ZodNumber>;
+        channels: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+    }, z.core.$strip>]>;
+    video: z.ZodObject<{
+        codec: z.ZodEnum<{
+            h264: "h264";
+            h265: "h265";
+            copy: "copy";
+        }>;
+        profile: z.ZodOptional<z.ZodEnum<{
+            high: "high";
+            baseline: "baseline";
+            main: "main";
+        }>>;
+        level: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        fps: z.ZodOptional<z.ZodNumber>;
+        bitrateKbps: z.ZodOptional<z.ZodNumber>;
+        gopFrames: z.ZodOptional<z.ZodNumber>;
+        bf: z.ZodOptional<z.ZodNumber>;
+        preset: z.ZodOptional<z.ZodEnum<{
+            fast: "fast";
+            ultrafast: "ultrafast";
+            superfast: "superfast";
+            veryfast: "veryfast";
+            faster: "faster";
+            medium: "medium";
+        }>>;
+        tune: z.ZodOptional<z.ZodEnum<{
+            zerolatency: "zerolatency";
+            film: "film";
+            animation: "animation";
+        }>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type EgressEncode = z.infer<typeof EgressEncodeSchema>;
+/**
+ * How the encoder is bounded. `'tight'` is a one-second VBV window for a
+ * consumer whose budget is enforced per second (HomeKit); `'relaxed'` is two
+ * seconds, letting a keyframe spike borrow from the next second (a browser,
+ * an Echo). Named rather than numeric so the INTENT survives.
+ */
+export declare const EgressRateControlSchema: z.ZodEnum<{
+    tight: "tight";
+    relaxed: "relaxed";
+}>;
+export type EgressRateControl = z.infer<typeof EgressRateControlSchema>;
+export declare const EgressTranscodeRequestSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"profile">;
+        profile: z.ZodEnum<{
+            high: "high";
+            mid: "mid";
+            low: "low";
+        }>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"cam-stream">;
+        camStreamId: z.ZodString;
+    }, z.core.$strip>], "kind">;
+    encode: z.ZodObject<{
+        audio: z.ZodUnion<readonly [z.ZodLiteral<"passthrough">, z.ZodObject<{
+            codec: z.ZodEnum<{
+                copy: "copy";
+                opus: "opus";
+                aac: "aac";
+                pcmu: "pcmu";
+                pcma: "pcma";
+            }>;
+            bitrateKbps: z.ZodOptional<z.ZodNumber>;
+            sampleRateHz: z.ZodOptional<z.ZodNumber>;
+            channels: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+        }, z.core.$strip>]>;
+        video: z.ZodObject<{
+            codec: z.ZodEnum<{
+                h264: "h264";
+                h265: "h265";
+                copy: "copy";
+            }>;
+            profile: z.ZodOptional<z.ZodEnum<{
+                high: "high";
+                baseline: "baseline";
+                main: "main";
+            }>>;
+            level: z.ZodOptional<z.ZodString>;
+            width: z.ZodOptional<z.ZodNumber>;
+            height: z.ZodOptional<z.ZodNumber>;
+            fps: z.ZodOptional<z.ZodNumber>;
+            bitrateKbps: z.ZodOptional<z.ZodNumber>;
+            gopFrames: z.ZodOptional<z.ZodNumber>;
+            bf: z.ZodOptional<z.ZodNumber>;
+            preset: z.ZodOptional<z.ZodEnum<{
+                fast: "fast";
+                ultrafast: "ultrafast";
+                superfast: "superfast";
+                veryfast: "veryfast";
+                faster: "faster";
+                medium: "medium";
+            }>>;
+            tune: z.ZodOptional<z.ZodEnum<{
+                zerolatency: "zerolatency";
+                film: "film";
+                animation: "animation";
+            }>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    rateControl: z.ZodOptional<z.ZodEnum<{
+        tight: "tight";
+        relaxed: "relaxed";
+    }>>;
+    bitstreamFilter: z.ZodOptional<z.ZodEnum<{
+        dump_extra: "dump_extra";
+        h264_mp4toannexb: "h264_mp4toannexb";
+        hevc_mp4toannexb: "hevc_mp4toannexb";
+    }>>;
+    publishLocally: z.ZodOptional<z.ZodBoolean>;
+    pixelFormat: z.ZodOptional<z.ZodEnum<{
+        yuv420p: "yuv420p";
+        nv12: "nv12";
+    }>>;
+    decodeHwAccel: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        auto: "auto";
+        videotoolbox: "videotoolbox";
+        vaapi: "vaapi";
+        qsv: "qsv";
+        cuda: "cuda";
+    }>>;
+    hostname: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EgressTranscodeRequest = z.infer<typeof EgressTranscodeRequestSchema>;
+export declare const EgressTranscodeSchema: z.ZodObject<{
+    url: z.ZodString;
+    pipelineKey: z.ZodString;
+    videoCodec: z.ZodEnum<{
+        H264: "H264";
+        H265: "H265";
+    }>;
+    resolution: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>;
+    transcoded: z.ZodBoolean;
+    encoder: z.ZodString;
+    decodeHwAccel: z.ZodNullable<z.ZodString>;
+    camStreamId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type EgressTranscode = z.infer<typeof EgressTranscodeSchema>;
 export declare const streamBrokerCapability: {
     readonly name: "stream-broker";
     readonly scope: "system";
@@ -321,6 +496,7 @@ export declare const streamBrokerCapability: {
                         baseline: "baseline";
                         main: "main";
                     }>>;
+                    level: z.ZodOptional<z.ZodString>;
                     width: z.ZodOptional<z.ZodNumber>;
                     height: z.ZodOptional<z.ZodNumber>;
                     fps: z.ZodOptional<z.ZodNumber>;
@@ -691,6 +867,134 @@ export declare const streamBrokerCapability: {
             released: z.ZodBoolean;
             refcount: z.ZodNumber;
         }, z.core.$strip>, "mutation">;
+        /**
+         * THE ffmpeg primitive. Acquire an encoded stream matching a structured
+         * encode plan; the broker builds the argv through the ONE builder
+         * (`@camstack/types` `ffmpeg/invocation.ts`), resolves decode hardware from
+         * the DECODER ADDON's per-node ranking, and returns a dialable RTSP url.
+         *
+         * **Refcounted and deduplicated on EXACT match.** Two requesters whose
+         * requests produce the same `egressTranscodeSharingKey` receive the SAME
+         * `pipelineKey` and the same child process. Nearly-identical requests are
+         * NOT merged.
+         *
+         * **The handle is immutable.** There is deliberately no `reconfigure`
+         * method and this one never accepts a `pipelineKey` alongside encode
+         * parameters: a consumer whose requirements change releases and
+         * re-acquires. A mutable shared handle is exactly what made Alexa's old
+         * `derived:alexa-<id>` stream a co-tenant hazard — one consumer's
+         * downgrade dragged every other consumer down with it.
+         *
+         * Placement: unpinned, `classifyCapRoute` serves this hub-in-process
+         * (Priority 1). A caller that wants the transcode elsewhere passes
+         * `nodePin(nodeId)` and a `hostname` it can dial.
+         */
+        readonly acquireEgressTranscode: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"profile">;
+                profile: z.ZodEnum<{
+                    high: "high";
+                    mid: "mid";
+                    low: "low";
+                }>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"cam-stream">;
+                camStreamId: z.ZodString;
+            }, z.core.$strip>], "kind">;
+            encode: z.ZodObject<{
+                audio: z.ZodUnion<readonly [z.ZodLiteral<"passthrough">, z.ZodObject<{
+                    codec: z.ZodEnum<{
+                        copy: "copy";
+                        opus: "opus";
+                        aac: "aac";
+                        pcmu: "pcmu";
+                        pcma: "pcma";
+                    }>;
+                    bitrateKbps: z.ZodOptional<z.ZodNumber>;
+                    sampleRateHz: z.ZodOptional<z.ZodNumber>;
+                    channels: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>]>>;
+                }, z.core.$strip>]>;
+                video: z.ZodObject<{
+                    codec: z.ZodEnum<{
+                        h264: "h264";
+                        h265: "h265";
+                        copy: "copy";
+                    }>;
+                    profile: z.ZodOptional<z.ZodEnum<{
+                        high: "high";
+                        baseline: "baseline";
+                        main: "main";
+                    }>>;
+                    level: z.ZodOptional<z.ZodString>;
+                    width: z.ZodOptional<z.ZodNumber>;
+                    height: z.ZodOptional<z.ZodNumber>;
+                    fps: z.ZodOptional<z.ZodNumber>;
+                    bitrateKbps: z.ZodOptional<z.ZodNumber>;
+                    gopFrames: z.ZodOptional<z.ZodNumber>;
+                    bf: z.ZodOptional<z.ZodNumber>;
+                    preset: z.ZodOptional<z.ZodEnum<{
+                        fast: "fast";
+                        ultrafast: "ultrafast";
+                        superfast: "superfast";
+                        veryfast: "veryfast";
+                        faster: "faster";
+                        medium: "medium";
+                    }>>;
+                    tune: z.ZodOptional<z.ZodEnum<{
+                        zerolatency: "zerolatency";
+                        film: "film";
+                        animation: "animation";
+                    }>>;
+                }, z.core.$strip>;
+            }, z.core.$strip>;
+            rateControl: z.ZodOptional<z.ZodEnum<{
+                tight: "tight";
+                relaxed: "relaxed";
+            }>>;
+            bitstreamFilter: z.ZodOptional<z.ZodEnum<{
+                dump_extra: "dump_extra";
+                h264_mp4toannexb: "h264_mp4toannexb";
+                hevc_mp4toannexb: "hevc_mp4toannexb";
+            }>>;
+            publishLocally: z.ZodOptional<z.ZodBoolean>;
+            pixelFormat: z.ZodOptional<z.ZodEnum<{
+                yuv420p: "yuv420p";
+                nv12: "nv12";
+            }>>;
+            decodeHwAccel: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                auto: "auto";
+                videotoolbox: "videotoolbox";
+                vaapi: "vaapi";
+                qsv: "qsv";
+                cuda: "cuda";
+            }>>;
+            hostname: z.ZodOptional<z.ZodString>;
+            tag: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            url: z.ZodString;
+            pipelineKey: z.ZodString;
+            videoCodec: z.ZodEnum<{
+                H264: "H264";
+                H265: "H265";
+            }>;
+            resolution: z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>;
+            transcoded: z.ZodBoolean;
+            encoder: z.ZodString;
+            decodeHwAccel: z.ZodNullable<z.ZodString>;
+            camStreamId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>, "mutation">;
+        /** Drop one reference. The child dies when the last holder releases. */
+        readonly releaseEgressTranscode: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            pipelineKey: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            released: z.ZodBoolean;
+            refcount: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
         /**
          * ── Decoded audio-chunk plane (Phase 5 / D9) ──────────────────────
          *

package/dist/capabilities/stream-params.cap.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { type InferNativeProvider } from './capability-definition.js';
 import { DeviceType } from '../device/device-type.js';
+import { type InferNativeProvider } from './capability-definition.js';
 /** One of the camera's stream profiles. */
 export declare const StreamProfileSchema: z.ZodEnum<{
     sub: "sub";
@@ -183,7 +183,13 @@ export declare const StreamParamsOptionsSchema: z.ZodObject<{
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /** A partial change to one profile — every field optional; a provider
- *  ignores fields it doesn't support. */
+ *  ignores fields it doesn't support.
+ *
+ *  There is deliberately NO `audio` here. It existed until 2026-08-07,
+ *  reachable from no form and honoured by exactly one provider, while the
+ *  camera's microphone is a whole-device fact. It now has one writer,
+ *  `privacyMask.setAudioEnabled`, which writes every profile — see
+ *  `privacy-mask.cap.ts`. */
 export declare const StreamProfilePatchSchema: z.ZodObject<{
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
@@ -203,7 +209,6 @@ export declare const StreamProfilePatchSchema: z.ZodObject<{
         main: "main";
     }>>;
     gop: z.ZodOptional<z.ZodNumber>;
-    audio: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type StreamParamsStatus = z.infer<typeof StreamParamsStatusSchema>;
 export type StreamParamsOptions = z.infer<typeof StreamParamsOptionsSchema>;
@@ -316,7 +321,6 @@ export declare const streamParamsCapability: {
                     main: "main";
                 }>>;
                 gop: z.ZodOptional<z.ZodNumber>;
-                audio: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
         /**

package/dist/device/device-profile.d.ts

@@ -120,10 +120,18 @@ export interface DeviceProfile {
      */
     readonly defaults: DeviceProfileDefaults;
     /**
-     * Generic settings overrides (snapshot interval, pre-buffer flag,
-     * etc.). Same sticky semantics as defaults — applied on first read,
-     * operator override wins. Keys are dot-paths interpreted by the
-     * per-driver / per-addon config schema.
+     * Generic settings overrides, keyed by dot-path, intended to be
+     * interpreted by the per-driver / per-addon config schema.
+     *
+     * **Nothing reads this today.** It is a declared extension point with no
+     * consumer anywhere in the workspace, so any entry placed here is inert. It
+     * shipped populated — `snapshot.minRefreshIntervalSec: 3600` and
+     * `streamBroker.preBufferEnabled: false` on the battery profile — which read
+     * as live policy and were not: both behaviours are really enforced off
+     * `DeviceFeature.BatteryOperated` directly, by `BATTERY_DEFAULT_MAX_AGE_S`
+     * in `snapshot.addon.ts` and by `getEffectivePreBufferSec` in
+     * `stream-broker-manager.ts`. Emptied 2026-08-07; keep it empty until a
+     * reader exists, or an entry here is just documentation that lies.
      */
     readonly settings: Readonly<Record<string, unknown>>;
 }

package/dist/device/system-mirror.d.ts

@@ -62,6 +62,17 @@ export interface SystemMirrorApi extends SliceHandleApi {
                 addonId?: string;
             }): Promise<ReadonlyArray<DeviceInfo>>;
         };
+        /**
+         * Single-device metadata read. Required — `refreshDeviceMetadata`
+         * runs once per `device.registered` / `device.updated` event, and a
+         * full-catalog fetch there is what melts the hub during a
+         * deploy/restart storm (see `refreshDeviceMetadata`).
+         */
+        readonly getDevice: {
+            query(input: {
+                deviceId: number;
+            }): Promise<DeviceInfo | null>;
+        };
     };
     readonly deviceState: SliceHandleApi['deviceState'] & {
         readonly getAllSnapshots: {

package/dist/encode-profile.d.ts

@@ -22,6 +22,7 @@ export declare const VideoEncodeSchema: z.ZodObject<{
         baseline: "baseline";
         main: "main";
     }>>;
+    level: z.ZodOptional<z.ZodString>;
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
     fps: z.ZodOptional<z.ZodNumber>;
@@ -68,6 +69,7 @@ export declare const EncodeProfileSchema: z.ZodObject<{
             baseline: "baseline";
             main: "main";
         }>>;
+        level: z.ZodOptional<z.ZodString>;
         width: z.ZodOptional<z.ZodNumber>;
         height: z.ZodOptional<z.ZodNumber>;
         fps: z.ZodOptional<z.ZodNumber>;

package/dist/ffmpeg/encode-defaults.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The ONE home for live-egress encode constants.
+ *
+ * Before this file there were five sets, in four packages, that nobody could
+ * diff: the WebRTC fallback, Alexa's "fallback", the transcode-down ceiling,
+ * the broker's audio presets, and HomeKit's inline block. Three of them
+ * disagreed about Opus channel count alone. They live here now because the
+ * consumers are separate ADDONS and addons may never import each other —
+ * `@camstack/types` is the only legal shared home.
+ *
+ * ## What changed value, and what kept a deliberate divergence
+ *
+ * KEPT, with the reason:
+ * - **VBV window.** HomeKit uses a ONE-second window; the browser and Alexa
+ *   use TWO. HomeKit's link budget is enforced per second by the controller,
+ *   so a keyframe allowed to borrow from the next second overshoots and the
+ *   iOS client drops the stream. A browser wants the opposite: let a keyframe
+ *   spike, keep the average. Encoded as {@link FfmpegRateControl}, not as two
+ *   copies of a number.
+ * - **`preset`.** HomeKit and the browser use `ultrafast` (the encoder is on
+ *   the interactive path); Alexa uses `veryfast` (Echo tolerates ~200 ms more
+ *   latency and the extra quality is visible on a 10" panel).
+ * - **`-bsf:v dump_extra`** is HomeKit-only on BOTH the copy and encode
+ *   branches: HAP negotiates its own SDP and cannot carry out-of-band
+ *   extradata. Nothing else needs it, and emitting it elsewhere costs bytes.
+ *
+ * CHANGED — the divergences that were accidents:
+ * - **Opus channels.** Was 2 (broker preset), 1 (Alexa), 1 (HomeKit). Now 1
+ *   everywhere: every consumer here is a camera microphone, which is mono at
+ *   the source, and encoding a duplicated second channel spent bitrate on
+ *   nothing. The broker's 2 was the outlier and it is the one that changed.
+ * - **Alexa gained `level: '3.1'`.** Its SDP advertises `profile-level-id=
+ *   42e01f` and its encoder was unconstrained. Now it matches.
+ * - **Alexa GOP.** Was 25 frames at 25 fps (1 s); the browser is 30 at 25 fps
+ *   (1.2 s). Both are now expressed as `gopSeconds` × fps so the intent is
+ *   legible; Alexa's numeric GOP is unchanged, the browser's rounds to 30.
+ */
+import type { EncodeProfile } from '../encode-profile.js';
+import type { FfmpegAudioEncodePlan, FfmpegRateControl } from './invocation.js';
+/**
+ * The shape every live egress starts from: H.264 Baseline 3.1 at 720p25.
+ * Baseline because it is the one profile every consumer in this repo decodes
+ * (Echo, iOS, an old browser); 3.1 because that is what the SDPs advertise.
+ */
+export declare const BASE_LIVE_EGRESS_PROFILE: EncodeProfile;
+/**
+ * The browser WebRTC viewer's transcode profile. Used only when the broker
+ * MUST spawn ffmpeg (source codec ∉ the browser-accepted set — an H.265 source
+ * on an H.264-only browser). Audio is `passthrough` because werift carries the
+ * audio plane out-of-band; putting it in the video pipeline would encode a
+ * track nothing reads.
+ */
+export declare const WEBRTC_EGRESS_PROFILE: EncodeProfile;
+/**
+ * Alexa's egress profile. Alexa's audio ALSO rides the WebRTC session's own
+ * audio plane (out-of-band), so this is `passthrough` exactly like the browser
+ * — see the ADR for why the previous in-band Opus was encoded and discarded.
+ */
+/**
+ * Alexa's egress asks for OPUS, and that is a change with a history.
+ *
+ * The previous profile encoded Opus IN-BAND into an MPEG-TS, where it was
+ * discarded: Opus is `stream_type 0x06` and the broker's demuxer maps only
+ * `0x0f` (aac), `0x03`/`0x04` (mp2) and `0x81` (ac3). Every frame it produced
+ * died at the demuxer, so the encode was replaced with `passthrough` — correct,
+ * because paying libopus for nothing is worse than silence.
+ *
+ * But `passthrough` means the egress emits NO audio at all, and Alexa's audio
+ * does not arrive by magic: it rides the published stream, which is what the
+ * WebRTC session dials. So the Echo had video and silence either way.
+ *
+ * Opus here now reaches the egress AUDIO SIDECAR — a separate RTP leg the
+ * restreamer grafts onto its SDP — which never touches the MPEG-TS demuxer that
+ * killed the in-band attempt. Same codec, different plane, and this one the
+ * consumer can actually negotiate.
+ */
+export declare const ALEXA_EGRESS_PROFILE: EncodeProfile;
+/** VBV window for a consumer whose budget is enforced per second (HomeKit). */
+export declare const RATE_CONTROL_TIGHT: FfmpegRateControl;
+/** VBV window for a consumer that tolerates a keyframe spike (browser, Echo). */
+export declare const RATE_CONTROL_RELAXED: FfmpegRateControl;
+/**
+ * Transcode-DOWN ceiling: the shape a remote/unhealthy WebRTC session is
+ * reduced to. 360p / 400 kbps is the `low` rung of the adaptive ladder — a
+ * session steered here is already failing, so the ceiling is chosen to survive
+ * a bad link, not to look good.
+ */
+export declare const TRANSCODE_DOWN_MAX_HEIGHT = 360;
+export declare const TRANSCODE_DOWN_MAX_BITRATE_KBPS = 400;
+/**
+ * Camera-microphone audio, per codec. Defined in `./invocation.js` (an import
+ * cycle otherwise) and re-exported here, which is where to read it.
+ */
+export { AUDIO_PRESETS } from './invocation.js';
+/**
+ * HomeKit's two-way audio leg. `lowdelay` + a short frame duration because the
+ * leg is interactive; `globalHeader` because HAP owns the SDP and ffmpeg must
+ * not put extradata in-band. `sampleRateHz` and `frameDurationMs` are
+ * NEGOTIATED per session — the controller picks them — so they are absent here
+ * and filled in by the caller.
+ */
+export declare const HAP_AUDIO_BITRATE_KBPS = 24;
+export declare const HAP_AUDIO_BASE: FfmpegAudioEncodePlan;
+/** HomeKit's `-bufsize` for the audio plane — four seconds of its 24 kbps. */
+export declare const HAP_AUDIO_VBV_KBITS: number;
+/** Seconds between forced IDRs on a HomeKit transcode. */
+export declare const HAP_KEYFRAME_INTERVAL_SEC = 4;

package/dist/ffmpeg/hwaccel.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Decode hardware acceleration for an EGRESS transcode — resolved through the
+ * ONE ranking that is known to work on this hardware.
+ *
+ * ## Why this file exists
+ *
+ * The repo has two hwaccel opinions and they disagree in the direction that
+ * breaks things:
+ *
+ * - the raw kernel resolver (`ctx.kernel.hwaccel.resolve()`) returns
+ *   `['qsv','vaapi']` for an Intel host — qsv FIRST;
+ * - `addon-decoder-ffmpeg`'s `DECODE_HWACCEL_RANK` puts **vaapi above qsv on
+ *   purpose**, because on this exact hub a qsv decode child exits `code=171`
+ *   producing no frames, while vaapi decodes 8 MP h264 at ~50 fps.
+ *
+ * **The decoder addon is the authority.** It publishes its answer per node as
+ * the `probedBestHwaccel@<node>` setting and exposes it on the `decoder` cap's
+ * `getInfo` — the same value `AgentLoadService.readNodeDecodeHwaccel` reads to
+ * show per-node hwaccel in the UI. This module reads THAT, and deliberately
+ * never re-derives a ranking: a second copy of the rank table is exactly how
+ * the two opinions appeared. Addons may not import each other, so the read is
+ * a `ctx.api.decoder.getInfo` call injected as {@link EgressHwAccelDeps.readDecoderBackend}.
+ *
+ * ## Why the kernel resolver is still a dependency here
+ *
+ * It is only ever used to say something in a log line. It is never allowed to
+ * SELECT a backend: if the decoder cannot answer, this resolver returns
+ * software rather than adopting the kernel's qsv-first order, because that
+ * order is the known-bad one. `never silently downgrades` in the spec is the
+ * test that holds this.
+ *
+ * ## The failure mode this must not reproduce
+ *
+ * A silent fall back to software decode is a FLOW bug on this hub, not a
+ * capability limit (vaapi works — 10 concurrent 4K decodes pass). So every
+ * path that ends in software calls {@link EgressHwAccelDeps.onFallback}, which
+ * the caller logs at `warn` with `tags: { deviceId }`. Silence reads as
+ * "hardware was used".
+ */
+/** Why a resolve ended in software decode. */
+export type EgressHwAccelFallbackReason = 
+/** The `decoder` cap could not be reached (offline node, cap not mounted). */
+'decoder-unreadable'
+/** The decoder answered, but has not probed a backend on this node yet. */
+ | 'decoder-unprobed';
+export interface EgressHwAccelFallback {
+    readonly reason: EgressHwAccelFallbackReason;
+    /** What the kernel resolver would have said — for the log line ONLY. */
+    readonly kernelPreferred: readonly string[];
+    readonly error?: string;
+}
+/**
+ * A bounded memo so a per-session resolve is not a per-session cross-process
+ * cap call. Owned by the caller (one per broker / exporter), never a module
+ * global — a module global would outlive an addon respawn and survive an
+ * operator changing the decoder backend.
+ */
+export interface HwAccelCache {
+    read(): string | null | undefined;
+    write(value: string | null): void;
+}
+export interface HwAccelCacheOptions {
+    readonly ttlMs: number;
+    readonly now?: () => number;
+}
+export declare function createHwAccelCache(options: HwAccelCacheOptions): HwAccelCache;
+export interface EgressHwAccelDeps {
+    /**
+     * `ctx.api.decoder.getInfo.query(undefined, nodePin(nodeId)).probedBestHwaccel`
+     * — the DECODER ADDON's own answer for THIS node, already re-ranked through
+     * `DECODE_HWACCEL_RANK`. Throw or return `''` when it is not knowable.
+     */
+    readDecoderBackend(): Promise<string>;
+    /**
+     * `ctx.kernel.hwaccel.resolve().preferred` — reported in the fallback log so
+     * an operator can see the disagreement. NEVER used to select a backend.
+     */
+    readKernelPreferred(): Promise<readonly string[]>;
+    /** Called on every path that ends in software. The caller logs at `warn`. */
+    onFallback(fallback: EgressHwAccelFallback): void;
+    /**
+     * An explicit operator choice (`decoder.hwaccel`, or a per-consumer pin).
+     * `'auto'` is passed through as the literal ffmpeg instruction; `'none'` /
+     * `'copy'` force software; anything else pins that backend. Absent ⇒ ask the
+     * decoder.
+     */
+    readonly override?: string | null;
+    readonly cache?: HwAccelCache;
+}
+/**
+ * Resolve the `-hwaccel` value for an egress transcode. Hardware is the
+ * DEFAULT — an egress that decodes in software on a hub with working vaapi is
+ * paying for nothing — and every software outcome is announced.
+ *
+ * Returns a concrete backend name, the literal `'auto'`, or `null` for
+ * software decode (⇒ {@link buildFfmpegArgs} emits no `-hwaccel` at all).
+ */
+export declare function resolveEgressDecodeHwAccel(deps: EgressHwAccelDeps): Promise<string | null>;