Installation

This guide covers the installation of ttsforge and its dependencies.

System Requirements

Python: 3.10 or later
Operating System: Linux, macOS, or Windows
Disk Space: ~330MB for ONNX models (downloaded automatically on first use)

Dependencies

ttsforge requires the following external tools:

AudioSig waveform primitives

TTSForge depends directly on AudioSig >=0.1.2,<0.2 for reusable NumPy waveform operations: duration-based silence generation and arithmetic-mean channel downmixing. NumPy remains a direct dependency for TTSForge arrays, composition, playback buffers, and bounded I/O buffers. SoundFile remains required for audio decoding and encoding; AudioSig does not replace TTSForge’s file, FFmpeg, or audiobook orchestration layers.

PyKokoro, kokorog2p, and spaCy model policy

The package requires released PyKokoro >=0.8.4,<0.9, kokorog2p >=0.8.0,<0.9, SSMD >=0.8.1,<0.9, and phrasplit >=0.3.4,<0.4. TTSForge directly owns the PyKokoro and kokorog2p runtime boundary; the ownership chain is TTSForge -> PyKokoro -> kokorog2p -> Spokenform/abbr2words. These releases provide the public spaCy request/resolution and memory-ownership APIs used by TTSForge. TTSForge selects only already installed spaCy packages and never downloads them automatically. The default use_spacy=null policy selects the highest compatible local model and falls back to non-spaCy splitting when no compatible model is installed. use_spacy=true, --spacy, an exact package, or an exact tier is strict; use_spacy=false and --no-spacy disable spaCy.

Users should not install spokenform separately for TTSForge. The compatible kokorog2p release owns its Spokenform and abbr2words constraints. The exact PyKokoro 0.8.4 and kokorog2p 0.8.0 releases must be available from the package index before installing the TTSForge 0.3.4 release.

Install one or more compatible local spaCy packages when strict behavior or higher quality automatic selection is wanted:

python -m spacy download en_core_web_lg

With multiple tiers installed, automatic conversion may use a different model after an environment change. The concrete model is recorded in state; an incompatible old run is rejected rather than mixing model identities. Use an explicit spacy_model or spacy_model_size to make a workflow reproducible.

ffmpeg (Required for MP3/FLAC/OPUS/M4B)

ffmpeg is required for MP3/FLAC/OPUS/M4B output and chapter merging.

Termux (Android):

pkg install ffmpeg

Ubuntu/Debian:

sudo apt-get install ffmpeg

macOS (Homebrew):

brew install ffmpeg

Windows:

Download from https://ffmpeg.org/download.html and add it to PATH.

Optional: bundled ffmpeg via Python (not available on all platforms)

If you cannot install a system ffmpeg, you can try the optional prebuilt binaries:

pip install "ttsforge[static_ffmpeg]"

espeak-ng (Required for Phonemization)

espeak-ng is used for text-to-phoneme conversion.

Ubuntu/Debian:

sudo apt-get install espeak-ng

macOS (Homebrew):

brew install espeak-ng

Windows:

Download from https://github.com/espeak-ng/espeak-ng/releases

Audio Playback (Optional)

Audio playback features (--play flags and the read command) require sounddevice:

pip install "ttsforge[audio]"

Or install directly:

pip install sounddevice

spaCy Models (Optional)

spaCy is used for sentence splitting, name extraction, and spaCy-aware phonemization workflows. The base conversion does not require a local model in automatic mode:

pip install spacy
python -m spacy download en_core_web_sm
python -m spacy download en_core_web_md

Installing ttsforge

From PyPI (Recommended)

pip install ttsforge

The base installation includes the CPU ONNX Runtime provider. Provider-dependent modules are loaded only when audio rendering starts, so import ttsforge, ttsforge --help, and configuration/inspection commands work without model initialization.

Optional extras:

# Audio playback (required for --play and read)
pip install "ttsforge[audio]"

# Bundled ffmpeg binaries
pip install "ttsforge[static_ffmpeg]"

# GPU acceleration
pip install "ttsforge[gpu]"

From Source

git clone https://github.com/buchwandler/ttsforge.git
cd ttsforge
pip install -e .

Development Installation

For development with testing and linting tools:

git clone https://github.com/buchwandler/ttsforge.git
cd ttsforge
pip install -e ".[dev]"

ONNX Runtime Providers

Select a provider with an alias or full runtime provider name. The legacy Boolean interface remains available for compatibility, but NNAPI and XNNPACK are execution providers rather than GPU modes:

ttsforge config --set onnx_provider cpu
ttsforge sample "Provider test" --provider xnnpack

For CUDA, install the GPU extra in a fresh environment so CPU and GPU ONNX Runtime distributions are not installed together:

pip install "ttsforge[gpu]"
ttsforge config --set onnx_provider cuda

For Termux/Android, use the declared PyKokoro release with an ONNX Runtime build exposing NNAPI or XNNPACK:

ttsforge config \
  --set model_source github \
  --set model_variant v1.0 \
  --set model_quality fp32 \
  --set onnx_provider nnapi
ttsforge config --show
ttsforge download
ttsforge sample "Termux provider test" --provider nnapi

Use --gpu as a compatibility shortcut for --provider auto or --no-gpu for --provider cpu. Provider availability and the documented ONNX_PROVIDER environment override are handled by PyKokoro. With the required patched PyKokoro release, GitHub v1.0 uses the embedded standard vocabulary and does not download Hugging Face config.json. NNAPI is not guaranteed; use a provider exposed by the installed Android ONNX Runtime build.

Memory diagnostics

Set TTSFORGE_MEMORY_DEBUG=1 to log RSS, peak RSS, available memory, and the effective ONNX provider before and after runner initialization, chapter synthesis, WAV writing, result release, state saves, final merging, and converter cleanup. Native allocators may retain pages at a high-water mark after audio release; this diagnostic does not claim a provider-native leak from RSS alone.

Mixed-Language Support (Optional)

For automatic detection and handling of multiple languages in text (e.g., German text with English technical terms):

pip install lingua-language-detector

Then enable mixed-language mode:

ttsforge config --set use_mixed_language true
ttsforge config --set mixed_language_primary de
ttsforge config --set mixed_language_allowed "['de', 'en-us']"

Or use the --use-mixed-language flag with commands:

ttsforge convert book.epub \
    --use-mixed-language \
    --mixed-language-primary de \
    --mixed-language-allowed de,en-us

Downloading Models

ttsforge uses Kokoro ONNX models (~330MB total) which are downloaded automatically on first use. You can also download them proactively:

# Download models
ttsforge download

# Force re-download
ttsforge download --force

Models are stored in:

Linux: ~/.cache/ttsforge/
macOS: ~/Library/Caches/ttsforge/
Windows: %LOCALAPPDATA%\ttsforge\Cache\

Verifying Installation

Verify that ttsforge is installed correctly:

# Check version
ttsforge --version

# Show current configuration
ttsforge config --show

# Generate a sample audio file
ttsforge sample "Hello, world!"

If the sample command succeeds and creates sample.wav, ttsforge is ready to use.

Troubleshooting

ffmpeg not found

If you see “ffmpeg not found” errors when creating M4B files:

Ensure ffmpeg is installed (see above)
Verify it’s in your PATH: ffmpeg -version
On Windows, you may need to restart your terminal after installation

espeak-ng not found

If phonemization fails:

Ensure espeak-ng is installed (see above)
On Linux, the library should be libespeak-ng.so.1
On macOS with Homebrew, it’s typically at /opt/homebrew/lib/libespeak-ng.dylib