epub_to_audiobook

Purpose

epub_to_audiobook is a tool that converts EPUB format e-books into audiobooks. It generates audio files for each chapter of the e-book through text-to-speech (TTS) technology, and the output results are optimized for Audiobookshelf, making it convenient for users to import and listen in the audiobook management platform.

Main Capabilities

• Supports multiple TTS providers: Microsoft Azure Text to Speech API, Edge TTS, OpenAI Text to Speech API, and Piper TTS.
• Converts each chapter in the EPUB file into a separate MP3 file, and extracts chapter titles as metadata.
• Provides a command-line interface and a Gradio-based WebUI graphical interface.
• WebUI features include: file upload (drag and drop), TTS provider selection, voice configuration (language, voice, output format), advanced settings, real-time logs, preview mode, search and replace (used to correct pronunciation or expand abbreviations).
• Supports configuring API credentials through environment variables.
• Provides a Docker image and docker-compose configuration to simplify deployment.
• Supports preview mode, allowing you to view the character count statistics for each chapter before conversion.
• Supports search and replace files, with each line containing a regular expression search and replacement, separated by '=='.

Usage

Installation

1. Clone the repository:git clone https://github.com/p0n1/epub_to_audiobook.git then cd epub_to_audiobook.
2. Create and activate a virtual environment:python3 -m venv venv then source venv/bin/activate.
3. Install dependencies:pip install -r requirements.txt. Note: Python 3.14 requires the updated dependency set in the repository; older versions pinned gradio==5.33.1, which may cause pydantic-core source builds to fail with PyO3 compatibility errors.
4. Set environment variables:
   • Azure:export MS_TTS_KEY=<your_subscription_key> and export MS_TTS_REGION=<your_region>
   • OpenAI：export OPENAI_API_KEY=<your_openai_api_key>
   • When using Kokoro TTS, no official OpenAI key is required, but a placeholder value needs to be set in the environment variables (for example export OPENAI_API_KEY='fake'), unless using the docker compose file.

Command-Line Usage

Basic command format:python3 main.py "path/to/book.epub" "path/to/output/folder" --tts <provider>

Examples:

• Azure basic conversion:python3 main.py "path/to/book.epub" "path/to/output/folder" --tts azure
• Azure custom language and voice:python3 main.py "path/to/book.epub" "path/to/output/folder" --tts azure --language zh-CN --voice_name "zh-CN-YunyeNeural" --log DEBUG
• Azure chapter range and paragraph interval:python3 main.py "path/to/book.epub" "path/to/output/folder" --tts azure --chapter_start 5 --chapter_end 10 --break_duration "1500"
• OpenAI basic conversion:python3 main.py "path/to/book.epub" "path/to/output/folder" --tts openai
• OpenAI HD model and specific voice:python3 main.py "path/to/book.epub" "path/to/output/folder" --tts openai --model_name "tts-1-hd" --voice_name "fable"
• OpenAI preview and text output:python3 main.py "path/to/book.epub" "path/to/output/folder" --tts openai --preview --output_text

You can use the --preview option to get a summary of each chapter (character count statistics) before conversion.

WebUI Usage

Start the WebUI: after running the corresponding command, the default access address is http://127.0.0.1:7860, and the host and port can be customized.

WebUI operation steps:

1. Upload the EPUB file.
2. Select the TTS provider from the tab (OpenAI, Azure, Edge, or Piper).
3. Configure provider-specific settings:
   • OpenAI: select model, voice, speed, and format.
   • Azure: select language, voice, format, and interval duration.
   • Edge: set language, voice, rate, volume, and pitch.
   • Piper: configure local or Docker deployment and voice options.
4. Set the output directory or use the default timestamped folder.
5. Adjust advanced options as needed (chapter range, text processing, etc.).
6. Click Start to begin conversion.
7. Monitor progress through the integrated log viewer.

You can select a few chapters to preview the audio before starting the full conversion.

Docker Usage

You can use the provided docker-compose.webui.yml file to run the WebUI. Make sure to edit the file to fill in the TTS provider's API key. The WebUI can be accessed through http://localhost:7860 or http://127.0.0.1:7860 access.

You can also use the Docker image directly: pull the image from GitHub Container Registry, then run the command. For example, OpenAI:docker run ...(refer to the repository for the specific command).-v ./:/app option mounts the current directory to the /app directory in the container, so that files can be read and written.-i and -t options are used to enable interactive mode and allocate a pseudo-terminal.

Use cases

• Convert a personal collection of EPUB e-books into audiobooks for easy management and listening in Audiobookshelf.
• Users who need to batch-convert e-book chapters while preserving chapter title metadata.
• Users who want to operate through a graphical interface (WebUI) rather than the command line.
• Users who are familiar with Docker and want to deploy quickly.
• Advanced users who need to customize parameters such as voice, language, and chapter range.

Limitations

• Requires Python 3.10+ or a Docker environment.
• Using Azure TTS requires a Microsoft Azure account and access to the Cognitive Services Speech service.
• Using OpenAI TTS requires an OpenAI API Key (except for Kokoro TTS, but a placeholder value must be set).
• Using Piper TTS requires an executable file and a model.
• The chapter title extraction method is based on parsing the title tag in HTML. It may not be perfect for EPUB files with complex or unusual formatting, and will use the first few words of the chapter text as a fallback title.
• The WebUI is a locally running web application with no authorization mechanism and should not be exposed to the public internet, otherwise it may lead to unauthorized access to the TTS provider.
• Edge TTS is based on the Edge read-aloud feature and does not require an API Key, but its parameters are limited (such as custom SSML).
• When using OpenAI-compatible services (such as matatonic/openedai-speech), the corresponding configuration must be set.
• Specific pricing and billing information is not currently provided.