@camstack/types 1.2.41 → 1.2.42

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>;

package/dist/ffmpeg/invocation.d.ts

@@ -0,0 +1,250 @@
+/**
+ * THE ffmpeg argv builder. Every ffmpeg this repo spawns for a LIVE MEDIA
+ * transcode — the broker transcode pool, the WebRTC transcode leg, a derived
+ * stream, HomeKit's SRTP egress, Alexa — assembles its argument list here.
+ *
+ * It lives in `@camstack/types` rather than in an addon for one reason: three
+ * addons need it (`addon-pipeline`, `addon-export-hap`, `addon-export-alexa`)
+ * and addons may never import each other. `@camstack/types` is the framework
+ * package all three already depend on, and it already owns `EncodeProfile`.
+ *
+ * The builder is PURE — argument list only. The binary path comes from
+ * `system-config`'s `ffmpeg.binaryPath` and goes to `spawn` separately (see
+ * `../ffmpeg-node/process.js` for the lifecycle wrapper).
+ *
+ * ## The one rule this file exists to enforce
+ *
+ * **`-hwaccel` is an INPUT option.** ffmpeg accepts it after `-i` without any
+ * error and then silently decodes in software: the CPU cost stays, the GPU is
+ * idle, and the log line still says "using hardware decode". Everything that
+ * configures the INPUT is emitted by {@link buildInputArgs} strictly before
+ * `-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';
+/** 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. */
+    readonly url: string;
+    /**
+     * `-rtsp_transport`. `null` for a non-RTSP input (stdin, file). TCP is the
+     * only value in production use: the broker's loopback restreams are TCP and
+     * UDP loses packets under a burst.
+     */
+    readonly rtspTransport?: 'tcp' | 'udp' | null;
+    /** `-fflags` values, e.g. `['+discardcorrupt']`, `['+genpts']`. */
+    readonly fflags?: readonly string[];
+    /** Caller-supplied input options (an `EncodeProfile.inputArgs`, probe flags). */
+    readonly extraArgs?: readonly string[];
+}
+/** ffmpeg video encoder ids the repo selects between. */
+export type FfmpegVideoEncoderId = 'libx264' | 'libx265' | 'h264_videotoolbox' | 'hevc_videotoolbox' | 'h264_vaapi' | 'hevc_vaapi' | 'h264_qsv' | 'hevc_qsv' | 'h264_nvenc' | 'hevc_nvenc' | 'h264_amf' | 'hevc_amf';
+/**
+ * How the encoder is bounded.
+ *
+ * - `'cbr'` — a TARGET bitrate plus a matching peak (`-b:v` + `-maxrate`).
+ *   What a real-time egress with a fixed budget wants.
+ * - `'cap'` — a CEILING only (`-maxrate`, no `-b:v`): the encoder spends less
+ *   on an easy scene but never exceeds the bound.
+ *
+ * `vbvSeconds` is the VBV window as a multiple of the bitrate. One second is a
+ * tight window that keeps instantaneous rate near the target (HomeKit's link
+ * budget is per-second); two seconds lets a keyframe spike borrow from the next
+ * second, which is what a browser viewer wants.
+ */
+export type FfmpegRateControl = {
+    readonly kind: 'cbr';
+    readonly vbvSeconds: number;
+} | {
+    readonly kind: 'cap';
+    readonly vbvSeconds: number;
+};
+/** Fit-inside (never upscale, even dimensions) vs an exact rescale. */
+export interface FfmpegScalePlan {
+    readonly mode: 'fit' | 'exact';
+    readonly width: number;
+    readonly height: number;
+}
+export interface FfmpegVideoEncodePlan {
+    readonly kind: 'encode';
+    readonly encoder: FfmpegVideoEncoderId;
+    readonly scale?: FfmpegScalePlan | null;
+    readonly preset?: string;
+    readonly tune?: string;
+    /** `-profile:v` — baseline / main / high. */
+    readonly profile?: string;
+    /**
+     * `-level`. Omitting this while advertising a level in SDP is the defect
+     * that kept HomeKit black for a year and that Alexa shipped too: a stream
+     * that does not match its own advertisement.
+     */
+    readonly level?: string;
+    readonly pixelFormat?: string;
+    readonly fps?: number;
+    readonly gopFrames?: number;
+    readonly bf?: number;
+    readonly bitrateKbps?: number;
+    readonly rateControl?: FfmpegRateControl;
+    /** `-bsf:v`, e.g. `dump_extra` when the consumer negotiates its own SDP. */
+    readonly bitstreamFilter?: string;
+}
+export interface FfmpegVideoCopyPlan {
+    readonly kind: 'copy';
+    readonly bitstreamFilter?: string;
+}
+export type FfmpegVideoPlan = FfmpegVideoCopyPlan | FfmpegVideoEncodePlan;
+export type FfmpegAudioCodecId = 'opus' | 'aac' | 'pcmu' | 'pcma';
+export interface FfmpegAudioEncodePlan {
+    readonly kind: 'encode';
+    readonly codec: FfmpegAudioCodecId;
+    readonly bitrateKbps?: number;
+    readonly sampleRateHz?: number;
+    readonly channels?: number;
+    /** libopus `-application` — `lowdelay` for a real-time two-way leg. */
+    readonly application?: 'lowdelay' | 'voip' | 'audio';
+    /** libopus `-frame_duration` in ms — negotiated per consumer session. */
+    readonly frameDurationMs?: number;
+    /** `-bufsize` for the audio plane, in kbit. */
+    readonly vbvBufferKbits?: number;
+    /** `-flags +global_header` — required when the consumer owns the SDP. */
+    readonly globalHeader?: boolean;
+    /** `-af` filter chain, e.g. `aresample=async=1000:first_pts=0`. */
+    readonly filter?: string;
+}
+export type FfmpegAudioPlan = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'copy';
+} | FfmpegAudioEncodePlan;
+/**
+ * Camera-microphone audio, per codec. Lives HERE rather than in
+ * `encode-defaults.ts` only to avoid an import cycle (`encode-defaults` depends
+ * on these types); it is re-exported from there, which is where to read it.
+ *
+ * Every source in this repo is a mono camera mic. The former broker preset
+ * encoded Opus at `channels: 2`, spending bitrate duplicating one channel —
+ * that is the value this consolidation changed.
+ */
+export declare const AUDIO_PRESETS: Readonly<Record<'aac' | 'opus' | 'pcmu', FfmpegAudioEncodePlan>>;
+/** One RTP output leg. The payload type / SSRC / MTU are the CONSUMER's facts. */
+export interface FfmpegRtpOutput {
+    /** `rtp://host:port[?pkt_size=N]`. */
+    readonly url: string;
+    readonly payloadType?: number;
+    /** ffmpeg parses `-ssrc` as a SIGNED int32 — callers coerce with `| 0`. */
+    readonly ssrc?: number;
+    /** Path ffmpeg writes this output's SDP to (`-sdp_file`). */
+    readonly sdpFile?: string;
+}
+export type FfmpegSink = {
+    readonly kind: 'rtsp-listen';
+    readonly url: string;
+} | {
+    readonly kind: 'stdout';
+    readonly container: 'h264' | 'hevc' | 'mpegts';
+}
+/**
+ * Two independent mapped RTP outputs. Generic ffmpeg RTP vocabulary — the
+ * SRTP encryption, the port allocation and the payload-type numbers stay
+ * with the consumer that negotiated them.
+ */
+ | {
+    readonly kind: 'rtp-outputs';
+    readonly video: FfmpegRtpOutput | null;
+    readonly audio: FfmpegRtpOutput | null;
+};
+/**
+ * An optional SECOND output carrying source audio as its own RTP stream,
+ * alongside an elementary video sink (which is `-an`). ffmpeg writes the
+ * authoritative SDP to `sdpFile`.
+ */
+export interface FfmpegAudioSidecar {
+    readonly codec: FfmpegAudioCodecId;
+    readonly rtpUrl: string;
+    readonly sdpFile: string;
+}
+export interface FfmpegInvocation {
+    readonly logLevel: 'error' | 'warning' | 'info';
+    /**
+     * A concrete `-hwaccel` backend, the literal `'auto'`, or a software
+     * sentinel (`null` / `'none'` / `'copy'`) ⇒ no `-hwaccel` at all.
+     * Resolved by `resolveDecodeHwAccel` (see `./hwaccel.js`), which reads the
+     * DECODER ADDON's ranking, never the raw kernel resolver's.
+     */
+    readonly decodeHwAccel: string | null;
+    readonly input: FfmpegInputPlan;
+    readonly video: FfmpegVideoPlan;
+    readonly audio: FfmpegAudioPlan;
+    /** `0` = auto (omit `-threads` and let ffmpeg decide). */
+    readonly threadCount: number;
+    /** Consumer output options, emitted verbatim after the encode block. */
+    readonly outputArgs: readonly string[];
+    readonly sink: FfmpegSink;
+    readonly audioSidecar?: FfmpegAudioSidecar | null;
+}
+/** `-hide_banner -loglevel <level>` — every ffmpeg site opens with this. */
+export declare function logBannerArgs(level: 'error' | 'warning' | 'info'): string[];
+/** `true` when the resolved value means "decode in software" (⇒ no `-hwaccel`). */
+export declare function isSoftwareDecode(decodeHwAccel: string | null): boolean;
+/**
+ * Every INPUT option, in order, terminated by `-i <url>`. Nothing may be
+ * appended to this list by a caller — that is the whole point of the function.
+ */
+export declare function buildInputArgs(input: FfmpegInputPlan, decodeHwAccel: string | null): string[];
+/** The whole video block (`-vf` … `-c:v` … knobs), after `-i`. */
+export declare function buildVideoArgs(video: FfmpegVideoPlan, outputArgs: readonly string[]): string[];
+/** The whole audio block, after `-i`. */
+export declare function buildAudioArgs(audio: FfmpegAudioPlan): string[];
+/**
+ * Assemble the full ffmpeg argument list. Layout:
+ *
+ *   -hide_banner -loglevel <level>
+ *   [-hwaccel <backend|auto>]        ─┐ INPUT options — strictly before -i.
+ *   [<input.extraArgs>]               │
+ *   [-fflags <flag>…]                 │
+ *   [-rtsp_transport tcp]             │
+ *   -i <url>                         ─┘
+ *   <video block>  <threads>  <audio block>   ─┐ OUTPUT options.
+ *   <consumer outputArgs verbatim>             │
+ *   <sink>                                    ─┘ terminal
+ */
+export declare function buildFfmpegArgs(inv: FfmpegInvocation): string[];
+/**
+ * The hardware encoder for a target codec on `backend`, or the software one.
+ * `'auto'` is NOT a backend identity (it is an instruction to ffmpeg), so it
+ * maps to software encoding.
+ */
+export declare function pickVideoEncoder(target: 'h264' | 'h265', backend: string | null, useHardware: boolean): FfmpegVideoEncoderId;
+/** Map an `EncodeProfile.audio` to an audio plan. */
+export declare function audioPlanFromEncodeProfile(audio: AudioEncode): FfmpegAudioPlan;
+export interface EncodeProfileInvocationInput {
+    readonly profile: EncodeProfile;
+    /** The SOURCE's video codec — drives the smart-copy decision. */
+    readonly sourceCodec: 'h264' | 'h265';
+    readonly sourceUrl: string;
+    readonly sink: FfmpegSink;
+    readonly decodeHwAccel: string | null;
+    /**
+     * Defeat smart-copy. A DERIVED stream always applies its profile — applying
+     * it is its entire reason to exist — so it re-encodes even when the source
+     * already speaks the target codec. A `copy` profile still copies.
+     */
+    readonly forceReencode?: boolean;
+    /** Select the hardware encoder for {@link decodeHwAccel}'s backend. */
+    readonly hardwareEncoders?: boolean;
+    readonly logLevel?: 'error' | 'warning' | 'info';
+    readonly threadCount?: number;
+    readonly audioSidecar?: FfmpegAudioSidecar | null;
+}
+/**
+ * Adapt an `EncodeProfile` (the operator/consumer-facing shape) into an
+ * {@link FfmpegInvocation}. This is the ONLY bridge between the two models —
+ * a second one is how the repo grew two argv builders that disagreed about
+ * hardware.
+ *
+ * Smart video copy: when the source already speaks the requested codec the
+ * encode block is elided entirely and ffmpeg runs as a re-muxer on the video
+ * plane. Width / height / fps / bitrate in the profile are a downstream BUDGET,
+ * not a forced rescale.
+ */
+export declare function invocationFromEncodeProfile(input: EncodeProfileInvocationInput): FfmpegInvocation;

package/dist/ffmpeg/process.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `FfmpegProcess` — the ONE spawn/lifecycle wrapper for a live-media ffmpeg.
+ *
+ * Extracted from `TranscodeEgress.spawnAttempt`, which was already the most
+ * complete of the repo's hand-rolled lifecycles: first-data deadline, hardware
+ * →software retry, SIGTERM-then-SIGKILL. This generalises it and adds the two
+ * things every copy was missing — a `tags: { deviceId }` on every line, and a
+ * bounded restart — so a consumer gets them by construction instead of by
+ * remembering.
+ *
+ * ## What it owns
+ *
+ * - spawn, with the argv from the ONE builder (`./invocation.js`);
+ * - a FIRST-DATA deadline: an ffmpeg that starts but never emits is dead, and
+ *   nothing downstream can tell that apart from a slow camera;
+ * - HARDWARE→SOFTWARE retry, announced at `warn`. A silent downgrade on this
+ *   hub is a flow bug, not a capability limit — see `docs/design/decode-path.md`;
+ * - exit classification (`ok` / `signalled-by-us` / `crashed` / `no-output`);
+ * - bounded restart with backoff, and a terminal give-up (never an infinite
+ *   loop — the same rule `CrashSupervisor` enforces for runners, D6);
+ * - SIGTERM then SIGKILL after a grace, gated on the child not having already
+ *   exited.
+ *
+ * ## What it does NOT own
+ *
+ * The output PLUMBING. A consumer attaches to `stdout` / `stderr` itself,
+ * because what the bytes mean is the consumer's business: the broker deframes
+ * Annex-B into a restreamer, the WebRTC leg regroups access units, HomeKit
+ * writes nothing to stdout at all (its output is two RTP sockets). A wrapper
+ * that also owned the bytes would need a mode per consumer, which is the same
+ * mistake as one builder per consumer.
+ */
+import { spawn, type ChildProcess, type SpawnOptions } from 'node:child_process';
+import type { IScopedLogger } from '../interfaces/logging.js';
+/** How a child ended. */
+export type FfmpegExitClass = 
+/** Exited 0. */
+'ok'
+/** We asked it to stop — an exit code here is expected, not a failure. */
+ | 'stopped'
+/** Exited non-zero / on a signal we did not send. */
+ | 'crashed'
+/** Ran, but never produced a byte before the first-data deadline. */
+ | 'no-output';
+export interface FfmpegExit {
+    readonly classification: FfmpegExitClass;
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    /** The last stderr lines — the only diagnosis available after the fact. */
+    readonly stderrTail: readonly string[];
+    /** Whether this child was decoding in hardware. */
+    readonly decodeHwAccel: string | null;
+}
+export interface FfmpegProcessOptions {
+    /** `system-config` `ffmpeg.binaryPath`. */
+    readonly binaryPath: string;
+    /**
+     * Build the argv for one attempt. Called per spawn so a retry can lower
+     * `decodeHwAccel` to `null` (software) without the caller re-deriving
+     * anything else.
+     */
+    readonly buildArgs: (decodeHwAccel: string | null) => readonly string[];
+    /** The resolved hardware backend for the FIRST attempt (`null` ⇒ software). */
+    readonly decodeHwAccel: string | null;
+    readonly logger: IScopedLogger;
+    /**
+     * The camera this ffmpeg serves. Stamped on EVERY line as `tags.deviceId`:
+     * a miss rate or a media gap is always asked per camera, and a line without
+     * it cannot answer "why is 617 worse than 615".
+     */
+    readonly deviceId: number;
+    /** Free-form label for the log (`'webrtc-transcode'`, `'hap-egress'`, …). */
+    readonly role: string;
+    /** Extra queryable tags (sessionId, brokerId, camStreamId…). */
+    readonly tags?: Readonly<Record<string, string | number>>;
+    readonly stdio?: SpawnOptions['stdio'];
+    /** Wire up stdout/stderr. Called once per spawned child. */
+    readonly onChild: (child: ChildProcess) => void;
+    /**
+     * Called when a child ends. `restart` tells the wrapper whether to respawn;
+     * it is bounded by {@link maxRestarts} regardless of what this returns.
+     */
+    readonly onExit?: (exit: FfmpegExit) => void;
+    /** Wall-clock budget for the first output byte. `0` disables the deadline. */
+    readonly firstDataTimeoutMs?: number;
+    /** `0` ⇒ never restart (a run-to-completion job). */
+    readonly maxRestarts?: number;
+    readonly restartDelayMs?: number;
+    /** Consecutive-failure counter resets after a child has run this long. */
+    readonly stableRunMs?: number;
+    readonly killGraceMs?: number;
+    /** Injected for tests. */
+    readonly spawnFn?: typeof spawn;
+    readonly now?: () => number;
+    readonly setTimeoutFn?: typeof setTimeout;
+}
+export declare class FfmpegProcess {
+    private readonly opts;
+    private child;
+    private stopped;
+    private producedOutput;
+    private consecutiveFailures;
+    private startedAtMs;
+    private stderrTail;
+    private activeHwAccel;
+    private triedSoftwareFallback;
+    private firstDataTimer;
+    constructor(opts: FfmpegProcessOptions);
+    /** Queryable tags on every line — `deviceId` is never optional. */
+    private get logTags();
+    private get now();
+    /** `true` while a child is running. */
+    isRunning(): boolean;
+    /** The backend the CURRENT child decodes with (`null` ⇒ software). */
+    activeDecodeHwAccel(): string | null;
+    /**
+     * Spawn the first child. Resolves as soon as it produces output; rejects if
+     * it dies or stays silent past the deadline AFTER the software retry has
+     * also been exhausted. A caller that wants fire-and-forget can ignore the
+     * promise — the restart loop runs regardless.
+     */
+    start(): Promise<void>;
+    private spawnAttempt;
+    /**
+     * A child failed before going live. Try SOFTWARE once if it was decoding in
+     * hardware — loudly — then fall through to the bounded restart.
+     */
+    private handleFailure;
+    private scheduleRestart;
+    private report;
+    private clearFirstDataTimer;
+    /** Terminate for good. Idempotent; no restart follows. */
+    stop(): void;
+    private killChild;
+}

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

@@ -0,0 +1,39 @@
+import type { EgressTranscodeRequest } from '../capabilities/stream-broker.cap.js';
+/**
+ * The fields that describe WHAT IS ENCODED. Everything outside this shape is
+ * excluded on purpose:
+ *
+ * - `hostname` only rewrites the DIAL address of a restreamer that is the same
+ *   object either way (`substituteRtspHost`), so folding it in would fork the
+ *   child once per consuming node;
+ * - `tag` is attribution for the broker panel.
+ */
+interface CanonicalEgressPlan {
+    readonly deviceId: number;
+    readonly source: string;
+    readonly video: Readonly<Record<string, string | number>>;
+    readonly audio: Readonly<Record<string, string | number>>;
+    readonly rateControl: string;
+    readonly bitstreamFilter: string;
+    readonly pixelFormat: string;
+    readonly decodeHwAccel: string;
+}
+/**
+ * The normalised plan a key is computed from. Exported so a test — and a
+ * 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;
+/**
+ * The refcount / dedup key. `canonicalHash` sorts object keys at every depth,
+ * so a request built with a different field order produces the same digest.
+ *
+ * The handle this keys is IMMUTABLE: there is no `reconfigure`. A consumer
+ * whose requirements change RELEASES and re-acquires; the refcount does the
+ * rest. That is what stops co-tenants disturbing each other — the co-tenant
+ * hazard that made Alexa's shared `derived:alexa-<id>` stream a hazard was
+ * exactly a mutable shared object, where one consumer's downgrade dragged
+ * every other consumer to 360p.
+ */
+export declare function egressTranscodeSharingKey(request: EgressTranscodeRequest): string;
+export {};

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

@@ -4370,6 +4370,20 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof notificationRulesCapability.methods.setRuleEnabled.output>;
             meta: object;
         }>;
+        listDeviceMutes: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof notificationRulesCapability.methods.listDeviceMutes.input>;
+            output: z.infer<typeof notificationRulesCapability.methods.listDeviceMutes.output>;
+            meta: object;
+        }>;
+        setDeviceMuted: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof notificationRulesCapability.methods.setDeviceMuted.input>;
+            output: z.infer<typeof notificationRulesCapability.methods.setDeviceMuted.output>;
+            meta: object;
+        }>;
         testRule: TRPCMutationProcedure<{
             input: {
                 [x: string]: unknown;
@@ -4735,6 +4749,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof pipelineAnalyticsCapability.methods.deleteTracks.output>;
             meta: object;
         }>;
+        setTrackFlags: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof pipelineAnalyticsCapability.methods.setTrackFlags.input>;
+            output: z.infer<typeof pipelineAnalyticsCapability.methods.setTrackFlags.output>;
+            meta: object;
+        }>;
         getEventStoreFootprint: TRPCQueryProcedure<{
             input: {
                 [x: string]: unknown;
@@ -5358,6 +5379,20 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof pipelineOrchestratorCapability.methods.resolvePipeline.output>;
             meta: object;
         }>;
+        getCameraSwitches: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof pipelineOrchestratorCapability.methods.getCameraSwitches.input>;
+            output: z.infer<typeof pipelineOrchestratorCapability.methods.getCameraSwitches.output>;
+            meta: object;
+        }>;
+        setCameraSwitch: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof pipelineOrchestratorCapability.methods.setCameraSwitch.input>;
+            output: z.infer<typeof pipelineOrchestratorCapability.methods.setCameraSwitch.output>;
+            meta: object;
+        }>;
         getCameraStatus: TRPCQueryProcedure<{
             input: {
                 [x: string]: unknown;
@@ -5477,6 +5512,13 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof pipelineRunnerCapability.methods.runDetailSubtree.output>;
             meta: object;
         }>;
+        runStatelessStep: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof pipelineRunnerCapability.methods.runStatelessStep.input>;
+            output: z.infer<typeof pipelineRunnerCapability.methods.runStatelessStep.output>;
+            meta: object;
+        }>;
     }>>;
     plateGallery: TRPCBuiltRouter<{
         ctx: TrpcContext;
@@ -6827,6 +6869,20 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof streamBrokerCapability.methods.releaseStreamWithCodec.output>;
             meta: object;
         }>;
+        acquireEgressTranscode: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof streamBrokerCapability.methods.acquireEgressTranscode.input>;
+            output: z.infer<typeof streamBrokerCapability.methods.acquireEgressTranscode.output>;
+            meta: object;
+        }>;
+        releaseEgressTranscode: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof streamBrokerCapability.methods.releaseEgressTranscode.input>;
+            output: z.infer<typeof streamBrokerCapability.methods.releaseEgressTranscode.output>;
+            meta: object;
+        }>;
         subscribeAudioChunks: TRPCMutationProcedure<{
             input: {
                 [x: string]: unknown;
@@ -8274,14 +8330,14 @@ export type AppRouter = TrpcCoreRouter<{
     }, import("@trpc/server").TRPCDecorateCreateRouterOptions<{
         listCapabilities: import("@trpc/server").TRPCQueryProcedure<{
             input: void;
-            output: import("@camstack/types").CapabilityInfo[];
+            output: import("packages/types/dist").CapabilityInfo[];
             meta: object;
         }>;
         getCapability: import("@trpc/server").TRPCQueryProcedure<{
             input: {
                 name: string;
             };
-            output: import("@camstack/types").CapabilityInfo | null;
+            output: import("packages/types/dist").CapabilityInfo | null;
             meta: object;
         }>;
         setActiveSingleton: import("@trpc/server").TRPCMutationProcedure<{
@@ -8353,14 +8409,14 @@ export type AppRouter = TrpcCoreRouter<{
     }>> & import("@trpc/server").TRPCDecorateCreateRouterOptions<{
         listCapabilities: import("@trpc/server").TRPCQueryProcedure<{
             input: void;
-            output: import("@camstack/types").CapabilityInfo[];
+            output: import("packages/types/dist").CapabilityInfo[];
             meta: object;
         }>;
         getCapability: import("@trpc/server").TRPCQueryProcedure<{
             input: {
                 name: string;
             };
-            output: import("@camstack/types").CapabilityInfo | null;
+            output: import("packages/types/dist").CapabilityInfo | null;
             meta: object;
         }>;
         setActiveSingleton: import("@trpc/server").TRPCMutationProcedure<{

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

@@ -273,7 +273,7 @@ export interface DeviceProxy {
     readonly faceGallery: Pick<InferDeviceProxyCap<typeof faceGalleryCapability>, 'getFaceByTrack'>;
     readonly networkQuality: Pick<InferDeviceProxyCap<typeof networkQualityCapability>, 'getDeviceStats' | 'reportClientStats'>;
     readonly pipelineExecutor: Pick<InferDeviceProxyCap<typeof pipelineExecutorCapability>, 'runPipeline' | 'runPipelineBatch'>;
-    readonly pipelineOrchestrator: Pick<InferDeviceProxyCap<typeof pipelineOrchestratorCapability>, 'assignPipeline' | 'unassignPipeline' | 'setPipelineDevicePin' | 'getPipelineDevicePin' | 'getPipelineAssignment' | 'getCameraMetrics' | 'assignAudio' | 'unassignAudio' | 'getAudioAssignment' | 'getAudioAssignments' | 'getCameraSettings' | 'setCameraStepToggle' | 'getCameraStepOverrides' | 'setCameraStepOverride' | 'setCameraPipelineForAgent' | 'resolvePipeline' | 'getCameraStatus' | 'getDeviceSettingsContribution' | 'getDeviceLiveContribution' | 'applyDeviceSettingsPatch'>;
+    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'>;

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: 866 method paths across 120 capabilities.
+ * Coverage: 874 method paths across 120 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {