light-ocr

Purpose

light-ocr is used for offline OCR text recognition of images and PDFs locally. It targets Node.js and C++ projects, and can directly recognize text in PDFs, JPEGs, PNGs, or raw image data. Results are returned as text lines in reading order, along with confidence scores and quadrilateral coordinates. All processing is done on the local machine; images, PDFs, and OCR results never leave the user's device.

Main capabilities

• Based on PP-OCRv6, the npm package includes the PP-OCRv6 Small model, PDFium, a Chinese fallback font, and precompiled components for macOS, Linux, and Windows.
• Supports Core ML / WebGPU hardware acceleration; the default createEngine() uses Auto mode, preferring Core ML on macOS 15+ Apple Silicon and preferring WebGPU on Linux and Windows builds.
• Applications can explicitly select auto, cpu, apple, or webgpu via the execution option.
• In addition to image files, recognize() also accepts GRAY8, RGB8, BGR8, and RGBA8 pixel data.
• PDF and multi-page document OCR are built into the package. Matching PDFium binaries and a checksum-pinned Noto Sans SC fallback font are provided with the platform npm packages, with no postinstall script, runtime downloads, compiler, system fonts, or separate installation required.
• Recognition runs outside the JavaScript main thread and supports queues, cancellation, and explicit cleanup; an optional chunked mode preserves small text and dense text in high-resolution images.
• Output uses a versioned schemaVersion: 1 contract; EXIF orientation is automatically corrected.

Usage

Supports Node.js 22 or newer, with 22 and 24 LTS as Tier 1 (fully tested); the stable Node-API ABI allows newer Node versions to load the same precompiled binary without releasing a new library. CommonJS uses the same exports via require("@arcships/light-ocr"). After installation, the light-ocr command is available with no extra setup. Image commands include recognize (default), detect (detection boxes only), info (version diagnostics), doctor (system diagnostics). Passing a .pdf path goes directly into document OCR; the document command handles explicit multi-source tasks. Platform acceleration: the npm package provides eight builds; applications needing explicit control can select auto, cpu, apple, or webgpu via the execution option. Small is the stable default; Tiny and Medium are optional preview packages under the next tag, and all three expose the same API, types, result structure, and error model, but each installation includes only the selected model. NPU support is installed separately via @arcships/light-ocr-openvino-linux-x64-gnu or @arcships/light-ocr-amdnpu-linux-x64-gnu and requires explicitly selecting a provider; the default installation does not include the libraries or compiled models for these providers. C++ projects build a static library from source and link against the light_ocr::core CMake target; the API accepts already-decoded GRAY8, RGB8, BGR8, and RGBA8 pixels.

Use cases

• Recognize text in images and PDFs locally in Node.js or C++ applications.
• OCR results requiring confidence scores and coordinates, such as field extraction and layout analysis.
• Recognition of small or dense text within large images, using chunked mode.
• Provide a workflow for AI agents that can invoke local commands: the project includes an Agent Skill providing scenario-driven workflows, command selection guidance, and an exit code reference, covering when to use OCR versus multimodal models, the detect-then-recognize flow for large images, ROI field extraction for receipts and forms, and using deterministic OCR to verify multimodal output.

Limitations and notes

• Supports Node.js 22 or newer; 22 and 24 LTS are Tier 1 (fully tested).
• The default installation includes only the Small model; Tiny and Medium are optional preview packages under the next tag.
• NPU support requires installing the corresponding package separately and explicitly selecting a provider; the default installation does not include it.
• On macOS, downstream packagers may re-sign the native binary, and the loader accepts a re-signed Mach-O when signature verification passes and the signing identity matches the host application (same TeamIdentifier, or both are ad-hoc signed); other platforms and unsigned changes still maintain strict size + SHA-256 verification.
• Performance data comes from a same-machine CPU path comparison of 0.3.0 on three real devices, and results vary with workload and hardware; the Apple run passed the same locked CPU thresholds, and two WebGPU runs were byte-for-byte identical to CPU FP32 across all 14 images.
• The project uses the Apache License 2.0.
• Information such as pricing and charging models is not yet provided.