@camstack/types 1.2.227 → 1.2.229

package/dist/capabilities/device-manager.cap.d.ts

@@ -252,6 +252,7 @@ export declare const MigrateSwitchReportSchema: z.ZodObject<{
         "object-detection": "object-detection";
         "device-audio": "device-audio";
         "broker-audio": "broker-audio";
+        "event-saving": "event-saving";
     }>;
     outcome: z.ZodEnum<{
         off: "off";
@@ -275,6 +276,7 @@ export declare const MigrateDeviceResultSchema: z.ZodObject<{
             "object-detection": "object-detection";
             "device-audio": "device-audio";
             "broker-audio": "broker-audio";
+            "event-saving": "event-saving";
         }>;
         outcome: z.ZodEnum<{
             off: "off";
@@ -293,6 +295,7 @@ export declare const MigrateDeviceResultSchema: z.ZodObject<{
         "object-detection": "object-detection";
         "device-audio": "device-audio";
         "broker-audio": "broker-audio";
+        "event-saving": "event-saving";
     }>>>;
     swapped: z.ZodBoolean;
 }, z.core.$strip>;
@@ -362,6 +365,7 @@ export declare const deviceManagerCapability: {
                     "object-detection": "object-detection";
                     "device-audio": "device-audio";
                     "broker-audio": "broker-audio";
+                    "event-saving": "event-saving";
                 }>;
                 outcome: z.ZodEnum<{
                     off: "off";
@@ -380,6 +384,7 @@ export declare const deviceManagerCapability: {
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
                 "broker-audio": "broker-audio";
+                "event-saving": "event-saving";
             }>>>;
             swapped: z.ZodBoolean;
         }, z.core.$strip>, "mutation">;

package/dist/capabilities/pipeline-orchestrator.cap.d.ts

@@ -519,6 +519,7 @@ declare const CameraStatusSchema: z.ZodObject<{
         "object-detection": "object-detection";
         "device-audio": "device-audio";
         "broker-audio": "broker-audio";
+        "event-saving": "event-saving";
     }>>>;
     degraded: z.ZodReadonly<z.ZodArray<z.ZodObject<{
         stage: z.ZodEnum<{
@@ -1264,6 +1265,7 @@ export declare const pipelineOrchestratorCapability: {
                     "object-detection": "object-detection";
                     "device-audio": "device-audio";
                     "broker-audio": "broker-audio";
+                    "event-saving": "event-saving";
                 }>;
                 label: z.ZodString;
                 costWhenOff: z.ZodString;
@@ -1324,6 +1326,7 @@ export declare const pipelineOrchestratorCapability: {
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
                 "broker-audio": "broker-audio";
+                "event-saving": "event-saving";
             }>;
             enabled: z.ZodBoolean;
         }, z.core.$strip>, z.ZodObject<{
@@ -1338,6 +1341,7 @@ export declare const pipelineOrchestratorCapability: {
                     "object-detection": "object-detection";
                     "device-audio": "device-audio";
                     "broker-audio": "broker-audio";
+                    "event-saving": "event-saving";
                 }>;
                 label: z.ZodString;
                 costWhenOff: z.ZodString;
@@ -1489,6 +1493,7 @@ export declare const pipelineOrchestratorCapability: {
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
                 "broker-audio": "broker-audio";
+                "event-saving": "event-saving";
             }>>>;
             degraded: z.ZodReadonly<z.ZodArray<z.ZodObject<{
                 stage: z.ZodEnum<{
@@ -1625,6 +1630,7 @@ export declare const pipelineOrchestratorCapability: {
                 "object-detection": "object-detection";
                 "device-audio": "device-audio";
                 "broker-audio": "broker-audio";
+                "event-saving": "event-saving";
             }>>>;
             degraded: z.ZodReadonly<z.ZodArray<z.ZodObject<{
                 stage: z.ZodEnum<{

package/dist/deps/binary-downloader.d.ts

@@ -24,6 +24,18 @@ export interface DownloadOptions {
     readonly archiveFormat?: 'zip' | 'tar.gz' | 'tar.xz';
     /** Relative path within archive to the binary (e.g., 'ffmpeg-6.1/bin/ffmpeg') */
     readonly archiveInnerPath?: string;
+    /**
+     * SHA-256 the downloaded ARCHIVE must have, verified before a byte of it is
+     * extracted.
+     *
+     * Optional only because the python downloader predates it. For ffmpeg it is
+     * not optional in practice: the download is the ONLY source of the binary
+     * every transcode runs through, it arrives over a redirect to a third-party
+     * host, and the publisher ships no checksums of its own — so ours is the only
+     * thing standing between a changed artifact and a silent swap of the most
+     * privileged subprocess this system spawns.
+     */
+    readonly sha256?: string;
 }
 /**
  * Download a binary to the target directory.

package/dist/deps/ffmpeg-artifacts.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The ffmpeg build every CamStack node downloads, per platform and arch.
+ *
+ * ## Why a download, on every node, including the container
+ *
+ * The version of ffmpeg used to be CODE: baked into the image, changeable only
+ * by rebuilding and rolling it. Now it is DATA — this file states the release,
+ * and a node that boots with a different one downloads it. Changing ffmpeg is a
+ * framework bump, not an image rebuild.
+ *
+ * It also settles the licence question by removing it. FFmpeg's licence is
+ * chosen at compile time: the core is LGPL 2.1+, `--enable-gpl` makes it GPL
+ * (for x264/x265), `--enable-version3` makes that v3, and `--enable-nonfree`
+ * makes the result undistributable. These are GPL v3 builds, and we do not
+ * distribute them: the user's own node fetches the archive from the project
+ * that publishes it, so we convey no GPL work and inherit none of the
+ * obligations that come with conveying one. That is the whole reason the image
+ * no longer installs ffmpeg at all — not a technical preference.
+ *
+ * ## Why jellyfin-ffmpeg
+ *
+ * One vendor covering linux-amd64, linux-arm64, darwin-arm64 and darwin-x64
+ * from one release, with the widest hardware surface of anything maintained:
+ * VAAPI, QSV, NVENC/NVDEC, AMF, Vulkan, OpenCL and DRM on amd64, plus Rockchip
+ * MPP on arm64. It reaches the vendor libraries through dlopen trampolines,
+ * so the binary is not linked against a driver stack it may not find.
+ *
+ * **What it still needs from the host, measured 2026-09-19.** On the Unraid
+ * HOST, which has no libva, `-vaapi_device` aborts the process outright —
+ * `implib-gen: libva-drm.so.2: failed to load library ... Assertion '0 &&
+ * "Assertion in generated code"' failed`. Inside our container, which installs
+ * libva plus the iHD driver, the same command encodes: verified end to end with
+ * `testsrc → format=nv12,hwupload → h264_vaapi`. So the image drops ffmpeg and
+ * KEEPS the Intel media stack; the drivers are the part a binary cannot bring.
+ *
+ * ## Why each artifact carries a checksum and a claim
+ *
+ * The download is now the only source, so `sha256` is verified before anything
+ * is extracted — jellyfin publishes no checksums on its release assets, so
+ * these are ours, taken at the version bump. And `expectedHwaccels` is what the
+ * build is supposed to be able to do: a binary that probes short of its own
+ * claim is a source that changed under us, which is precisely what went
+ * unnoticed for months when a static build turned out to carry no VAAPI at all
+ * (D536).
+ */
+/** The pinned jellyfin-ffmpeg release. Changing this is the version change. */
+export declare const FFMPEG_RELEASE: "8.1.2-5";
+/** ffmpeg 8.1.2 is what this release builds — for the log line, not resolution. */
+export declare const FFMPEG_VERSION: "8.1.2";
+export interface FfmpegArtifact {
+    readonly url: string;
+    readonly archiveFormat: 'zip' | 'tar.gz' | 'tar.xz';
+    /** SHA-256 of the ARCHIVE, verified before extraction. */
+    readonly sha256: string;
+    /** Bytes, as published — for the "downloading 60 MB" line. */
+    readonly sizeBytes: number;
+    /**
+     * `-hwaccels` names this build must report. Asserted after download: short of
+     * this is a changed source, not a quiet degradation.
+     */
+    readonly expectedHwaccels: readonly string[];
+}
+/** The artifact for this node, or a refusal naming what was asked for. */
+export declare function getFfmpegArtifact(platform: string, arch: string): FfmpegArtifact;
+/** The URL alone, for a caller that wants nothing else. */
+export declare function getFfmpegDownloadUrl(platform: string, arch: string): string;

package/dist/deps/ffmpeg-binary-source.d.ts

@@ -1,74 +1,72 @@
 /**
- * WHICH ffmpeg a node runs, and why it is never the host's.
+ * WHICH ffmpeg a node runs — one rule, on every node.
  *
- * CamStack spawns ffmpeg for the broker's egress and derived transcodes, the
- * WebRTC transcode leg, the recorder, snapshots and the camera grid. What that
- * binary is compiled with decides whether any of them can use the machine's
- * hardware, so it is not a detail to leave to whatever the host happens to have
- * on its PATH:
+ * ## The rule
  *
- * - a host binary is an unknown version with unknown vendor libraries, and it
- *   changes under us on any host update;
- * - a self-hosted NVR cannot assume the host has ffmpeg at all.
+ * 1. `CAMSTACK_FFMPEG_PATH`, when the operator set it and it exists. Pointing
+ *    at your own build is a deliberate act and it wins over everything.
+ * 2. The pinned build this node has already downloaded, named by release
+ *    (`ffmpeg-<release>`), in `<dataDir>/deps`.
+ * 3. Nothing — the caller downloads it. See `ffmpeg-artifacts.ts`.
  *
- * So the binary is always OURS. Two ways it can be ours, and which one applies
- * is a property of where the node runs — not of an environment variable:
+ * The system PATH is not on that list and must never be. A host binary is an
+ * unknown version with unknown vendor libraries, and it changes under us on any
+ * host update; a self-hosted NVR cannot assume the host has ffmpeg at all
+ * (D536).
  *
- * | Node | Binary |
- * | --- | --- |
- * | our container image | {@link BUNDLED_FFMPEG_PATH}, installed by the image |
- * | anything else (a native macOS agent) | the static build we download into `<dataDir>/deps` |
+ * ## Why the container image is not special any more
  *
- * `BUNDLED_FFMPEG_PATH` is a CamStack-owned path that only our image creates
- * (a link to the ffmpeg the image installs). That is what makes "is this ours?"
- * answerable: `/usr/bin/ffmpeg` is ours INSIDE the image and the host's outside
- * it, and nothing in the process can tell those apart. A path only we ever
- * write can.
+ * It was, for one day: the image installed ffmpeg, CamStack preferred it, and
+ * that made the answer depend on where a node ran — an image node got VAAPI, a
+ * native one got a portable build with none. Now every node downloads the same
+ * pinned build, so:
  *
- * The image build is the reason to prefer it over the download: the image
- * installs Ubuntu's ffmpeg next to the Intel media driver, so it carries VAAPI
- * and QSV. The portable static builds carry neither — measured on the hub,
- * 2026-09-18:
+ *  - the ffmpeg version is DATA, not code: changing it is a framework bump, not
+ *    an image rebuild and a container swap on every machine;
+ *  - we ship no ffmpeg binary, so we convey no GPL work — the node fetches it
+ *    from the project that publishes it;
+ *  - one binary, one set of capabilities, everywhere. A bug that depends on
+ *    which ffmpeg answered stops being possible.
  *
- * ```
- * /data/deps/ffmpeg   7.0.2 johnvansickle static   hwaccels: vdpau
- * /usr/bin/ffmpeg     6.1.1 Ubuntu, in the image   hwaccels: vdpau cuda vaapi qsv drm opencl vulkan
- * ```
+ * What the image still owes is the DRIVERS, which no binary can bring: libva
+ * plus the iHD media driver for Intel. Measured 2026-09-19 — the portable build
+ * encodes VAAPI inside our container and ABORTS on the bare Unraid host, where
+ * `libva-drm.so.2` does not exist.
  *
- * A child spawned with the first one asks for `-hwaccel vaapi` and gets
- * `Device creation failed: -12` — the name parses, the device cannot exist —
- * then transcodes in software with nothing naming the cause.
+ * ## Absent is absent
  *
- * {@link FFMPEG_PATH_ENV} is an operator's VOLUNTARY override, and only that:
- * unset is the normal, correct state on every node, and nothing in the product
- * sets it.
+ * The naming carries the release, so two versions coexist during a change and a
+ * rollback is a file that is already on disk rather than a download.
  */
-/** Where our container image puts the ffmpeg it installs. Only the image writes this. */
-export declare const BUNDLED_FFMPEG_PATH = "/opt/camstack/bin/ffmpeg";
 /** Operator override. Unset on every node unless a human deliberately set it. */
 export declare const FFMPEG_PATH_ENV = "CAMSTACK_FFMPEG_PATH";
-export type FfmpegBinaryOrigin = 'override' | 'bundled' | 'downloaded';
+export type FfmpegBinaryOrigin = 'override' | 'downloaded';
 export interface FfmpegBinaryChoice {
     readonly origin: FfmpegBinaryOrigin;
     readonly path: string;
 }
 export interface FfmpegBinarySourceInput {
     readonly platform: string;
-    /** `<dataDir>/deps/ffmpeg`, where a downloaded copy lands. */
-    readonly downloadedPath: string;
+    /** `<dataDir>/deps/ffmpeg-<release>` — where the pinned build lands. */
+    readonly pinnedPath: string;
     /** The raw value of {@link FFMPEG_PATH_ENV}, or null/empty when unset. */
     readonly override: string | null | undefined;
     readonly exists: (path: string) => boolean;
 }
 /**
- * The binary to use, or `null` when there is nothing yet and one must be
- * downloaded.
+ * The file name the pinned build is stored under.
+ *
+ * Versioned on purpose: a download is then idempotent, two releases can sit
+ * side by side while a change rolls through a cluster, and going back is a path
+ * that already exists instead of a fetch that has to succeed.
+ */
+export declare function ffmpegBinaryName(platform: string): string;
+/**
+ * The binary to use, or `null` when it has to be downloaded first.
  *
  * An override that does not exist is NOT silently skipped — it is an operator
  * mistake, and falling through to a different binary than the one they named
- * would hide it. The caller reports it and carries on with the default, which
- * is the only safe direction: a typo must not stop a node from serving video.
+ * would hide it. The caller reports it and carries on with the pinned build,
+ * which is the only safe direction: a typo must not stop a node serving video.
  */
 export declare function chooseFfmpegBinary(input: FfmpegBinarySourceInput): FfmpegBinaryChoice | null;
-/** The image-provided path for a platform, or `null` where we ship no image. */
-export declare function bundledFfmpegPath(platform: string): string | null;

package/dist/deps/ffmpeg-downloader.d.ts

@@ -1,47 +1,18 @@
 import type { IScopedLogger } from '../interfaces/logging.js';
 /**
- * One artifact per platform+arch: the URL, how it is packed, and what the
- * binary inside is SUPPOSED to be able to do.
+ * The ffmpeg this node runs, downloading the pinned build if it is not here
+ * yet, and reporting what it got.
  *
- * It is a table rather than two functions computing strings because the three
- * facts belong together and drifted apart when they did not:
+ * Order: the operator's `CAMSTACK_FFMPEG_PATH` → the pinned build already on
+ * disk → download it. No PATH, no image copy, no per-platform special case —
+ * see `ffmpeg-binary-source.ts` for why the image stopped being special after
+ * exactly one day.
  *
- * - the darwin branch computed an arch and then discarded it, handing an
- *   Intel Mac an arm64 Mach-O it cannot execute under any translation;
- * - a single `FFMPEG_VERSION = '7.1'` named the version of nothing — the linux
- *   URL is unversioned and serves 7.0.2 — so the inner path built from it never
- *   matched and only the extractor's recursive fallback saved it;
- * - and nothing recorded what a download was expected to be capable of, which
- *   is how a build with no VAAPI at all served every transcode on this fleet
- *   for months (D536).
- *
- * `expectedHwaccels` is that missing claim. It is deliberately EMPTY for the
- * linux static builds: they carry no hardware support and pretending otherwise
- * would make the assertion a lie. That emptiness is the honest description of
- * a portable build, and the reason a node that has an image prefers the image's
- * ffmpeg over this one.
- */
-export interface FfmpegArtifact {
-    readonly url: string;
-    readonly archiveFormat: 'zip' | 'tar.gz' | 'tar.xz';
-    /** `-hwaccels` names this artifact is built with. Empty = none, honestly. */
-    readonly expectedHwaccels: readonly string[];
-}
-/** The artifact for this node, or a refusal naming what was asked for. */
-export declare function getFfmpegArtifact(platform: string, arch: string): FfmpegArtifact;
-/** The URL alone, for a caller that wants nothing else. */
-export declare function getFfmpegDownloadUrl(platform: string, arch: string): string;
-/**
- * Ensure an ffmpeg binary WE provide is available on this node, and report
- * which one and what it can do.
- *
- * Order: the operator's voluntary override → the one our image installed → a
- * copy we already downloaded → download it. The system PATH is not in that
- * list and must never be: see `ffmpeg-binary-source.ts`.
- *
- * The line it logs is the point as much as the path is. "Which ffmpeg am I
- * running, and does it have vaapi" had no answer anywhere in the product, and
- * that is what let a hardware-incapable binary serve every transcode on a hub
- * with a working iGPU for months, silently in software.
+ * The line it logs is half the point. "Which ffmpeg am I running, and does it
+ * have vaapi" had no answer anywhere in the product, and that is what let a
+ * hardware-incapable binary serve every transcode on a hub with a working iGPU
+ * for months. The other half is the assertion beneath it: a build that probes
+ * short of what its artifact claims is a source that changed under us, and it
+ * says so with both lists.
  */
 export declare function ensureFfmpeg(dataDir: string, logger: IScopedLogger): Promise<string>;

package/dist/deps/index.d.ts

@@ -1,3 +1,4 @@
 export { ensureBinary, downloadBinary, findInPath, getPlatformInfo, buildBinaryPath, } from './binary-downloader.js';
-export { ensureFfmpeg, getFfmpegArtifact, getFfmpegDownloadUrl } from './ffmpeg-downloader.js';
+export { ensureFfmpeg } from './ffmpeg-downloader.js';
+export { FFMPEG_RELEASE, getFfmpegArtifact, getFfmpegDownloadUrl } from './ffmpeg-artifacts.js';
 export { ensurePython, installPythonPackages, installPythonRequirements, getPythonDownloadUrl, PYTHON_VERSION, } from './python-downloader.js';

package/dist/index.js

@@ -1072,6 +1072,7 @@ var CameraSwitchIdSchema = zod.z.enum([
 	"device-audio",
 	"broker-audio",
 	"audio-analysis",
+	"event-saving",
 	"recording",
 	"notifications"
 ]);
@@ -1098,6 +1099,7 @@ var CAMERA_SWITCH_ORDER = [
 	"device-audio",
 	"broker-audio",
 	"audio-analysis",
+	"event-saving",
 	"recording",
 	"notifications"
 ];
@@ -1182,6 +1184,13 @@ var AUDIO_ANALYSIS_CAP_NAME = "audio-analysis";
 */
 var PRIVACY_MASK_CAP_NAME = "privacy-mask";
 /**
+* The wrapper that TURNS DETECTIONS INTO STORED HISTORY — tracks, events and
+* their media. Named here for the same reason as the others, and with one
+* extra: it has no gate of its own except this binding, so it is the only
+* thing standing between a camera's detections and the database.
+*/
+var PIPELINE_ANALYTICS_CAP_NAME = "pipeline-analytics";
+/**
 * Every analyser a camera CamStack BUILDS is created with switched off.
 *
 * A grid and a Terminal camera are `DeviceType.Camera`, so every wrapper that
@@ -1210,7 +1219,7 @@ var DERIVED_CAMERA_SILENCED_CAP_NAMES = [
 	"motion-detection",
 	DETECTION_PIPELINE_CAP_NAME,
 	AUDIO_ANALYSIS_CAP_NAME,
-	"pipeline-analytics",
+	PIPELINE_ANALYTICS_CAP_NAME,
 	"scene-monitor"
 ];
 /**
@@ -1272,6 +1281,16 @@ var CAMERA_SWITCH_CATALOG = {
 		},
 		countsAsSwitchedOff: true
 	},
+	"event-saving": {
+		id: "event-saving",
+		label: "Event saving",
+		costWhenOff: "Off: nothing about this camera is written to its history — no tracks, no events and no event snapshots or clips. Detection keeps running and live boxes still appear, so the camera looks busy while its timeline stays empty, and anything that fires ON an event (notification rules, event-triggered recording) has nothing to fire on. Continuous recording is unaffected, and history already written is kept.",
+		authority: {
+			kind: "wrapper-binding",
+			capName: PIPELINE_ANALYTICS_CAP_NAME
+		},
+		countsAsSwitchedOff: true
+	},
 	recording: {
 		id: "recording",
 		label: "Recording",
@@ -59037,6 +59056,7 @@ exports.OsdSourceValueTypeEnum = OsdSourceValueTypeEnum;
 exports.OsdStatusSchema = OsdStatusSchema;
 exports.PET_FEEDER_MANUAL_FEED_MAX = PET_FEEDER_MANUAL_FEED_MAX;
 exports.PET_FEEDER_MANUAL_FEED_MIN = PET_FEEDER_MANUAL_FEED_MIN;
+exports.PIPELINE_ANALYTICS_CAP_NAME = PIPELINE_ANALYTICS_CAP_NAME;
 exports.PIPELINE_FLOW_CAPABILITY_NAMES = PIPELINE_FLOW_CAPABILITY_NAMES;
 exports.PIPELINE_OWNER_CAPABILITY_NAMES = PIPELINE_OWNER_CAPABILITY_NAMES;
 exports.PRIVACY_MASK_CAP_NAME = PRIVACY_MASK_CAP_NAME;