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
- Smarter LLM failover and speaker profiling - Prep Text now retries temporary high-demand errors on the same profile before advancing, switches immediately on explicit quota exhaustion, and supports a daily request cap for each backup profile. Speaker Properties can also build an AI profile for one selected tagged speaker.
- Production-ready audiobook exports - corrected ACX-oriented MP3 encoding, improved chapter title handling, preserved saved rebuild settings, and added clearer M4B cover-art validation and confirmation.
- More reliable online generation - configurable parallel cloud jobs, stronger timeout and retry handling, resumable progress, and safer finalization help long audiobook projects complete without restarting finished work.
- Improved progress feedback for generation, bulk speaker regeneration, and audio recompilation.
- Added OpenAI-compatible TTS with configurable models, voices, instructions, concurrency, and custom compatible endpoints.
- Improved cross-platform installation and updates for Windows, Linux, macOS, Apple Silicon, and Pinokio.
- Added Edge TTS, ElevenLabs, and Microsoft Azure Speech cloud engines, 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.
|
|
|
- Seventeen selectable TTS engine options spanning local CPU, local GPU, 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.
Setup is automatic. It creates the required environments, selects a compatible PyTorch build, installs supported engine dependencies, and downloads required tools. Individual local engines may download their model weights on first use.
- 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 environment and automatically selects CPU or supported NVIDIA CUDA packages, 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 only reconcile dependencies when definitions changed.
For a comprehensive repair:
# Windows
setup.bat --repair
# Linux/macOS
./setup.sh --repairTTS-Story exposes seventeen 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 and supported non-verbal tags. |
| 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. |
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.
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.
- 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.