mac-ocr: CLI OCR macOS tạo PDF tìm kiếm được

mac-ocr là gì?

mac-ocr là một chương trình gốc viết bằng Swift, bọc quanh API VNRecognizeTextRequest của Apple Vision framework để nhận diện văn bản trong ảnh và PDF, hoàn toàn ngay trên máy. Nó được đóng gói thành gói npm kèm sẵn universal binary, nên bạn cài như mọi công cụ dòng lệnh khác bằng `npm install -g mac-ocr`, và cũng có một API Node.js với kiểu dữ liệu rõ ràng để dùng logic OCR và tạo PDF tìm kiếm được ngay trong script.

Khả Năng Cốt Lõi

• ✓Đọc văn bản từ một ảnh hoặc nhiều ảnh cùng lúc (`mac-ocr photo.png`, `mac-ocr *.png`), với kết quả mặc định là văn bản thuần.
• ✓Xuất văn bản nhận diện được từ PDF nhiều trang theo từng trang bằng `--format jsonl`, nên tài liệu dài bắt đầu cho ra kết quả trước khi xử lý xong toàn bộ file.
• ✓Tạo PDF có thể tìm kiếm được từ tài liệu scan hoặc ảnh chụp bằng lệnh con `searchable-pdf`, thêm một lớp văn bản vô hình có thể chọn được thay vì chỉ in ra văn bản.
• ✓Chạy một bước quét phân vùng tùy chọn, tự động chia nhỏ các trang độ phân giải cao thành từng vùng khi lần quét toàn trang đầu tiên bỏ sót chữ nhỏ.
• ✓Nhận dữ liệu đầu vào từ file, luồng nhập chuẩn, hoặc một yêu cầu GET đơn giản tới URL, và có thể gộp nhiều ảnh/PDF thành một PDF kết quả duy nhất bằng `--merge`.
• ✓Cung cấp API Node.js có kiểu dữ liệu rõ ràng, dùng promise (`ocr`, `ocr.pages`, `createSearchablePdf`, `supportedLanguages`) với các tùy chọn giống hệt cờ lệnh của CLI, để dùng trong script.
• ✓Hỗ trợ chọn ngôn ngữ theo chuẩn BCP-47, thêm từ vựng tùy chỉnh, và đặt ngưỡng độ tin cậy để lọc bỏ văn bản nhận diện có độ tin cậy thấp.

Ứng Dụng Thực Tế

• •Biến một thư mục hóa đơn hoặc biên lai đã scan thành file văn bản để làm sổ sách, dùng `-o '[dir]/[name].txt'` để ghi một file .txt cho mỗi ảnh rồi tìm kiếm trong kết quả.
• •Biến một PDF scan cũ, như hợp đồng thuê nhà hay một mẫu giấy tờ, thành bản có thể chọn và tìm kiếm được mà không cần gõ lại, qua lệnh `mac-ocr searchable-pdf scan.pdf`.
• •Cho một coding agent khả năng OCR cục bộ thay vì tốn token của mô hình thị giác để đọc ảnh chụp màn hình hay tài liệu — README có nhắc tới một agent skill đi kèm cho đúng việc này.
• •Trích văn bản có kèm khung tọa độ và độ tin cậy (`--format json`) cho một pipeline phía sau cần vị trí từng từ, không chỉ văn bản thô.
• •Gộp nhiều trang ảnh chụp thành một PDF tìm kiếm được có thứ tự, dùng `--merge`, tiện khi scan tài liệu nhiều trang bằng camera điện thoại.

Bắt Đầu Sử Dụng

Cài đặt toàn cục bằng `npm install -g mac-ocr`, hoặc bỏ qua bước cài và chạy thử một lần với `npx mac-ocr receipt.jpg`. Gói npm đi kèm sẵn universal binary, nên không cần cài Xcode hay bộ công cụ Swift — chỉ cần macOS 10.15 trở lên là đủ. Nếu chỉ cần API Node.js trong một dự án, `npm install mac-ocr` cũng kéo theo binary tương tự và cung cấp các hàm `ocr`, `ocr.pages`, `createSearchablePdf` thay vì một dòng lệnh.

Công Cụ OCR Khác Cho macOS

Câu Hỏi Thường Gặp

Vấn đề mà nó giải quyết

Phần lớn lựa chọn OCR dạng dòng lệnh trên macOS buộc bạn chọn một trong hai: gửi tài liệu lên máy chủ OCR đám mây và trả phí theo từng trang, hoặc cài Tesseract cùng các gói dữ liệu ngôn ngữ và chuỗi phụ thuộc riêng của nó. mac-ocr thay vào đó gọi thẳng Vision framework vốn có sẵn trong macOS, nên việc nhận diện chạy ngay trên máy, không cần tải thêm mô hình nào ngoài gói npm, và không có gì được tải lên đâu cả.

Cách sử dụng

OCR là hành động mặc định, nên không cần thêm lệnh con: `mac-ocr receipt.jpg` in văn bản nhận diện ra màn hình, còn `mac-ocr scan.pdf` xử lý PDF nhiều trang. Nó cũng đọc được từ luồng nhập chuẩn (`cat screenshot.png | mac-ocr`) và từ URL bằng một yêu cầu GET đơn giản. Kết quả mặc định là văn bản thuần; thêm `--format json` để lấy khung tọa độ và độ tin cậy cho từng vùng nhận diện, hoặc `--format jsonl` để xuất mỗi trang PDF thành một đối tượng JSON ngay khi nhận diện xong. Với PDF tìm kiếm được, `mac-ocr searchable-pdf scan.pdf` ghi ra `scan.ocr.pdf` cạnh file gốc, giữ nguyên ảnh gốc và thêm một lớp văn bản vô hình đặt theo từng từ bằng Core Graphics và Core Text, tại đúng tọa độ Vision trả về. Ở chế độ không gộp, các trang đã có sẵn văn bản chọn được sẽ bị bỏ qua mặc định — thêm `--ocr-all-pages` để ép quét lại toàn bộ trang. Bên dưới, cả hai lệnh đều gọi `VNRecognizeTextRequest` của Apple Vision framework, nên việc nhận diện diễn ra ngay trên máy đang chạy lệnh, và README khẳng định không có gì được tải lên.

Nên dùng cho ai — và ai nên bỏ qua

Nên thử mac-ocr nếu bạn đang xây một script, agent, hoặc công cụ nội bộ chỉ chạy trên macOS, cần lấy văn bản từ ảnh chụp màn hình, hóa đơn, hoặc PDF scan mà không muốn gửi gì lên API đám mây — API Node.js và kết quả JSON xuất theo dòng giúp gắn nó vào pipeline có sẵn khá dễ. Bỏ qua nếu code của bạn còn phải chạy trên máy chủ Linux hoặc máy Windows, vì toàn bộ công cụ dựa vào một framework chỉ có trên macOS, hoặc nếu bạn chỉ cần đọc một tài liệu duy nhất một lần — kéo file vào Live Text trong Preview còn nhanh hơn cài đặt bất cứ thứ gì.

Repo liên quan