light-ocr

English | 简体中文

Fast, offline OCR for Node.js and C++.

Recognize text in JPEG, PNG, or raw image data directly on your machine. light-ocr returns lines in reading order with confidence scores and quadrilateral coordinates. For Node.js, the npm package includes PP-OCRv6 Small and prebuilt components for macOS, Linux, and Windows.

Quick start

Node.js 22 and 24 are supported.

npm install @arcships/light-ocr

import { createEngine } from "@arcships/light-ocr";
import { readFile } from "node:fs/promises";

const engine = await createEngine();
const result = await engine.recognizeEncoded(
  await readFile("image.jpg"),
);

for (const line of result.lines) {
  console.log(line.text, line.confidence, line.box);
}

await engine.close();

createEngine() automatically chooses the right execution mode for the current platform. If your application already decodes images, recognize() also accepts GRAY8, RGB8, BGR8, and RGBA8 pixel data.

What you get

• Local processing. Images and OCR results stay on your machine.
• One package to install. The model and matching prebuilt component are included with the npm package.
• Useful output. Every line includes recognized text, confidence, and its position in the original image.
• Hardware acceleration by default. Auto tries Core ML first on macOS 15+ Apple Silicon, and WebGPU first on the Linux and Windows builds below.
• Application-friendly execution. Recognition runs off the JavaScript main thread and supports queues, cancellation, and explicit cleanup.
• Small text in large images. An optional tiled mode preserves small and dense text in high-resolution images.

⭐ Like light-ocr? Give it a star — it helps others discover the project and keeps us motivated!

Platform acceleration

The npm package provides the following six builds. The default createEngine() call uses Auto mode:

Platform	Auto mode
macOS on Apple Silicon	Core ML on macOS 15+, then CPU
macOS on Intel	CPU
Linux x64 with glibc	WebGPU through Vulkan, then CPU
Linux arm64 with glibc	CPU
Windows x64	WebGPU through D3D12, then CPU
Windows arm64	CPU

Applications that need explicit control can choose auto, cpu, apple, or webgpu through the execution option.

Measured performance

Version 0.3.0 was measured on three real devices:

Device	Acceleration	End-to-end speedup	OCR process CPU time
Apple M4 Max	Core ML	2.30× on HELLO 123; 2.85× on a dense form	95.91%–97.67% less
NVIDIA RTX 5060 Ti on Linux	WebGPU / Vulkan	5.70× overall across 14 test images	69.97% less
AMD Radeon 780M on Windows	WebGPU / D3D12	2.44× overall across 14 test images	46.33% less

These are same-machine comparisons with the CPU path, and results vary by workload and hardware. For the 14-image results, overall speedup is the sum of the per-image CPU median times divided by the sum of the WebGPU median times. The CPU column measures cumulative OCR process CPU time over the same workloads, rather than an instantaneous system-utilization sample; lower CPU time leaves more capacity for the rest of the application while OCR is active. The Apple run passed its locked CPU-parity thresholds; both WebGPU runs were byte-identical to CPU FP32 on all 14 images. See the 0.3.0 release report for complete measurements and methodology.

C++

C++ projects build the static library from source and link the light_ocr::core CMake target. The API accepts decoded GRAY8, RGB8, BGR8, or RGBA8 pixels; start with the C++ API guide and build instructions.

Documentation

• Node.js API and examples
• C++ API
• Apple Silicon acceleration
• Linux WebGPU acceleration
• Windows WebGPU acceleration
• Model bundle
• Build and release
• Changelog
• npm 0.3.0 release report

Community and license

Issues and pull requests are welcome — see CONTRIBUTING.md for guidelines. All participants are expected to follow our Code of Conduct.

light-ocr is available under the Apache License 2.0.