Prerequisites

A working Android quickstart
An app-owned I420 source with stable dimensions and direct buffers

When to use this guide

Use external-frame processing when your application already owns the camera or video source. If Nosmai owns the camera and you only need processed output, use DUAL_OUTPUT and a frame callback instead.

Prepare the pipeline

Initialize Nosmai first, then configure the stable input dimensions:

boolean ready = NosmaiSDK.initializeExternalFramePipeline(width, height);
if (!ready) {
    throw new IllegalStateException("External processing is unavailable");
}

NosmaiSDK.setExternalFrameMode(true);
NosmaiSDK.setExternalFrameThreadMode(NosmaiSDK.ThreadMode.GL_THREAD);

Reinitialize the pipeline if the input dimensions change.

Process I420 planes

NosmaiSDK.ProcessedI420Frame output =
    NosmaiSDK.processExternalI420Sync(
        yBuffer, uBuffer, vBuffer,
        width, height,
        yStride, uStride, vStride,
        rotation, mirror
    );

if (output != null) {
    consumer.onFrame(output);
}

The three inputs must be direct ByteBuffer instances with correct strides. Consume or copy the returned native buffers before submitting the next frame.

Process writable planes in place

boolean processed = NosmaiSDK.processExternalI420InPlace(
    yBuffer, uBuffer, vBuffer,
    width, height,
    yStride, uStride, vStride,
    rotation, mirror
);

Use this path only when the source planes are writable and large enough for their declared strides. The call blocks until processing finishes.

Stop safely

Stop the source before disabling the pipeline:

NosmaiSDK.clearAllEffects();
NosmaiSDK.setFrameCallback(null);
NosmaiSDK.setExternalFrameMode(false);

Verify it worked

Use a visible effect and confirm output dimensions, orientation, timestamp order, and color on a physical arm64 device. Track dropped or late frames in the host consumer.

Common errors

Symptom	Cause	Fix
Processing returns `null` or `false`	Buffer type, strides, dimensions, or pipeline state are invalid	Use direct buffers and reinitialize after an input-size change
Colors or orientation are wrong	Plane order, stride, rotation, or mirror metadata is incorrect	Validate the source contract before submitting the frame

Process external frames on Android