@camstack/types 1.2.41 → 1.2.43

package/dist/ffmpeg/invocation.d.ts

@@ -0,0 +1,348 @@
+/**
+ * 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 { AudioEncode, EncodeProfile } from '../encode-profile.js';
+/** Everything that configures the ffmpeg INPUT. Emitted strictly before `-i`. */
+export interface FfmpegInputPlan {
+    /** An RTSP url, a `pipe:0` stdin feed, or a file path. */
+    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[];
+    /**
+     * `-analyzeduration` (microseconds) and `-probesize` (bytes): how long ffmpeg
+     * inspects the input before it emits ANYTHING.
+     *
+     * Unset means ffmpeg's defaults — 5 s and 5 MB — and on a live egress pull
+     * that is a five-second stall before the first packet, paid by whoever is
+     * staring at the player. Measured on the live hub: a HomeKit session on a
+     * 9 fps slot took 9 s from `stream started` to the first packet out of
+     * ffmpeg and 12.2 s to the first key frame. The SLOWER the slot, the longer
+     * the wait, because the default budget is wall-clock over an input that
+     * delivers few frames per second — which is why the 25 fps slot looked fine
+     * and the 9 fps one looked broken.
+     *
+     * Safe to shrink on RTSP specifically: the SDP already declares the codec,
+     * so there is nothing for the probe to discover. Leave unset for inputs that
+     * genuinely need discovery (a file of unknown provenance, a raw pipe).
+     */
+    readonly analyzeDurationUs?: number;
+    readonly probeSizeBytes?: number;
+    /** Caller-supplied input options (an `EncodeProfile.inputArgs`, probe flags). */
+    readonly extraArgs?: readonly string[];
+}
+/** 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;
+    /**
+     * `-force_key_frames expr:gte(t,n_forced*<sec>)` — an IDR every `<sec>`
+     * seconds of OUTPUT time, regardless of what the source does.
+     *
+     * Only a fragmented-MP4 consumer needs this today, and it needs it for a
+     * structural reason rather than a quality one: an fMP4 fragment written with
+     * `frag_keyframe` is cut at a key frame, so the key-frame cadence IS the
+     * fragment cadence. `-g` bounds the GOP the encoder would choose anyway;
+     * this pins the boundary to a wall-clock grid the muxer can meet.
+     *
+     * Structurally absent from {@link FfmpegVideoCopyPlan}: a copy has no
+     * encoder to instruct, and ffmpeg accepts the flag there, warns, and ignores
+     * it — the silent-no-op shape this file exists to prevent.
+     */
+    readonly forceKeyFramesSeconds?: number;
+    readonly bf?: number;
+    readonly bitrateKbps?: number;
+    readonly rateControl?: FfmpegRateControl;
+    /** `-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;
+}
+/**
+ * A fragmented-MP4 bytestream on stdout: `ftyp`+`moov` once, then a
+ * `moof`+`mdat` per fragment. The shape HomeKit Secure Video's recording
+ * delegate consumes, and the shape a CamStack clip source can consume from the
+ * same child (D67's primitive, one fragmenter, two consumers).
+ *
+ * ## Why `frag_keyframe` + `min_frag_duration`, and NOT `frag_duration`
+ *
+ * HKSV requires every media fragment to START on a sync sample. `frag_keyframe`
+ * cuts a fragment at each key frame, which satisfies that by construction.
+ * `-frag_duration` cuts at a wall-clock boundary *whether or not* a key frame
+ * has arrived, so a source whose IDR is late produces a fragment that opens on
+ * a delta frame — accepted by the muxer, rejected by the consumer, and
+ * invisible in an argv test. `-min_frag_duration` is the safe half of the pair:
+ * it only ever DELAYS a cut, so the boundary stays a key frame and a source
+ * with a 1 s GOP does not emit four fragments where one was negotiated.
+ *
+ * The consequence, stated because it decides what the caller must do: the
+ * fragment length is the key-frame cadence, so a caller that wants ~N-second
+ * fragments must also pin {@link FfmpegVideoEncodePlan.forceKeyFramesSeconds}.
+ * On a `copy` plan it cannot, and the fragment length is then whatever the
+ * SOURCE's GOP makes it — `fragmentMs` becomes a floor, not a target.
+ */
+export interface FfmpegFmp4Sink {
+    readonly kind: 'stdout';
+    readonly container: 'mp4';
+    /**
+     * The negotiated fragment length in milliseconds. Emitted as
+     * `-min_frag_duration` (microseconds): no fragment is cut before this much
+     * media has accumulated, and the cut itself still lands on a key frame.
+     */
+    readonly fragmentMs: number;
+}
+export type FfmpegSink = {
+    readonly kind: 'rtsp-listen';
+    readonly url: string;
+} | {
+    readonly kind: 'stdout';
+    readonly container: 'h264' | 'hevc' | 'mpegts';
+} | FfmpegFmp4Sink
+/**
+ * Two independent mapped RTP outputs. Generic ffmpeg RTP vocabulary — the
+ * SRTP encryption, the port allocation and the payload-type numbers stay
+ * 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;
+    /**
+     * How the encoder is bounded. `EncodeProfile` carries a bitrate but not the
+     * WINDOW it is enforced over, and the window is the difference between a
+     * HomeKit stream that fits its per-second budget and one that overshoots on
+     * every key frame. Absent ⇒ the relaxed two-second default a browser wants.
+     *
+     * The three overlays below are on the INVOCATION rather than on
+     * `EncodeProfile` on purpose: they are consumer-protocol facts
+     * (`acquireEgressTranscode` exposes each as its own named request field),
+     * while `EncodeProfile` is the operator-facing shape a derived-stream editor
+     * writes. Folding them into the profile would put ffmpeg detail in front of
+     * an operator who has no way to judge it.
+     */
+    readonly rateControl?: FfmpegRateControl;
+    /** `-bsf:v` — `dump_extra` for a consumer that negotiates its own SDP. */
+    readonly bitstreamFilter?: string;
+    /** `-pix_fmt`. */
+    readonly pixelFormat?: string;
+    /**
+     * `-force_key_frames` on a fixed grid — see
+     * {@link FfmpegVideoEncodePlan.forceKeyFramesSeconds}. An overlay like the
+     * three above rather than an `EncodeProfile` field: it is a CONSUMER-protocol
+     * fact (an fMP4 fragment length the consumer negotiated), not something an
+     * operator authoring a derived stream can judge.
+     *
+     * Applies only to the encode branch. On a smart COPY there is no encoder to
+     * instruct, and the caller — not this adapter — has to decide whether a
+     * source-dictated GOP is acceptable, because only the caller knows what it
+     * promised its consumer.
+     */
+    readonly forceKeyFramesSeconds?: number;
+}
+/**
+ * Adapt an `EncodeProfile` (the operator/consumer-facing shape) into an
+ * {@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,91 @@
+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.
+ *
+ * `publishLocally` is INSIDE the shape, and it is not a delivery detail like
+ * `hostname`. A push child emits MPEG-TS and its demuxed packets go straight
+ * into a published cam stream; a dial child emits an elementary Annex-B
+ * bytestream into a restreamer a consumer dials. Same encode parameters,
+ * completely different transports — so with it excluded, whoever acquired
+ * FIRST decided the transport for every later sharer, and the loser received a
+ * handle whose transport its consumer cannot use.
+ */
+/**
+ * How the encoded bytes REACH the consumer. Three transports, three containers,
+ * three delivery mechanisms — and a child can serve exactly one of them, which
+ * is why this is in the key and `hostname` is not.
+ *
+ * - `dial` — elementary Annex-B into a restreamer the consumer dials.
+ * - `push` — MPEG-TS demuxed straight into a locally published cam stream.
+ * - `fragments` — a fragmented-MP4 byte stream split into an initialisation
+ *   segment plus `moof`+`mdat` units, delivered IN-PROCESS on a subscribable
+ *   plane. No url and no cam stream: the consumer holds an object, not an
+ *   address. Not reachable from `EgressTranscodeRequest` today — see
+ *   {@link egressTransportFromRequest}.
+ */
+export type EgressTransport = 'dial' | 'push' | 'fragments';
+/**
+ * Everything about DELIVERY that decides which child a request lands on.
+ *
+ * It is a second argument rather than fields on `EgressTranscodeRequest`
+ * because the `fragments` transport has no cap surface yet: HKSV's delegate and
+ * the clip source that will share its fragmenter are both in-process consumers,
+ * and putting `fragmentMs` on the request schema now would mean a codegen run
+ * and a `@camstack/system` train for a field nothing off-node can call. When
+ * that changes, {@link egressTransportFromRequest} is the ONE place that learns
+ * to read it, and every sharing decision follows automatically.
+ */
+export interface EgressTransportPlan {
+    readonly transport: EgressTransport;
+    /**
+     * Negotiated fragment length, `fragments` only. In the key: two consumers
+     * that negotiated different fragment lengths are asking for differently-cut
+     * media out of differently-configured muxers, so they cannot share a child.
+     */
+    readonly fragmentMs?: number;
+}
+/**
+ * The transport a CAP request describes. `fragments` is deliberately
+ * unreachable from here — the request schema has no way to ask for it, so the
+ * cap path can never be handed a fragment child by accident.
+ */
+export declare function egressTransportFromRequest(request: EgressTranscodeRequest): EgressTransportPlan;
+interface CanonicalEgressPlan {
+    readonly deviceId: number;
+    readonly source: string;
+    /** See {@link EgressTransport}. */
+    readonly transport: EgressTransport;
+    /** The negotiated fragment length, or `-1` for a transport without one. */
+    readonly fragmentMs: number;
+    readonly video: Readonly<Record<string, string | number>>;
+    readonly audio: Readonly<Record<string, string | number>>;
+    readonly rateControl: string;
+    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, delivery?: EgressTransportPlan): CanonicalEgressPlan;
+/**
+ * The refcount / dedup key. `canonicalHash` sorts object keys at every depth,
+ * so a request built with a different field order produces the same digest.
+ *
+ * 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, delivery?: EgressTransportPlan): string;
+export {};