Performance & Device Support

The Android SDK is optimized to support a broad range of native Android phones and tablets. The SDK does not require every device to sustain 30 accepted frames per second. Instead, it tracks accepted quality frames and uploads a tensor payload that includes the actual frame count and FPS.

Default capture policy

Setting	Default	Purpose
`measurementDurationSeconds`	`30`	Target time window for the measurement
`targetCaptureFps`	`10`	Upper bound for analysis work before bitmap conversion
`minimumAcceptedFrames`	`150`	Minimum quality frames required to finish
`maximumAcceptedFrames`	`720`	Safety cap for memory and payload size

This policy lets the SDK upload as soon as enough usable signal is available. On slower devices, capture continues only until the minimum frame count is reached or the capture timeout is hit.

Recommended configuration

val sdk = CircadifySDK(
    context = context,
    config = CircadifyConfig(
        apiKey = "ck_live_your_key_here",
        measurementDurationSeconds = 30,
        targetCaptureFps = 10,
        minimumAcceptedFrames = 150,
        maximumAcceptedFrames = 720,
        callbacks = CircadifyCallbacks(
            onProgress = { event ->
                progressBar.progress = event.percent
            },
            onQualityWarning = { warning ->
                statusText.text = warning.message
            },
        ),
    ),
)

Lower-end device behavior

The SDK applies several device-friendly safeguards:

Frame analysis is throttled before full bitmap conversion.
Frames without a detected face are not converted to large ARGB bitmaps.
Readiness requires valid ROI extraction, so users are prompted before capture starts if the face is too far away or partially occluded.
Capture completion is based on accepted quality frames with a timeout, not a fixed 720-frame requirement.
Progress events expose acceptedFrames, targetFrames, captureFps, and remainingSeconds for diagnostics.

UI guidance

Use event.percent for the primary progress indicator. Avoid displaying raw frame counts to end users unless your app is a developer or QA tool.

callbacks = CircadifyCallbacks(
    onProgress = { event ->
        progressBar.progress = event.percent
        statusText.text = when (event.phase) {
            MeasurementPhase.READINESS -> "Checking scan conditions"
            MeasurementPhase.CAPTURING -> "Hold still while measurement completes"
            MeasurementPhase.UPLOADING -> "Uploading scan data"
            MeasurementPhase.PROCESSING -> "Processing result"
            MeasurementPhase.INITIALIZING -> "Starting measurement"
        }
    },
)

Keep scan UI lightweight. Prefer a PreviewView, simple quality indicators, and a stable progress bar over animated overlays that track landmarks every frame.

When to tune

Scenario	Suggested adjustment
Device heats up or preview stutters	Lower `targetCaptureFps` to `10` or `12` after validation
Scan takes too long to reach upload	Improve lighting/position guidance before lowering `minimumAcceptedFrames`
Payloads are too large for your network profile	Lower `targetCaptureFps` first, then validate confidence
Clinical or regulated workflow	Keep defaults or stricter values and validate on approved hardware

Next Steps

Configuration - Full SDK configuration reference
Methods - Measurement lifecycle
Error Handling - Retry and failure handling