Headless Mode

The SDK doesn't ship UI. Register lambdas with SetOnMetrics, SetOnVideoOutput, and SetOnError; rendering is your code's job. The C++ sample apps show reference UI implementations.

Use this when you want to:

• Render metrics in your own UI
• Process metrics with no UI at all (logging, server-side, batch)
• Feed your own frames instead of the SDK's built-in camera

Processing Status

Lifecycle states (same across all platforms):

Example

namespace spectra = presage::smartspectra;

spectra::SmartSpectraConfig config;
config.api_key = "YOUR_API_KEY";
config.requested_metrics = spectra::SmartSpectraConfig::BreathingMetrics();

spectra::SmartSpectra sdk(config);

sdk.SetOnMetrics([](const spectra::Metrics& metrics, int64_t ts) {
    // Process metrics
});

sdk.SetOnVideoOutput([](const spectra::FrameBuffer& frame, int64_t ts) {
    // Optional: render frame in your own UI
});

if (const auto source_error =
        sdk.UseCamera().SetResolution(1280, 720).SetFps(30).Build();
    !source_error.ok()) {
    // Handle setup error
} else if (const auto err = sdk.Start(); !err.ok()) {
    // Handle startup error
}

// ... run until done ...

sdk.Stop();

Custom frame input

For custom frame input instead of the built-in camera:

std::shared_ptr<spectra::CustomInput> handle;
if (auto err = sdk.UseCustomInput().Build(handle); !err.ok()) {
    // Handle setup error: err.FullMessage()
}
// Feed frames manually:
// handle->Send(frame, timestamp_us);
// timestamp_us must be strictly monotonic.

Reading Metrics

SetOnMetrics fires the same way regardless of frame source. See C++ Metrics for the metric request configuration and the metric catalog.

Running Headlessly in CI

Feed a recorded video through UseFile instead of a live camera to run an unattended measurement in a CI pipeline — see Headless Testing in CI for the cross-platform model and prerequisites (API key, network access, your own recorded video).

The minimal_example sample supports this out of the box:

./build/samples/minimal_example/minimal_example \
  --api_key=YOUR_API_KEY --input_video_path=/path/to/video.mp4

The sample plays the file through the same pipeline as a live camera, prints metrics as they arrive, and exits when the file finishes — a non-zero exit code (or no metrics printed) means the run failed. Use a short clip (a few seconds, well-lit, mostly still face) in a widely-supported container/codec such as MP4 (H.264).

A provider-neutral CI step (GitHub Actions), after installing or building the SDK for your platform:

- name: Headless measurement smoke
  run: |
    ./build/samples/minimal_example/minimal_example \
      --api_key="${{ secrets.SMARTSPECTRA_API_KEY }}" \
      --input_video_path=./test-assets/face.mp4

There is no offline mode — the CI runner needs network access to the SmartSpectra service to authenticate and run a measurement.