scan-to-ebook là gì, và tại sao đáng dùng? scan-to-ebook là một công cụ miễn phí, mã nguồn mở, do anh Phúc Nguyễn (phuc-nt) viết. Nó nhận đầu vào là ảnh chụp/scan sách giấy hoặc file PDF scan, và xuất ra file EPUB sạch đẹp đọc được trên Kindle, máy tính bảng, điện thoại. Điểm hay so với cách số hóa truyền thống (OCR bằng ABBYY FineReader, Tesseract...): Dùng AI thị giác (vision LLM) để đọc chữ — nhận diện tiếng Việt có dấu cực tốt, kể cả chữ Quốc ngữ cổ. Tác giả đã test với tạp chí Nam Phong 1917 (75 trang) đạt 0 lỗi OCR. Hiểu ngữ cảnh sách — đọc trước vài trang mẫu để nắm tên sách, tên riêng, quy ước chính tả, rồi áp dụng nhất quán cho toàn bộ sách. Báo trước chi phí — chạy thử 10 trang và ước tính tiền cho cả cuốn trước khi bạn quyết định. Rất rẻ — một cuốn 400 trang thường chỉ tốn khoảng 20.000 - 30.000 VNĐ tiền API. Trang dự án: Vui lòng đăng nhập hoặc đăng ký để xem link Bạn cần chuẩn bị gì? 1. Một máy tính Windows (bài này hướng dẫn Windows; Mac/Linux có cách tương tự, xem README gốc). 2. Nguồn sách — một trong hai dạng: Thư mục chứa ảnh các trang sách (JPG/PNG/HEIC), hoặc Một file PDF scan của cuốn sách. 3. Tài khoản OpenRouter để dùng AI đọc chữ. OpenRouter là dịch vụ trung gian cho phép gọi nhiều loại AI khác nhau bằng một API key. Bạn cần nạp tiền vào (tối thiểu khoảng 5 USD, đủ dùng cho nhiều cuốn sách). 4. Khoảng 1-2 tiếng cho lần cài đặt đầu tiên. Những lần sau chỉ vài phút. Tin vui: mọi thứ không cần quyền admin trên máy tính. Phần 1: Cài đặt (làm một lần duy nhất) Bước 1.1: Cài Python Python là "động cơ" để chạy công cụ. Cài như sau: Vào Vui lòng đăng nhập hoặc đăng ký để xem link và tải bản mới nhất (Python 3.12 hoặc 3.13). Chạy file vừa tải. Quan trọng: Tick vào ô "Add Python to PATH" ở dưới cùng (rất quan trọng, đừng quên). Bỏ tick "Install for all users" nếu có (để không cần admin). Bấm Install Now và chờ. Kiểm tra cài thành công: mở PowerShell (bấm phím Windows, gõ "powershell"), gõ: python --version Nếu hiện ra Python 3.12.x (hoặc số tương tự) là OK. Bước 1.2: Tải pandoc (công cụ tạo file EPUB) Vào Vui lòng đăng nhập hoặc đăng ký để xem link Tìm file có tên dạng pandoc-X.Y-windows-x86_64.zip (file ZIP, đừng tải file .msi). Giải nén ra một thư mục dễ nhớ, ví dụ: C:\Users\<tên-bạn>\Tools\pandoc\ Bên trong sẽ có file pandoc.exe. Bước 1.3: Tải poppler (chỉ cần nếu nguồn là file PDF) Nếu sách của bạn là PDF, cần thêm poppler để chuyển PDF thành ảnh: Vào Vui lòng đăng nhập hoặc đăng ký để xem link Tải file Release-XX.XX.X-0.zip mới nhất. Giải nén ra thư mục, ví dụ: C:\Users\<tên-bạn>\Tools\poppler\ Tìm file pdftoppm.exe bên trong (thường nằm ở poppler\Library\bin\ hoặc poppler\bin\) — nhớ đường dẫn thư mục chứa nó. Nếu nguồn của bạn là ảnh JPG/PNG thì bỏ qua bước này. Bước 1.4: Tải code scan-to-ebook Vào Vui lòng đăng nhập hoặc đăng ký để xem link Bấm nút xanh Code → Download ZIP. Giải nén ra thư mục dễ nhớ, ví dụ: C:\Users\<tên-bạn>\Tools\scan-to-ebook\ Bước 1.5: Cài Python package Mở PowerShell, đi vào thư mục code: cd C:\Users\<tên-bạn>\Tools\scan-to-ebook (Đổi <tên-bạn> thành tên thư mục thật của bạn.) Tạo môi trường ảo và cài: python -m venv .venv .\.venv\Scripts\pip install -e . Chờ vài phút cho xong. Không có lỗi đỏ là thành công. Bước 1.6: Đăng ký OpenRouter và lấy API key Vào Vui lòng đăng nhập hoặc đăng ký để xem link → bấm Sign In (đăng ký bằng Google/GitHub). Vào mục Credits → nạp tiền (tối thiểu 5 USD, dùng được rất lâu). Vào mục Keys → bấm Create Key → đặt tên bất kỳ → bấm Create. Copy chuỗi key (dạng sk-or-v1-...) và lưu lại — bạn sẽ cần nó ở bước sau. Bước 1.7: Tạo file cấu hình API key Vẫn trong PowerShell ở thư mục scan-to-ebook: copy .env.example .env notepad .env Notepad sẽ mở. Tìm dòng OPENROUTER_API_KEY= và dán key của bạn vào sau dấu =, ví dụ: OPENROUTER_API_KEY=sk-or-v1-abc123... Lưu (Ctrl+S) và đóng Notepad. Phần 2: Cấu hình PATH (mỗi lần mở PowerShell) Đây là bước hay quên nhất. Mỗi lần mở PowerShell mới để chạy công cụ, phải làm bước này trước. Trong PowerShell, gõ (đổi đường dẫn cho đúng máy bạn): " # Báo cho Windows biết pandoc ở đâu $envATH = "C:\Users\<tên-bạn>\Tools\pandoc;" + $envATH # Báo cho Windows biết pdftoppm ở đâu (chỉ nếu dùng PDF) $envATH = "C:\Users\<tên-bạn>\Tools\poppler\Library\bin;" + $envATH # Vào thư mục code và kích hoạt môi trường cd C:\Users\<tên-bạn>\Tools\scan-to-ebook .\.venv\Scripts\Activate.ps1 " Mẹo tiết kiệm thời gian: lưu 4 dòng này vào một file .ps1 (ví dụ start.ps1), lần sau chỉ cần chạy .\start.ps1 là xong. Kiểm tra mọi thứ sẵn sàng: scan2ebook doctor Cần thấy đủ ✓ ở python, pandoc, openrouter_key. Cuối cùng phải hiện "OK — sẵn sàng chạy". Nếu có ✗ ở pandoc, là PATH chưa đúng — xem lại đường dẫn. (Các cảnh báo ⚠ về heic_convert, pdf_render, rclone chỉ là tùy chọn — chỉ cần khắc phục nếu bạn dùng đến.) Phần 3: Chuyển sách thành EPUB Bước 3.1: Chuẩn bị nguồn Nếu nguồn là PDF: đặt file PDF ở chỗ dễ tìm. Quan trọng: tên file đừng có dấu tiếng Việt, đừng có khoảng trắng. Đổi tên thành ten-sach.pdf cho an toàn. Ví dụ: thay vì Bẫy hạnh phúc.pdf, đổi thành bay-hanh-phuc.pdf. Nếu nguồn là ảnh: bỏ tất cả ảnh các trang vào một thư mục. Tên ảnh tốt nhất nên đánh số thứ tự (page_001.jpg, page_002.jpg...). Bước 3.2: Đăng ký sách với công cụ scan2ebook init ten-sach --from "C:\duong-dan\den\nguon" Trong đó: ten-sach là cái tên nội bộ bạn đặt (chỉ dùng chữ thường, gạch ngang, không dấu). Đường dẫn nguồn trỏ đến file PDF hoặc thư mục ảnh. Ví dụ: scan2ebook init bay-hanh-phuc --from "C:\Users\Huy\Tools\scan-to-ebook\book\bay-hanh-phuc.pdf" Công cụ sẽ tạo một thư mục làm việc tại C:\Users\<bạn>\scan2ebook\ten-sach\. Đây là nơi lưu kết quả. Bước 3.3: Chạy thử 10 trang (smoke test) Đây là bước quan trọng — chạy thử và xem trước chi phí: scan2ebook all ten-sach --smoke Công cụ sẽ: Đọc lướt vài trang để hiểu sách (tên, tên riêng, chính tả...). OCR 10 trang đầu. Dựng bản EPUB mẫu. Báo chi phí ước tính cho cả cuốn. Dừng lại hỏi bạn có muốn chạy tiếp không. Output sẽ giống như: Done. ok=10 blank=0 fail=0 cost~$0.0203 Nghĩa là 10 trang đã tốn ~0,02 USD (~500 VNĐ). Sách 400 trang sẽ tốn khoảng 0,80 USD (~20.000 VNĐ). Bước 3.4: Xem bản preview trước khi chạy đầy đủ Trước khi gõ y, hãy mở bản EPUB preview để kiểm tra chất lượng: explorer C:\Users\<bạn>\scan2ebook\ten-sach\dist Mở file .smoke.epub bằng Calibre hoặc app đọc sách bất kỳ. Kiểm tra: Dấu tiếng Việt có đúng không? Tên riêng có chính xác không? Định dạng (đậm, nghiêng, tiêu đề) có hợp lý không? Nếu ổn, quay lại PowerShell và gõ y để chạy nốt toàn bộ sách. Nếu chưa ổn, gõ n rồi xem mục Xử lý sự cố ở dưới. Bước 3.5: Chờ và lấy thành quả Công cụ sẽ chạy nốt các trang còn lại. Một cuốn 400 trang thường mất 15-30 phút, tùy tốc độ mạng và model AI. Khi xong, file EPUB hoàn chỉnh nằm tại: C:\Users\<bạn>\scan2ebook\ten-sach\dist\ten-sach.epub Copy ra, đưa vào Calibre để chỉnh sửa metadata (bìa, tác giả, thể loại) trước khi chia sẻ. Xử lý sự cố thường gặp Lỗi --from không phải thư mục ảnh hay file PDF dù file rõ ràng ở đó: → Tên file/thư mục có dấu tiếng Việt hoặc khoảng trắng. Đổi tên sang ASCII (không dấu, không space). Lỗi pandoc YAML parse exception khi build EPUB: → Tựa sách có dấu hai chấm :. Mở file scans\metadata.json trong thư mục làm việc, đổi dấu : trong title thành dấu gạch ngang - . Doctor báo pandoc: not installed dù bạn đã tải: → PATH chưa đúng. Kiểm tra bằng where.exe pandoc. Nếu không ra gì, set lại PATH (chú ý dấu chấm phẩy ; ngăn cách). Chạy nửa chừng bị lỗi, mất điện, đứt mạng: → Yên tâm, chạy lại lệnh scan2ebook all ten-sach là nó tự bỏ qua các trang đã OCR và làm tiếp từ chỗ dừng. Không mất tiền. Chất lượng OCR kém một vài trang: → Xóa file .md của trang đó trong thư mục làm việc, rồi chạy lại — tool sẽ OCR lại trang đó. Một vài lưu ý: Về chi phí: OpenRouter có nhiều model AI khác nhau với giá khác nhau. Mặc định công cụ chọn model rẻ và chất lượng tốt. Nếu cuốn sách khó (chữ mờ, font lạ), có thể cấu hình model mạnh hơn — xem README gốc. Về chất lượng nguồn: Ảnh càng rõ, chữ càng sắc nét thì kết quả càng tốt. Sách scan 300dpi trở lên, chụp đủ sáng, ít cong vênh sẽ cho kết quả gần như hoàn hảo. Về việc đóng góp lại cho dự án: Nếu bạn dùng tốt, hãy ghé GitHub của tác giả bấm Star ⭐ để ủng hộ, và báo lỗi/góp ý qua mục Issues. Tác giả là người Việt, rất hoan nghênh phản hồi từ cộng đồng số hóa sách Việt. Hướng dẫn này được tổng hợp dựa trên kinh nghiệm thực tế cài đặt và sử dụng. Mọi góp ý xin gửi vào thread này để mọi người cùng thảo luận ạ. * Bài hướng dẫn này em tạo bằng AI dựa trên demo em làm thủ một cuốn để kiểm tra thử phần mềm có hiệu quả không. Kính mong mọi người góp ý ạ. Trân trọng, Hoaithuat
