pdf2speech

Offline text-to-speech toolkit

PDF to audiobook, narrated with real pacing, entirely offline

pdf2speech reads your PDF, or a folder of chapter Markdown files, aloud with neural text-to-speech, adds the pauses a human narrator would use, and hands you an MP3 and a YouTube-ready video. Nothing leaves your machine.

Read the source on GitHub Jump to install

What it does

Five things that matter if you are turning a manuscript into something people will actually listen to.

Offline and private

Everything runs on your machine. No API keys, no upload, no subscription, no bill that scales with the length of your book.

Natural voices

Kokoro-82M for expressive English narration, or Piper when you need speed, or a language Kokoro does not cover.

Paced like a person is reading

Chapter announcements, a beat after epigraphs, a breath between paragraphs, and a longer rest at chapter ends.

YouTube-ready out of the box

H.264 1080p video with a cover pulled from your book's first page, or a generated title card, plus a chapter list with real timestamps to paste into the description.

Multilingual, proven in production

English, Persian (فارسی), and Danish, with voices auditioned by ear rather than picked off a list.

How it works

  1. 1

    Point it at your text

    A single PDF for a quick draft, or a folder of chapter Markdown files for book-length narration with structured pauses.

  2. 2

    Pick a voice and an engine

    Kokoro for the most natural English narrator, Piper when you want speed or need a language Kokoro does not have, such as Persian or Danish.

  3. 3

    Get files ready to publish

    An MP3, an MP4, and a chapter-timestamp file land next to your source, ready for an audiobook feed or a YouTube upload.

Install

Five commands, run once. The CPU build of torch has to go in before requirements.txt, or pip pulls the multi-gigabyte CUDA build instead.

git clone https://github.com/cocodedk/pdf2speech
cd pdf2speech
python3 -m venv .venv
.venv/bin/pip install torch --index-url https://download.pytorch.org/whl/cpu
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m piper.download_voices en_US-lessac-medium --data-dir voices

Kokoro's model downloads automatically from Hugging Face the first time you use it (about 330 MB). Other Piper voices, including the Persian and Danish ones, use the same download_voices command with a different model name.

Usage

Three tools, in order of how much book you are feeding them.

pdf2speech: quick WAV

A fast draft tool. One PDF in, one WAV out, read by Piper at an unhurried pace.

./pdf2speech mybook.pdf
./pdf2speech mybook.pdf -o out.wav

make_audiobook: MP3 and MP4 from one file

Narrates a single PDF or Markdown file and writes both an MP3 and a YouTube-ready MP4 with a static cover.

./make_audiobook mybook.pdf
./make_audiobook notes.md -o ~/out/ --engine kokoro --voice am_michael

narrate_book: the chapter-aware flagship

Reads a folder of per-chapter Markdown files in order and produces one MP3 and MP4 with heading announcements, epigraph beats, paragraph breaths, and chapter-end rests. Works in any language Piper has a voice for.

./narrate_book mybook/chapters --voice am_michael --cover-pdf book.pdf

./narrate_book mybook/persian --engine piper --voice fa_IR-ganji_adabi-medium \
    --chapter-label فصل --cover-pdf mybook-fa.pdf --name mybook-fa