@smartspectra/node-sdk 3.3.0-rc.3 → 3.3.0-rc.6

package/js/renderer/index.js

@@ -15,6 +15,8 @@
 
 'use strict';
 
+const { FrameTimestampAnchor } = require('./timestamp');
+
 const SUPPORTED_EVENTS = new Set([
     'processingStatus',
     'validationStatus',
@@ -112,13 +114,14 @@ class SmartSpectraSDK {
         this._reader           = null;
         this._frameLoopActive  = false;
         this._frameLoopPromise = null;
-        // Monotonic frame-timestamp ratchet. Lives on the instance (not the
-        // frame loop) so it persists across stop()/start() cycles: the main
-        // process reuses one native session whose per-session monotonic guard
-        // is NOT reset by stop/start, so a fresh camera clock starting lower
-        // than the previous session's last timestamp would otherwise trip
-        // kNonMonotonicTimestamp.
-        this._lastFrameTs      = 0n;
+        // Epoch-anchor + monotonic-ratchet for VideoFrame.timestamp. Lives on
+        // the instance (not the frame loop) so it persists across
+        // stop()/start() cycles: the main process reuses one native session
+        // whose per-session monotonic guard is NOT reset by stop/start, so a
+        // fresh camera clock starting lower than the previous session's last
+        // timestamp would otherwise trip kNonMonotonicTimestamp. See
+        // ./timestamp.js for why the epoch anchor is needed at all.
+        this._frameTimestamps  = new FrameTimestampAnchor();
         // Set true once the AE/AWB/focus lock has been attempted post-Running
         // so we don't try to relock every frame after kRunning.
         this._cameraLocked     = false;
@@ -500,13 +503,11 @@ class SmartSpectraSDK {
                     ctx.drawImage(vf, 0, 0);
                     const imageData = ctx.getImageData(0, 0, vf.codedWidth, vf.codedHeight);
 
-                    // VideoFrame.timestamp is already in microseconds.
-                    // Ratchet to guarantee strict monotonicity across stream
-                    // pauses, re-attaches, and stop()/start() restarts (see
-                    // _lastFrameTs).
-                    let ts = BigInt(vf.timestamp || 0);
-                    if (ts <= this._lastFrameTs) ts = this._lastFrameTs + 1n;
-                    this._lastFrameTs = ts;
+                    // VideoFrame.timestamp is already in microseconds, but in
+                    // the frame's own media-clock domain — anchor it to the
+                    // Unix epoch and ratchet it monotonic (see
+                    // ./timestamp.js).
+                    const ts = this._frameTimestamps.next(vf.timestamp);
 
                     const ab = imageData.data.buffer;
                     this._bridge.postMessage({

package/js/renderer/timestamp.js

@@ -0,0 +1,56 @@
+// js/renderer/timestamp.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+//
+// Anchors a WebCodecs VideoFrame.timestamp (relative to an unspecified
+// internal media clock, NOT the Unix epoch) to wall-clock epoch
+// microseconds, then ratchets it to guarantee strict monotonicity across
+// stream pauses, re-attaches, and stop()/start() restarts. Extracted from
+// the renderer's frame loop into its own module so the anchor + ratchet
+// math is unit-testable in plain Node — renderer/index.js itself needs
+// OffscreenCanvas/MediaStreamTrackProcessor, which don't exist there.
+//
+// Android/iOS/Linux each apply an equivalent one-time boot/mach-to-epoch
+// offset before a camera frame's timestamp reaches the graph
+// (SmartSpectraVitalsProcessor.kt, avfoundation_camera_source.mm,
+// v4l2_camera_source.cc); this is the Electron/WebCodecs binding's
+// counterpart, so Metrics.timestamp is wall-clock-comparable across every
+// binding instead of only self-consistent within one Electron session.
+
+'use strict';
+
+class FrameTimestampAnchor {
+    constructor() {
+        // Set from the first frame passed to next(); null means "not yet
+        // anchored". Persists for the anchor's lifetime (kept on the
+        // instance, not recomputed per stop()/start(), the same reasoning
+        // as _lastFrameTs below — VideoFrame.timestamp's clock domain is
+        // page-navigation-relative, not per-stream).
+        this._epochOffsetUs = null;
+        // Last timestamp handed out, for the monotonic ratchet.
+        this._lastFrameTs = 0n;
+    }
+
+    /**
+     * @param {number|bigint} rawTimestampUs VideoFrame.timestamp — already
+     *   microseconds, but in its own media-clock domain.
+     * @param {number} [nowMs] Wall-clock epoch milliseconds at the moment of
+     *   the first call. Defaults to Date.now(); overridable so callers (and
+     *   tests) can pin a deterministic anchor.
+     * @returns {bigint} Epoch microseconds, strictly greater than every
+     *   previous value returned by this instance.
+     */
+    next(rawTimestampUs, nowMs = Date.now()) {
+        const raw = BigInt(rawTimestampUs || 0);
+        if (this._epochOffsetUs === null) {
+            this._epochOffsetUs = BigInt(nowMs) * 1000n - raw;
+        }
+        let ts = raw + this._epochOffsetUs;
+        if (ts <= this._lastFrameTs) ts = this._lastFrameTs + 1n;
+        this._lastFrameTs = ts;
+        return ts;
+    }
+}
+
+module.exports = { FrameTimestampAnchor };

package/js/smartspectra.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const { Session } = require('./ffi');
+const { Session, ensurePreconfigured } = require('./ffi');
 const {
     ProcessingStatus,
     SmartSpectraLogLevel,
@@ -250,6 +250,10 @@ class SmartSpectraSDK {
 
     _ensureSession() {
         if (this._session) return;
+        // ARTERIAL_PRESSURE_TRACE, EDA_TRACE, and micromotion metrics need the
+        // EMD cache directory Preconfigure() sets up before the graph starts;
+        // best-effort and idempotent, so plain metrics work even if it fails.
+        ensurePreconfigured();
         // Listeners may be added/replaced after start(), so the lookup
         // happens at emit time rather than capture time.
         this._session = new Session(this._options, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartspectra/node-sdk",
-  "version": "3.3.0-rc.3",
+  "version": "3.3.0-rc.6",
   "description": "Node.js (Electron) FFI binding for SmartSpectra vitals measurement",
   "author": "Presage Technologies, Inc.",
   "license": "SEE LICENSE IN LICENSE",
@@ -33,12 +33,14 @@
     "COPYING.LGPLv2.1",
     "COPYING.LGPLv3",
     "THIRD_PARTY_FFMPEG.md",
+    "THIRD_PARTY_NOTICES.txt",
+    "NOTICE",
     "README.md"
   ],
   "scripts": {
     "prepare": "node scripts/gen-proto.cjs",
     "build:proto": "node scripts/gen-proto.cjs",
-    "test": "node test/log-level-pin.js && node test/smoke.js",
+    "test": "node test/log-level-pin.js && node test/renderer-timestamp.js && node test/smoke.js",
     "test:models-allowlist": "node test/models-allowlist.js"
   },
   "keywords": [
@@ -62,19 +64,19 @@
     "registry": "https://registry.npmjs.org/"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "_nativeRuntime_doc": "Per-platform native packages (@smartspectra/node-sdk-<plat>-<arch>) are injected into dependencies at publish time (absent here so source installs don't fetch them). Why hard deps, not optionalDependencies: see js/resolve-native.js.",
   "dependencies": {
     "koffi": "^2.10.0",
     "protobufjs": "^7.5.0",
-    "@smartspectra/node-sdk-linux-x64": "3.3.0-rc.3",
-    "@smartspectra/node-sdk-linux-arm64": "3.3.0-rc.3",
-    "@smartspectra/node-sdk-darwin-arm64": "3.3.0-rc.3",
-    "@smartspectra/node-sdk-win32-x64": "3.3.0-rc.3"
+    "@smartspectra/node-sdk-linux-x64": "3.3.0-rc.6",
+    "@smartspectra/node-sdk-linux-arm64": "3.3.0-rc.6",
+    "@smartspectra/node-sdk-darwin-arm64": "3.3.0-rc.6",
+    "@smartspectra/node-sdk-win32-x64": "3.3.0-rc.6"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^24.0.0",
     "protobufjs-cli": "^1.1.3"
   },
   "_overrides_doc": "tmp is pulled in transitively (protobufjs-cli → tmp) as a build-only devDependency; it is never a runtime dependency and is not shipped to consumers (the published tarball ships js/ + prebuilds only, no node_modules). Pinned to an exact version (not a >= range) to clear GHSA-ph9p-34f9-6g65 (path traversal, affects tmp <0.2.6) AND to keep installs deterministic — an open range would let a future install pull a brand-new, not-yet-vetted release. Bump deliberately. Drop this once protobufjs-cli ships a release whose tmp range is already >=0.2.6.",