@smartspectra/node-sdk 3.4.0 → 3.5.0-rc.2

package/README.md

@@ -263,6 +263,20 @@ once the graph reports `Running`. Call `sdk.useMediaStream(stream)` before
 are managed by the host; SDK-acquired streams are released on
 `stop()` / `reset()` / `destroy()`.
 
+For a camera mounted sideways or upside down, pass a `FrameTransform` with the
+stream:
+
+```ts
+import { FrameTransform } from '@smartspectra/node-sdk/renderer';
+sdk.useMediaStream(stream, { frameTransform: FrameTransform.kRotate90CW });
+```
+
+The default is `FrameTransform.kNone`. The SDK rotates or mirrors each frame
+before processing from the next `start()`; your preview element is not
+transformed. The selected transform survives `stop()` / `start()` and `reset()`.
+Each `useMediaStream()` call replaces the previous transform, so pass it again
+when you swap streams.
+
 The renderer uses `MediaStreamTrackProcessor` + `OffscreenCanvas` to
 extract RGBA pixels and ships each frame to the main process via the
 MessagePort. Graph callbacks flow back through the same port.

package/js/renderer/index.d.ts

@@ -4,6 +4,7 @@
 // SPDX-License-Identifier: LicenseRef-Proprietary
 
 import type {
+    FrameTransformValue,
     ProcessingStatusValue,
     ValidationCodeValue,
     SmartSpectraErrorCodeValue,
@@ -52,6 +53,18 @@ export interface RendererSmartSpectraOptions extends SmartSpectraOptions {
     sendTimeoutMs?: number;
 }
 
+/** Options for `useMediaStream()`. */
+export interface MediaStreamOptions {
+    /**
+     * Spatial transform the SDK applies to every frame before processing,
+     * e.g. `FrameTransform.kRotate90CW` for a camera mounted sideways.
+     * Takes effect on the next `start()`; the host's preview is not
+     * transformed. Defaults to `FrameTransform.kNone`; each
+     * `useMediaStream()` call replaces the previous transform.
+     */
+    frameTransform?: FrameTransformValue;
+}
+
 /**
  * Renderer-side `SmartSpectraSDK` for Electron applications. By default
  * the SDK acquires the host's front-facing camera at 1280x720 / 30 fps,
@@ -100,9 +113,10 @@ export declare class SmartSpectraSDK {
      * acquires its own MediaStream with sensible defaults and emits it via
      * the `'streamAvailable'` event. When the host supplies the stream
      * the host also owns its lifecycle; the SDK never stops the original
-     * tracks.
+     * tracks. Throws an `Error` with `code` `kConfigurationFailed` when
+     * `options.frameTransform` is not a `FrameTransform` value.
      */
-    useMediaStream(stream: MediaStream): this;
+    useMediaStream(stream: MediaStream, options?: MediaStreamOptions): this;
 
     /**
      * Begin processing. If no stream was provided via `useMediaStream()`,

package/js/renderer/index.js

@@ -16,6 +16,9 @@
 'use strict';
 
 const { FrameTimestampAnchor } = require('./timestamp');
+const { FrameTransform, SmartSpectraErrorCode } = require('../constants');
+
+const FRAME_TRANSFORM_VALUES = new Set(Object.values(FrameTransform));
 
 const SUPPORTED_EVENTS = new Set([
     'processingStatus',
@@ -109,6 +112,8 @@ class SmartSpectraSDK {
         // false when the host supplied the stream via useMediaStream() —
         // the host owns the lifecycle in that case.
         this._streamOwned      = false;
+        // Applied by the main-process SDK to every frame; sent with `start`.
+        this._frameTransform   = FrameTransform.kNone;
         this._track            = null;
         this._processor        = null;
         this._reader           = null;
@@ -174,13 +179,30 @@ class SmartSpectraSDK {
      *
      * When the host supplies the stream the host also owns its lifecycle —
      * the SDK never stops the original tracks, only its own internal clone.
+     *
+     * `options.frameTransform` (a `FrameTransform` value, default `kNone`)
+     * rotates or mirrors every frame before processing, e.g. for a camera
+     * mounted sideways. It takes effect on the next `start()`; the host
+     * preview is not transformed. Each call replaces the previous stream and
+     * transform, so pass `frameTransform` again when swapping streams.
+     *
+     * @param {MediaStream} stream
+     * @param {Object} [options]
+     * @param {number} [options.frameTransform=FrameTransform.kNone]
      */
-    useMediaStream(stream) {
+    useMediaStream(stream, options) {
         if (!(stream instanceof MediaStream)) {
             throw new TypeError('useMediaStream: argument must be a MediaStream');
         }
+        const frameTransform = options?.frameTransform ?? FrameTransform.kNone;
+        if (!FRAME_TRANSFORM_VALUES.has(frameTransform)) {
+            throw Object.assign(
+                new Error('useMediaStream: frameTransform must be a FrameTransform value'),
+                { code: SmartSpectraErrorCode.kConfigurationFailed, retryable: false });
+        }
         this._stream = stream;
         this._streamOwned = false;
+        this._frameTransform = frameTransform;
         return this;
     }
 
@@ -237,7 +259,7 @@ class SmartSpectraSDK {
         // and drained once the loop starts below.
 
         try {
-            await this._send({ kind: 'start', frameTransform: 0 });
+            await this._send({ kind: 'start', frameTransform: this._frameTransform });
         } catch (err) {
             // _stopFrameLoop is idempotent: cleans up reader/track even if the
             // loop was never started.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartspectra/node-sdk",
-  "version": "3.4.0",
+  "version": "3.5.0-rc.2",
   "description": "Node.js (Electron) FFI binding for SmartSpectra vitals measurement",
   "author": "Presage Technologies, Inc.",
   "license": "SEE LICENSE IN LICENSE",
@@ -40,8 +40,8 @@
   "scripts": {
     "prepare": "node scripts/gen-proto.cjs",
     "build:proto": "node scripts/gen-proto.cjs",
-    "test": "npm run test:types && node --test test/log-level-pin.js test/renderer-timestamp.js test/camera-selection.js test/reset-lifecycle.js test/smoke.js",
-    "test:types": "tsc --noEmit --strict --skipLibCheck --target es2022 --module nodenext test/camera-selection-types.ts",
+    "test": "npm run test:types && node --test test/log-level-pin.js test/renderer-timestamp.js test/renderer-frame-transform.js test/camera-selection.js test/reset-lifecycle.js test/smoke.js",
+    "test:types": "tsc --noEmit --strict --skipLibCheck --target es2022 --module nodenext test/camera-selection-types.ts test/renderer-types.ts",
     "test:models-allowlist": "node test/models-allowlist.js"
   },
   "keywords": [
@@ -71,10 +71,10 @@
   "dependencies": {
     "koffi": "^2.10.0",
     "protobufjs": "^7.6.5",
-    "@smartspectra/node-sdk-linux-x64": "3.4.0",
-    "@smartspectra/node-sdk-linux-arm64": "3.4.0",
-    "@smartspectra/node-sdk-darwin-arm64": "3.4.0",
-    "@smartspectra/node-sdk-win32-x64": "3.4.0"
+    "@smartspectra/node-sdk-linux-x64": "3.5.0-rc.2",
+    "@smartspectra/node-sdk-linux-arm64": "3.5.0-rc.2",
+    "@smartspectra/node-sdk-darwin-arm64": "3.5.0-rc.2",
+    "@smartspectra/node-sdk-win32-x64": "3.5.0-rc.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",