Android

Use the Android Java API for bitmap and camera input. The 1.2.4.post1 package includes native InspireFace 1.2.4, the complete portable Java API, face capture and detection snapshots. Kotlin can call the same interfaces.

Start with a bitmap to verify model loading, then connect the camera. The Android build chapter covers source builds and packaging. For desktop applications and services on a regular JVM, use the Java guide.

Choose a package or source build

For an Android app, use the AAR below. The native 1.2.4 Release ZIP is also available for C/C++ or portable Java integration. It includes headers, a JAR and libraries for all three ABIs; models and the complete Android convenience API come with the AAR instead. See native package setup for the ZIP layout and Gradle configuration.

Add JitPack to your dependency repositories in settings.gradle:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

In the application module:

dependencies {
    implementation 'com.github.HyperInspire:inspireface-android-sdk:v1.2.4.post1'
}

The leading v is part of the JitPack version.

The AAR is sufficient for an Android application; no NDK build or separate JNI adapter is needed. If upgrading an app that previously added its own SDK bridge or copied classes, remove those duplicates when switching to this package. Use the source build when you need to modify the native SDK.

Run the example project

The Android example uses CameraX and covers photo analysis, tracking, enrollment and search. Open it in Android Studio with JDK 17 and Android SDK 35. Its Java source level is 8; the build tools use JDK 17.

With an Android device connected and USB debugging enabled, or an emulator using one of the supported ABIs:

git clone https://github.com/tunmx/InspireFace-Example-Android.git
cd InspireFace-Example-Android
./gradlew :app:assembleDebug
./gradlew :app:installDebug

Android Studio writes the SDK location to local.properties; command-line builds can use ANDROID_HOME. The debug APK is under app/build/outputs/apk/debug/. Open a photo feature first, then grant camera permission when entering a camera feature. You can also install the demo app directly.

Add the model and initialize

The AAR already contains Pikachu and Megatron. GlobalLaunch(context, modelName) copies these assets into the application's external files directory and opens the selected pack. Run launch once on the SDK worker, outside the UI thread, and keep sessions alive for the work they own.

import android.content.Context;
import com.insightface.sdk.inspireface.InspireFace;
import com.insightface.sdk.inspireface.base.CustomParameter;
import com.insightface.sdk.inspireface.base.Session;
import com.insightface.sdk.inspireface.jni.CPUEngine;

// Call on the SDK worker. Keep the returned session for subsequent frames.
public static Session openSession(Context context) {
    CPUEngine.setGlobalPowerMode(CPUEngine.PowerMode.NORMAL);
    boolean launched = Boolean.TRUE.equals(InspireFace.GlobalLaunch(
            context.getApplicationContext(), InspireFace.PIKACHU));
    if (!launched) throw new IllegalStateException("Cannot load the model pack");

    CustomParameter options = InspireFace.CreateCustomParameter();
    Session session = InspireFace.CreateSession(
            options, InspireFace.DETECT_MODE_ALWAYS_DETECT, 10, 320, -1);
    if (session == null || session.handle == 0L) {
        throw new IllegalStateException("Cannot create the face session");
    }
    return session;
}

To supply your own pack, place the resource file at app/src/main/assets/inspireface/Pikachu, or manage a local file and pass its path to GlobalLaunch(String resourcePath). InspireFace.ValidateResourcePack(path) can validate an external pack before launch. See model packs for downloads and compatibility.

CPU power mode

NORMAL is the default CPU power policy. HIGH and LOW are also available through CPUEngine.PowerMode; measure latency and power on the target device before changing the policy. Set it before creating sessions. It affects subsequently initialized CPU runtimes and does not change existing sessions, model thread counts or precision. Launch, reload and terminate preserve the setting; do not change it concurrently with model or session initialization.

Detect a bitmap

This method accepts an already-created session and releases the stream even if detection fails:

import android.graphics.Bitmap;
import com.insightface.sdk.inspireface.InspireFace;
import com.insightface.sdk.inspireface.base.ImageStream;
import com.insightface.sdk.inspireface.base.MultipleFaceData;
import com.insightface.sdk.inspireface.base.Session;

public static int detectCount(Session session, Bitmap bitmap) {
    ImageStream stream = InspireFace.CreateImageStreamFromBitmap(
            bitmap, InspireFace.CAMERA_ROTATION_0);
    if (stream == null || stream.handle == 0L) {
        throw new IllegalStateException("Cannot create the image stream");
    }
    try {
        MultipleFaceData faces = InspireFace.ExecuteFaceTrack(session, stream);
        if (faces == null) throw new IllegalStateException("Face detection failed");
        for (int i = 0; i < faces.detectedNum; i++) {
            // Read faces.rects[i], faces.trackIds[i] and faces.trackCounts[i].
            // Extract features with this stream and faces.tokens[i] before releasing it.
        }
        return faces.detectedNum;
    } finally {
        InspireFace.ReleaseImageStream(stream);
    }
}

A count of zero is a valid result; a null result indicates a processing failure. In 1.2.4.post1, ExecuteFaceTrack returns independent Java arrays, including copied tokens and trackCounts. Feature extraction and pipeline analysis still need the matching image stream and should finish before the next frame on the same session.

When the owning worker is finished, call InspireFace.ReleaseSession(session). Release all application sessions before InspireFace.GlobalTerminate(). Use try/finally for streams and sessions in Kotlin as well.

Process camera frames

Create a DETECT_MODE_LIGHT_TRACK session once for the camera sequence. Use a single analysis executor for that session and keep frames ordered. If processing is slower than capture, drop stale frames instead of building an unbounded queue.

CreateImageStreamFromByteBuffer accepts byte[] pixels, width, height, pixel format and rotation. Convert CameraX YUV_420_888 planes to packed NV21 using each plane's row and pixel strides. Keep the converted bytes available until processing finishes, then close the ImageProxy in a finally block.

Handle preview mirroring separately from inference orientation. Image inputs and coordinates describes the raw-frame and display transforms; the example's UprightFaceCameraAnalyzer and frame helpers show its camera-specific choices.

The example rotates NV21 into an upright frame and creates the stream with CAMERA_ROTATION_0. To use SDK rotation, submit the original frame with the corresponding rotation flag and apply the matching transform to the preview.

Optional analysis

Build a CustomParameter with the features you need and pass it to session creation. For pipeline outputs, call MultipleFacePipelineProcess with the requested parameters and check its boolean result before reading getters such as GetFaceQualityConfidence.

Dense landmarks are available from detection tokens in all three detection modes. GetFaceDenseLandmarkFromFaceToken decodes them; GetFaceFiveKeyPointsFromFaceToken provides the five alignment points. No extra JNI bridge or enableDetectModeLandmark flag is required for these outputs.

Only enable the options needed by the screen, and check the selected pack's model capabilities. The guides provide Android tabs for recognition, landmarks, liveness and optional analysis.

Face capture

The AAR includes FaceCapture and FaceDetectionSnapshot; both implement AutoCloseable. Create the capture policy once with FaceCapture.create(session, FaceCapture.defaultConfig()), then pass increasing frame IDs and timestamps to update(stream, frameId, timestampMs). The default track-count filter needs a tracking session.

If the same detection is needed for display and capture, create a FaceDetectionSnapshot and pass it to capture.update(stream, snapshot, frameId, timestampMs). That snapshot creation already runs tracking; avoid tracking the same frame again. snapshot.getFaces() returns copied Java results, including tokens and track counts.

Capture results contain tokens and metadata, not image pixels. Retain the corresponding frame if you need a crop or a recognition feature. Close capture and snapshots before their source session. See face capture for complete code, filters and frame retention.

Full Java API and diagnostics

Use the Android helpers for Bitmap, byte[], ordinary sessions and copied results. For functions closer to the C API, the same AAR provides jni.Native, descriptors in jni.NativeTypes, and constants in jni.NativeConstants. The Java guide and the Java tabs in each feature guide use these portable bindings; they are also available on Android.

Both API layers load the same libInspireFace.so. Release a stream through the layer that created it: InspireFace.ReleaseImageStream for Android bitmap/byte-array helpers, Native.HFReleaseImageStream for portable streams. These layers retain input buffers differently, so do not swap their release calls.

Native preserves C status codes; use InspireFaceException.check(status) to turn a failure into an exception. Existing Android methods generally retain boolean/null failure results. New query and control helpers throw InspireFaceException; CreateSessionV2, five-point decoding and ID enumeration return null on failure.

import android.util.Log;
import com.insightface.sdk.inspireface.InspireFace;
import com.insightface.sdk.inspireface.base.InspireFaceVersion;

public static void logSdkVersion() {
    InspireFaceVersion version = InspireFace.QueryInspireFaceVersion();
    Log.i("InspireFace", "Native " + version.major + "."
            + version.minor + "." + version.patch);
    Log.i("InspireFace", "C API " + InspireFace.QueryCAPILevel());
    Log.i("InspireFace", InspireFace.QueryInspireFaceDiagnosticInformation());
}

The Android dependency is 1.2.4.post1, while the native version reports 1.2.4 and the C API level is 2. Include these values when reporting an integration problem.

Build the native library

To modify the native SDK, prepare the source and third-party dependencies, install a JDK, Python 3 and the Android NDK, then run from the SDK directory:

export ANDROID_NDK=/absolute/path/to/android-ndk
bash command/build_android.sh

The script builds native API 21 libraries for arm64-v8a, armeabi-v7a and x86_64, with the static C++ runtime. The Android AAR's minimum SDK remains 24. Headers are under build/inspireface-android/include, one combined library per ABI is under lib/<abi>, and java/ contains the portable inspireface.jar, sources, manifest and consumer rules. The Android build guide explains the output and application packaging.