pdffr

A PDF decompiler, not an image reader. PDF → Markdown in the browser or Node, in milliseconds for born-digital pages — with on-device OCR spent only on the pixels the text layer can't explain.

Try it in your browser → — drop any PDF; it never leaves the tab.

import { decompile } from 'pdffr';

const { markdown, stats } = await decompile(file);
// stats.firstOutputMs ≈ 150ms for a typical report; the file never leaves the tab

npx pdffr report.pdf -o report.md

Why this exists

Every PDF→Markdown tool sits at one of two extremes:

~80% of real-world PDFs are born-digital: every glyph's exact coordinates, size and font are already in the file. pdffr treats PDF as what it is — a drawing program — and decompiles the drawing back into structure:

• Geometry-native decompilation. Glyph runs → lines → an XY-cut reading-order tree over whitespace → headings (font-size clustering), paragraphs (leading analysis), nested lists (marker glyph + indent), tables (ruling lines from the content stream, or column x-alignment), inline **bold**/*italic*/<sup>, math fonts and sub/superscripts transliterated to $LaTeX$, rotated text re-framed upright, running header/footer stripping, hyphenation repair. No rasterization. Milliseconds per page.
• Render-diff oracle. When a page carries bitmaps or thin text coverage, the page is rendered once, the raster's ink mask is computed, and the dilated boxes of every native glyph are erased from it. What's left is ink the text layer cannot explain — scans, stamps, screenshots with burned-in text. Exact image rectangles from the content stream (CTM-tracked) sharpen the regions further. Only those regions go to OCR.
• One IR for both sources. OCR words come back with boxes and confidence, get gated by a text-plausibility test (confidence alone lies on icons and charts), and enter the same geometry engine as native glyphs. Structure recovery is source-agnostic.
• Parallel and optimistic. Pages decompile concurrently; markdown streams out immediately with placeholders; a pool of tesseract workers fills them in place. Whole-page scans are split along their own ink into chunks so the pool works in parallel.
• Private by construction. pdf.js and tesseract.js run in web workers in the user's tab. Nothing is uploaded.
• Same engine in Node. pdffr/node runs the identical pipeline on the server or the command line, with @napi-rs/canvas standing in for the DOM.

Install

npm install pdffr pdfjs-dist tesseract.js
# Node / CLI additionally:
npm install @napi-rs/canvas

pdfjs-dist and tesseract.js are peer dependencies; @napi-rs/canvas is an optional peer used only by the Node entry.

Usage

Browser

import { decompile, warmOcr, setPdfWorkerSrc } from 'pdffr';

// Bundled apps: point pdf.js at its worker. Without this, pdffr falls back to the jsdelivr build.
setPdfWorkerSrc(new URL('pdfjs-dist/build/pdf.worker.min.mjs', import.meta.url).href);

// Optional: pre-load OCR workers while the user is still choosing a file.
warmOcr();

const result = await decompile(file, {
  ocr: true, // escalate unexplained ink to on-device OCR (default true)
  lang: 'eng', // tesseract language(s): 'deu', 'eng+ara', 'chi_sim', …
  concurrency: 4, // pages decompiled in parallel
  onPage(page, md) {
    // streams: first the native pass, then again as OCR regions land
    render(page, md);
  },
  onEvent(e) {
    // every trace line, page (re)emit, and stats update
    if (e.type === 'trace') console.log(e.kind, e.msg);
  },
});

result.markdown; // the whole document
result.pages[0].blocks; // typed blocks: heading | para | math | list | table
result.stats; // firstOutputMs, nativeDoneMs, totalMs, ocrRegions, nativeChars, ...

Node

import { decompileFile, terminateOcr } from 'pdffr/node';

const { markdown } = await decompileFile('invoice.pdf', { lang: 'deu' });
await terminateOcr(); // let the process exit once the tesseract workers are done

Command line

pdffr scan.pdf                    # markdown on stdout, progress on stderr
pdffr scan.pdf -o scan.md --lang eng+fra
pdffr paper.pdf --no-ocr -q       # native text only, silent
pdffr paper.pdf --json --pages 1-3  # per-page markdown, typed blocks and stats as JSON

API

• decompile(input, options?) → Promise<DecompileResult> — input is an ArrayBuffer, Uint8Array, Blob or File. Options: ocr, lang, concurrency, pool, onPage, onEvent, pdfWorkerSrc.
• decompileFile(path, options?) — Node only.
• warmOcr(lang?) / terminateOcr() — pre-load or shut down the shared tesseract pool.
• ocrPool(lang?) — the shared OcrPool; pass your own via options.pool to control worker count.
• runPipeline(buffer, emit, { ocr, concurrency, escalate }) — the streaming core, if you want raw events.
• blocksToMarkdown(blocks) — render typed blocks yourself.
• setPdfWorkerSrc(url) — configure pdf.js's worker.

Types: Block, ListItem, Run, Region, Rules, PageState, Stats, PipelineEvent.

Integrations

from langchain_pdffr import PdffrLoader
docs = PdffrLoader("report.pdf").load()   # one Markdown Document per page

{ "mcpServers": { "pdffr": { "command": "npx", "args": ["-y", "pdffr-mcp"] } } }

How a page flows through

getTextContent ─► runs (x, y, w, h, size, bold, italic, math font, rotation)
                   │
getOperatorList ─► exact bitmap rects + ruling lines (CTM walk), font resolution
                   │
        suspicious? (bitmaps, or thin coverage)
             │ no                          │ yes
             ▼                             ▼
     structure pass                render page once (print intent)
                                   ink mask − native glyph boxes = residual
                                   regions = bitmap rects ∪ residual components
                                   large regions split along their ink
                                   ─► OCR pool (2×/3× upsampling for small crops,
                                      second read of doubtful words,
                                      text-plausibility gate)
                                   ─► OCR runs join the same structure pass

Structure pass: rotated runs re-framed upright (a dominant rotation turns the whole page; a minority is a sidebar group) → buildLines (math spans → LaTeX) → orderRuns (XY-cut: tall prose gutter → vertical cut; largest whitespace band → horizontal cut; ruled and aligned tables detected first as atomic boxes) → toBlocks (headings, lists with nesting, paragraphs by leading, display math, tables, furniture stripping) → markdown.

Demo

npm install
npm run dev