Skip to content
Projects

jarodise/pdf2epub-paddle

View on GitHub

jarodise/pdf2epub-paddle has 357 GitHub stars and 40 forks. GitHot measured +1 stars in 24 hours. Last checked 2026-11-19 20:27 UTC. Last push 2026-08-22.

How these counts are measured

What you can do

  • High-Quality Layout Analysis: Powered by PaddleOCR-VL 1.6 (OmniDocBench 96.3% SOTA, PP-DocLayoutV3) to intelligently detect paragraphs, headers, images, and tables.
  • Asynchronous Cloud Processing: Uses the PaddleOCR v2 Jobs API for native multi-page processing with real-time progress updates (extractedPages / totalPages).
  • Smart Chapter Splitting: Automatically detects chapter headings from OCR output. An interactive TOC review lets you confirm, remove, or adjust detected chapters before generating the EPUB.
  • Cover Image: Automatically extracts the first page of the PDF as the EPUB cover.

Measured star growth

in 24h
+1
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

This tool converts scanned PDF books into clean, readable EPUB ebooks using the Baidu PaddleOCR-VL 1.6 Layout Analysis Jobs API.

Developer Tools

README.md

Original

Scanned PDF to Epub Converter

English | 中文

This tool converts scanned PDF books into clean, readable EPUB ebooks using the Baidu PaddleOCR-VL 1.6 Layout Analysis Jobs API.

Features

  • High-Quality Layout Analysis: Powered by PaddleOCR-VL 1.6 (OmniDocBench 96.3% SOTA, PP-DocLayoutV3) to intelligently detect paragraphs, headers, images, and tables.
  • Asynchronous Cloud Processing: Uses the PaddleOCR v2 Jobs API for native multi-page processing with real-time progress updates (extractedPages / totalPages).
  • Smart Chapter Splitting: Automatically detects chapter headings from OCR output. An interactive TOC review lets you confirm, remove, or adjust detected chapters before generating the EPUB.
  • Cover Image: Automatically extracts the first page of the PDF as the EPUB cover.
  • Metadata Support: Interactively prompts for book title and author based on OCR'd first-page text, or accepts them via CLI arguments.
  • Image Embedding: Preserves and embeds images from the original PDF into the EPUB.
  • Clean Output: Removes headers, footers, and page numbers, and reflows split sentences for a seamless reading experience.
  • Robust Checkpointing: Saves job ID and result JSON locally. If interrupted, simply re-run to resume immediately.

Prerequisites

  • Python 3.8+
  • PaddleOCR API Token

Getting an API Token

  1. Log in to Baidu AIStudio (飞桨星河社区).
  2. Go to the PaddleOCR / PaddleOCR-VL-1.6 model or application section.
  3. Copy your private API Token from your user profile or API dashboard.

Installation & Usage (Recommended: uv)

This project uses uv for fast, reliable dependency management.

  1. Clone the repository:

    git clone https://github.com/yourusername/pdf2epub-paddle.git
    cd pdf2epub-paddle
    
  2. Install uv (if you haven't already):

    # On macOS/Linux
    curl -LsSf https://astral.sh/uv/install.sh | sh
    
  3. Set up your API token:

    cp .env.example .env
    

    Edit .env and add your token:

    PADDLE_API_TOKEN=your_api_token_here
    # Optional override:
    # PADDLE_API_URL=https://paddleocr.aistudio-app.com/api/v2/ocr/jobs
    # PADDLE_MODEL=PaddleOCR-VL-1.6
    
  4. Run directly with uv:

    uv run pdf2epub_paddle.py /path/to/your/book.pdf
    

    The tool will submit the PDF as an OCR job, show real-time progress, display OCR'd text from the first page, prompt for metadata, and review TOC chapters.

CLI Options

  • Provide Metadata Directly:

    uv run pdf2epub_paddle.py --title "Book Title" --author "Author Name" /path/to/your/book.pdf
    
  • Custom Output Path:

    uv run pdf2epub_paddle.py --output /path/to/output.epub /path/to/your/book.pdf
    
  • Skip Interactive TOC Review (Auto-detect):

    uv run pdf2epub_paddle.py --auto-toc /path/to/your/book.pdf
    
  • Single Chapter EPUB (No TOC splitting):

    uv run pdf2epub_paddle.py --no-toc /path/to/your/book.pdf
    

Global Command Support

You can run the tool from anywhere using the epub command:

  1. Setup: Create a symbolic link to the epub script in your PATH:

    sudo ln -s "$(pwd)/epub" /usr/local/bin/epub
    
  2. Usage:

    epub /path/to/your/book.pdf
    

License

MIT License