epub_to_audiobook

The project supports multiple Text-to-Speech (TTS) engines:

• Edge TTS: Highly recommended for quick testing because it does not require an API key (it uses Edge read-aloud functionality). However, it has more restricted parameters (e.g., limited custom SSML support).
• Azure TTS: Offers a wide range of professional voices and languages. Requires an Azure Speech resource key and region.
• OpenAI TTS: Provides high-quality models like tts-1-hd. Requires an OpenAI API key.

The output of this tool is optimized for Audiobookshelf.

• File Structure: Each chapter in the EPUB is converted into a separate MP3 file.
• Metadata: The tool attempts to extract chapter titles from the EPUB's HTML title tags. If no title tag is found, it generates a fallback title using the first few words of the chapter text.
• Navigation: When imported into Audiobookshelf, these extracted titles appear as chapter markers, allowing for easy navigation.

The --tts option allows you to choose between different Text-to-Speech providers. Note the required environment variables for cloud-based services:

• azure: Azure Cognitive Services. Requires MS_TTS_KEY and MS_TTS_REGION environment variables.
• openai: OpenAI TTS API. Requires OPENAI_API_KEY environment variable.
• edge: Microsoft Edge TTS.
• piper: Local Piper TTS.

Example (Azure):

python3 main.py input.epub output_dir --tts azure

Example (OpenAI):

python3 main.py input.epub output_dir --tts openai

You can run the tool using Docker to avoid managing Python dependencies. Pull the image from the GitHub Container Registry and mount your current directory to /app using -v ./:/app to allow access to local files.

Pull the image:

docker pull ghcr.io/p0n1/epub_to_audiobook:latest

Run with Azure:

docker run -i -t --rm -v ./:/app -e MS_TTS_KEY=$MS_TTS_KEY -e MS_TTS_REGION=$MS_TTS_REGION ghcr.io/p0n1/epub_to_audiobook your_book.epub audiobook_output --tts azure

Run with OpenAI:

docker run -i -t --rm -v ./:/app -e OPENAI_API_KEY=$OPENAI_API_KEY ghcr.io/p0n1/epub_to_audiobook your_book.epub audiobook_output --tts openai

To convert an EPUB ebook to an audiobook, run the main.py script with the input file path and the desired output folder. You must specify a TTS provider using the --tts option.

Basic Usage:

python3 main.py <input_file> <output_folder> [options]

Example:

python3 main.py examples/The_Life_and_Adventures_of_Robinson_Crusoe.epub output_folder

This will generate a directory named output_folder containing MP3 files for each chapter using the default TTS provider and voice.

You can fix pronunciations or expand abbreviations by providing a search and replace file via --search_and_replace_file. The file should contain one regex replacement per line using the <search>==<replace> format.

Example search.conf content:

# fix cardinal direction abbreviations
N\.E\.==north east
# pronounce Barbadoes like the locals
Barbadoes==Barbayduss

Usage:

python3 main.py input.epub output_dir --search_and_replace_file search.conf

python3 main.py examples/The_Life_and_Adventures_of_Robinson_Crusoe.epub output_folder --search_and_replace_file search.conf

To convert an ebook using the graphical interface, follow these steps:

1. Upload: Drag and drop your EPUB file into the file selector.
2. Select Provider: Choose between OpenAI, Azure, Edge, or Piper tabs.
3. Configure Settings:
   • OpenAI: Select model, voice, speed, and format.
   • Azure: Choose language, voice, format, and break duration.
   • Edge: Set language, voice, rate, volume, and pitch.
   • Piper: Configure local or Docker deployment with voice options.
4. Output: Set your output directory (defaults to a timestamped folder).
5. Advanced: Adjust chapter ranges or text processing if needed.
6. Preview (Optional): Select specific chapters to preview the audio before committing to a full conversion.
7. Start: Click Start and monitor progress via the integrated real-time log viewer.

To use Azure TTS, you need an Azure subscription and a Speech resource.

1. Create an Azure subscription.
2. Create a Speech resource in the Azure portal.
3. Once deployed, select Go to resource to find your Speech resource key and region.

Follow these steps to set up the converter in a local Python environment:

1. Clone the repository:

   git clone https://github.com/p0n1/epub_to_audiobook.git
   cd epub_to_audiobook

2. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

Note for Python 3.14 users: Ensure you use the updated dependency set provided in this repository to avoid pydantic-core source build failures caused by PyO3 compatibility errors.