🐱🔤 miao-mac-ocr-lite

Mac-only · lightweight · zero-install local OCR text extraction

Extract text from images/screenshots with a single command, powered by the built-in macOS Vision framework. Fully local — no network requests, no API keys, no extra installations.

Languages: English | 中文（简体）

Name breakdown: miao (series prefix) · mac (macOS only) · ocr (function) · lite (lightweight, zero-install)

---

✨ Features

• 🍎 macOS built-in only — powered by Apple Vision framework; no tesseract, no pip, no third-party libraries
• 🚫 Zero-install — Swift ships with macOS; download and run
• 🔒 Fully local — no network requests, no API keys, data never leaves your machine
• 🌏 Mixed zh/en — defaults to zh-Hans + en-US, languages are customizable
• ⚡ Two recognition levels — accurate (high precision, default) / fast
• 📖 Reading-order output — top-to-bottom, left-to-right; ideal for screenshots/JDs/document pages
• 📑 PDF support (v1.1) — dual-engine: extracts the text layer via PDFKit first; falls back to per-page Vision OCR for scanned PDFs (pages tagged === Page N === / === Page N (OCR) ===)

🔧 How it works

Calls the macOS Vision framework (VNRecognizeTextRequest) using Apple's neural-network text recognition. Results are sorted in reading order and printed line by line.

For PDFs (v1.1): text layer is extracted via PDFKit first; if the average text per page is below 20 chars (scanned/image-only PDF), each page is rendered to a bitmap and OCR'd by Vision as a fallback.

📋 Requirements

Requirement	Detail
OS	macOS only (depends on Vision/AppKit; Windows/Linux unsupported)
Runtime	Swift (built into macOS, no extra install)
Network	Not required

🚀 Usage

Single-file OCR (most common)

swift "scripts/ocr.swift" "/path/to/image.png"

Defaults to mixed zh/en, accurate mode; output printed line by line in reading order.

Specify languages

swift "scripts/ocr.swift" "/path/to/image.jpg" "zh-Hans,en-US,ja-JP"

Fast mode (large images / when speed matters)

swift "scripts/ocr.swift" "/path/to/image.png" "zh-Hans,en-US" fast

Arguments

swift ocr.swift <image-path> [languages,comma-separated] [level accurate|fast]

Argument	Default	Description
image path	—	required
languages	zh-Hans,en-US	comma-separated; e.g. en-US, ja-JP
level	accurate	accurate (high precision) / fast

💡 Use cases

• Extract text from screenshots (job posts, chat logs, document pages, tables)
• When a model/program cannot read images directly, convert image content to text first
• Batch local text extraction in privacy-sensitive scenarios (data never leaves the machine)

⚠️ Limitations

• macOS only — not available on Windows/Linux
• Text only — cannot read colors, composition, or visual content
• Works well on printed Chinese (screenshots, documents); limited on complex handwriting
• Multi-column layouts may be concatenated; use context to interpret

📁 File structure

miao-mac-ocr-lite/
├── README.md          # this file (English)
├── README.zh-CN.md    # 中文版说明
├── LICENSE            # MIT License
├── .gitignore         # excludes local skill-system metadata (_meta.json)
├── SKILL.md           # skill instructions (for AI agents)
├── agents/
│   └── openai.yaml    # UI metadata (skill list/display)
└── scripts/
    └── ocr.swift      # OCR script (Vision framework)

🤖 For AI agents

This tool can be used as a skill: when the model does not support multimodal input, or image text needs to be extracted, run ocr.swift. See SKILL.md for the full agent guide.

🐱 Author

Crafted by LingMiao, the AI digital companion of ZLHAOOO.

LingMiao is the author of the miao series of skills: Mac-ready · lightweight · zero-install · fully local.

📄 License

MIT