TTS-Story

❤️ Thank You for Supporting Our Work

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

Current Updates and Notes - updated 08-07-2026

• 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.

Previous Updates

• 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

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.

Highlights

• 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.

Installation

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.

Windows

1. Right-click and save install-update.bat.
2. Run install-update.bat and allow setup to finish.
3. Run run.bat.
4. 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.

Linux and macOS

git clone https://github.com/Xerophayze/TTS-Story.git
cd TTS-Story
chmod +x install-update.sh run.sh
./install-update.sh
./run.sh

Linux/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.

Pinokio

1. Open the TTS-Story community page in Pinokio and select Install.
2. Wait until the terminal reaches Setup Complete.
3. Select Start, then Open Web UI.

If an older Pinokio installation stopped partway through setup, use Factory Reset and install again.

Updates and repair

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 --repair

Supported Engines and Hardware

TTS-Story exposes seventeen normal generation choices. Qwen3 VoiceDesign and OmniVoice Design are additional Voice Creation workflows rather than full-job engines.

Local engine hardware guide

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.

Cloud engine requirements

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.

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.

Basic Workflow

1. Open Generate and paste text or load a supported document.
2. Optionally run Prep Text if the manuscript needs cleanup or speaker tagging.
3. Review detected speakers, headings, sections, and text statistics.
4. Select a TTS engine and assign a compatible voice to every speaker.
5. Use Quick Test to confirm the voice, pitch, speed, and reference audio.
6. Choose output format, chapter behavior, timing, and optional ACX-oriented processing.
7. Select Generate Audio and monitor the Job Queue.
8. 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.

Voice Cloning

1. Open Available Voices → Voice Prompts.
2. Upload a clean WAV, MP3, M4A, FLAC, or OGG recording.
3. Use approximately 10–15 seconds of one speaker with minimal noise, music, echo, or compression.
4. Add an accurate transcript when the selected engine supports or requires one.
5. Return to Generate, select a compatible cloning engine, and assign the prompt to the speaker.
6. 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.

Speaker Tags

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.

Performance Guidance

• 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.py

Use python scripts/engine_versions.py --json for machine-readable output. See Performance Tuning and Generation Time and ETA for more detail.

Help and Troubleshooting

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 --repair or ./setup.sh --repair when 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.

Local Settings and Privacy

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.

License

Apache 2.0.

Credits

• 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

Support

For bugs, feature requests, or questions, open an issue on the TTS-Story GitHub repository.