During the measurement

After the measurement has started, you can monitor the stage and progress of the measurement.

Checking the measurement state

To see what is happening underneath you can call the getMeasurementState() method. It returns the following enumeration informing you about the state of the measurement.


enum MeasurementState {
  notStarted,                       // Measurement has not started yet
  waitingForFace,                   // Waiting for face to be properly positioned in the frame
  runningSignalShort,               // Measurement started: Signal is too short for any conclusions
  runningSignalGood,                // Measurement proceeding: Signal quality is good
  runningSignalBad,                 // Measurement stalled due to poor signal quality
  runningSignalBadDeviceUnstable,   // Measurement stalled due to poor signal quality (caused by unstable device)
  finalizing,                       // Measurement capture has ended and final result computation is in progress
  finished,                         // Measurement has finished successfully
  failed,                           // Measurement has failed
}


enum MeasurementState {
  NOT_STARTED = 0, // Measurement has not started yet
  WAITING_FOR_FACE, // Waiting for face to be properly positioned in the frame
  RUNNING_SIGNAL_SHORT, // Measurement started: Signal is too short for any conclusions
  RUNNING_SIGNAL_GOOD, // Measurement proceeding: Signal quality is good
  RUNNING_SIGNAL_BAD, // Measurement stalled due to poor signal quality
  RUNNING_SIGNAL_BAD_DEVICE_UNSTABLE, // Measurement stalled due to poor signal quality (caused by unstable device)
  FINALIZING, // Measurement capture has ended and final result computation is in progress
  FINISHED, // Measurement has finished successfully
  FAILED // Measurement has failed
}


enum MeasurementState {
  NOT_STARTED = 0, // Measurement has not started yet
  WAITING_FOR_FACE, // Waiting for face to be properly positioned in the frame
  RUNNING_SIGNAL_SHORT, // Measurement started: Signal is too short for any conclusions
  RUNNING_SIGNAL_GOOD, // Measurement proceeding: Signal quality is good
  RUNNING_SIGNAL_BAD, // Measurement stalled due to poor signal quality
  RUNNING_SIGNAL_BAD_DEVICE_UNSTABLE, // Measurement stalled due to poor signal quality (caused by unstable device)
  FINALIZING, // Measurement capture has ended and final result computation is in progress
  FINISHED, // Measurement has finished successfully
  FAILED // Measurement has failed
}


public enum MeasurementState
{
    NOT_STARTED = 0,                // Measurement has not started yet
    WAITING_FOR_FACE,               // Waiting for face to be properly positioned in the frame
    RUNNING_SIGNAL_SHORT,           // Measurement started: Signal is too short for any conclusions
    RUNNING_SIGNAL_GOOD,            // Measurement proceeding: Signal quality is good
    RUNNING_SIGNAL_BAD,             // Measurement stalled due to poor signal quality
    RUNNING_SIGNAL_BAD_DEVICE_UNSTABLE, // Measurement stalled due to poor signal quality (caused by unstable device)
    FINALIZING,                     // Measurement capture has ended and final result computation is in progress
    FINISHED,                       // Measurement has finished successfully
    FAILED                          // Measurement has failed
}


enum MeasurementState {
  case notStarted                     // Measurement has not started yet
  case waitingForFace                 // Waiting for face to be properly positioned in the frame
  case runningSignalShort             // Measurement started: Signal is too short for any conclusions
  case runningSignalGood              // Measurement proceeding: Signal quality is good
  case runningSignalBad               // Measurement stalled due to poor signal quality
  case runningSignalBadDeviceUnstable // Measurement stalled due to poor signal quality (caused by unstable device)
  case finalizing                     // Measurement capture has ended and final result computation is in progress
  case finished                       // Measurement has finished successfully
  case failed                         // Measurement has failed
}


enum MeasurementState {
  NOT_STARTED,                        // Measurement has not started yet
  WAITING_FOR_FACE,                   // Waiting for face to be properly positioned in the frame
  RUNNING_SIGNAL_SHORT,               // Measurement started: Signal is too short for any conclusions
  RUNNING_SIGNAL_GOOD,                // Measurement proceeding: Signal quality is good
  RUNNING_SIGNAL_BAD,                 // Measurement stalled due to poor signal quality
  RUNNING_SIGNAL_BAD_DEVICE_UNSTABLE, // Measurement stalled due to poor signal quality (caused by unstable device)
  FINALIZING,                         // Measurement capture has ended and final result computation is in progress
  FINISHED,                           // Measurement has finished successfully
  FAILED                              // Measurement has failed
}


import { MeasurementState } from "@shenai/sdk"
 
// Retrieve the current measurement state
const measurementState = shenaiSDK.getMeasurementState()
 
switch (measurementState) {
  case MeasurementState.NOT_STARTED:
    console.log("Measurement has not started yet")
    break
  case MeasurementState.WAITING_FOR_FACE:
    console.log("Waiting for face to be properly positioned in the frame")
    break
  case MeasurementState.RUNNING_SIGNAL_SHORT:
    console.log("Measurement started: signal is too short for any conclusions")
    break
  case MeasurementState.RUNNING_SIGNAL_GOOD:
    console.log("Measurement proceeding: signal quality is good")
    break
  case MeasurementState.RUNNING_SIGNAL_BAD:
    console.log("Measurement stalled due to poor signal quality")
    break
  case MeasurementState.RUNNING_SIGNAL_BAD_DEVICE_UNSTABLE:
    console.log("Measurement stalled due to device instability")
    break
  case MeasurementState.FINALIZING:
    console.log("Measurement capture has ended and final result computation is in progress")
    break
  case MeasurementState.FINISHED:
    console.log("Measurement has finished successfully")
    break
  case MeasurementState.FAILED:
    console.log("Measurement has failed")
    break
}


shen_measurement_state_t state = SHEN_MEAS_NOT_STARTED;
shen_get_measurement_state(ctx, &state);


state = sdk.get_measurement_state()

After a measurement has been started and the face is properly recognized, the measurement state is one of the RunningSignal* variants. Until at least four heartbeats are available, the measurement remains in RunningSignalShort. After this warm-up, RunningSignalGood means that the SDK has recently detected a heartbeat meeting the configured confidence threshold. If no such heartbeat is detected within the freshness timeout, the state changes to RunningSignalBad, or to RunningSignalBadDeviceUnstable when device instability is detected. These bad-signal states describe signal quality and metric availability, not a stopped measurement. RunningSignalGood does not guarantee that every real-time metric is already available: individual metrics can require additional warm-up time or a longer heartbeat history.

To monitor the end of a measurement, wait for Finished or Failed. Either state indicates that the measurement has concluded.

Tracking the measurement progress

To check the progress of the whole measurement you can call the getMeasurementProgressPercentage() method, returning a floating point number between 0 and 100.

Real-time metrics

During the measurement you can query the SDK for real-time metrics. These metrics are updated every second and calculated over their configured periods. If no heartbeat is detected within the freshness timeout, heartbeat-derived live metrics become unavailable. The embedded UI retains the last displayed values and marks them as stale until fresh metrics are available again.

Heart rate

You can query the real-time heart rate based on either the last 10 or 4 seconds of the measurement. The provided value is the average heart rate over the specified time interval and is expressed in beats per minute (BPM), rounded to the nearest integer.


final hr10s = await ShenaiSdk.getHeartRate10s();
final hr4s = await ShenaiSdk.getHeartRate4s();


import { getHeartRate10s, getHeartRate4s } from "@shenai/react-native-sdk"
 
const hr10s = await getHeartRate10s()
const hr4s = await getHeartRate4s()

You can also use provided React Hooks to get realtime heart rate values:


import { useRealtimeHeartRate, useRealtimeHeartRate4s } from "@shenai/react-native-sdk"
 
const hr10s = useRealtimeHeartRate()
const hr4s = useRealtimeHeartRate4s()


import { ShenaiSdkCapacitor } from "@shenai/capacitor-sdk"
 
const { value: hr10s } = await ShenaiSdkCapacitor.getHeartRate10s()
const { value: hr4s } = await ShenaiSdkCapacitor.getHeartRate4s()


using Shenai.Maui;
 
var hr10s = await ShenaiSdk.GetHeartRate10sAsync();
var hr4s = await ShenaiSdk.GetHeartRate4sAsync();


let hr = ShenaiSDK.getHeartRate10s()
let hr = ShenaiSDK.getHeartRate4s()


int hr10s = shenaiSDKHandler.getHeartRate10s();
int hr4s = shenaiSDKHandler.getHeartRate4s();


const hr10s = shenaiSDK.getHeartRate10s()
const hr4s = shenaiSDK.getHeartRate4s()


int hr_10s = 0;
int hr_4s = 0;
 
shen_get_heart_rate_10s(ctx, &hr_10s);
shen_get_heart_rate_4s(ctx, &hr_4s);


hr_10s = sdk.get_heart_rate_10s()
hr_4s = sdk.get_heart_rate_4s()

The 10 seconds value will be more stable (like a value displayed on a typical smartwatch), while the 4 seconds value will more accurately depict moment-to-moment fluctuations of the heart rate.

HRV and Stress Index

You can query the SDK for real-time Heart Rate Variability and Stress Index values. You can choose the period over which the metrics are calculated. Note that shorter time periods may lead to unstable values, but may be useful in biofeedback scenarios.

See the Measurement Results section for details on the returned structure shape. Note that Breathing Rate and Blood Pressure will be null in the result of getRealtimeMetrics.


final metrics = await ShenaiSdk.getRealtimeMetrics(30.0);


import { getRealtimeMetrics, MeasurementResults } from '@shenai/react-native-sdk';
 
const metrics: MeasurementResults = await getRealtimeMetrics(30.0);


import { ShenaiSdkCapacitor, MeasurementResults } from '@shenai/capacitor-sdk';
 
const { value: metrics } = await ShenaiSdkCapacitor.getRealtimeMetrics({ periodSec: 30.0 });


using Shenai.Maui;
 
var metrics = await ShenaiSdk.GetRealtimeMetricsAsync(30.0f);


let metrics = ShenaiSDK.getRealtimeMetrics(30.0)


MeasurementResults metrics = shenaiSDKHandler.getRealtimeMetrics(30.0);


const metrics = shenaiSDK.getRealtimeMetrics(30.0)


shen_realtime_metrics_t metrics;
shen_get_realtime_metrics(ctx, 30.0, &metrics);


metrics = sdk.get_realtime_metrics(30.0)

Intervals

You can also query the SDK for real-time heartbeat intervals. Optionally, you can specify the period to limit the returned intervals. Heartbeat intervals are returned independently of live-metric freshness, so earlier intervals may still be available when current heartbeat-derived metrics are unavailable. Each returned heartbeat interval includes the start and end locations (in seconds) and the duration between heartbeats (in milliseconds, rounded to the nearest integer).


final heartbeats = await ShenaiSdk.getRealtimeHeartbeats(30.0);


import { getRealtimeHeartbeats, Heartbeat } from '@shenai/react-native-sdk';
 
const heartbeats: Heartbeat[] = await getRealtimeHeartbeats(30.0);


import { ShenaiSdkCapacitor, Heartbeat } from '@shenai/capacitor-sdk';
 
const { value: heartbeats } = await ShenaiSdkCapacitor.getRealtimeHeartbeats({ periodSec: 30.0 });


using Shenai.Maui;
 
var heartbeats = await ShenaiSdk.GetRealtimeHeartbeatsAsync(30.0f);


let heartbeats = ShenaiSDK.getRealtimeHeartbeats(30.0)


Heartbeat[] heartbeats = shenaiSDKHandler.getRealtimeHeartbeats(30.0);


const heartbeats = shenaiSDK.getRealtimeHeartbeats(30.0)


shen_heartbeat_array_t heartbeats = {0};
shen_get_realtime_heartbeats(ctx, 30.0, &heartbeats);
shen_release_heartbeat_array(&heartbeats);


heartbeats = sdk.get_realtime_heartbeats(30.0)

Signal quality

You can query the SDK for real-time signal quality - the value can be used to provide additional feedback to the user. A higher value means a better signal quality.

The metric follows the same logic as the in-UI quality stars.

The value is a floating point number between 0 and 1, where 1 means highest confidence in the signal.

If Blood Pressure is selected as one of the measurement outputs, this signal quality value reflects environmental conditions relevant for BP estimation.

If Blood Pressure is not selected, the signal quality value reflects conditions used for other selected metrics, such as Heart Rate or HRV.

In practice, the Blood Pressure-focused index value will usually be lower than the base-metric index value, because Blood Pressure estimation requires stricter environmental conditions than HR/HRV.


final signalQuality = await ShenaiSdk.getCurrentSignalQualityMetric();


import { getCurrentSignalQualityMetric } from "@shenai/react-native-sdk"
 
const signal_quality = await getCurrentSignalQualityMetric()


import { ShenaiSdkCapacitor } from "@shenai/capacitor-sdk"
 
const { value: signalQuality } = await ShenaiSdkCapacitor.getCurrentSignalQualityMetric()


using Shenai.Maui;
 
var signalQuality = await ShenaiSdk.GetCurrentSignalQualityMetricAsync();


let signal_quality = ShenaiSDK.getCurrentSignalQualityMetric()


float signalQuality = shenaiSDKHandler.getCurrentSignalQualityMetric();


const signalQuality = shenaiSDK.getCurrentSignalQualityMetric()


float signal_quality = 0.0f;
shen_get_current_signal_quality_metric(ctx, &signal_quality);


signal_quality = sdk.get_current_signal_quality_metric()

Freshness timeout

The freshness timeout adapts to the recent heart rate and ranges from 3 to 6 seconds. A slower heart rate naturally produces longer intervals between heartbeats, so the SDK allows more time before treating metrics as stale. This avoids false interruptions at low heart rates while still making metrics unavailable promptly when new heartbeats stop arriving.

Measurement success

When the Shen.AI SDK engine enters the Finished state it means that the measurement has concluded and computed metrics are available.

See Results to see how to access the results.