@bynn-intelligence/autocapture-sdk

On-device React component that opens the camera, detects an ID card, passport or driver's licence in real time with live guidance ("move closer", "reduce glare", "hold still"), and auto-captures the document at full native resolution the moment every quality check passes.

Detection runs entirely in the browser via onnxruntime-web — no image ever leaves the device for detection or capture.

• No server round-trip for detection or capture
• Real-time guidance overlay with corner tracking
• Perspective-corrected, edge-tight output at native camera resolution
• Mobile (rear camera) and desktop (front camera) aware
• 39 UI languages, auto-detected from the browser
• Domain-locked SDK licensing

Install

npm install @bynn-intelligence/autocapture-sdk onnxruntime-web

react, react-dom and onnxruntime-web are peer dependencies.

Usage

import { IDAutoCapture, type AutoCaptureResult } from "@bynn-intelligence/autocapture-sdk";

<IDAutoCapture
  license={import.meta.env.VITE_AUTOCAPTURE_LICENSE}
  modelBaseUrl="/models"          // serves the detector + decoder model files
  documentTypes={["passport", "id_card", "drivers_license"]}
  onCapture={(r: AutoCaptureResult) => {
    // r.blob     - deskewed JPEG at native camera resolution
    // r.type     - "id_card" | "passport" | "drivers_license"
    // r.corners  - 4 document corners in native-resolution pixels
    // r.quality  - the quality report that triggered the capture
  }}
  onError={(e) => console.error(e)}
/>

Render it inside a sized container — it fills 100% width/height.

Props

| Prop | Type | Default | Description | |---|---|---|---| | license | string | — | Bynn-issued runtime license token (required). | | documentTypes | DocumentType[] | all | Restrict which document types are accepted. | | modelBaseUrl | string | /models | Base URL the model files are served from. | | language | string | auto | BCP-47 UI language (e.g. "fr", "pt-BR"). Auto-detected from the browser when omitted. | | mirror | boolean | auto | Mirror the preview. Auto: on for desktop (front camera), off for mobile (rear camera). | | minQuality | number | 0.85 | Composite quality score (0–1) required to capture. | | stableFrames | number | 5 | Consecutive stable frames required before capture. | | executionProviders | ExecutionProvider[] | ["webgpu","wasm"] | onnxruntime-web execution providers. | | debug | boolean | false | Show developer overlays (bounding box, keypoints, metrics HUD). | | onCapture | (r: AutoCaptureResult) => void | — | Fired once when a document is captured. | | onCancel | () => void | — | When set, renders a close button. | | onQuality | (r: QualityReport) => void | — | Per-frame quality reports. | | onError | (e: Error) => void | — | License / camera / runtime errors. |

Performance: keep the props stable

<IDAutoCapture> owns a camera loop and an inference Web Worker. Do not re-render it with fresh prop references every frame — it will tear down and re-initialise the detector worker each time, and the page will freeze.

This is easy to trigger by accident. onQuality fires on every frame, so if its handler calls setState, the component rendering <IDAutoCapture> re-renders 30–60×/second. If any prop is then a new reference per render — an inline arrow (onError={(e) => …}), an inline array (executionProviders={["wasm"]}), an object literal — the SDK sees new props every frame and re-initialises.

Keep every prop referentially stable:

• Wrap callbacks in useCallback.
• Hoist arrays/objects (executionProviders, documentTypes) to module scope, or useMemo them.
• If per-frame state (e.g. an onQuality-driven progress bar) must re-render the parent, useMemo the element so React skips the SDK subtree entirely:

const onCapture = useCallback((r) => { /* … */ }, []);
const onQuality = useCallback((r) => setScore(r.score), []);

// Stable element: a per-frame re-render of this component does NOT
// re-render or re-initialise the SDK.
const view = useMemo(
  () => (
    <IDAutoCapture
      license={LICENSE}
      executionProviders={["wasm"]}
      onCapture={onCapture}
      onQuality={onQuality}
    />
  ),
  [onCapture, onQuality],
);

Don't run a second ML engine on the same screen

<IDAutoCapture> already runs a neural-net detector (WebAssembly) plus a live camera. Running a second heavy ML / WebGL library on the same screen at the same time — MediaPipe, TensorFlow.js, a WebGL face tracker — exhausts GPU/memory on low-end and older phones, and the page crashes with WebGL: context lost.

This bites when such a library is initialised globally — a provider at the app root, or an eagerly-created singleton — because it then runs on every screen, including the one hosting <IDAutoCapture>.

Fix: initialise other ML/camera libraries lazily — only when the screen that actually needs them mounts — so they never run concurrently with the SDK. The SDK itself uses WebAssembly (not WebGL) and creates no WebGL context, so on its own screen there is nothing to crash.

FAQ

The page crashes with WebGL: context lost, mostly on older phones. Another WebGL/ML library is running on the same screen as <IDAutoCapture> — see the section above. The SDK does not use WebGL; the lost context belongs to the other library.

It freezes / "Loading detector…" never finishes. The component is being re-rendered with unstable props every frame (see Performance), which re-initialises the detector worker each render. Memoise the element and the props.

Inference seems heavy / the device gets hot. The detector is throttled to a few inferences per second by default — that is expected and sufficient for capture. If it still struggles, the device may be below the bar for on-device inference; offer a manual photo-upload fallback.

Licensing

The SDK requires a Bynn-issued runtime license token — it is domain-locked and refuses to run without one. localhost and 127.0.0.1 are always permitted, so local development works with no token.

To obtain a trial license, email [email protected].

Commercial licensing inquiries: [email protected]

License

Proprietary commercial software. © Bynn Intelligence Inc. All rights reserved. See LICENSE.