pdfextract API
    Preparing search index...

    OCR and self-hosted assets

    "@pdfextract/ocr".createTesseractOcr creates a provider lazily. The application owns it and may share it across PDFs. Close each PDF first, then close the provider after all borrowers finish. Importing a package does not start a worker or download a model.

    auto recognizes embedded image regions, including images on pages that already have native text. Geometry and normalized content suppress duplicate hidden OCR layers while preserving distinct repeated placements. A scan (an image over half the page) under a text layer of 20 or more words, whose lines run down a fifth of it or more, is judged by how cleanly the layer reads: 85% or more of its words reading as words, numbers or codes skips recognition; a poorer layer is recognized again, and when the recognized words read at least 10 points cleaner (and number at least half as many), they replace the layer within the scan. Smaller images are skipped when native text covers 30% of their area (backgrounds, watermarks), as are images too small to hold a letter. A page without native text that is drawn with many vector shapes (outlined lettering) is rendered and recognized. always recognizes bounded page rasters; off uses only native text. Complex layouts and arbitrary-document OCR accuracy are not guaranteed.

    Page renders target 300 DPI, and image regions shown below 200 DPI are enlarged toward 300 DPI, within limits.maxOcrPixels. Recognized words below minOcrConfidence (default 0.3; 0 keeps every word) are dropped, which removes most noise from photos and graphics:

    const text = await pdf.getStructuredText({ ocr: 'auto', minOcrConfidence: 0.5 });
    

    On pages larger than any paper (over 17 in, as image-to-PDF tools make from scans), an image whose recognition finds no words is read once more without enlargement, the recognizer estimating its resolution. A page that still has no text at all (handwriting, forms, faint scans) has its images read again as scattered words.

    Core accepts any "@pdfextract/core".OcrProvider. It passes tightly packed RGBA8 rasters ( "@pdfextract/core".OcrRaster) with their effective resolution in dpi when known, and layout: 'sparse' when it asks for scattered words; a provider may use both or ignore them. Words come back in raster pixels with a confidence in [0, 1], and core maps them onto the page. A provider that reports concurrency above one gets that many pages at once during OCR.

    Copy the complete dist/assets trees from the installed core and OCR packages, including sibling codecs/fonts/notices. Host separately supplied language models as languages/eng.traineddata.gz, and optionally deu.traineddata.gz, with their notices:

    pdfextract/
      core/          # pdf.mjs, pdf.worker.mjs, png.mjs, wasm/, iccs/, fonts and CMaps
      ocr/           # tesseract.mjs, worker.min.js, core/ with LSTM JS/WASM variants
      languages/     # traineddata.gz files and license information
    

    In this repository, pnpm assets prepares that layout for the browser example. This typechecked browser example accepts the base URL of the hosted directory:

    import { openPdf, type PdfInput } from '@pdfextract/core';
    import { createTesseractOcr } from '@pdfextract/ocr';

    /** assetBase is an absolute directory URL with a trailing slash. */
    export async function recognizePdf(input: PdfInput, assetBase: URL, signal?: AbortSignal) {
    const ocr = createTesseractOcr({
    languages: ['eng'],
    assets: {
    workerUrl: new URL('ocr/worker.min.js', assetBase),
    coreBaseUrl: new URL('ocr/core/', assetBase),
    languageDataBaseUrl: new URL('languages/', assetBase),
    },
    });
    try {
    const pdf = await openPdf(input, {
    ocr,
    signal,
    assets: { baseUrl: new URL('core/', assetBase) },
    });
    try {
    return await pdf.getStructuredText({ ocr: 'auto', signal });
    } finally {
    await pdf.close();
    }
    } finally {
    await ocr.close();
    }
    }

    Serve JavaScript as text/javascript and WASM as application/wasm. Serve .traineddata.gz as gzip-file bytes; do not label already compressed files with an HTTP Content-Encoding: gzip header that would decompress them before Tesseract reads them. Cross-origin asset servers need appropriate CORS. Keep URLs under your application's non-root base when applicable.

    CSP must permit same-origin scripts/module workers, fetching model/codec assets and WASM compilation ('wasm-unsafe-eval' where supported). The provider uses direct worker URLs; it does not require a mandatory CDN, hosted extraction service or cross-origin isolation headers. Use a single trusted asset origin where practical.

    The same asset configuration works inside a dedicated module Web Worker (new Worker(url, { type: 'module' })). There, core starts the PDF.js worker as a nested worker and renders full-page OCR (ocr: 'always') with OffscreenCanvas; SVG-based transfer-function filters are skipped, as in Node. Pass bytes (ArrayBuffer) or a File to the worker.

    Node resolves packaged engine/worker assets automatically through the packages' node export condition. Supply assets.languageDataBaseUrl as a filesystem path or file: URL. An optional coreBaseUrl can identify a different Tesseract core directory. Use Node's default OCR worker rather than the browser worker.min.js override shown above.

    Worker concurrency defaults to half the logical processors (at least one, at most four) and is bounded from one to eight. With more than one worker, core reads that many pages at a time during OCR, so their recognition overlaps: an 8-page scan took 16.5 s with one worker and 6.5 s with four, with the same text. Each worker holds its own Tesseract instance and the page rasters in flight, so memory grows with it; set concurrency: 1 where memory is tight. Workers start on first use, and a further one only when recognitions overlap: a document read one raster at a time uses one worker. The Tesseract provider consumes tightly packed RGBA8 and returns word/line boxes in the supplied raster pixels. Core maps them back into page coordinates. Missing/broken assets reject with OCR_ASSET_UNAVAILABLE; recognition failures use OCR_FAILED. Collect mode preserves failed regions as partial results, even when another region succeeds.

    Only Node full-page OCR (always) and composite image export (composite: true) need the native canvas addon. It is an optional peer dependency of core and is not installed automatically: run npm install @napi-rs/canvas to enable them, otherwise full-page OCR rejects with OCR_ASSET_UNAVAILABLE and composites with UNSUPPORTED_IMAGE_FEATURE. Native text, exact embedded-image exports and automatic image-region OCR never load it. Browsers and Web Workers use their built-in canvas.