@parselo/capacitor-mrz

Capacitor plugin for on-device MRZ (Machine Readable Zone) text recognition. Wraps Apple Vision (VNRecognizeTextRequest) on iOS and ML Kit Text Recognition on Android. Returns the recognised text lines; pair with @parselo/scanner-core to locate, parse, and validate the ICAO 9303 MRZ.

Supports all ICAO TD3 travel document types: standard passports (P<), emergency travel documents (PU), permanent resident travel documents (PR), and foreign passports.

Platform support

| Platform | Backend | Min version | |---|---|---| | iOS | Vision — VNRecognizeTextRequest, .accurate level | iOS 13 | | Android | ML Kit Text Recognition v2, Latin script | API 21 |

Language correction is disabled on both platforms — it would corrupt MRZ tokens and check digits.

Install

npm install @parselo/capacitor-mrz @parselo/scanner-core
npx cap sync

iOS — camera permission

Add to ios/App/App/Info.plist (if not already present):

<key>NSCameraUsageDescription</key>
<string>Used to scan the MRZ on your travel document.</string>

CocoaPods installs the MrzPlugin.m ObjC bridge automatically. If the plugin throws "not implemented" at runtime, verify that pod install ran after cap sync and that MrzPlugin.m is listed in the Xcode target's Compile Sources.

Android

No extra configuration needed — the ML Kit dependency is declared in the plugin's build.gradle.

API

import { Mrz } from "@parselo/capacitor-mrz";

const { lines, raw } = await Mrz.recognizeText({ image });
// lines: string[]  — one element per Vision/ML Kit text observation
// raw:   string    — lines joined with "\n"

image accepts a data: URI, file:// URI, bare absolute path, or raw base64 string.

Pass the full camera frame — the plugin sends the entire image to the OCR engine. scanner-core locates the two 44-char MRZ lines anywhere in the returned array and handles OCR noise in the surrounding biographical text.

Integration with scanner-core

import { Scanner } from "@parselo/scanner-core";
import { Mrz }     from "@parselo/capacitor-mrz";

const scanner = new Scanner({
  license: {
    token:      "…",
    bundleId:   "com.example.app",
    publicKeys: { "<kid>": "<base64-spki>" },
  },
  analytics: {
    ingestUrl: "…",
    store: { get, set },
  },
  native:    { captureAndDecodePdf417: … },  // still needed for barcode scanning
  mrzNative: {
    captureAndRecognizeMrz: async () => {
      const { lines } = await Mrz.recognizeText({ image: dataUrl });
      return lines;
    },
  },
});

await scanner.init();
const result = await scanner.scanPassport();
// result.document.documentType === "passport"
// result.document.fields.firstName.value, .dateOfBirth.value, .country.value, …

How name extraction works

OCR-B MRZ uses < as a word separator, which Vision and ML Kit frequently misread as C, S, K, @, etc. scanner-core automatically cross-references Vision's biographical-zone lines (the human-readable area above the MRZ, read in a standard font) to recover correct first and last names even when the MRZ separator characters are corrupted.

See the full integration guide for a complete setup walkthrough including the camera UI component.

License

MIT