expo-doc-vision

Expo native module for offline document text extraction on iOS.

⚠️ iOS only — Android is not supported yet ⚠️ Requires Expo Dev Client or Bare Workflow — Not compatible with Expo Go ⚠️ Fully offline — No network requests, no third-party SDKs ⚠️ No data leaves the device — Privacy-first design

Features

• 🚀 Blazing fast — Native on-device processing with hardware acceleration
• 📄 PDF support — Extract text from both text-based and scanned PDFs
• 🖼️ Image OCR — Recognize text in JPG, PNG, and HEIC images
• 📝 DOCX extraction — Fast offline text extraction from Word documents
• 📃 TXT support — Read plain text files with automatic encoding detection
• 📚 EPUB extraction — Offline text extraction from EPUB books
• 🔒 Privacy-first — All processing happens on-device, no data leaves your phone
• 🌐 Multi-language — Support for 18+ languages with auto-detection (iOS 16+)
• ⚡ Fast & Accurate modes — Choose between speed and precision

Installation

npx expo install expo-doc-vision

Or with npm/yarn:

npm install expo-doc-vision
# or
yarn add expo-doc-vision

iOS Requirements

• iOS 13.0+ (minimum supported version)
• Expo SDK 50+ (or React Native 0.73+)
• Expo Dev Client or Bare Workflow

iOS Version Compatibility

| iOS Version | Features | |-------------|----------| | iOS 13-14 | Basic OCR, PDF text extraction, English only (en-US) | | iOS 15 | Multi-language support (18+ languages) | | iOS 16+ | Auto language detection, improved accuracy |

Note: automaticallyDetectsLanguage and usesLanguageCorrection options require iOS 16+. On older versions, these options are ignored gracefully.

Setup with Expo Dev Client

Add the plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": ["expo-doc-vision"]
  }
}

Then rebuild your development client:

npx expo prebuild
npx expo run:ios

Usage

Basic Usage

import { recognize } from 'expo-doc-vision';

// Recognize text from an image
const result = await recognize({
  uri: 'file:///path/to/image.jpg',
});

console.log(result.text);
// => "Hello, World!"

PDF Documents

import { recognize } from 'expo-doc-vision';

// Recognize text from a PDF
const result = await recognize({
  uri: 'file:///path/to/document.pdf',
});

console.log(result.text);
// => Full text from all pages

console.log(result.pages);
// => [{ page: 1, text: "Page 1 content..." }, ...]

console.log(result.source);
// => "pdf-text" (text-based PDF) or "vision" (scanned PDF)

With Options

import { recognize } from 'expo-doc-vision';

const result = await recognize({
  uri: 'file:///path/to/document.pdf',
  type: 'auto',              // 'auto' | 'pdf' | 'image' | 'epub'
  mode: 'accurate',          // 'fast' | 'accurate'
  language: ['en-US', 'zh-Hans'], // BCP 47 language codes
});

EPUB Documents

import { recognize } from 'expo-doc-vision';

// Recognize text from an EPUB
const result = await recognize({
  uri: 'file:///path/to/book.epub',
});

console.log(result.source);
// => "epub-html"

API Reference

recognize(options: RecognizeOptions): Promise<OcrResult>

Performs OCR on a document (image, PDF, EPUB, or text document).

RecognizeOptions

| Property | Type | Default | Description | |----------|------|---------|-------------| | uri | string | required | URI of the document (file://, content://, or absolute path) | | type | 'auto' \| 'pdf' \| 'image' \| 'epub' | 'auto' | Document type (auto-detected from extension) | | mode | 'fast' \| 'accurate' | 'accurate' | Recognition mode | | language | string[] | [] | Recognition languages (BCP 47 codes) | | automaticallyDetectsLanguage | boolean | true | Auto-detect language (iOS 16+) | | usesLanguageCorrection | boolean | true | Apply language-specific corrections |

OcrResult

| Property | Type | Description | |----------|------|-------------| | text | string | Full concatenated text from all pages | | pages | OcrPageResult[] | Per-page results (only for multi-page documents) | | source | 'vision' \| 'pdf-text' \| 'docx-xml' \| 'txt' \| 'epub-html' | Source of text extraction |

OcrPageResult

| Property | Type | Description | |----------|------|-------------| | page | number | Page number (1-indexed) | | text | string | Recognized text from this page |

Error Handling

import { recognize, ExpoDocVisionError, ExpoDocVisionErrorCode } from 'expo-doc-vision';

try {
  const result = await recognize({ uri: 'file:///invalid/path.pdf' });
} catch (error) {
  if (error instanceof ExpoDocVisionError) {
    switch (error.code) {
      case ExpoDocVisionErrorCode.FILE_NOT_FOUND:
        console.error('File not found');
        break;
      case ExpoDocVisionErrorCode.UNSUPPORTED_FILE_TYPE:
        console.error('Unsupported file type');
        break;
      case ExpoDocVisionErrorCode.DOCUMENT_LOAD_FAILED:
        console.error('Failed to load document');
        break;
      case ExpoDocVisionErrorCode.OCR_FAILED:
        console.error('OCR processing failed');
        break;
      case ExpoDocVisionErrorCode.PLATFORM_NOT_SUPPORTED:
        console.error('Platform not supported (iOS only)');
        break;
    }
  }
}

Supported File Types

| Type | Extensions | Strategy | |------|------------|----------| | Image | .jpg, .jpeg, .png, .heic, .heif | Apple Vision OCR | | PDF (text-based) | .pdf | PDFKit text extraction | | PDF (scanned) | .pdf | PDFKit → render → Vision OCR | | DOCX | .docx | Offline XML extraction (no OCR) | | TXT | .txt | Direct read with encoding detection | | EPUB | .epub | Offline HTML/XHTML extraction |

Limitations

• iOS only — Android support is planned for future releases
• No bounding boxes — Only text content is returned
• No streaming — Results are returned all at once
• No handwriting — Optimized for printed text
• No .doc support — Legacy Word binary format (.doc) cannot be parsed offline; convert to .docx or .pdf

How It Works

PDF Processing

1. Load PDF using PDFDocument
2. Try to extract text using PDFDocument.string
3. If text length > 20 characters → return as text-based PDF
4. Otherwise → render each page to image → run Vision OCR

Image Processing

1. Load image using CGImageSource
2. Run VNRecognizeTextRequest with specified options
3. Return concatenated text from all observations

DOCX Processing

1. Read DOCX file as ZIP archive (DOCX is a ZIP container)
2. Extract word/document.xml from the archive
3. Parse XML and extract text from <w:t> elements
4. Return plain text (no OCR needed, significantly faster)

TXT Processing

1. Read file as raw bytes
2. Detect encoding via BOM (Byte Order Mark) if present
3. Try encodings in order: UTF-8, UTF-16, then legacy encodings
4. Supported encodings: UTF-8, UTF-16, UTF-32, GB18030, GBK, GB2312, Big5, Shift-JIS, EUC-JP, EUC-KR, Windows-1252, ISO-8859-1

EPUB Processing

1. Read EPUB container (META-INF/container.xml) to locate the package document
2. Parse the package manifest and spine to find readable content
3. Extract text from HTML/XHTML entries in reading order
4. Strip markup and return plain text

Roadmap

• [ ] Android support (ML Kit)
• [ ] Bounding box coordinates
• [ ] Progress callbacks
• [ ] Confidence scores
• [ ] Page rotation detection

License

MIT © zhanziyang

Contributing

Contributions are welcome! Please open an issue or submit a pull request.