[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-85141":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":14,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":17,"hasPages":17,"topics":19,"createdAt":9,"pushedAt":9,"updatedAt":32,"readmeContent":33,"aiSummary":9,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":34,"discoverSource":35},85141,"mac-ocr","privatenumber\u002Fmac-ocr","privatenumber","macOS CLI for OCR and searchable PDFs using Apple's Vision framework.",null,"Swift",176,8,2,0,38.71,"MIT License",false,"develop",[20,21,22,23,24,25,26,27,28,29,30,31],"apple-vision","cli","command-line-tool","image-to-text","macos","nodejs","ocr","pdf","searchable-pdf","swift","text-recognition","vision-framework","2026-06-15 10:04:49","\u003Cp align=\"center\">\n\t\u003Cimg src=\".github\u002Flogo.webp\" width=\"200\" alt=\"mac-ocr logo\">\n\u003C\u002Fp>\n\n\u003Ch1 align=\"center\">mac-ocr\u003C\u002Fh1>\n\n\u003Cp align=\"center\">\n\tA macOS command-line tool that reads text from images and PDFs, and creates searchable PDFs.\u003Cbr>\n\tRuns entirely on your Mac with Apple's \u003Ca href=\"https:\u002F\u002Fdeveloper.apple.com\u002Fdocumentation\u002Fvision\">Vision framework\u003C\u002Fa>; nothing is uploaded.\n\u003C\u002Fp>\n\n> [!TIP]\n> Useful for AI agents too: instead of spending vision tokens reading documents, an agent can run `mac-ocr` locally for free. A [skill](#agent-skills) is bundled so agents know how to use it.\n\n### Features\n\n- **Read text from an image:** `mac-ocr photo.png`\n- **Read text from many images:** `mac-ocr *.png`\n- **Stream text from a PDF, page by page:** `mac-ocr scan.pdf --format jsonl`\n- **Turn an image into a searchable PDF:** `mac-ocr searchable-pdf photo.png` → `photo.ocr.pdf`\n- **Add a selectable text layer to a scanned PDF:** `mac-ocr searchable-pdf scan.pdf` → `scan.ocr.pdf`\n\n## Install\n\n```sh\nnpm install -g mac-ocr\n```\n\nOr run it without installing:\n\n```sh\nnpx mac-ocr receipt.jpg\n```\n\n**Requirements:** macOS 10.15+. The npm package ships a prebuilt universal binary, so no Xcode or Swift toolchain is needed.\n\n## Recognize text\n\nOCR is the default action — you don't need a subcommand:\n\n```sh\nmac-ocr receipt.jpg                 # text → stdout\nmac-ocr page1.png page2.png         # multiple images\nmac-ocr scan.pdf                    # multi-page PDF\ncat screenshot.png | mac-ocr        # stdin\nmac-ocr https:\u002F\u002Fexample.com\u002Fa.png   # URL (simple GET)\n```\n\nDefault output is plain text. Use JSON when you need bounding boxes, confidence, or page metadata:\n\n```sh\nmac-ocr receipt.jpg --format json\nmac-ocr document.pdf --format jsonl   # one JSON object per page, streamed\n```\n\nPDF pages stream as they're recognized, so with a large document you see the first page's text right away.\n\n### Save text to files\n\n```sh\nmac-ocr ~\u002FScreenshots\u002F*.png -o '[dir]\u002F[name].txt'   # a .txt next to each image\nmac-ocr scan.pdf -o notes.md                        # recognized text to a chosen .txt\u002F.md file\nmac-ocr receipts\u002F*.pdf -o out\u002F                      # one file per input in out\u002F\ngrep -rli \"invoice\" ~\u002FScreenshots                    # then search with normal tools\n```\n\n`-o` takes a file, a directory (`out\u002F`), or a filename template ([all placeholders](docs\u002FCLI.md#writing-to-files)). Quote templates, since `[…]` is a glob pattern in zsh. Whatever the extension, the content is the plain recognized text.\n\n## Create a searchable PDF\n\n`searchable-pdf` takes a PDF or an image and writes a PDF that looks identical to the source but whose text is selectable and searchable. By default it writes `[name].ocr.pdf` next to each input — one searchable PDF per input (inputs are never merged):\n\n```sh\nmac-ocr searchable-pdf scan.pdf            # writes scan.ocr.pdf\nmac-ocr searchable-pdf photo.jpg            # image → one-page photo.ocr.pdf\nmac-ocr searchable-pdf *.pdf                # writes \u003Cname>.ocr.pdf for each\n```\n\nUse `-o` to control the destination — a directory, a `[name]` template, a fixed file, or `-` for stdout:\n\n```sh\nmac-ocr searchable-pdf scan.pdf -o out\u002F              # out\u002Fscan.ocr.pdf\nmac-ocr searchable-pdf scan.pdf -o '[name]-ocr.pdf'  # scan-ocr.pdf\nmac-ocr searchable-pdf scan.pdf -o searchable.pdf    # fixed path\nmac-ocr searchable-pdf scan.pdf -o - > scan.pdf      # stdout\n```\n\nA fixed path or `-` (stdout) takes a single input; for multiple inputs use a directory or a `[name]` template.\n\nPages that already have selectable text are skipped — only scanned pages get OCR. A PDF that needs no OCR at all passes through unchanged. To OCR every page regardless, pass `--ocr-all-pages`. The finer points (what survives a rewrite, how \"already has text\" is decided) are in [docs\u002FCLI.md](docs\u002FCLI.md#searchable-pdf).\n\nIn an interactive terminal you get a live `[page\u002Ftotal]` progress counter. Piped or redirected runs are silent on success, so scripts stay clean.\n\n## Options\n\nBoth OCR and `searchable-pdf` accept the recognition options:\n\n| Flag | Effect |\n|------|--------|\n| `--fast` | Faster, lower-accuracy recognition ([details](docs\u002FCLI.md#recognition-levels)) |\n| `--password \u003Cpassword>` | Password for an encrypted PDF (or set `MAC_OCR_PDF_PASSWORD`) |\n| `-l, --language \u003Ccode>` | Recognition language (BCP-47, repeatable). e.g. `-l en-US -l ja-JP` |\n| `-c, --confidence \u003C0–1>` | Drop observations below this confidence |\n| `-w, --custom-words \u003Cword>` | Add custom vocabulary (repeatable) |\n| `--custom-words-file \u003Cpath>` | Custom vocabulary file, one word per line |\n| `--no-language-correction` | Disable language correction |\n| `--min-text-height \u003C0–1>` | Ignore text shorter than this fraction of image height |\n| `--pdf-dpi \u003Cauto\\|72–600>` | PDF rasterization DPI (default `auto`) |\n| `--roi \u003Cx,y,w,h>` | Region of interest: restrict recognition to a normalized region (top-left origin) |\n\n### `mac-ocr \u003Cfile>`\n\n| Flag | Effect |\n|------|--------|\n| `-f, --format \u003Ctext\\|json\\|jsonl>` | Output format (default `text`) |\n| `-o, --output \u003Cpath>` | Output path, directory, or template (`[name]`, `[ext]`, `[dir]`, `[page]`). Default: stdout. Any extension — e.g. `.txt` or `.md`. |\n| `--max-candidates \u003C1–10>` | Alternative text candidates per observation |\n\n### `mac-ocr searchable-pdf \u003Cfile>`\n\n| Flag | Effect |\n|------|--------|\n| `-o, --output \u003Cdest>` | Output path, `[name]` template, directory, or `-` for stdout. Default: `[name].ocr.pdf` next to each input. |\n| `--ocr-all-pages` | OCR every page, including pages that already have selectable text (skipped by default) |\n\nList the recognition languages available on your macOS version with `mac-ocr languages` (add `--fast` for the fast recognizer's set).\n\nSee [docs\u002FCLI.md](docs\u002FCLI.md) for the full reference — every command and flag, plus the JSON output schema.\n\n## Node.js API\n\nThe same package exposes a typed, promise-based API that wraps the binary. Inputs are image or PDF **bytes** — read files or fetch URLs in your own code and pass the bytes:\n\n```sh\nnpm install mac-ocr\n```\n\n```ts\nimport fs from 'node:fs\u002Fpromises'\nimport { ocr, createSearchablePdf, supportedLanguages } from 'mac-ocr'\n\n\u002F\u002F Recognize text in an image or single-page PDF\nconst result = await ocr(await fs.readFile('receipt.jpg'))\nconsole.log(result.text)\nfor (const { text, confidence, boundingBox } of result.observations) { \u002F* … *\u002F }\n\n\u002F\u002F Multi-page PDF: stream pages as they finish…\nfor await (const page of ocr.pages(await fs.readFile('book.pdf'))) {\n    console.log(page.page, '\u002F', page.pageCount, page.text)\n}\n\u002F\u002F …or collect the whole thing into an array\nconst pages = await Array.fromAsync(ocr.pages(await fs.readFile('book.pdf')))\n\n\u002F\u002F Build a searchable PDF (returns the PDF bytes)\nconst pdf = await createSearchablePdf(await fs.readFile('scan.pdf'), { fast: true })\nawait fs.writeFile('scan.ocr.pdf', pdf)\n\n\u002F\u002F Recognition languages supported on this macOS version (for ocr and createSearchablePdf)\nconst languages = await supportedLanguages()\n```\n\nOptions mirror the CLI flags (like `{ fast: true }` above), plus an `AbortSignal` for cancellation. Failures throw a `MacOcrError` with a `kind` you can branch on. See [docs\u002FNODE.md](docs\u002FNODE.md) for every option, the result types, and error handling.\n\n## How it works\n\n`mac-ocr` is a native Swift binary built on Apple's Vision framework (`VNRecognizeTextRequest`). Recognition happens entirely on-device — nothing is uploaded. The searchable-PDF layer is invisible text drawn with Core Graphics + Core Text, placed word by word where Vision found each word.\n\n## Agent Skills\n\nThe package bundles an [agent skill](https:\u002F\u002Fagentskills.io) covering the CLI and Node API — set up [`skills-npm`](https:\u002F\u002Fgithub.com\u002Fantfu\u002Fskills-npm) in your project and coding agents discover it automatically.\n","2026-06-15 02:30:07","CREATED_QUERY"]