npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

tearout-pdf

v0.8.6

Published

High-fidelity PDF-to-Markdown conversion using Vision-Ripped pipeline with YOLOv12

Readme

Tearout

High-fidelity PDF → Markdown for Node.js, Bun, and Vercel.

A layout-detection model finds regions visually, PDFium extracts the text, and Tearout maps one to the other — preserving headings, multi-column reading order, and table structure. Plain prose pages skip the detector and are built straight from the PDF text.

Installation · Quick Start · Presets · Benchmarks · Usage

Node ≥22 TypeScript License: Apache-2.0

Installation

Requires Node.js 22 or newer.

pnpm add tearout-pdf   # core pipeline + SLANet + bundled PP-OCRv6 assets

tearout-pdf ships the pipeline plus SLANet (tables) and bundled PP-OCRv6 tiny/small assets used by the OCR fallback path. Each preset additionally needs its detector. The small bespoke detectors ship as npm packages; the large upstream models (pp-v3, table-transformer) are downloaded on demand from HuggingFace into a local cache (~/.cache/tearout/models, override with TEAROUT_MODEL_CACHE) on first use — nothing to install.

| Preset | Install alongside tearout-pdf | Auto-downloaded on first use | | ------------ | ---------------------------------------------- | ---------------------------- | | fast | tearout-pp-doclayout-small | — | | fast-yolo | tearout-yolov12-doclaynet-nano | — | | balanced ⭐ | — | pp-v3 (~130 MB) | | max | — | pp-v3, table-transformer | | hybrid | tearout-pp-doclayout-small | pp-v3, table-transformer | | hybrid-ocr | tearout-pp-doclayout-small ppu-paddle-ocr | — |

ppu-paddle-ocr is an optional peer dep (the OCR runtime for hybrid-ocr, page-level auto-OCR, region-level auto-OCR, and scanned-document full-page OCR). To install everything the npm-distributed presets need in one go:

pnpm add tearout-pdf \
  tearout-pp-doclayout-small \
  tearout-yolov12-doclaynet-nano \
  ppu-paddle-ocr

Air-gapped? Set TEAROUT_OFFLINE=1 to forbid downloads and pre-populate the cache, or install the matching @vrejf/tearout-* package (it's still resolved first). To skip the download you can also point TEAROUT_MODEL_CACHE at a directory holding pp-v3/model.onnx etc.

The math preset (@vrejf/tearout-pp-doclayout-plus-l + @vrejf/tearout-pix2text-mfr) is published manually and not covered here yet.

Quick Start

import { initTearout, toMarkdown } from "tearout-pdf";

await initTearout({ preset: "fast" });

const markdown = await toMarkdown("document.pdf");

Presets

Pick a preset based on the size/accuracy tradeoff you want. Each one bundles a detector with the right table refinements.

| Preset | Detector size | Best for | License | | ------------ | ---------------- | ------------------------------------------------- | ---------- | | fast | ~5 MB | Smallest install, fastest path | Apache-2.0 | | fast-yolo | ~10 MB | Better headers/footers than fast | AGPL-3.0 ⚠ | | balanced ⭐ | ~124 MB | Best overall accuracy, multi-column, tables | Apache-2.0 | | max | ~152 MB | Same as balanced + extra table refinement | Apache-2.0 | | hybrid | ~5 MB + 130 MB | fast, re-running flagged and table pages with pp-v3 | Apache-2.0 | | hybrid-ocr | ~25 MB | Best tables via OCR escalation on dense pages | Apache-2.0 | | math | ~123 MB + 118 MB | LaTeX recognition for equation-heavy PDFs (arxiv) — not a general replacement for balanced | MIT / Apache |

SLANet (table structure) and PP-OCRv6 tiny/small model assets are bundled in tearout-pdf. Unless explicitly disabled, auto-OCR runs on every preset in three cases: page-level (a page extracts fewer than 100 characters), scanned-document full-page rescue (used when the normal OCR path is sparse or fragmented), and region-level (a large region comes back empty on an otherwise text-rich page — catches scanned tables/blocks embedded in digital documents). Region-level OCR skips regions that already hold native text, so overlapping layout boxes no longer produce a second OCR copy of a paragraph. OCR requires the optional ppu-paddle-ocr peer dep; if it is absent, OCR fallback paths skip cleanly.

For pages() and toMarkdown(), ocrFallback: { enabled: false } disables all built-in OCR fallback, including automatic page/region OCR, scanned-page rescue, and OCR during hybrid escalation. An omitted option preserves automatic OCR and preset defaults; { enabled: true } enables region fallback for missing/garbage text. An explicit per-call value wins over preset and initialization defaults. This switch does not disable table-structure or formula-recognition models.

fast and fast-yolo use the prose fast path by default: plain single-column prose pages skip rendering and layout detection, and regions are built from the PDF text. Pages with tables, figures, columns, unusual scripts or annotations fall back to the detector. See Pages iterator for how to spot these pages and turn the fast path off.

Text from PDFs whose ToUnicode map PDFium rejects (common symptom: å/ä/ö coming out as #/!/") is repaired automatically.

The scanned-document full-page rescue is default-on and guarded. It only replaces region markdown when it produces a clear text gain or repairs OCR table-fragment artifacts, and it still honors header/footer filtering. Set TEAROUT_FULL_PAGE_SCANNED_OCR=0 to disable it for A/B testing.

// At init...
await initTearout({ preset: "balanced" });

// ...or per-call
const md = await toMarkdown(buf, { preset: "max" });

Benchmarks

Focused OCR and legal-policy guardrails

Run 2026-06-25 on selected Riksdagen documents with fast-yolo:

| Bench | Before | Current | Notes | | --- | ---: | ---: | --- | | Scanned OCR GM (AAAE8B78..., 10 pages) | 75.5 | 84.4 | Content 64.3 → 81.0, order 42.6 → 61.1, OCR quality 87.5 → 90.0 | | Policy/legal GM (BCE89CD5..., 10 pages) | 2/10 | 10/10 | Repeated-text rescue for side-by-side legal amendments | | OLM dev guardrail | 191/256 | 191/256 | No regression; headers/footers stayed 31/33 |

The scanned OCR GM targets real scanned Swedish government pages where region-by-region OCR produced jumbled order or missed text. The policy/legal GM targets born-digital side-by-side legal amendments where detector-region formatting can duplicate near-identical old/new wording.

olmOCR-bench (full, 1269 PDFs)

fast re-run 2026-06-18 (with region-scoped auto-OCR); fast-yolo / hybrid-ocr run 2026-05-20; balanced is the 2026-05-31 high — all on an M3 MacBook:

| Preset | Tables | Multi-col | Hdr/Ftr | Tiny txt | Total | Time | | ------------ | --------: | --------: | --------: | --------: | ----------: | -----: | | fast | 79.7% | 44.7% | 83.2% | 40.5% | 82.0% | 3:11 | | fast-yolo | 75.5% | 42.8% | 88.0% | 46.8% | 82.1% | 5:55 | | hybrid-ocr | 81.5% | 42.5% | 78.3% | 41.6% | 81.4% | 8:12 | | balanced ⭐ | 77.1% | 50.8% | 92.2% | 54.5% | 84.6% | 12:26 |

Region-scoped auto-OCR (default-on) is preset-independent; on fast it nets +0.2pp overall vs the same build without it (tables +1.4pp), driven by recovering empty scanned table regions. The fast-yolo / hybrid-ocr / balanced rows predate it and will shift slightly when re-run.

Math accuracy isn't reported here — formula recognition is enabled exclusively by the math preset (see below); the other presets emit math regions as raw text.

ParseBench (structured-document suite)

On ParseBench (charts, layout, tables, text content, text formatting), balanced scores Overall 0.5009 — chart 0.015 · layout 0.813 · table 0.438 · text-content 0.747 · text-formatting 0.492 (full run, 2026-06-01).

Direct local comparison against LiteParse (full run, 2026-06-21; LiteParse 2.1.1, markdown output, OCR disabled). The fast row is the cap-95 rerun after fixing pages({ preset }) defaults and restoring large table-region OCR rescues without allowing full-page-sized false positives.

| Pipeline | Chart | Table | Text | Formatting | Shared 4-cat mean | Layout fallback | Local 5-cat mean | ms/file | | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | | liteparse_markdown | 0.033 | 0.000 | 0.648 | 0.408 | 0.272 | 0.848 | 0.387 | 17.5 | | fast | 0.056 | 0.387 | 0.703 | 0.413 | 0.390 | 0.797 | 0.471 | 12365.0 | | fast-yolo | 0.106 | 0.412 | 0.695 | 0.434 | 0.412 | 0.756 | 0.481 | 707.4 |

The shared 4-category mean is the cleanest direct parse comparison because ParseBench's local layout fallback is not the same as LiteParse's published Visual Grounding column. The LiteParse table score did not reproduce the blog number locally: the API and CLI both emitted markdown tables, but their cell/row structure collapsed enough to score 0.000 GriTS on this run. Full notes: eval/findings/2026-06-21-liteparse-direct-parsebench.md.

Opt-in vector table hints recover ruled-grid tables missed by the detector. With fast, vectorTableHints: true, and selective synthetic-hint SLANet skipping, full ParseBench table moved from 0.3871 to 0.4070 (503/503 successful). Text guardrails stayed flat: text-content 0.7036, text-formatting 0.4134. The latest speed rerun averaged 14.87s/file queued benchmark latency on a loaded local machine; use it as a sanity check, not an idle-machine speed claim.

Two header-bleed fixes (0.6.1, 0.6.2) stopped the first data row being folded into the table header when it carried an annotation marker (#34B[$76.70) or was sparse (a text label, one $ value, and n/a cells). On the confident-geometry table config these lifted full ParseBench table grits_trm_composite 0.4250 → 0.4255 → 0.4266 and table_record_match to 0.2574, with grits_con flat and OLM dev unchanged at 193/256. An isolated fast-yolo A/B of the same fixes was also net-positive (trm 0.4230 → 0.4242, record_match 0.2617 → 0.2647). A follow-up (0.6.3) caps the strong-data header signal to the first few rows so transposed tables no longer collapse into the header, recovering the fast-yolo con to 0.5614 (trm 0.4246) with the fast path unchanged. Details: eval/findings/2026-06-23-table-header-bleed-fixes.md.

Vs. other pipelines

| System | Overall | Tables | Multi-Col | Hdr/Ftr | | ----------------------- | -------: | -------: | --------: | -------: | | Tearout balanced | 84.6 | 77.1 | 50.8 | 92.2 | | Chandra OCR 0.1.0 | 83.1 | 88.0 | 81.2 | 90.8 | | Infinity-Parser 7B | 82.5 | 85.0 | 84.2 | 88.7 | | olmOCR v0.4.0 | 82.4 | 84.9 | 83.7 | 96.1 | | Tearout fast | 81.6 | 79.0 | 43.4 | 82.8 | | PaddleOCR-VL | 80.0 | 84.1 | 79.9 | 97.0 | | Marker 1.10.1 | 76.1 | 72.9 | 80.0 | 86.6 | | Mistral OCR API | 72.0 | 60.6 | 71.3 | 93.6 |

Tearout balanced tops the olmOCR leaderboard while running locally on a laptop. It trades raw multi-column and tiny-text accuracy (where VLMs win by reading pixels) for far better tables, speed, and cost — no GPU, no API key.

Math (math preset)

When to use it: equation-heavy PDFs (arxiv preprints, lecture notes) where you need LaTeX in the output. For general academic papers without dense math, stick with balanced — the math preset trades ~30pp of page-header/footer accuracy for formula recognition (it uses pp-doclayout-plus-l, which has stronger formula recall than pp-v3 but weaker header/footer recall).

Run 2026-05-24 on M3 MacBook, olmocr-bench arxiv_math (522 PDFs / 2927 tests), upstream Python scorer:

| Backend | arxiv_math | sec/PDF | Runtime deps | | -------------------------------- | ---------: | ------: | -------------------------- | | onnx (pix2text-mfr-1.5) ⭐ | 80.0 | ~15 s | None — pure Node | | paddlex (opt-in) | 76.7 | ~22 s | paddlex[ocr] + Python venv |

await initTearout({ preset: "math" });
const md = await toMarkdown("paper.pdf");

The default onnx backend (pix2text-mfr-1.5, ~118 MB ONNX) is pure Node — no Python required. For the opt-in paddlex backend, install paddlex[ocr] in a Python env and point TEAROUT_FORMULA_PYTHON at it (or drop a venv at .venv-table-test/bin/python), then pass { formula: { enabled: true, backend: "paddlex" } }.

Usage

import { initTearout, toMarkdown } from "tearout-pdf";

await initTearout({ preset: "balanced" });

const markdown = await toMarkdown("document.pdf");

Progress & cancellation

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

const markdown = await toMarkdown(pdfBuffer, {
  maxPages: 10,
  signal: controller.signal,
  onProgress: ({ currentPage, totalPages, phase }) => {
    console.log(`Page ${currentPage}/${totalPages}: ${phase}`);
  },
});

Pages iterator

For page-by-page control with quality metrics:

import { pages } from "tearout-pdf";

for await (const page of pages("document.pdf", { preset: "fast" })) {
  if (page.quality.isProblematic) {
    // route to a heavier model
  }
  console.log(page.markdown);
}

toMarkdown() already joins pages for you. When you stream pages and build the document yourself, join them with joinPageMarkdown (new in 0.8.0) rather than join("\n\n"), so the result matches toMarkdown(): sentences and hyphenated words split at a page break are re-stitched.

import { joinPageMarkdown, pages } from "tearout-pdf";

const parts: string[] = [];
for await (const page of pages("document.pdf", { preset: "fast" })) parts.push(page.markdown);
const markdown = joinPageMarkdown(parts);

page.quality.flags.usedProseFastPath reports pages where the prose fast path skipped rendering and layout detection (on by default for fast and fast-yolo; proseFastPath: false or TEAROUT_PROSE_FAST_PATH=0 turns it off). No detector ran on those pages, so region confidences and page.quality.confidence are a fixed 1, not detector scores, and lowConfidence is never set. Leave them out of confidence statistics. page.quality.timings.proseFastPathMs is the time spent on the guard and region synthesis. The fast path is skipped when a stage needs page pixels (onProblematicPage, includePageImage, regionHandler, includeEmbedded, image output other than the placeholder, a describer, OCR fallback, formula mode), so page.quality.isProblematic and onProblematicPage keep their detector-based meaning. Pages the fast path declines produce the same Markdown as with it off.

page.quality.flags.usedTextFirst reports when the guarded native text path was used. page.quality.ocrDiagnostics reports OCR mode, requested/filled region counts, per-region trigger reasons, and elapsed OCR time. page.quality.graphicsDiagnostics reports PDF vector path counts and ruled-table candidates. By default this is telemetry only. Set vectorTableHints: true to let guarded ruled-grid candidates create low-confidence table regions when the layout detector missed them. When enabled, accepted/rejected hint counts are reported in page.quality.graphicsDiagnostics.hintDiagnostics:

const markdown = await toMarkdown("document.pdf", {
  preset: "fast",
  vectorTableHints: true,
});

This is experimental and disabled by default. The strict guarded ParseBench run improved table GriTS (0.3871 -> 0.4061) without aggregate text regression, and a selective synthetic-hint SLANet bypass improved it to 0.4070 by only skipping SLANet for simple 2x2 ruled-grid hints:

const markdown = await toMarkdown("document.pdf", {
  preset: "fast",
  vectorTableHints: true,
  slanet: { enabled: true, skipVectorTableHints: "selective" },
});

The broader skipVectorTableHints: true mode remains an explicit speed experiment; it is faster but scored lower (0.4034) on full ParseBench table.

Include classified regions when your pipeline needs geometry/table metadata instead of only page markdown:

for await (const page of pages("document.pdf", {
  preset: "balanced",
  includeRegions: true,
  toc: { strip: true },
})) {
  for (const region of page.regions ?? []) {
    console.log(region.type, region.bbox, region.confidence, region.text);
  }
}

To replace built-in processing of scanned pages, use externalOcr (pages() only). Rotated scan support and unreadScan require version 0.8.4 or newer:

for await (const page of pages("document.pdf", {
  preset: "fast",
  concurrency: 2, // Native page processing/rendering, independent of external calls
  dpi: 100,
  ocrFallback: { enabled: false },
  externalOcr: {
    concurrency: 16,
    handler: async (ctx) => {
      const image = await ctx.getImage({ format: "jpeg", quality: 80 });
      return sendToExternalOcr(image, {
        pageNumber: ctx.pageNumber,
        signal: ctx.signal,
      });
    },
  },
})) {
  if (page.quality.flags.unreadScan) {
    console.warn("No readable text recovered; inspect this image page", page.pageNumber);
  }
  console.log(page.pageNumber, page.markdown);
}

sendToExternalOcr is your own service adapter; Tearout makes no external requests itself. The handler receives pageNumber (1-based document page), pagesTotal (the entire document, even with startPage/maxPages), pdfBuffer, the rendered RGB pageImage, an AbortSignal, and lazy getImage() encoding (PNG by default; JPEG defaults to quality 90). PDF /Rotate (0/90/180/270) is already applied to both pageImage and getImage(); do not rotate them again. This follows the PDF's display orientation, without detecting sideways content inside the scan. The page image uses dpi, default 100. Pass ctx.signal to your network request so cancellation can stop it.

The replacement path runs after native text extraction and rendering, before layout detection, table processing, or built-in OCR. Its scan heuristic requires fewer than 100 non-whitespace native characters and image boxes covering at least 40% of the visible page, spanning at least 60% of both its width and height, without double-counting overlapping boxes. This includes scanned content inside wide page margins, rotated pages, and offset CropBoxes. Coverage uses native image bounds; it adds no image decoding, pixel rotation, or extra rendering. Sparse pages with small logos and text-rich mixed pages keep their normal processing. This is a heuristic: a full-page photo with little native text can also qualify. Pages whose image geometry cannot be safely interpreted stay on the normal path. With externalOcr, the layout model loads only if a page needs layout detection; documents handled entirely by the scan replacement path skip model loading too.

externalOcr.concurrency defaults to 5 and limits external requests separately from concurrency. Both in-flight work and buffered results are bounded. A limit of 16 allows at most 16 requests at once; 43 pages still need multiple batches plus rendering time. Ordered delivery remains the default; ordered: false yields whichever page finishes first.

The rotation evaluation report records local throughput, real-document output comparisons, and coverage limits.

The handler's returned Markdown becomes the page output. Its errors propagate; there is no silent retry or built-in OCR fallback. pageTimeout covers native page stages; set network timeouts in your adapter. Externally processed pages skip onProblematicPage, have no detected regions, and report page.externalOcr.elapsedMs separately from built-in page.ocrDiagnostics.elapsedMs (0). Pages outside the scan heuristic still use the normal pipeline; the example disables their built-in OCR too.

Check page.quality.flags.unreadScan for image pages with fewer than 100 non-whitespace native characters and no readable output. Image placeholders do not count as text. The flag sets quality.isProblematic, even if the detector found a figure; it also flags an empty external OCR response. This signals potentially unread content, not proof of text: a blank scanned sheet or artwork can also trigger it.

To repair output after the normal pipeline, use onProblematicPage:

for await (const page of pages("document.pdf", {
  preset: "fast",
  expectsExternalOcr: true,
  onProblematicPage: async (page, ctx) => sendToMistralOcr(ctx.pdfBuffer, page.pageNumber),
})) {
  // page.markdown is already replaced if the callback fired
}

This repair callback runs only when the completed page is quality-flagged. It does not receive every scanned page, and it does not skip layout or built-in OCR. It shares the page worker's concurrency slot. If it throws, Tearout logs the error and keeps the original Markdown. Its context also has pageNumber, pagesTotal, and getImage(), alongside pdfBuffer, pageImage, and cropRegion().

expectsExternalOcr is only a scheduling hint for this repair callback. With auto concurrency and no preset concurrency override it chooses 5 workers; it does not select external processing or disable OCR. An explicit concurrency always wins. The separate externalOcr replacement path needs no such hint.

Regions iterator

For region-at-a-time pipelines, regions() flattens pages({ includeRegions: true }) and keeps page-level quality metadata on each result:

import { regions } from "tearout-pdf";

for await (const r of regions("document.pdf", {
  preset: "balanced",
  regionTypes: ["title", "section-header", "text", "list-item", "table"],
  toc: { strip: true },
})) {
  const crop = await r.cropImage({ format: "png" });
  console.log(r.pageNumber, r.type, r.bbox, r.markdown, crop.length);
}

Each RegionResult includes the raw region, convenience mirrors (type, bbox, confidence, text), per-region markdown, pageQuality, optional toc metadata, image dimensions, and cropImage().

TOC detection and stripping

Tearout exports TOC helpers for region-aware pipelines:

import { detectTableOfContents, isTocPage, parseTocEntries } from "tearout-pdf";

toMarkdown() can generate a normalized TOC prefix from detected source TOC pages:

const markdown = await toMarkdown("document.pdf", {
  preset: "balanced",
  toc: { enabled: true },
});

Use toc: { strip: true } to remove detected source TOC pages from toMarkdown(), pages(), or regions() output. Combine both flags to replace the source TOC with the generated normalized TOC:

const markdown = await toMarkdown("document.pdf", {
  preset: "balanced",
  toc: { enabled: true, strip: true },
});

Region handler (charts/tables → data, your own VLM)

pdfium reads the text layer, but a chart's values live in its pixels, and dense/borderless tables defeat structure heuristics. regionHandler is an opt-in seam: tearout detects the region locally and hands your callback a tight crop + the page's extracted text; you return markdown (e.g. an HTML table from a vision model), which is spliced into the page in reading order.

tearout ships no VLM, API key, or network code for this — the model call lives entirely in your handler. Unset, it's a zero-cost no-op.

import { pages } from "tearout-pdf";
import type { RegionHandler } from "tearout-pdf";

const toTable: RegionHandler = async (region, ctx) => {
  const crop = await ctx.cropImage({ format: "png" }); // tight region crop
  // Send `crop` + `ctx.pageText` (labels/cell-text context) to *your* VLM.
  // Branch on region.type for a chart vs table prompt. Return HTML/markdown,
  // or null to keep tearout's default rendering.
  return await myVlm.toTable(crop, ctx.pageText, region.type);
};

for await (const page of pages("document.pdf", {
  preset: "balanced",
  regionHandler: toTable,
  regionHandlerTypes: ["chart", "figure", "table"],
})) {
  console.log(page.markdown);
}

A complete, runnable consumer (Gemini Flash-Lite via OpenRouter, type-aware prompt + retry) lives in examples/chart-vlm/. Measured on ParseBench (12% subset, real scorers) the seam lifts the two dimensions pdfium structurally can't:

| dimension | local (balanced) | + seam | | --------- | ---------------- | ------ | | chart (rule_pass_rate) | 0.02 | 0.73 | | table (grits_trm_composite) | 0.39 | 0.87 |

≈ +0.23 ParseBench Overall (0.50 → ~0.73), at ~$4 / 1,000 docs and ~1.7 s/doc (VLM-bound, concurrency 6). The lift is detector-agnostic — fast/fast-yolo

  • seam reach the same chart/table scores, since the VLM does the content work and the detector only supplies the region box. Cost is incurred only on chart/figure/table regions; local-only runs are unchanged and free.

When a regionHandler is set, concurrency: "auto" scales up (network-bound, like external OCR) so a multi-page PDF overlaps its VLM calls.

Vercel serverless

// api/convert.ts
import { initTearout, toMarkdown } from "tearout-pdf";

const initPromise = initTearout({ preset: "fast", logLevel: "silent" });

export async function POST(request: Request) {
  await initPromise;
  const pdf = await request.arrayBuffer();
  const markdown = await toMarkdown(pdf, { maxPages: 5, pageTimeout: 25000 });
  return Response.json({ markdown });
}

Configuration

Common options for initTearout, toMarkdown, and pages:

| Option | Type | Default | Description | | -------------------- | ------------------- | --------- | ---------------------------------------- | | preset | PresetName | — | fast, fast-yolo, balanced, max, hybrid, hybrid-ocr, math | | dpi | number | 100 | Render DPI (72–150) | | concurrency | number \| "auto" | "auto" | Parallel pages | | skipHeadersFooters | boolean | true | Skip page headers/footers | | keepFirstPageHeader | boolean | false | Keep the first page's header (letterhead) as text | | includePageBreaks | boolean | false | Insert --- between pages | | pageTimeout | number | 30000 | Per-page timeout in ms | | logLevel | LogLevel | "info" | silent, error, warn, info, debug | | toc | TocOptions | — | Generate or strip detected source TOC pages | | includeRegions | boolean | false | pages() only — include raw classified regions | | textFirst | boolean \| TextFirstOptions | false | Use guarded positioned-text markdown on high-coverage born-digital pages | | proseFastPath | boolean | true for fast, fast-yolo; else false | Skip render and layout detection on plain prose pages. TEAROUT_PROSE_FAST_PATH=0 forces it off | | regionHandler | RegionHandler | — | pages() only — per-region callback (crop + page text → markdown). See above. | | regionHandlerTypes | RegionType[] | ["chart","figure"] | Region types regionHandler fires for | | ocrFallback | OcrFallbackOptions | preset/automatic | pages() / toMarkdown() — explicit enabled: false disables all built-in OCR fallback | | externalOcr | ExternalOcrOptions | — | pages() only — replace scanned-page processing; separate request concurrency (default 5) | | onProblematicPage | callback | — | pages() only — repair quality-flagged output after the pipeline | | expectsExternalOcr | boolean | false | pages() only — legacy repair-hook scheduling hint; does not skip OCR |

concurrency: "auto" uses two page workers per available CPU and caps at four (1 CPU → 2, 2+ CPUs → 4). This is the fast default. fast-yolo stays at one; the heavier presets stay at four. Pass a number per call to override them.

fast-yolo reads the runtime's actual CPU quota (os.availableParallelism()) and uses one detector thread on proven true two-CPU environments. Affinity masks over larger hosts, other CPU counts, and GPU paths retain ONNX Runtime defaults. Set TEAROUT_DETECTOR_INTRA_OP_THREADS=default to restore ONNX Runtime's policy, auto for Tearout's policy, or a positive integer for an explicit override. The setting is read when the detector session is created.

Tearout exports typed errors (TimeoutError, RenderError, DetectionError, AbortError) and an isTearoutError guard — see src/errors.ts.

License

Apache-2.0