PDF Reader & TTS Server

A PDF-to-HTML reader with Microsoft Edge neural text-to-speech (TTS) and word-level audio synchronization.

Extracts text directly from PDFs with embedded text layers, falling back to OCR for scanned documents.

---

Key Features

• Direct Text Extraction: Extracts selectable text layers without OCR overhead across Windows, macOS, and Linux.
• OCR Fallback: Optical character recognition for scanned documents (native winocr on Windows; pytesseract on macOS/Linux).
• Edge Neural TTS: Proxies text to Microsoft Edge neural voice endpoints with SQLite caching for audio segments.
• Web Reader UI: Responsive reader with synchronized word-by-word highlighting, playback speed and volume controls, themes, image filters, and keyboard shortcuts.
• Offline Mode: Falls back to the browser Web Speech API when the local backend server is offline.

---

Installation

1. Install Dependencies

Install requirements directly:

pip install -r requirements.txt

2. Install Project (Optional)

Install the package to expose the pdf-tts CLI tool on your system path:

pip install .

---

Getting Started

Windows Startup

Run run_server.bat to start the local server and open the most recently converted document in the default web browser.

Command Line CLI

If installed via pip install .:

pdf-tts [file.pdf | file.html] [options]

Or run directly with Python:

python -m pdf_to_speech.cli [file.pdf | file.html] [options]

Automatic File Detection

Running pdf-tts without arguments:

1. Scans the current directory for .html files and serves the newest document.
2. If no .html file is found, converts the newest .pdf into an HTML reader and starts the server.

---

Command Line Arguments

positional arguments:
  file                  Path to the PDF to convert, or HTML to serve.

options:
  -h, --help            show this help message and exit
  --convert, -c         Force conversion and text extraction of the PDF.
  --serve, -s           Start the local TTS web server.
  --output OUTPUT, -o OUTPUT
                        Custom output path for the generated HTML.
  --port PORT, -p PORT  Port to host the server (default: 8000).
  --host HOST           Host address to bind the server (default: 127.0.0.1).
  --lang LANG, -l LANG  Language code for OCR (default: hu for Hungarian).
  --force-ocr           Force OCR processing even if PDF has a text layer.

Examples

• Convert a PDF and run the server (auto-detects text layer):

  pdf-tts book.pdf

• Force OCR on a PDF with a text layer:

  pdf-tts book.pdf --force-ocr

• Serve an already converted HTML reader on a custom port:

  pdf-tts book.html --port 9000

• Convert a document using language-specific OCR:

  pdf-tts spanish_book.pdf --lang es