.NET 8 wrapper for SmartSpectra on Windows. The managed API wraps the
SmartSpectra C ABI shim with IDisposable, .NET events, and protobuf metrics
types.
Supported Platforms
| Platform | Status | Notes |
|---|---|---|
| Windows 10 / 11 (x64) | Experimental | .NET 8 runtime required |
For platforms not listed above, contact support@presagetech.com if you have a specific need.
Prerequisites
- .NET 8 SDK or Visual Studio 2022 with the .NET desktop development workload
- SmartSpectra native runtime (
smartspectra.dll,smartspectra_capi.dll, and dependencies) - API Key from physiology.presagetech.com — an AI assistant connected to the SmartSpectra MCP Server can fetch it from your account for you
Installation
Add the public stable feed as a package source (one-time):
nuget sources add -Name SmartSpectra `
-Source https://packages.presagetech.com/nuget/index.json
For release candidate builds, also add the RC feed:
nuget sources add -Name SmartSpectra-RC `
-Source https://packages.presagetech.com/nuget-rc/index.json
Add the package to your .csproj:
<!-- Stable release -->
<PackageReference Include="SmartSpectra.Net" Version="<version>" />
<!-- RC build -->
<PackageReference Include="SmartSpectra.Net" Version="<version>-rc.<n>" />
Google.Protobuf, SmartSpectra.Net.Protos, and the native runtime DLLs are
copied to your output directory by the package targets.
Quick Start: Video File
using Presage.SmartSpectra;
var config = new SmartSpectraConfig
{
ApiKey = Environment.GetEnvironmentVariable("SMARTSPECTRA_API_KEY")
?? throw new InvalidOperationException("SMARTSPECTRA_API_KEY is required"),
// Leave empty for the SDK default metrics: chest breathing, abdomen
// breathing, and breathing rate. Pass native MetricType integer values to
// request additional metrics.
RequestedMetrics = Array.Empty<int>(),
};
using var session = SmartSpectraSession.Create(config);
session.ValidationChanged += (_, hint, timestampUs) =>
Console.WriteLine($"Validation: {hint} @ {timestampUs}");
session.MetricsReceived += (metrics, timestampUs) =>
{
var br = metrics.Breathing?.Rate.FirstOrDefault()?.Value;
if (br.HasValue)
Console.WriteLine($"Breathing rate: {br:F1} bpm @ {timestampUs / 1_000_000.0:F1}s");
};
session.ErrorOccurred += error =>
Console.Error.WriteLine($"Error: {error}");
var error = session.RunFile("sample.mp4", timestampsPath: null);
if (!error.Ok)
throw new SmartSpectraException(error);
Quick Start: Custom Frames
Use custom input when your app owns camera capture:
using var session = SmartSpectraSession.Create(config);
var startError = session.StartCustom(FrameTransform.None);
if (!startError.Ok)
throw new SmartSpectraException(startError);
// Push frames from your capture loop. The buffer is consumed synchronously
// during SendFrame; keep it valid for the duration of the call.
var frameError = session.SendFrame(
frameBytes,
width,
height,
strideBytes,
PixelFormat.Nv12,
timestampUs);
if (!frameError.Ok)
Console.Error.WriteLine(frameError);
session.Stop();
session.Wait(timeoutMs: 5000);
API Reference
SmartSpectraConfig
| Property | Type | Description |
|---|---|---|
ApiKey | string | API key authentication |
RequestedMetrics | int[] | Native MetricType integer values. Empty uses the SDK default metrics: chest breathing, abdomen breathing, and breathing rate |
Unavailable metrics: breathing amplitude, apnea, respiratory line length, baseline, and inhale/exhale ratio (MetricType values 3 to 7, since .NET passes raw integers) are Unavailable. Requesting any of them makes RunFile/StartCustom return a SmartSpectraError with code ConfigurationFailed, and the SDK log names them. Remove them from RequestedMetrics.
SmartSpectraSession
Create sessions with SmartSpectraSession.Create(config). The constructor is
not public.
Events — all fire on internal worker threads; marshal to the UI thread if needed.
| Event | Payload | Description |
|---|---|---|
StatusChanged | ProcessingStatus | Graph lifecycle state |
ValidationChanged | (ValidationCode code, string hint, long timestampUs) | Face / imaging readiness |
MetricsReceived | (Metrics metrics, long timestampUs) | Serialized protobuf metrics decoded into managed types |
ErrorOccurred | SmartSpectraError | Runtime error |
FrameDisposed | (bool sent, long timestampUs) | Custom-input frame acceptance result |
Lifecycle methods. The public surface is small:
SmartSpectraSession Create(SmartSpectraConfig config);
SmartSpectraError RunFile(string videoPath, string? timestampsPath = null);
SmartSpectraError StartCustom(FrameTransform transform = FrameTransform.None);
SmartSpectraError SendFrame(ReadOnlySpan<byte> data, int width, int height,
int strideBytes, PixelFormat pixelFormat, long timestampUs);
void Stop();
bool Wait(int timeoutMs = -1);
Error handling
Lifecycle methods (RunFile, StartCustom, SendFrame) return a
SmartSpectraError describing the outcome:
| Property | Type | Description |
|---|---|---|
Code | SmartSpectraErrorCode | Error category — Ok (0) means success |
Message | string | Human-readable detail |
Retryable | bool | true if the caller can safely retry the operation |
Ok | bool | Shorthand for Code == SmartSpectraErrorCode.Ok |
SustainedLowFrameRate (14) means the frame rate stayed too low to measure
reliably, so the session ended. ErrorOccurred delivers it. In a RunFile
session it is not retryable, because the same file stops the same way; RunFile
itself returns ProcessingFailed, as for every error that ends a run. From
StartCustom frames it is retryable: the host may offer a user-initiated fresh
start; do not restart automatically. A SendFrame that meets the stop returns
the same code.
Create throws SmartSpectraException on failure (wrapping a
SmartSpectraError exposed via the Error property) instead of returning
it. Wait throws on an unexpected native status; a timeout simply returns
false.
Metrics
MetricsReceived uses Presage.SmartSpectra.Metrics from
SmartSpectra.Net.Protos. It has the same protobuf fields as the native SDK:
Breathing, Cardio, Face, and Eda.
Enums
ProcessingStatus, ValidationCode, SmartSpectraErrorCode,
FrameTransform, and PixelFormat mirror the native C++ integer values.
Package Layout
SmartSpectra.Net.<version>.nupkg
├── lib/net8.0/
│ ├── SmartSpectra.Net.dll
│ ├── SmartSpectra.Net.Native.dll
│ └── SmartSpectra.Net.Protos.dll
├── runtimes/win-x64/native/
│ ├── smartspectra.dll
│ ├── smartspectra_capi.dll
│ └── opencv_world4100.dll
└── build/
└── SmartSpectra.Net.targets
Thread Safety
All events fire on internal worker threads, not the calling thread. Do not call
SmartSpectraSession methods from inside an event handler without external
synchronization. For UI updates, dispatch to the UI thread:
// WPF
session.MetricsReceived += (metrics, _) =>
Dispatcher.InvokeAsync(() => UpdateUI(metrics));
// WinUI 3
session.MetricsReceived += (metrics, _) =>
DispatcherQueue.TryEnqueue(() => UpdateUI(metrics));
Troubleshooting
| Problem | Fix |
|---|---|
BadImageFormatException | Ensure the project targets x64, not AnyCPU — the native DLLs are x64-only |
DllNotFoundException | Check that the native runtime DLLs are in the output directory |
FileNotFoundException: SmartSpectra.Net.Protos | The protos DLL must be in the same directory as SmartSpectra.Net.dll |
| No metrics callbacks | Check the returned SmartSpectraError from RunFile, StartCustom, or SendFrame |
| Events fire on the wrong thread | Use Dispatcher.InvokeAsync / DispatcherQueue.TryEnqueue to marshal to the UI thread |