Xerophayze/TTS-Story

What is TTS‑Story?

TTS‑Story is a web‑based application that lets you turn a written story (or any text) into a narrated audiobook. It stitches together a front‑end UI (served locally at http://localhost:5000) with a plug‑in system for many text‑to‑speech (TTS) back‑ends – both cloud services (Google Gemini TTS, Azure, ElevenLabs, etc.) and local models that run on your CPU or GPU.

Core ideas

Feature	How it works (as described in the README)
Multi‑voice narration	You tag sections of the script with speaker tags like [narrator]…[/narrator] or [alice‑female]…[/alice‑female]. Each tag is linked to a voice profile that can be a built‑in preset, a locally‑hosted clone, or a Google‑hosted custom voice.
Voice design / cloning	The app can design new voices using Google’s Gemini TTS Cloud Voice Design (Flash or Flash‑Lite) or local “design” workflows such as Qwen3, OmniVoice, Breeze, IndexTTS, etc. The workflow creates up to four candidate voices per speaker, lets you audition them, and saves the chosen voice’s ID for later use.
Engine plug‑in system	In Settings → Engine Settings you enable any of the ~20 supported engines. Each engine lives in its own isolated virtual‑environment folder, so installing one does not affect the others. Engines can be CPU‑only, CUDA‑GPU, Apple‑MPS, or cloud‑hosted.
Job queue & checkpoints	Generation runs in a queue with progress bars, ETA, pause/resume, cancellation and automatic checkpointing. Bulk generation (e.g., generating a whole chapter for many speakers) respects Google quota limits and saves intermediate results to avoid re‑billing on failures.
Audio library & export	Finished chunks appear in an in‑app library where you can play, rename, delete, or re‑generate per‑speaker audio. The whole project can be exported as MP3 or M4B (audiobook) files with chapter metadata.
Optional LLM‑assisted text prep	Before synthesis you can run the manuscript through a language model (Gemini, Atlas Cloud, OpenRouter, LM Studio, Ollama) to clean up formatting, add directions, or generate fallback prompts.

Who might use it?

• Authors & podcasters who want a DIY audiobook pipeline without paying per‑minute fees to a single SaaS.
• Developers / researchers experimenting with different TTS models and voice‑cloning techniques.
• Small studios that need to produce multi‑character narration and want fine‑grained control over voice selection, emotion, and pacing.

Getting started (quick‑start)

1. Clone & run – git clone https://github.com/Xerophayze/TTS-Story.git, then run the provided install‑update script (Windows .bat or Linux/macOS .sh). The script creates a Python 3.11 environment, installs the core, and launches the web UI.
2. Add an engine – Open the UI, go to Settings → Engine Settings, click Install Engine, and follow the prompts (e.g., select IndexTTS 2.5 and provide an API key for any cloud service you want).
3. Create a project – Upload or paste your manuscript, add speaker tags, and optionally run an LLM pre‑processor.
4. Design voices – For each speaker open Speaker Properties, choose Gemini TTS · Cloud Voice Design (or a local design workflow), generate 1‑4 candidates, audition, and click Use voice.
5. Generate audio – Hit Generate on the main page. The queue will process each speaker, showing progress and allowing you to pause/resume.
6. Review & export – Use the Audio Library to listen, re‑generate, or delete chunks, then export the whole story as MP3 or M4B.

Notable technical details (from the README)

• Google Gemini integration – Uses a dedicated Gemini TTS API key (separate from Gemini LLM key). Supports Flash and Flash‑Lite models, up to four concurrent candidates per speaker, and respects a 200‑voice project limit with a one‑year expiry.
• Local engine isolation – Each engine gets its own virtual environment and cache folder, preventing dependency clashes.
• Emotion & direction support – IndexTTS 2.5 adds per‑chunk emotion strength (0‑1). Breeze and IndexTTS also accept directed narration metadata that influences tone without prepending a voice‑type prompt.
• Bulk voice casting – When generating many speakers, the UI batches Gemini requests, saves checkpoints after each speaker, and only retries on network‑level failures to avoid duplicate billing.
• Export formats – MP3 for simple playback; M4B for audiobook‑compatible chapter metadata.

Limitations & caveats

• Billing – Cloud engines (Google Gemini, Azure, ElevenLabs, etc.) are billable; the UI warns you before each request and shows Google’s error reason on failure.
• Voice expiry – Hosted Google voice IDs expire after a year or when deleted; you must replace them in saved projects.
• Hardware requirements – High‑quality local models (e.g., IndexTTS 2.5, Dot.TTS, Audio8) need 8‑12 GB+ of free GPU VRAM; CPU‑only fallback is possible but can be very slow.
• No local voice cloning upload – The app does not upload your own voice samples to Google; cloning is performed entirely by the selected engine.

Community & support

• The README includes a Patreon‑style support link for donations.
• A built‑in Help Center provides searchable screenshots and usage tips.
• Updates are tracked in the “Current Updates and Notes” section (latest as of 09‑13‑2026).

---

All information above is taken directly from the repository’s README; no external assumptions have been added.