Circadify

Performance & Device Support

Tune the Circadify Android SDK for lower-end devices without changing the backend integration.

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

SettingDefaultPurpose
measurementDurationSeconds30Target time window for the measurement
targetCaptureFps10Upper bound for analysis work before bitmap conversion
minimumAcceptedFrames150Minimum quality frames required to finish
maximumAcceptedFrames720Safety 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.

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
            },
        ),
    ),
)
kotlin
Tip

Start with the defaults. Change capture values only after testing on the exact devices and lighting conditions you plan to support.

Lower-end device behavior

The SDK applies several device-friendly safeguards:

  • Frame analysis is throttled before full bitmap conversion.
  • Frames are converted to bitmaps for detection, but when no face is found the bitmap is recycled immediately instead of being propagated down the pipeline.
  • 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"
        }
    },
)
kotlin

Keep scan UI lightweight. For the scan glow, reach for the SDK's first-party CircadifyOverlayView rather than a hand-rolled overlay that redraws landmarks every frame: it is optimized for per-frame face tracking, only animates while a face is present, and respects the system "remove animations" setting. See Scan Overlay for setup. Otherwise prefer a PreviewView, simple quality indicators, and a stable progress bar.

When to tune

ScenarioSuggested adjustment
Device heats up or preview stuttersLower targetCaptureFps below the default of 10 (e.g. 8) after validation
Scan takes too long to reach uploadImprove lighting/position guidance before lowering minimumAcceptedFrames
Payloads are too large for your network profileLower targetCaptureFps first, then validate confidence
Clinical or regulated workflowKeep defaults or stricter values and validate on approved hardware
Caution

Do not lower minimumAcceptedFrames to hide poor capture quality. Lower frame counts can still process, but confidence may decrease.

Next Steps