epub-tts

Python project to gather several projects that convert EPUB files to audiobooks (M4B files, mostly), with different TTS backends.

TL;DR

Setup

git clone https://git.silveirarosa.com/renatoxsr/epub-tts
cd .\epub-tts\
pyenv local 3.11
python3 -m venv .venv
git submodule update --init --recursive

Install on Windows

.\.venv\Scripts\python.exe -m pip install -e '.[dev]'
.\.venv\Scripts\download-epub-minimal.exe
.\.venv\Scripts\download-moby-dick.exe
.\.venv\Scripts\download-moby-dick-media-overlays.exe
.\.venv\Scripts\epub-tts.exe -i .\.tmp-samples\minimal.epub -o .\.tmp-m4b\minimal.m4b -b epub2tts-edge

Install on POSIX

.\.venv\bin\python -m pip install -e '.[dev]'
.\.venv\bin\download-epub-minimal
.\.venv\bin\download-moby-dick
.\.venv\bin\download-moby-dick-media-overlays
.\.venv\bin\epub-tts -i ./.tmp-samples/minimal.epub -o ./.tmp-m4b/minimal.m4b -b epub2tts-edge

Requirements

• ffmpeg available (your distribution's version should be ok)
• Recent Python (>=3.11), pip (>=22.3), and some sort of virtual environment recommended (such as the builtin venv package).
• a Rust compatible platform. Avoid embedded systems which do not have pre-built binaries for the compiled requirements (e.g., Android's Termux try to build everything from sources and fails miserably when doing so).
• For GPU use, make sure you are installing compatible versions of pytorch and adjust your backends installation method, for instance, run pip install --force-reinstall with the correct args inside the relevant virtual environments.

Installation

1. [Optional] Create virtual environment anywhere, e.g.: python -m venv .venv and activate it.

   • See your virtual environment package's documentation, such as venv
   • A virtual environment may be “activated” using a script in its binary directory (bin on POSIX; Scripts on Windows).
   • Example: source .venv/bin/activate or .venv\Scripts\Activate.ps1

2. Install depedencies with pip install ., which should read the [dependencies] section in pyproject.toml or pip install -e '.[dev]' to install in editable mode, including dev dependencies section ([optional-depedencies]).

3. Test install running epub-tts --version

   • Make sure the venv is activated or that pip installed the package in your PATH

Sample EPUB download

After cloning with submodules, the repository now includes the EPUB 3 sample collection under src/vendor/epub3-samples.

Use the new console entrypoints to export the Moby Dick samples as EPUB files:

• download-moby-dick creates .tmp-samples/moby-dick.epub
• download-moby-dick-media-overlays creates .tmp-samples/moby-dick-mo.epub
• download-epub-minimal creates .tmp-samples/minimal.epub

The staging directory .tmp-samples/ is included in .gitignore so generated artifacts stay out of version control.

Citation

There is no need for academic citation specifics, just mention this project's URL and author, according to LICENSE.

License

See LICENSE.

Agents

See AGENTS.md.