@trillboards/edge-sdk 0.2.3 → 0.2.6

package/dist/RecorderAddressRecovery.js

@@ -0,0 +1,359 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecorderAddressRecovery = void 0;
+exports.normalizeMacAddress = normalizeMacAddress;
+exports.lookupMacAddress = lookupMacAddress;
+exports.rewriteStreamHost = rewriteStreamHost;
+exports.shouldAttemptRecorderAddressRecovery = shouldAttemptRecorderAddressRecovery;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const ChannelProber_1 = require("./ChannelProber");
+const discovery_1 = require("./discovery");
+const OnvifClient_1 = require("./OnvifClient");
+const DEFAULT_RECOVERY_COOLDOWN_MS = 60000;
+const DEFAULT_VALIDATION_TIMEOUT_MS = 8000;
+const ADDRESS_FAILURE_RE = /(timed? out|timeout|econnrefused|connection refused|enetunreach|ehostunreach|network is unreachable|host is unreachable|no route to host|could not resolve|getaddrinfo|not found|\b404\b)/i;
+function normalizeMacAddress(value) {
+    const match = String(value || '').match(/(?:^|[^0-9a-f])([0-9a-f]{1,2}(?:[:-][0-9a-f]{1,2}){5})(?![0-9a-f])/i);
+    if (!match)
+        return null;
+    const normalized = match[1]
+        .split(/[:-]/)
+        .map((octet) => octet.padStart(2, '0'))
+        .join(':')
+        .toLowerCase();
+    return normalized === '00:00:00:00:00:00' ? null : normalized;
+}
+function runAddressCommand(executable, args) {
+    return new Promise((resolve, reject) => {
+        (0, child_process_1.execFile)(executable, args, { timeout: 2000, maxBuffer: 64 * 1024, windowsHide: true }, (error, stdout) => error ? reject(error) : resolve(String(stdout || '')));
+    });
+}
+/** Read one already-contacted LAN host from the operating system's neighbor table. */
+async function lookupMacAddress(host) {
+    const commands = process.platform === 'win32'
+        ? [['arp.exe', ['-a', host]]]
+        : process.platform === 'darwin'
+            ? [['/usr/sbin/arp', ['-n', host]]]
+            : [
+                ['/usr/sbin/ip', ['neigh', 'show', host]],
+                ['ip', ['neigh', 'show', host]],
+                ['/usr/sbin/arp', ['-n', host]],
+                ['arp', ['-n', host]],
+            ];
+    for (const [executable, args] of commands) {
+        try {
+            const mac = normalizeMacAddress(await runAddressCommand(executable, [...args]));
+            if (mac)
+                return mac;
+        }
+        catch {
+            // Try the next platform spelling.
+        }
+    }
+    return null;
+}
+function decoded(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function credentialsFromUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (!parsed.username)
+            return null;
+        return { username: decoded(parsed.username), password: decoded(parsed.password) };
+    }
+    catch {
+        return null;
+    }
+}
+function hostFromUrl(url) {
+    try {
+        return new URL(url).hostname || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Replace only the host, preserving credentials, port, path, query, and RTSPS. */
+function rewriteStreamHost(streamUrl, host) {
+    const parsed = new URL(streamUrl);
+    parsed.hostname = host;
+    return parsed.toString();
+}
+function shouldAttemptRecorderAddressRecovery(error) {
+    const message = error instanceof Error ? error.message : String(error ?? '');
+    return ADDRESS_FAILURE_RE.test(message);
+}
+function onvifPorts(candidate) {
+    const ports = new Set();
+    for (const xaddr of candidate.xaddrs || []) {
+        try {
+            const parsed = new URL(xaddr);
+            ports.add(Number(parsed.port) || (parsed.protocol === 'https:' ? 443 : 80));
+        }
+        catch {
+            // Keep the conventional fallbacks below.
+        }
+    }
+    ports.add(80);
+    ports.add(8899);
+    return [...ports];
+}
+async function defaultSerialMatch(candidate, expectedSerial, credentials) {
+    for (const port of onvifPorts(candidate)) {
+        try {
+            const info = await new OnvifClient_1.OnvifClient({
+                host: candidate.host,
+                port,
+                username: credentials.username,
+                password: credentials.password,
+                timeoutMs: 5000,
+            }).getDeviceInformation();
+            if (String(info.serialNumber || '').trim() === expectedSerial)
+                return true;
+        }
+        catch {
+            // A candidate that is not this recorder is normal during LAN discovery.
+        }
+    }
+    return false;
+}
+/**
+ * Finds a recorder again after DHCP changes its address.
+ *
+ * Recovery is deliberately conservative: the MAC address must match before
+ * credentials are used. An ONVIF serial is then verified when setup captured
+ * one; otherwise an existing channel recipe validates the matched recorder.
+ * Credentials are never tried against an unmatched LAN device.
+ */
+class RecorderAddressRecovery {
+    constructor(config, options = {}) {
+        this.groups = new Map();
+        this.currentHost = new Map();
+        this.inFlight = new Map();
+        this.lastFailedAt = new Map();
+        this.configPath = options.configPath;
+        this.log = options.log ?? (() => undefined);
+        this.cooldownMs = Math.max(1000, options.cooldownMs ?? DEFAULT_RECOVERY_COOLDOWN_MS);
+        this.now = options.now ?? Date.now;
+        this.discover = options.discover ?? discovery_1.discoverOnvifHosts;
+        this.sweep = options.sweep ?? discovery_1.sweepLanForRecorders;
+        this.matchSerial = options.matchSerial ?? defaultSerialMatch;
+        this.lookupMac = options.lookupMac ?? lookupMacAddress;
+        this.validateStream = options.validateStream ?? (async (url, feed) => {
+            const result = await (0, ChannelProber_1.grabOneFrameAnyTransport)(url, {
+                ffmpegPath: feed.ffmpegPath,
+                timeoutMs: DEFAULT_VALIDATION_TIMEOUT_MS,
+            });
+            return result.ok;
+        });
+        for (const camera of config.cameras || []) {
+            if (camera.sourceType !== 'recorder' || !camera.recorder?.id || !camera.rtspUrl)
+                continue;
+            const id = camera.recorder.id;
+            const group = this.groups.get(id) || { identity: camera.recorder, cameras: [] };
+            group.cameras.push(camera);
+            this.groups.set(id, group);
+            const host = hostFromUrl(camera.rtspUrl);
+            if (host && !this.currentHost.has(id))
+                this.currentHost.set(id, host);
+        }
+    }
+    canRecover(feed) {
+        if (!feed.recorder?.id)
+            return false;
+        const identity = this.groups.get(feed.recorder.id)?.identity;
+        return !!identity && !!normalizeMacAddress(identity.mac || '');
+    }
+    async recover(feed, currentUrl, error) {
+        const recorderId = feed.recorder?.id;
+        if (!recorderId || !this.groups.has(recorderId))
+            return null;
+        if (!shouldAttemptRecorderAddressRecovery(error))
+            return null;
+        if (!this.canRecover(feed))
+            return null;
+        const knownHost = this.currentHost.get(recorderId);
+        const failedHost = hostFromUrl(currentUrl);
+        if (knownHost && failedHost && knownHost !== failedHost) {
+            return rewriteStreamHost(currentUrl, knownHost);
+        }
+        const active = this.inFlight.get(recorderId);
+        if (active) {
+            const host = await active;
+            return host ? rewriteStreamHost(currentUrl, host) : null;
+        }
+        const lastFailure = this.lastFailedAt.get(recorderId) || 0;
+        if (this.now() - lastFailure < this.cooldownMs)
+            return null;
+        const attempt = this.findCurrentHost(this.groups.get(recorderId), failedHost)
+            .then((host) => {
+            if (!host) {
+                this.lastFailedAt.set(recorderId, this.now());
+                return null;
+            }
+            this.currentHost.set(recorderId, host);
+            this.updateGroupUrls(recorderId, host);
+            this.persistGroupUrls(recorderId, host);
+            this.log(`[recorder] DHCP address changed to ${host}; updated every channel.`);
+            return host;
+        })
+            .finally(() => this.inFlight.delete(recorderId));
+        this.inFlight.set(recorderId, attempt);
+        const host = await attempt;
+        return host ? rewriteStreamHost(currentUrl, host) : null;
+    }
+    async findCurrentHost(group, failedHost) {
+        const [onvifResult, sweepResult] = await Promise.allSettled([
+            this.discover({ timeoutMs: 4000 }),
+            this.sweep({}),
+        ]);
+        const onvif = onvifResult.status === 'fulfilled' ? onvifResult.value : [];
+        const swept = sweepResult.status === 'fulfilled' ? sweepResult.value : [];
+        const candidates = new Map();
+        for (const candidate of onvif)
+            candidates.set(candidate.host, candidate);
+        for (const candidate of swept) {
+            if (!candidates.has(candidate.host)) {
+                candidates.set(candidate.host, {
+                    host: candidate.host,
+                    xaddrs: candidate.xaddrs || [],
+                    scopes: [],
+                    name: candidate.name,
+                });
+            }
+        }
+        if (failedHost)
+            candidates.delete(failedHost);
+        const expectedMac = normalizeMacAddress(group.identity.mac || '');
+        if (!expectedMac)
+            return null;
+        const firstUrl = group.cameras.find((camera) => !!camera.rtspUrl)?.rtspUrl || '';
+        const credentials = credentialsFromUrl(firstUrl);
+        for (const candidate of candidates.values()) {
+            const candidateMac = normalizeMacAddress((await this.lookupMac(candidate.host)) || '');
+            if (candidateMac !== expectedMac)
+                continue;
+            if (group.identity.serial) {
+                if (!credentials)
+                    return null;
+                return await this.matchSerial(candidate, group.identity.serial, credentials)
+                    ? candidate.host
+                    : null;
+            }
+            // Hardware identity matched. Prove at least one existing channel before
+            // changing all live URLs; credentials are sent only to this matched host.
+            for (const camera of group.cameras) {
+                if (!camera.rtspUrl)
+                    continue;
+                try {
+                    if (await this.validateStream(rewriteStreamHost(camera.rtspUrl, candidate.host), camera)) {
+                        return candidate.host;
+                    }
+                }
+                catch {
+                    // Try another known-good channel on the same recorder.
+                }
+            }
+            return null;
+        }
+        return null;
+    }
+    updateGroupUrls(recorderId, host) {
+        const group = this.groups.get(recorderId);
+        if (!group)
+            return;
+        for (const camera of group.cameras) {
+            if (camera.rtspUrl)
+                camera.rtspUrl = rewriteStreamHost(camera.rtspUrl, host);
+        }
+    }
+    persistGroupUrls(recorderId, host) {
+        if (!this.configPath)
+            return;
+        const resolved = path.resolve(this.configPath);
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+        }
+        catch (error) {
+            this.log(`[recorder] Reconnected at ${host}, but could not read the local config: ${error.message}`);
+            return;
+        }
+        if (!Array.isArray(parsed.cameras))
+            return;
+        parsed.cameras = parsed.cameras.map((camera) => {
+            if (camera.recorder?.id !== recorderId || !camera.rtspUrl)
+                return camera;
+            return { ...camera, rtspUrl: rewriteStreamHost(camera.rtspUrl, host) };
+        });
+        const tempPath = `${resolved}.tmp-${process.pid}-${this.now()}`;
+        try {
+            fs.writeFileSync(tempPath, JSON.stringify(parsed, null, 2) + '\n', { mode: 0o600 });
+            try {
+                fs.chmodSync(tempPath, 0o600);
+            }
+            catch {
+                // Windows ACLs do not use POSIX modes.
+            }
+            fs.renameSync(tempPath, resolved);
+            try {
+                fs.chmodSync(resolved, 0o600);
+            }
+            catch {
+                // Best effort on Windows.
+            }
+        }
+        catch (error) {
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch {
+                // Already moved or never created.
+            }
+            this.log(`[recorder] Reconnected at ${host}, but could not save the new address: ${error.message}`);
+        }
+    }
+}
+exports.RecorderAddressRecovery = RecorderAddressRecovery;
+//# sourceMappingURL=RecorderAddressRecovery.js.map

package/dist/RecorderAddressRecovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecorderAddressRecovery.js","sourceRoot":"","sources":["../src/RecorderAddressRecovery.ts"],"names":[],"mappings":"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"}

package/dist/SceneChangeDetector.d.ts

@@ -0,0 +1,291 @@
+/**
+ * SceneChangeDetector + MotionGate — the connector's ONE motion implementation.
+ *
+ * This is the cheap stage of the cascade that stands in front of the expensive
+ * one: in a real store most frames are an empty aisle, and today every one of
+ * them is decoded, prompted and generated over by Gemma at 6–32 s a frame. The
+ * cheap stage answers "did anything change?" in single-digit milliseconds on a
+ * ~178x100 greyscale frame — about 116x fewer pixels than the 640x480 JPEG the
+ * VLM would otherwise chew through.
+ *
+ * PORTED FROM FRIGATE (MIT), `frigate/motion/improved_motion.py` +
+ * `frigate/config/camera/motion.py`, keeping its defaults and — more
+ * importantly — its two non-obvious behaviors:
+ *
+ *   1. THE BACKGROUND ONLY MOVES AFTER MOTION PERSISTS. `accumulateWeighted`
+ *      runs every frame while the scene is still, but while motion is present
+ *      it runs only once the motion has lasted `BACKGROUND_UPDATE_AFTER_FRAMES`
+ *      (10) frames. Without that rule a slowly-moving object is absorbed into
+ *      the background and becomes invisible mid-walk.
+ *   2. A CALIBRATION STATE MACHINE. A camera flipping its IR-cut filter at dusk
+ *      changes every pixel at once; so does a cloud crossing the sun. Frigate
+ *      treats "more than `lightningThreshold` of the frame moved" as a signal
+ *      to re-enter calibration rather than as motion, and stays calibrating
+ *      until the scene settles (<5% moved AND <=4 regions). We suppress
+ *      VLM-triggering while calibrating for exactly that reason — otherwise
+ *      dusk costs a 16-camera store one full inference storm per day.
+ *
+ * RELATIONSHIP TO THE ANDROID `SceneChangeDetector`. agent-core carries a class
+ * of the same name (`ctv/core/audience/SceneChangeDetector.kt`) built on
+ * luminance-HISTOGRAM chi-squared distance over Android `Bitmap`s. That is the
+ * right shape for a tablet whose camera frames a single face at arm's length,
+ * and the wrong shape here: a person crossing a wide CCTV frame moves a few
+ * percent of the pixels and barely perturbs a global histogram, which is why
+ * this port is region-based (threshold → dilate → connected components) instead.
+ * Two runtimes (Kotlin/Bitmap vs Node/Buffer) with two different jobs; there is
+ * exactly ONE motion implementation on each side, and this is the connector's.
+ */
+/** A single-channel 8-bit frame — what motion actually runs on. */
+export interface GreyFrame {
+    width: number;
+    height: number;
+    /** Row-major, one byte per pixel. */
+    data: Uint8Array;
+}
+/** A motion region, in MOTION-FRAME pixels (not source pixels). */
+export interface MotionBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Foreground pixel count in this region. */
+    area: number;
+}
+export interface MotionDetectResult {
+    /** At least one region survived the contour-area floor. */
+    motion: boolean;
+    boxes: MotionBox[];
+    /** Moving fraction of the frame, 0..1. */
+    pctMotion: number;
+    /** The detector does not yet trust its background model. */
+    calibrating: boolean;
+    /**
+     * Coarse fingerprint of WHERE the motion is. Two frames whose motion sits in
+     * the same cells share a signature — that is what makes a parked car or a
+     * swinging sign cheap (see MotionGate's stationary suppression).
+     */
+    signature: string;
+}
+export interface SceneChangeDetectorOptions {
+    /** Height (px) motion runs at. Frigate default 100. */
+    frameHeight?: number;
+    /** Per-pixel delta that counts as changed. Frigate default 30. */
+    threshold?: number;
+    /** Minimum region size (motion-frame px) that counts. Frigate default 10. */
+    contourArea?: number;
+    /** Background blend rate once settled. Frigate default 0.01. */
+    frameAlpha?: number;
+    /** Background blend rate while calibrating. Frigate default 0.2. */
+    calibratingAlpha?: number;
+    /** Moving fraction above which the frame is a lighting event. Default 0.8. */
+    lightningThreshold?: number;
+    /** Percentile contrast stretch before differencing. Frigate default true. */
+    improveContrast?: boolean;
+}
+/**
+ * The Frigate motion core, one instance per camera feed. Stateful: it owns the
+ * running background model, the contrast history and the calibration state, so
+ * frames must be fed to the SAME instance in capture order.
+ */
+export declare class SceneChangeDetector {
+    private readonly frameHeight;
+    private readonly threshold;
+    private readonly contourArea;
+    private readonly frameAlpha;
+    private readonly calibratingAlpha;
+    private readonly lightningThreshold;
+    private readonly improveContrast;
+    private avgFrame;
+    private avgWidth;
+    private avgHeight;
+    private motionFrameCount;
+    private calibrating;
+    private readonly contrastMin;
+    private readonly contrastMax;
+    private contrastIndex;
+    /** False until the ring has been seeded from a real frame (see CONTRAST_HISTORY). */
+    private contrastSeeded;
+    private framesSeen;
+    constructor(options?: SceneChangeDetectorOptions);
+    /** Height (px) callers must downscale to before calling `detect`. */
+    getFrameHeight(): number;
+    isCalibrating(): boolean;
+    /** Frames fed so far (a feed with 0 has never produced a motion verdict). */
+    getFramesSeen(): number;
+    /**
+     * Forget the background model. Call when the view itself changed (camera
+     * re-opened on a different channel, connector resumed after a long stop) so a
+     * stale baseline cannot report a whole-frame "change" that never happened.
+     */
+    reset(): void;
+    /**
+     * One motion verdict. `frame` must already be greyscale at `frameHeight`
+     * (see `decodeGreyFrame`), which is what keeps this stage ~116x cheaper than
+     * handing the full JPEG to the model.
+     */
+    detect(frame: GreyFrame): MotionDetectResult;
+    /**
+     * Frigate's `improve_contrast`: stretch the 4th–96th percentile band to
+     * 0..255 using the MEAN of the last 50 readings, so one odd frame cannot
+     * yank the mapping and manufacture motion everywhere.
+     */
+    private stretchContrast;
+}
+/** Why a frame was (or was not) sent to the model. */
+export type MotionGateReason = 
+/** Periodic proof-of-life: a genuinely static scene still reports. */
+'heartbeat'
+/** The scene changed. */
+ | 'motion'
+/** Nothing moved. */
+ | 'no_motion'
+/** Background model not trusted yet (startup, or a lighting event). */
+ | 'calibrating'
+/** Motion in the same places as the last analyzed frame (parked car, sign). */
+ | 'stationary'
+/** Motion, but the last analysis is too recent. */
+ | 'rate_limited'
+/** Frame could not be decoded — the gate fails OPEN and analyzes it. */
+ | 'undecodable';
+export interface MotionGateResult {
+    analyze: boolean;
+    reason: MotionGateReason;
+    /** Scene is live — drives the periodic/face-triggered cadence switch. */
+    motion: boolean;
+    pctMotion: number;
+    boxes: MotionBox[];
+}
+export interface MotionGateStats {
+    evaluated: number;
+    analyzed: number;
+    skipped: number;
+    byReason: Record<MotionGateReason, number>;
+    calibrating: boolean;
+    framesSeen: number;
+}
+export interface MotionGateOptions extends SceneChangeDetectorOptions {
+    /**
+     * Analyze at least this often per feed no matter how still the scene is
+     * (ms). This is what keeps "nothing is happening" distinguishable from "the
+     * connector is dead", so it is never optional. Wired to the existing
+     * `periodicIntervalMs` cadence knob.
+     */
+    heartbeatIntervalMs: number;
+    /**
+     * Floor between two motion-triggered analyses of one feed (ms). Wired to the
+     * existing `faceTriggeredIntervalMs` knob, so a busy feed can never analyze
+     * faster than the cadence the config already declares.
+     */
+    minAnalyzeIntervalMs?: number;
+    /**
+     * How many consecutive same-place motion verdicts to suppress before letting
+     * one through. Frigate re-checks a stationary object every `fps * 10` frames
+     * instead of every frame; 10 is that factor. 0 disables suppression.
+     */
+    stationaryReanalyzeEvery?: number;
+    /** Decoder override (tests / hosts without an image library). */
+    decode?: (jpeg: Buffer, targetHeight: number) => Promise<GreyFrame | null>;
+    /** Clock injection for tests. */
+    now?: () => number;
+}
+/**
+ * Per-feed cascade decision: decode cheap → motion → should this frame cost a
+ * VLM call? Owns the feed's `SceneChangeDetector`, its heartbeat clock and its
+ * stationary-suppression counter.
+ *
+ * FAILS OPEN. Any decode failure analyzes the frame. A motion gate that cannot
+ * see must not be allowed to silence a camera — the whole product is the alert
+ * that fires.
+ */
+export declare class MotionGate {
+    private readonly detector;
+    /**
+     * NOT readonly: the still-scene reporting floor tracks the cadence an operator
+     * deploys, and that can now change on a RUNNING connector. It is retuned in
+     * place rather than by rebuilding the gate — see `setHeartbeatIntervalMs`.
+     */
+    private heartbeatIntervalMs;
+    private readonly minAnalyzeIntervalMs;
+    private readonly stationaryReanalyzeEvery;
+    private readonly decodeFrame;
+    private readonly now;
+    private lastAnalyzedAtMs;
+    private lastAnalyzedSignature;
+    private stationarySuppressions;
+    private evaluated;
+    private analyzed;
+    private readonly byReason;
+    constructor(options: MotionGateOptions);
+    /**
+     * Decide whether this JPEG earns an inference. Decision order matters:
+     * heartbeat first (proof-of-life outranks everything), then the motion
+     * verdict, then the suppressions that make a busy-but-boring scene cheap.
+     */
+    evaluate(jpeg: Buffer, nowMs?: number): Promise<MotionGateResult>;
+    /**
+     * Confirm the frame really reached the model. Called by the manager only
+     * after `analyze()` resolves, so a frame the admission gate or the network
+     * dropped does not reset the heartbeat and silence the feed.
+     */
+    markAnalyzed(nowMs?: number): void;
+    /** The still-scene reporting floor currently in force (ms). */
+    getHeartbeatIntervalMs(): number;
+    /**
+     * Retune the still-scene reporting floor WITHOUT forgetting anything.
+     *
+     * Changing a cadence is a statement about how often a still scene must report.
+     * It is NOT a statement that the scene changed, that the camera moved, or that
+     * the last analysis never happened — but rebuilding the gate says all three:
+     * a new `SceneChangeDetector` has no background model, is back in
+     * `calibrating`, has an un-seeded contrast ring (the exact state the
+     * CONTRAST_HISTORY seeding fix exists to avoid), and a null
+     * `lastAnalyzedAtMs`, which makes the very next look heartbeat-DUE and buys a
+     * forced inference per feed for a scene the gate had already proven still.
+     *
+     * The heartbeat is a scalar the next `evaluate()` reads. Moving it is the
+     * whole change.
+     *
+     * @returns true when the interval actually changed.
+     */
+    setHeartbeatIntervalMs(intervalMs: number): boolean;
+    /** Forget the background model (camera re-opened on a different view). */
+    reset(): void;
+    getStats(): MotionGateStats;
+    private decide;
+}
+/** Test seam: forget which decoder was resolved. */
+export declare function resetGreyDecoderCache(): void;
+/**
+ * JPEG → greyscale at `targetHeight`, the ~116x pixel reduction the whole
+ * cascade rests on. `sharp` (a hard dependency of @trillboards/edge-sensing, so
+ * present wherever sensing runs) does it natively; `jpeg-js` is the pure-JS
+ * fallback. Returns null when neither is available, which makes the gate fail
+ * open rather than blind a camera.
+ *
+ * WHY NOT FRIGATE'S LITERAL `INTER_NEAREST`. Frigate picks nearest because
+ * `cv2.resize` nearest is the cheapest thing that exists and it blurs the
+ * result immediately afterwards anyway. sharp's "nearest" is not a true
+ * point-sample — it pre-shrinks on load — so asking for it buys none of
+ * Frigate's determinism and costs the two decoders their agreement (measured
+ * MAD 21.8 grey levels against a real point-sample, versus 4.2 for cubic
+ * against the fallback's box average). Both decoders low-pass before
+ * decimating, which is what the subsequent absdiff+threshold wants, and they
+ * land within ~4 grey levels of each other — far inside the threshold of 30, so
+ * a host with sharp and a host without cannot disagree about whether a scene
+ * moved.
+ */
+export declare function decodeGreyFrame(jpeg: Buffer, targetHeight: number): Promise<GreyFrame | null>;
+/**
+ * RGBA → greyscale + box-average downscale: each output pixel is the mean of
+ * the source rectangle it covers. Averaging (rather than point-sampling) is
+ * what keeps this in step with the sharp path and what stops a single noisy
+ * pixel from surviving a 4.8x decimation into the difference image.
+ */
+export declare function downscaleRgbaToGrey(rgba: Uint8Array, width: number, height: number, targetHeight: number): GreyFrame;
+/**
+ * Quantize motion regions onto a coarse grid so "the same thing is still there"
+ * produces a stable string. Deliberately lossy: a person walking one cell over
+ * changes it, a swinging sign does not.
+ */
+export declare function motionSignature(boxes: MotionBox[], width: number, height: number): string;
+//# sourceMappingURL=SceneChangeDetector.d.ts.map