We are deeply grateful to everyone who uses, shares, contributes to, and supports TTS-Story. Your encouragement helps us continue improving the project and keeping it freely available to the community.
If you appreciate what we do and would like to support ongoing development:
👉 Support TTS-Story and our other projects
- On-demand TTS engine management - initial setup now installs the lightweight TTS-Story core; local engines can be installed, removed, repaired, and monitored from Engine Settings, with each engine kept in its own isolated environment.
- LocalAI TTS integration - connect to an existing self-hosted LocalAI server, discover compatible TTS models and server voices, or use transcript-ready reference voices from TTS-Story without installing duplicate model runtimes.
- Improved voice casting and speaker workflows - strengthened Qwen3 voice-design prompts, added configurable candidates per speaker, improved bulk candidate generation, and made approved voice selections easier to review, filter, save, and reuse.
- More consistent projects and audiobook timing - saved projects now use shared server-side storage across localhost, IP-address, and alternate browser URLs, while configurable pause-marker timing and improved section detection provide better control over narration structure.
- Smarter LLM failover, configurable backup profiles, and individual speaker-profile generation.
- More reliable OmniVoice narration with protected sentence endings and configurable terminal buffers.
- Production-ready MP3/M4B exports with improved chapter metadata and rebuild handling.
- More reliable cloud generation with configurable concurrency, retries, pause/resume, and recovery checkpoints.
- Improved cross-platform installation and updates for Windows, Linux, macOS, Apple Silicon, and Pinokio.
- Added Edge TTS, ElevenLabs, Microsoft Azure Speech, and OpenAI-compatible TTS, plus the illustrated in-app Help Center.
TTS-Story is a web-based, multi-voice text-to-speech application for creating narrated stories and audiobooks. It supports local CPU and GPU models, hosted speech providers, speaker tagging, voice cloning, optional LLM-assisted text preparation, chapter collections, chunk-level repair, and MP3/M4B export workflows.
|
|
|
- Eighteen selectable TTS engine options spanning local CPU, local GPU, self-hosted, and cloud generation.
- Multi-speaker narration using tags such as
[narrator]...[/narrator]and[alice-female]...[/alice-female]. - Shared reference-voice library for Chatterbox, VoxCPM, Qwen3 Clone, OmniVoice, Pocket TTS Clone, IndexTTS, and Dot.TTS.
- Built-in voices, custom Kokoro blends, reference cloning, and Qwen3/OmniVoice voice-design workflows.
- Optional text preparation with Gemini, Atlas Cloud, OpenRouter, LM Studio, or Ollama, including configurable backup profiles.
- Automatic chapter/section detection, separate chapter exports, and optional combined Full Story output.
- Job queue with progress, ETA, pause/resume, cancellation, retry handling, and recovery checkpoints.
- Audio Library with playback, metadata, chunk review, speaker regeneration, rebuilding, MP3 downloads, and M4B packaging.
- Alternate Word Registry, per-speaker pitch/speed, pause markers, silence controls, and ACX-oriented processing.
- Searchable, screenshot-guided Help Center included inside the application.
Initial setup installs the lightweight TTS-Story application, shared audio tools, and core dependencies. It no longer downloads every local TTS engine or its model stack.
On first launch, the welcome guide directs you to Settings → Engine Settings. Local engines can be installed individually with Install Engine; each local engine receives its own virtual environment and model/cache folder so its dependency versions cannot alter another engine or the TTS-Story core. Connected engines become available after their required server address, API key, model, or service settings are saved. Engine tabs are red when setup is required and green when ready. Only ready engines appear in the Generate-page engine selector. Installed local engines can also be removed from the same panel; TTS-Story warns before deleting that engine's isolated runtime and model downloads while keeping projects, generated audio, settings, and saved voices. Installation and removal logs remain visible after navigation or refresh, and TTS-Story offers an in-app backend restart when a completed engine change requires it.
- Right-click and save install-update.bat.
- Run
install-update.batand allow setup to finish. - Run
run.bat. - Open http://localhost:5000.
The Windows installer manages the required Python 3.11 core environment. When you later install a local engine from Engine Settings, its installer selects compatible CPU or NVIDIA CUDA packages where that engine supports them, including RTX 50-series/Blackwell handling.
git clone https://github.com/Xerophayze/TTS-Story.git
cd TTS-Story
chmod +x install-update.sh run.sh
./install-update.sh
./run.shLinux/macOS setup supports Python 3.9 through 3.12. Apple Silicon uses unified memory rather than a separate VRAM pool; supported engines may use MPS, while the heavier CUDA-focused engines can be substantially slower on CPU.
- Open the TTS-Story community page in Pinokio and select Install.
- Wait until the terminal reaches Setup Complete.
- Select Start, then Open Web UI.
If an older Pinokio installation stopped partway through setup, use Factory Reset and install again.
Run install-update.bat on Windows, ./install-update.sh on Linux/macOS, or select Update in Pinokio. Normal updates reuse healthy environments and reconcile the core application without automatically installing optional engines.
For a comprehensive repair:
# Windows
setup.bat --repair
# Linux/macOS
./setup.sh --repairTTS-Story exposes eighteen normal generation choices. Qwen3 VoiceDesign and OmniVoice Design are additional Voice Creation workflows rather than full-job engines.
The figures below are practical planning ranges for the current adapters and default precision, not guaranteed minimums. Free VRAM matters: an 8 GB card with 2 GB already occupied does not provide 8 GB to the model.
| Local engine | Processing support | Approximate free VRAM to plan for | CPU-only use | Important notes |
|---|---|---|---|---|
| Kokoro-82M | CPU or NVIDIA CUDA | 0 GB required; allow roughly 1–2 GB when using CUDA | Practical | Lightweight built-in voices and local blends. |
| Chatterbox Turbo | NVIDIA CUDA recommended | About 8 GB | Selectable, but slow | English voice cloning in an isolated environment, avoiding Qwen3 dependency conflicts. |
| VoxCPM 1.5 | NVIDIA CUDA recommended | About 6 GB | Selectable, but impractical for long books | English/Chinese cloning; automatic transcription can add memory overhead. |
| Qwen3-TTS CustomVoice / Clone | NVIDIA CUDA recommended | Roughly 6–8 GB in bf16/fp16; 8 GB+ recommended | Selectable, but impractical for long books | Each mode normally loads its own 1.7B model. |
| OmniVoice Clone | NVIDIA CUDA, Apple MPS, or CPU | Roughly 4–6 GB in float16; 8 GB is safer | Supported, but extremely slow | Isolated environment; transcription or float32 can increase memory use. |
| Pocket TTS Preset / Clone | CPU only | 0 GB | Designed for CPU | English-only in the current adapter. |
| KittenTTS | CPU only | 0 GB | Designed for CPU | Eight English voices; model variants are approximately 25–80 MB. |
| IndexTTS | NVIDIA CUDA strongly recommended | Roughly 6–8 GB with FP16; allow 10–12 GB for FP32 | Selectable, but very slow | English/Chinese zero-shot cloning in an isolated environment. |
| Dot.TTS | NVIDIA CUDA strongly recommended | Plan for roughly 10–12 GB | Installation may work, but inference can be impractical | 2B-parameter, 48 kHz cloning model with multi-GB downloads. |
Cloud engines perform model inference remotely and therefore require no local TTS VRAM. Normal system RAM and CPU are still used for text handling, downloads, effects, merging, and encoding.
| Cloud engine | Local VRAM | Account or service requirement | Main consideration |
|---|---|---|---|
| Kokoro · Replicate | 0 GB | Replicate API token and billing/credits | Provider queues and prediction charges apply. |
| Chatterbox · Replicate | 0 GB | Replicate API token and billing/credits | Text and assigned reference audio are sent to Replicate. |
| Microsoft Azure Speech | 0 GB | Azure Speech key, matching region, and quota | Supported regional service with usage billing. |
| Microsoft Edge TTS | 0 GB | Internet connection; no API key | Experimental consumer endpoint with no availability guarantee. |
| ElevenLabs | 0 GB | API key, model/voice access, and character quota | Subscription and concurrency limits apply. |
| OpenAI-compatible TTS | 0 GB | Compatible endpoint, model, voice, and key when required | Cost and capabilities depend on the endpoint. |
| LocalAI TTS | Depends on the LocalAI host | Running LocalAI server with a TTS model; key only if authentication is enabled | Discovers TTS models and saved profiles, while also accepting freeform voice/speaker IDs and language values for models that do not advertise a voice catalog. |
VRAM use changes with precision, attention backend, chunk length, transcription device, drivers, and other loaded applications. FP16/bfloat16 generally use less memory than float32. NVIDIA CUDA is the primary tested path for the heavier local engines. Setup detects and validates optional FlashAttention 2 for Qwen3; when its CUDA/C++ build toolchain is unavailable, TTS-Story automatically uses PyTorch SDPA acceleration instead.
For model-specific controls, languages, privacy, and limitations, see the Engine Reference and Comparison.
- Open Generate and paste text or load a supported document.
- Optionally run Prep Text if the manuscript needs cleanup or speaker tagging.
- Review detected speakers, headings, sections, and text statistics.
- Select a TTS engine and assign a compatible voice to every speaker.
- Use Quick Test to confirm the voice, pitch, speed, and reference audio.
- Choose output format, chapter behavior, timing, and optional ACX-oriented processing.
- Select Generate Audio and monitor the Job Queue.
- Use the Audio Library to listen, repair individual chunks, regenerate speakers, rebuild audio, edit metadata, and export the final result.
The complete screenshot-guided workflow is available in Generate Your First Audio. See Install, Remove, and Reinstall TTS Engines for optional-engine management and LocalAI TTS for self-hosted speech setup.
Engine installation, removal, and backend restart remain localhost-only unless authenticated remote administration is explicitly enabled. This supports trusted LAN and reverse-proxy deployments without exposing destructive management actions by default.
- Open Available Voices → Voice Prompts.
- Upload a clean WAV, MP3, M4A, FLAC, or OGG recording.
- Use approximately 10–15 seconds of one speaker with minimal noise, music, echo, or compression.
- Add an accurate transcript when the selected engine supports or requires one.
- Return to Generate, select a compatible cloning engine, and assign the prompt to the speaker.
- Quick Test the assignment before submitting a long project.
Voice prompts can be renamed, previewed, filtered, bulk-uploaded, and reused across compatible engines. TTS-Story also provides access to the external TTS Samples library.
See Reference Voice Prompts and Assign and Test Voices for the complete workflow.
Use matching opening and closing tags:
[narrator]The wind moved through the trees.[/narrator]
[alice-female]Did you hear that?[/alice-female]
[marcus-male]Stay close. I'll check outside.[/marcus-male]
Speaker names may contain letters, numbers, underscores, and hyphens. When valid speaker-tagged blocks are present, untagged story text may not be synthesized, so review all tags before generating.
See Speaker and Expression Tags.
- The first local run is not a meaningful speed benchmark; it may include model downloads, loading, transcription initialization, and kernel warmup.
- Close games, image generators, local LLMs, and other GPU-heavy applications before loading a large TTS model.
- Use FP16 or bfloat16 where supported to reduce VRAM. Float32 normally requires substantially more memory.
- If CUDA runs out of memory, shorten the engine chunk size, move automatic transcription to CPU when available, or choose a lighter/local CPU/cloud engine.
- KittenTTS, Pocket TTS, and Kokoro are the most practical CPU choices. CPU fallbacks for large cloning models may technically run but can be unsuitable for audiobook-length work.
- Cloud speed depends on network latency, provider queues, quota, retry behavior, and configured concurrency. More parallel requests are not always faster.
- Test one representative chapter before committing to a full book, and compare later chunks rather than the first preview.
- Enable Unload GPU model after job when other applications need the VRAM between TTS-Story jobs.
To collect exact installed package and model information for troubleshooting:
python scripts/engine_versions.pyUse python scripts/engine_versions.py --json for machine-readable output. See Performance Tuning and Generation Time and ETA for more detail.
Open the Help tab inside TTS-Story for searchable, screenshot-guided instructions. The ? buttons beside interface controls open the relevant article directly. The same documentation is available under docs/help.
Useful starting points:
- First-Run Checklist
- Choose the Right Engine
- Troubleshooting Checklist
- Cloud Credentials, Quota, and Network Errors
- GPU, CPU, Model, and Dependency Errors
- Prepare a Useful Issue Report
Common first actions:
- Run the current installer/update script after pulling changes.
- Use
setup.bat --repairor./setup.sh --repairwhen an environment is damaged. - Reduce chunk size and close other GPU applications after a CUDA out-of-memory error.
- Re-fetch cloud voice/model catalogs after changing a key, region, endpoint, or account.
- Preserve the exact error message and engine-version report when opening an issue.
Settings and API keys are saved locally in config.json. The file is excluded from Git so personal settings do not block updates, but its contents are plain text. Never commit it, share it, or attach it to a public issue.
Local engines keep manuscript text and synthesis on the computer after required downloads. Cloud TTS providers receive the text they synthesize, and cloud cloning services may also receive reference audio. Cloud LLM providers receive the portions sent through Prep Text.
See Local Data, API Keys, and Backups and Configure Online Services Safely.
Apache 2.0.
- Kokoro-82M by hexgrad
- Chatterbox by Resemble AI
- VoxCPM by OpenVPI
- Qwen3-TTS by the Qwen team
- Pocket TTS by Kyutai
- KittenTTS by KittenML
- IndexTTS by the Bilibili IndexTTS team
- OmniVoice by k2-fsa
- Dot.TTS by RedNote HiLab
- TTS Samples by yaph
- StyleTTS2 by yl4579
- Replicate for hosted inference
For bugs, feature requests, or questions, open an issue on the TTS-Story GitHub repository.