Measurement preparation

After successfully installing, initializing and optionally configuring the SDK, your app should be ready to start the video measurement.

Before starting the measurement, the user should be instructed to keep a stable position without talking and changing the facial expression.

Initial conditions

After initialization, the SDK will start to analyze the video stream from the camera.

In order for the measurement to begin, the user needs to locate their face in the middle of the screen, in good lighting conditions. The embedded user interface displays face positioning hints, but you can also use the GetFaceState() and GetNormalizedFaceBbox() methods to check the current face position.


import 'package:shenai_sdk/shenai_sdk.dart';
 
// Get the current face state
final faceState = await ShenaiSdk.getFaceState();
 
switch (faceState) {
  case FaceState.ok:
    print("Face detected and centered");
    break;
  case FaceState.notCentered:
    print("Face detected but not centered");
    break;
  case FaceState.tooClose:
    print("Face is too close");
    break;
  case FaceState.tooFar:
    print("Face is too far");
    break;
  case FaceState.notVisible:
    print("Face is not visible");
    break;
  case FaceState.unknown:
    print("Unknown face state");
    break;
}
 
// Get the normalized bounding box of the face
final bbox = await ShenaiSdk.getNormalizedFaceBbox();
if (bbox != null) {
  print("normalized face bounding box: ${bbox.x} ${bbox.y} ${bbox.width} ${bbox.height}");
}


import { getFaceState, getNormalizedFaceBbox, FaceState } from 'react-native-shenai-sdk';
 
// Get the current face state
const faceState = await getFaceState();
 
switch (faceState) {
  case FaceState.OK:
    console.log("Face detected and centered");
    break;
  case FaceState.NOT_CENTERED:
    console.log("Face detected but not centered");
    break;
  case FaceState.TOO_CLOSE:
    console.log("Face is too close");
    break;
  case FaceState.TOO_FAR:
    console.log("Face is too far");
    break;
  case FaceState.NOT_VISIBLE:
    console.log("Face is not visible");
    break;
  case FaceState.UNKNOWN:
    console.log("Unknown face state");
    break;
}
 
// Get the normalized bounding box of the face
const bbox = await getNormalizedFaceBbox();
if (bbox) {
  console.log("normalized face bounding box:", bbox.x, bbox.y, bbox.width, bbox.height);
}


import { ShenaiSdkCapacitor, FaceState } from 'capacitor-shenai-sdk';
 
// Get the current face state
const { value: faceState } = await ShenaiSdkCapacitor.getFaceState();
 
switch (faceState) {
  case FaceState.OK:
    console.log("Face detected and centered");
    break;
  case FaceState.NOT_CENTERED:
    console.log("Face detected but not centered");
    break;
  case FaceState.TOO_CLOSE:
    console.log("Face is too close");
    break;
  case FaceState.TOO_FAR:
    console.log("Face is too far");
    break;
  case FaceState.NOT_VISIBLE:
    console.log("Face is not visible");
    break;
  case FaceState.UNKNOWN:
    console.log("Unknown face state");
    break;
}
 
// Get the normalized bounding box of the face
const bbox = await ShenaiSdkCapacitor.getNormalizedFaceBbox();
if (bbox) {
  console.log("normalized face bounding box:", bbox.x, bbox.y, bbox.width, bbox.height);
}


using Shenai.Maui;
 
// Get the current face state
var faceState = await ShenaiSdk.GetFaceStateAsync();
 
switch (faceState)
{
    case FaceState.OK:
        Console.WriteLine("Face detected and centered");
        break;
    case FaceState.NOT_CENTERED:
        Console.WriteLine("Face detected but not centered");
        break;
    case FaceState.TOO_CLOSE:
        Console.WriteLine("Face is too close");
        break;
    case FaceState.TOO_FAR:
        Console.WriteLine("Face is too far");
        break;
    case FaceState.NOT_VISIBLE:
        Console.WriteLine("Face is not visible");
        break;
    case FaceState.UNKNOWN:
        Console.WriteLine("Unknown face state");
        break;
}
 
// Get the normalized bounding box of the face
var bbox = await ShenaiSdk.GetNormalizedFaceBboxAsync();
if (bbox != null)
{
    Console.WriteLine($"normalized face bounding box: {bbox.X} {bbox.Y} {bbox.Width} {bbox.Height}");
}


// Get the current face state
let faceState = ShenaiSDK.getFaceState()
 
switch faceState {
case .ok:
  print("Face detected and centered")
case .notCentered:
  print("Face detected but not centered")
case .tooClose:
  print("Face is too close")
case .tooFar:
  print("Face is too far")
case .notVisible:
  print("Face is not visible")
case .unknown:
  print("Unknown face state")
}
 
// Get the normalized bounding box of the face
if let bbox = ShenaiSDK.getNormalizedFaceBbox() {
  print("normalized face bounding box: \(bbox.x) \(bbox.y) \(bbox.width) \(bbox.height)")
}


// Get the current face state
ShenAIAndroidSDK.FaceState faceState = shenaiSDKHandler.getFaceState();
 
switch (faceState) {
  case OK:
    System.out.println("Face detected and centered");
    break;
  case NOT_CENTERED:
    System.out.println("Face detected but not centered");
    break;
  case TOO_CLOSE:
    System.out.println("Face is too close");
    break;
  case TOO_FAR:
    System.out.println("Face is too far");
    break;
  case NOT_VISIBLE:
    System.out.println("Face is not visible");
    break;
  case UNKNOWN:
    System.out.println("Unknown face state");
    break;
}
 
// Get the normalized bounding box of the face
ShenAIAndroidSDK.NormalizedFaceBbox bbox = shenaiSDKHandler.getNormalizedFaceBbox();
if (bbox != null) {
  System.out.println("normalized face bounding box: " + bbox.x + " " + bbox.y + " " + bbox.width + " " + bbox.height);
}


import { FaceState } from "shenai-sdk";
 
// Get the current face state
const faceState = shenaiSDK.getFaceState();
 
switch (faceState) {
  case FaceState.OK:
    console.log("Face detected and centered");
    break;
  case FaceState.NOT_CENTERED:
    console.log("Face detected but not centered");
    break;
  case FaceState.TOO_CLOSE:
    console.log("Face is too close");
    break;
  case FaceState.TOO_FAR:
    console.log("Face is too far");
    break;
  case FaceState.NOT_VISIBLE:
    console.log("Face is not visible");
    break;
  case FaceState.TURNED_AWAY:
    console.log("Face turned away");
    break;
  case FaceState.UNKNOWN:
    console.log("Unknown face state");
    break;
}
 
// Get the normalized bounding box of the face
const bbox = shenaiSDK.getNormalizedFaceBbox();
 
console.log("normalized face bounding box:", bbox.x, bbox.y, bbox.width, bbox.height);


// Get the current face state
shen_face_state_t face_state;
shen_get_face_state(ctx, &face_state);
 
switch (face_state) {
  case SHEN_FACE_OK:
    printf("Face detected and centered\n");
    break;
  case SHEN_FACE_NOT_CENTERED:
    printf("Face detected but not centered\n");
    break;
  case SHEN_FACE_TOO_CLOSE:
    printf("Face is too close\n");
    break;
  case SHEN_FACE_TOO_FAR:
    printf("Face is too far\n");
    break;
  case SHEN_FACE_NOT_VISIBLE:
    printf("Face is not visible\n");
    break;
  case SHEN_FACE_TURNED_AWAY:
    printf("Face turned away\n");
    break;
  case SHEN_FACE_UNKNOWN:
    printf("Unknown face state\n");
    break;
}
 
// Get the normalized bounding box of the face
shen_normalized_face_bbox_t bbox;
shen_get_normalized_face_bbox(ctx, &bbox);
printf("normalized face bounding box: %f %f %f %f\n", bbox.x, bbox.y, bbox.width, bbox.height);


from shenai_sdk import FaceState
 
# Get the current face state
face_state = sdk.get_face_state()
 
if face_state == FaceState.OK:
    print("Face detected and centered")
elif face_state == FaceState.NOT_CENTERED:
    print("Face detected but not centered")
elif face_state == FaceState.TOO_CLOSE:
    print("Face is too close")
elif face_state == FaceState.TOO_FAR:
    print("Face is too far")
elif face_state == FaceState.NOT_VISIBLE:
    print("Face is not visible")
elif face_state == FaceState.TURNED_AWAY:
    print("Face turned away")
elif face_state == FaceState.UNKNOWN:
    print("Unknown face state")
 
# Get the normalized bounding box of the face
bbox = sdk.get_face_bbox()
if bbox is not None:
    print("normalized face bounding box:", bbox.x, bbox.y, bbox.width, bbox.height)

Starting the measurement

A measurement can be started either by clicking START in the embedded UI or by calling startMeasurement(). In the embedded UI, START remains inactive until the SDK is ready. For API-driven flows, mirror that behavior by checking isReadyToStartMeasurement() before calling startMeasurement() (for example, to enable/disable your own START button), or by polling readiness if you want to auto-start as soon as possible. Calling startMeasurement() before readiness is reached is a no-op. To stop an active measurement programmatically, call stopMeasurement().

If you want to start automatically as soon as possible, set the operating mode to MEASURE (either in initialization settings or via setOperatingMode), as described in OperatingMode.


if (await ShenaiSdk.isReadyToStartMeasurement()) {
  ShenaiSdk.startMeasurement();
}
// ...
ShenaiSdk.stopMeasurement();


import {
  isReadyToStartMeasurement,
  startMeasurement,
  stopMeasurement
} from 'react-native-shenai-sdk';
 
if (await isReadyToStartMeasurement()) {
  await startMeasurement();
}
// ...
await stopMeasurement();


import { ShenaiSdkCapacitor } from 'capacitor-shenai-sdk';
 
const { value: readyToStart } = await ShenaiSdkCapacitor.isReadyToStartMeasurement();
if (readyToStart) {
  await ShenaiSdkCapacitor.startMeasurement();
}
// ...
await ShenaiSdkCapacitor.stopMeasurement();


using Shenai.Maui;
 
if (await ShenaiSdk.IsReadyToStartMeasurementAsync())
{
    await ShenaiSdk.StartMeasurementAsync();
}
// ...
await ShenaiSdk.StopMeasurementAsync();


if ShenaiSDK.isReadyToStartMeasurement() {
  ShenaiSDK.startMeasurement()
}
// ...
ShenaiSDK.stopMeasurement()


if (shenaiSDKHandler.isReadyToStartMeasurement()) {
  shenaiSDKHandler.startMeasurement();
}
// ...
shenaiSDKHandler.stopMeasurement();


if (shenaiSDK.isReadyToStartMeasurement()) {
  shenaiSDK.startMeasurement();
}
// ...
shenaiSDK.stopMeasurement();


int ready_to_start = 0;
shen_is_ready_to_start_measurement(ctx, &ready_to_start);
if (ready_to_start) {
  shen_start_measurement(ctx);
}
// ...
shen_stop_measurement(ctx);


if sdk.is_ready_to_start_measurement():
    sdk.start_measurement()
# ...
sdk.stop_measurement()

Note that the actual measurement will not start until the user’s face is in the correct position.