@camstack/system 1.2.254 → 1.2.255

package/dist/builtins/camera-grid/grid-sentry-sources.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which URL a grid dials for one source: the live stream, or the SENTRY one.
+ *
+ * ## What "sentryMuted" turned out to be
+ *
+ * The operator asked for a stream that *"non esiste ancora"*. It half did.
+ * `SENTRY_PATH_SUFFIX` has existed since the sentry shipped, and
+ * `parseRestreamPath` already answers `muted: true` for it — the sentry path IS
+ * the muted one, by construction, because an `m=audio` nobody fills stalls a
+ * consumer for the hours a camera may sit asleep. What did not exist is the
+ * WRITER that turns an acquired restream url into that dial, and the broker
+ * telling a consumer whether one is on offer. Both are now in
+ * `addon-pipeline/src/stream-broker`: `withSentryIntent`, and `sentryUrl` on
+ * the `getStreamWithCodec` result.
+ *
+ * ## The rule, and the fallback it refuses
+ *
+ * An offered sentry is TAKEN. There is no sleep check and no fallback, and that
+ * is deliberate: "use the sentry if the camera is asleep, otherwise the live
+ * stream" reads reasonable and is exactly the wake. Whether a battery camera is
+ * asleep right now is a fact that changes between the read and the dial, and
+ * the dial is what wakes it. The ONE question asked is the one the broker
+ * already owns — is this camera offered a sentry at all — and the broker only
+ * offers it to a battery camera that declares the signals cap.
+ *
+ * ## What the operator sees
+ *
+ * A cell whose source is asleep composes that camera's last picture, held, for
+ * as long as it sleeps — visible, legible, and obviously not moving. The two
+ * alternatives are the ones D519 and the sentry both exist to refuse: dropping
+ * the cell (a hole an operator files as a broken grid) and dialling the camera
+ * (eleven seconds of battery for five seconds of video, measured on device 640).
+ */
+/** What `streamBroker.getStreamWithCodec` handed back for one source. */
+export interface GridSourceAcquisition {
+    readonly url: string;
+    /**
+     * The sentry counterpart, when the BROKER offers one. Absent and `null` mean
+     * the same thing — this camera has no sentry — and neither is ever resolved
+     * into the live url by guessing.
+     */
+    readonly sentryUrl?: string | null;
+    readonly pipelineKey: string;
+}
+export interface GridSourceDial {
+    readonly url: string;
+    /** The key the acquisition was issued under — releasing anything else leaks a dial. */
+    readonly pipelineKey: string;
+    /** What this cell is actually reading. Logged, so a still cell is never a mystery. */
+    readonly mode: 'live' | 'sentry';
+}
+export declare function gridSourceDial(acquired: GridSourceAcquisition): GridSourceDial;

package/dist/builtins/camera-grid/grid-snapshot.d.ts

@@ -0,0 +1,62 @@
+import { CamProfile } from '@camstack/types';
+import { GridStreamLogger } from './grid-stream-session.js';
+/** Where a grid's last composed frame is kept between compositions. */
+export interface GridLastFrameStore {
+    /** The last frame kept for this grid, or `null` — which is a real answer. */
+    get(deviceId: number): Promise<Buffer | null>;
+    put(deviceId: number, jpeg: Buffer): Promise<void>;
+}
+/** Just enough of a session for the snapshot to choose one and read its state. */
+export interface GridSnapshotSession {
+    readonly profile: CamProfile;
+    isRunning(): boolean;
+}
+export interface GridSnapshotAnswerInput {
+    readonly running: boolean;
+    readonly hasStoredFrame: boolean;
+}
+export type GridSnapshotAnswer = {
+    readonly kind: 'live';
+} | {
+    readonly kind: 'stored';
+} | {
+    readonly kind: 'none';
+    readonly reason: 'never-composed';
+};
+/**
+ * Which of the three answers applies. Pure, so the rule can be read — and
+ * sabotaged — without a socket, a file or an ffmpeg.
+ */
+export declare function gridSnapshotAnswerFor(input: GridSnapshotAnswerInput): GridSnapshotAnswer;
+export interface GridSnapshotImage {
+    readonly base64: string;
+    readonly contentType: string;
+}
+/**
+ * Generic in the session type so the addon can hand over its OWN session
+ * record — the one that also knows the instance and the stream — and get it
+ * back in `sampleFrame` without a cast or a second lookup.
+ */
+export interface GridSnapshotDeps<S extends GridSnapshotSession = GridSnapshotSession> {
+    readonly logger: GridStreamLogger;
+    /**
+     * This grid's sessions, one per published profile, in descending quality.
+     * EMPTY means this addon does not own the device — never "no picture".
+     */
+    readonly sessionsFor: (deviceId: number) => readonly S[];
+    /**
+     * One JPEG out of a composition that is ALREADY running. `null` when the
+     * bytes could not be turned into a frame — which is a miss, not a reason to
+     * start anything.
+     */
+    readonly sampleFrame: (session: S) => Promise<Buffer | null>;
+    readonly store: GridLastFrameStore;
+}
+export declare class GridSnapshotSource<S extends GridSnapshotSession = GridSnapshotSession> {
+    private readonly deps;
+    constructor(deps: GridSnapshotDeps<S>);
+    getSnapshot(deviceId: number): Promise<GridSnapshotImage | null>;
+    private sample;
+    private readStored;
+    private keep;
+}

package/dist/builtins/camera-grid/grid-stream-descriptor.d.ts

@@ -0,0 +1,24 @@
+import { CamProfile, CamStreamDescriptor } from '@camstack/types';
+export interface GridStreamDescriptorInput {
+    /** Which composition this is. Also the `profileHint` — see below. */
+    readonly profile: CamProfile;
+    readonly width: number;
+    readonly height: number;
+    readonly fps: number;
+    /** The on-demand endpoint the broker dials. Dialling it IS the demand. */
+    readonly url: string;
+}
+/**
+ * `profileHint` is load-bearing, not decoration.
+ *
+ * A device publishing a SINGLE stream with no hint is ranked by pixel count,
+ * and a single stream ranks into `mid` — the slot `recordings` does not select
+ * on its own (`high|mid` picks high), that `recordingsLow` ignores, and that
+ * scrub never reads. The Dreame robot's one 720p relay landed exactly there and
+ * its footage was written nowhere anything looked.
+ *
+ * With several compositions published the hint does a second job: it is the
+ * only thing that says which slot each one is FOR. Ranked by pixels a grid's
+ * `mid` would take the `high` slot on any grid whose `high` was not offered.
+ */
+export declare function gridStreamDescriptor(input: GridStreamDescriptorInput): CamStreamDescriptor;

package/dist/builtins/camera-grid/grid-stream-invocation.d.ts

@@ -0,0 +1,29 @@
+import { FfmpegInvocation, FfmpegVideoEncoderId } from '@camstack/types';
+import { GridLayout } from './grid-filter-graph.js';
+/** One ffmpeg input: the camera it is, and the URL this child will dial. */
+export interface GridStreamSource {
+    /** The SOURCE camera. Carried so every log line about it can be tagged. */
+    readonly deviceId: number;
+    /**
+     * A broker restream URL, acquired through `streamBroker.getStreamWithCodec`.
+     * That is the single demand-counted entry point: it rides the broker's ONE
+     * source dial instead of opening a second connection to the camera.
+     */
+    readonly url: string;
+}
+export interface GridStreamInvocationInput {
+    readonly layout: GridLayout;
+    /** In ffmpeg INPUT ORDINAL order — `sources[n]` is the graph's `[n:v]`. */
+    readonly sources: readonly GridStreamSource[];
+    readonly decodeHwAccel: string | null;
+    readonly encoder: FfmpegVideoEncoderId;
+    readonly fps: number;
+    readonly bitrateKbps: number;
+}
+/**
+ * @throws when the layout addresses an input the sources do not contain, or
+ * when there is nothing to compose. Both are plan errors: ffmpeg would refuse
+ * them at start-up with a message about a filter pad, which names the graph
+ * rather than the configuration that produced it.
+ */
+export declare function gridStreamInvocation(input: GridStreamInvocationInput): FfmpegInvocation;

package/dist/builtins/camera-grid/grid-stream-relay.d.ts

@@ -0,0 +1,36 @@
+import { CamProfile } from '@camstack/types';
+import { GridStreamLogger, GridStreamSession } from './grid-stream-session.js';
+/**
+ * Which grid, and WHICH COMPOSITION of it.
+ *
+ * The profile is a path segment and not a query string for the reason the
+ * restream suffixes are (`restream-intent.ts`): the choice belongs to the URL
+ * the consumer was handed, so a broker configured once keeps asking for the
+ * same thing. It is also REQUIRED — there is no default composition. A grid
+ * publishes one stream per profile it can serve, and a dial that named none
+ * would be the broker asking for "whichever", which is how a `low` slot ends
+ * up holding a `high` composition.
+ */
+export interface GridStreamRequest {
+    readonly instanceId: string;
+    readonly profile: CamProfile;
+}
+/** `/grid/<instanceId>/<profile>.flv`, or `null` when it is anything else. */
+export declare function parseGridStreamPath(url: string | undefined): GridStreamRequest | null;
+export interface GridStreamRelayDeps {
+    readonly logger: GridStreamLogger;
+    /** `null` when no grid serves that instance/profile pair right now. */
+    readonly sessionFor: (request: GridStreamRequest) => GridStreamSession | null;
+}
+export declare class GridStreamRelay {
+    private readonly deps;
+    private server;
+    private baseUrl;
+    private readonly open;
+    constructor(deps: GridStreamRelayDeps);
+    start(): Promise<void>;
+    /** The URL a grid's catalog descriptor advertises. Empty before {@link start}. */
+    streamUrl(request: GridStreamRequest): string;
+    private serve;
+    dispose(): Promise<void>;
+}

package/dist/builtins/camera-grid/grid-stream-session.d.ts

@@ -0,0 +1,113 @@
+import { FfmpegVideoEncoderId, IScopedLogger } from '@camstack/types';
+import { Readable } from 'node:stream';
+import { GridLayout } from './grid-filter-graph.js';
+/** The logging surface this session needs — a structural subset of the injected logger. */
+export type GridStreamLogger = Pick<IScopedLogger, 'debug' | 'info' | 'warn' | 'error'>;
+/** One acquired broker handle: what to dial, and what to release it by. */
+export interface GridSourceHandle {
+    readonly url: string;
+    readonly pipelineKey: string;
+}
+/** The spawned ffmpeg, as this session uses it. */
+export interface GridStreamChild {
+    readonly stdout: Readable;
+    stop(): Promise<void>;
+}
+/** Everything the composition needs that is not a per-run acquisition. */
+export interface GridStreamPlan {
+    readonly layout: GridLayout;
+    /** In ffmpeg INPUT ORDINAL order — `sourceDeviceIds[n]` is the graph's `[n:v]`. */
+    readonly sourceDeviceIds: readonly number[];
+    readonly encoder: FfmpegVideoEncoderId;
+    readonly decodeHwAccel: string | null;
+    readonly fps: number;
+    readonly bitrateKbps: number;
+}
+export interface GridStreamSessionDeps {
+    readonly logger: GridStreamLogger;
+    readonly acquireSource: (deviceId: number) => Promise<GridSourceHandle>;
+    readonly releaseSource: (pipelineKey: string) => Promise<void>;
+    readonly startChild: (plan: GridStreamPlan, sources: readonly GridSourceHandle[]) => Promise<GridStreamChild>;
+    /** Teardown debounce. `0` ⇒ tear down the moment the last consumer leaves. */
+    readonly lingerMs?: number;
+}
+export interface GridStreamConsumer {
+    readonly onData: (chunk: Buffer) => void;
+    /** Called once, with WHY, when this consumer's stream ends from our side. */
+    readonly onClose: (reason: string) => void;
+}
+export interface GridStreamHold {
+    close(): void;
+}
+export interface GridStreamSessionOptions {
+    /** The COMPOSITE camera's device id — every log line here is tagged with it. */
+    readonly deviceId: number;
+    readonly deps: GridStreamSessionDeps;
+    /**
+     * The current composition, re-read on every cold start. `null` ⇒ the grid has
+     * no cells yet, which is the normal state of a freshly created grid.
+     */
+    readonly resolvePlan: () => GridStreamPlan | null;
+}
+export declare class GridStreamSession {
+    private readonly options;
+    private readonly consumers;
+    /**
+     * The FLV stream's describing bytes, and where each reader may start.
+     *
+     * Rebuilt with every cold start: a new child means a new header and a new
+     * sequence header, and handing a reader the previous child's would decode
+     * noise. See `flv-join.ts` for why FLV needs this and MPEG-TS did not.
+     */
+    private join;
+    private running;
+    private starting;
+    private lingerTimer;
+    private teardown;
+    private disposed;
+    constructor(options: GridStreamSessionOptions);
+    private get logTags();
+    /** The COMPOSITE camera's device id — what every log line about this grid is tagged with. */
+    get deviceId(): number;
+    isRunning(): boolean;
+    consumerCount(): number;
+    /** Resolves once any in-flight start or teardown has finished. For tests and shutdown. */
+    settled(): Promise<void>;
+    /**
+     * Attach a consumer, starting the composition if this is the first one.
+     *
+     * @throws when the grid has nothing to compose, or a source could not be
+     * acquired. Both are LOGGED before they are thrown: a branch that accepts a
+     * consumer and then produces no media is exactly the branch that reads as
+     * "nothing ever happened".
+     */
+    open(consumer: GridStreamConsumer): Promise<GridStreamHold>;
+    /**
+     * Attach to a composition that is ALREADY running, or refuse.
+     *
+     * The whole difference from {@link open} is the refusal, and the refusal is
+     * the feature. A snapshot of a grid is a frame of the composition — which
+     * only exists while something is watching it — and the operator's rule is
+     * that producing a thumbnail must never be the reason N cameras get dialled.
+     * `open()` would start the composition, acquire every source, and on a
+     * battery camera that is a wake nobody asked for.
+     *
+     * `null` is a real answer: "there is no composition to take a frame from",
+     * which the caller turns into the stored last frame, or into nothing.
+     */
+    openIfRunning(consumer: GridStreamConsumer): GridStreamHold | null;
+    /** Forget a consumer AND the reader holding bytes on its behalf. */
+    private dropConsumer;
+    /**
+     * The child ended on its own. Every consumer is told WHY — a stream that
+     * simply stops is indistinguishable from a stalled one at the far end.
+     */
+    onChildEnded(reason: string): void;
+    dispose(): Promise<void>;
+    private ensureRunning;
+    private startCold;
+    private scheduleTeardownIfIdle;
+    private cancelLinger;
+    private stopNow;
+    private releaseAll;
+}

package/dist/builtins/camera-grid/grid-wire-format.d.ts

@@ -0,0 +1,14 @@
+import { CamStreamKind } from '@camstack/types';
+/** The ffmpeg muxer the composition writes to stdout. */
+export declare const GRID_WIRE_CONTAINER: "flv";
+/** What the relay answers with, and what the sampler must demux. */
+export declare const GRID_WIRE_CONTENT_TYPE = "video/x-flv";
+/** `/grid/<instanceId>/<profile>.flv`. */
+export declare const GRID_WIRE_PATH_SUFFIX = ".flv";
+/**
+ * How the broker must ingest it: `pull-flv` is documented as ALWAYS read
+ * through the ffmpeg source reader with `-c copy`. `pull-http` would have been
+ * the intuitive choice and means MJPEG in this broker — it answers with
+ * `HTTP_MJPEG_H264_OUTPUT_ARGS` and re-encodes an already-encoded H.264.
+ */
+export declare const GRID_WIRE_STREAM_KIND: CamStreamKind;

package/dist/builtins/camera-grid/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Camera Grids — composite cameras built from other cameras.
+ *
+ * The manifest `entry` points at THIS module's build (`./dist/index.js`), and
+ * `vite.config.ts` must carry an `entries` key for every module a manifest
+ * names — a manifest entry is just a string and nothing resolves it at build
+ * time, so a missing key compiles and fails at runtime.
+ * `scripts/check-addon-entries.ts` is what catches that.
+ */
+export { CameraGridAddon } from './addon.js';
+export { CameraGridAddon as default } from './addon.js';
+export { buildGridFilterGraph } from './grid-filter-graph.js';
+export type { GridCell, GridFilterGraph, GridLayout, NormalizedRect, } from './grid-filter-graph.js';
+export { buildGridCameraDeclarations, gridCameraReconciliationIndex, newGridCameraStableId, } from './grid-camera-declarations.js';
+export type { ExistingGridCameraRow, GridCameraConfig, GridCameraDeclaration, } from './grid-camera-declarations.js';
+export { GridCameraDevice, installGridCameraRuntime } from './grid-camera-device.js';
+export type { GridCameraRuntime } from './grid-camera-device.js';
+export { readGridInstances } from './grid-instances.js';
+export type { GridCellConfig, GridInstance } from './grid-instances.js';
+export { gridPlanFor } from './grid-plan.js';
+export type { GridPlanEncodeContext } from './grid-plan.js';
+export { normalizeGridRows } from './grid-row-normalization.js';
+export type { NormalizedGridRows } from './grid-row-normalization.js';
+export { gridStreamDescriptor } from './grid-stream-descriptor.js';
+export { GRID_CAM_STREAM_ID, GRID_PROFILES, gridCamStreamId, gridCanvasFor, offeredGridProfiles, } from './grid-profiles.js';
+export type { GridCanvas, GridProfileOffer } from './grid-profiles.js';
+export { gridSourceDial } from './grid-sentry-sources.js';
+export type { GridSourceAcquisition, GridSourceDial } from './grid-sentry-sources.js';
+export { GridSnapshotSource, gridSnapshotAnswerFor } from './grid-snapshot.js';
+export type { GridLastFrameStore, GridSnapshotAnswer, GridSnapshotDeps, GridSnapshotImage, GridSnapshotSession, } from './grid-snapshot.js';
+export { GridLastFrameFileStore } from './grid-last-frame-store.js';
+export { GridFrameSampler } from './grid-frame-sample.js';
+export type { GridFrameSource, GridSpawn } from './grid-frame-sample.js';
+export type { GridStreamDescriptorInput } from './grid-stream-descriptor.js';
+export { gridStreamInvocation } from './grid-stream-invocation.js';
+export type { GridStreamInvocationInput, GridStreamSource } from './grid-stream-invocation.js';
+export { GridStreamRelay, parseGridStreamPath } from './grid-stream-relay.js';
+export type { GridStreamRelayDeps, GridStreamRequest } from './grid-stream-relay.js';
+export { GridStreamSession } from './grid-stream-session.js';
+export type { GridSourceHandle, GridStreamChild, GridStreamConsumer, GridStreamHold, GridStreamLogger, GridStreamPlan, GridStreamSessionDeps, GridStreamSessionOptions, } from './grid-stream-session.js';
+export { startGridChild } from './grid-child.js';
+export type { GridChildContext } from './grid-child.js';
+export { GRID_SILENCED_CAP_NAMES, silenceAnalysisFor } from './silence-analysis.js';
+export type { SilenceAnalysisDeps } from './silence-analysis.js';