Finrandojin/alexandria-audiobook

Alexandria Audiobook Generator

What it is – A locally‑runnable web application that turns a plain‑text book ( .txt, .md, .epub ) into a full‑featured audiobook. It stitches together an LLM‑driven script‑annotation step with a built‑in Qwen‑3 text‑to‑speech (TTS) engine, letting you assign distinct synthetic voices to every character, edit the script line‑by‑line, and export the result as a single MP3, an M4B chaptered file, or per‑speaker WAV tracks for Audacity.

---

Core workflow (5‑step pipeline)

1. Setup – Point the app at an LLM server (LM Studio, Ollama, OpenAI, or any OpenAI‑compatible API) and choose the TTS mode (local Qwen3‑TTS or an external Gradio server).
2. Script – Upload the book; the LLM parses it into a JSON script that labels speakers, adds natural vocalizations, and supplies TTS instruction fields. An optional second‑pass “review” LLM cleans up attribution errors.
3. Voices – For each detected character you can:
   • Pick one of nine pre‑trained custom voices.
   • Clone a voice from a short reference audio clip.
   • Use a LoRA‑fine‑tuned voice adapter.
   • Generate a voice on‑the‑fly with the VoiceDesigner (text description → synthetic voice).
   • Auto‑generate personas: the LLM creates a voice description, the VoiceDesign model produces a reference sample, and the clone is attached to the character with a single click.
   • Map aliases (e.g., YOUNG ELENA → ELENA) so multiple names share the same voice.
4. Editor – Batch‑render all chunks (GPU‑accelerated, sub‑batching, optional torch.compile for 3‑4× speed). You can listen, edit text/instructions, or re‑render individual chunks without re‑doing the whole book.
5. Result – Preview the finished audiobook, then download:
   • One MP3 with natural pauses.
   • Chaptered M4B for audiobook players.
   • A zip containing per‑speaker WAV files, an Audacity project, and label files for multi‑track import.

---

Highlighted features

• LLM‑driven script annotation – automatic speaker detection, dialogue extraction, and TTS instruction generation.
• Built‑in Qwen3‑TTS – runs locally (no external TTS server required) with 9 ready‑made voices and full‑language support (EN, ZH, FR, DE, IT, JA, KO, PT, RU, ES, or auto‑detect).
• Voice cloning & LoRA training – create persistent voice identities from a 5‑15 s sample or fine‑tune a LoRA adapter via an interactive dataset builder.
• Smart chunking & context preservation – groups lines by speaker (≤ 500 chars) and carries over the last three script entries to keep style consistent.
• Batch processing & GPU optimisations – sub‑batching, parallel workers, optional torch.compile, and flash‑attention for NVIDIA/AMD GPUs.
• Web UI editor – edit any line, re‑render selectively, watch live logs, and preview audio instantly.
• Export flexibility – MP3, M4B with chapters, or Audacity‑ready multi‑track package.

---

System requirements

Component	Minimum	Recommended
GPU	8 GB VRAM (any CUDA‑12.8‑compatible NVIDIA, or AMD on Linux)	16 GB+ for comfortable batch sizes
RAM	8 GB	16 GB
Disk	~20 GB (environment + model weights)	–
OS	Windows, Linux, macOS (CPU‑only on Apple Silicon)	–
Dependencies	Pinokio platform (recommended) or Docker, Python 3.10+, PyTorch, Qwen3‑TTS weights (~3.5 GB per variant)	–

---

Installation options

Method	Steps
A – Pinokio (recommended)	1. Install Pinokio from https://pinokio.computer/. 2. In Pinokio click Install via Pinokio → paste https://github.com/Finrandojin/alexandria-audiobook. 3. Click Start – the web UI opens automatically.
B – Google Colab	Open the provided notebook, supply a free ngrok token, and run – a T4 GPU is provisioned for you. No local install needed.
C – Docker (NVIDIA GPU)	```bash
git clone https://github.com/Finrandojin/alexandria-audiobook.git
cd alexandria-audiobook
docker compose up --build
``` Access UI at http://localhost:4200.

---

Quick‑start checklist

1. Run an LLM server (LM Studio, Ollama, or OpenAI) and note its base URL and API key.
2. Launch Alexandria via Pinokio/Docker/Colab.
3. In the Setup tab, enter the LLM URL, key, and model name (e.g., qwen2.5-14b). Choose TTS mode = local.
4. Upload a book file on the Script tab and click Generate Annotated Script.
5. (Optional) click Review Script to clean up speaker errors.
6. Switch to Voices, press Generate Personas to auto‑assign clone voices, or manually pick/customize voices.
7. Go to Editor, press Render Pending – watch the progress bar and listen to preview chunks.
8. When satisfied, click Merge All then Result → Download the format you need.

---

Where to get help

• Wiki – detailed guides on voice types, LoRA training, batch tuning, and troubleshooting.
• Terminal logs – Pinokio’s terminal shows model download progress, VRAM usage, and error messages.
• Common issues – see the Troubleshooting page for GPU memory errors, download stalls, and first‑batch warm‑up delays.

---

License & Community

The repository is open‑source (MIT‑style license – see LICENSE in the repo). Contributions are welcome via pull requests; issues are accepted but the maintainer notes that response times may be slow due to limited resources.

---

Bottom line – Alexandria bundles the whole audiobook‑creation pipeline—LLM script generation, multi‑character voice synthesis, interactive editing, and flexible export—into a single web UI that runs on a consumer‑grade GPU. It’s aimed at hobbyists, podcasters, and anyone who wants to turn text into a polished, fully‑voiced audiobook without paying for commercial TTS services.