# tts-audiobook-generator

Generate audiobooks from books (epub, txt, pdf) using text-to-speech backends such as `audio.cpp` and `qwen-tts`. Installs and manages 

## Overview

The converter sends text extracted from your books to a locally running TTS server and assembles the returned audio into a single audiobook file.

- Input: `.txt`, `.pdf`, or `.epub`
- Output: `.m4b`, `.mp3`, `.ogg`, or `.flac`
- Supports [audio.cpp](https://github.com/0xShug0/audio.cpp), [qwen-tts](https://pypi.org/project/qwen-tts/), and [faster-qwen3-tts](https://github.com/andimarafioti/faster-qwen3-tts) backend servers
- Output a single file or one per chapter
- Automatic metadata (title/artist/album tags, chapter track numbers) and a generated cover
- Supports text-to-speech, voice cloning, voice design, and per-model controls like emotion/speed

## Prerequisites

- Python 3.12+
- ffmpeg

## Quick Start

```bash
git clone https://git.historia.vg/git/tts-audiobook-generator
cd tts-audiobook-generator
python audiobook.py
```

On first launch `audiobook.py` creates `app/envs/tts` (via `python -m venv`),
installs `requirements.txt` into it, and re-launches itself inside that
environment. Backend packages (`qwen-tts`, `faster-qwen3-tts[demo]`) are
pip-installed into the same venv by their setup wizards.


Put your book files (epub, etc.) in the `input/` directory. The output goes to `output/`.

## Quick start (TUI)

Run the generator with no arguments in a terminal:

```bash
python audiobook.py
```

A full-screen TUI opens and shows each backend's status in a table — **unavailable** (red, name dimmed: not installed and no server running), **installed** (orange), or **running** (green, when an external server is already accepting connections on its configured port). From the menu you can:

- **Convert books…** — process the `input/` directory with a ready/running backend (for a backend set up here it reads its `server.json` / `voices.json` so you pick the model and voice from menus; with only a running external server it queries the server itself instead — audio.cpp lists its models and voices over HTTP, faster asks you to type a voice name). If the server isn't running you're offered to start it automatically; after the conversion you're asked whether to stop it, or
- **Set up a backend…** — clone, build, and configure a backend end-to-end (audio.cpp, qwen, faster), or
- **Configure a backend…** — regenerate its config (a new `server.json`, rebuild `voices.json`, change ports/speaker), or
- **Server…** — manually start or stop a configured backend's server (the hub spawns it in the managed venv and polls until it accepts connections).

**Configure a backend…** and **Server…** only appear once at least one backend is installed — a merely-running external server unlocks **Convert books…**, but configuring it or starting/stopping its server needs it on this machine.

Everything the TUI does can also be scripted with flags: `python audiobook.py --backend audiocpp --model higgs --voice narrator`, or `python app/backends/audiocpp.py --families higgs_audio_tts --clone --build-backend cuda`.

You need one of the following backends (the TUI sets them up for you; manual steps below):

| Backend                                                              | Description                                            |
| -------------------------------------------------------------------- | ------------------------------------------------------ |
| [audio.cpp](https://github.com/0xShug0/audio.cpp)                    | Newer C++ TTS backend that supports many recent models |
| [Qwen-TTS](https://pypi.org/project/qwen-tts/)                       | Qwen demo server (qwen-tts-demo)                      |
| [Faster-Qwen-TTS](https://github.com/andimarafioti/faster-qwen3-tts) | Qwen server with 2-8x faster inference for NVidia GPUs |

## Options

| Flag                               | Description                                                                                                                                                                                                                                                        |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--backend {audiocpp,qwen,faster}` | TTS server to use (default `audiocpp`).                                                                                                                                                                                                                            |
| `--format {mp3,m4b,ogg,flac}`      | Output format (default `m4b`).                                                                                                                                                                                                                                     |
| `--input <dir>`                    | Directory containing the books to convert (default `./input`).                                                                                                                                                                                                     |
| `--output <dir>`                   | Directory to write finished audiobooks to (default `./output`).                                                                                                                                                                                                    |
| `--speed <n>`                      | Playback speed, pitch-preserving (`1.0` = normal). A normal-speed copy is also output.                                                                                                                                                                             |
| `--single-file`                    | Merge all chapters into a single file. `m4b` is always one file.                                                                                                                                                                                                   |
| `--language <lang>`                | Output language for the synthesized speech. Can add an accent even if the text is English.                                                                                                                                                                         |
| `--chunk`                          | Force client-side chunking into `CHUNK_SIZE`-word requests. Only matters for `--backend audiocpp`, which otherwise sends each chapter as one request and lets the server chunk long text itself (may double-chunk); the `qwen` and `faster` backends always chunk. |
| `--model <id>`                     | `audiocpp`: Choose the model from `server.json`                                                                                                                                                                                                               |
| `--instructions "..."`             | `audiocpp`: voice design or style instruction. Required for voice design models (`vdes`)                                                                           |
| `--option KEY=VALUE`               | `audiocpp`: Some models support custom options (e.g. `emotion=netural`) that can be passed with this flag                                                                                                                                                          |
| `--debug`                          | Dump each chunk's raw audio and sent text to `debug/` and log every request.                                                                                                                                                                                       |
| `--voice <name>`                   | `audiocpp`, `faster`: Server-side voice to request                                                                                                                                                                                                                 |
| `--clone <path>`                   | `qwen`: Reference audio (`wav`) for voice cloning.                                                                                                                                                                                                                 |
| `--transcription "..."`            | `qwen`: Override whisper auto-transcription with manual audio transcript.                                                                                                                                                                                          |
| `--no-transcription`               | `qwen`: Skip auto-transcription of the reference audio.                                                                                                                                                                                                            |

Other options including backend server URLs/ports are configured in `app/converter/config.py`

## TTS Backend Setup

Installation and usage documentation for each supported TTS backend is in the `app/docs/` directory:

- [audio.cpp instructions](app/docs/backend-audiocpp.md)
- [qwen-tts instructions](app/docs/backend-qwen.md)
- [faster-qwen-tts instructions](app/docs/backend-faster.md)

## Tips

Transcription affects the output a lot. Whisper does not always give perfect transcription. Manual transcription is better.

If you're cloning one language and outputting another language, `--no-transcription` will remove the accent. Alternatively, setting the "wrong" output `--language` can add an accent.

Even tiny amounts of pause between phrases in the sample audio can have a big impact. Try increasing or decreasing them or find a sample with different cadence.

## License

MIT

## Credits

- [Qwen3-Audiobook-Converter](https://github.com/WhiskeyCoder/Qwen3-Audiobook-Converter) by WhiskeyCoder. This project was originally built upon this.
- [Qwen3-TTS](https://github.com/QwenLM/Qwen3-TTS) voice model.
- [audio.cpp](https://github.com/0xShug0/audio.cpp) inference engine for the `audiocpp` backend.