buchwandler

Quick Start Guide

This guide will help you get started with ttsforge quickly.

Basic Conversion

Convert an EPUB file to an audiobook with default settings:

ttsforge convert mybook.epub

This creates mybook.m4b in the same directory with:

  • Default voice: af_heart (American English female)

  • Default format: M4B (with chapter markers)

  • Auto-detected language from EPUB metadata

Choosing a Voice

List available voices:

ttsforge voices

List voices for a specific language:

ttsforge voices -l a  # American English
ttsforge voices -l b  # British English

Convert with a specific voice:

ttsforge convert mybook.epub -v am_adam  # Male voice

Voice Blending

Mix multiple voices for unique narration by specifying voice blends in the --voice parameter:

# 50/50 blend of two voices
ttsforge sample "Hello world" --voice "af_nicole:50,am_michael:50" -p

# Weighted blend (70% Nicole, 30% Michael)
ttsforge convert mybook.epub --voice "af_nicole:70,am_michael:30"

# Three-way blend
ttsforge sample "Testing" --voice "af_sky:40,af_bella:30,am_adam:30" -p

The format is: voice1:weight1,voice2:weight2,... where weights are percentages (0-100).

You can also use the traditional --voice-blend parameter:

ttsforge convert mybook.epub --voice-blend "af_nicole:50,am_michael:50"

Output Formats

ttsforge supports multiple audio formats:

# M4B audiobook (default) - includes chapter markers
ttsforge convert mybook.epub -f m4b

# MP3
ttsforge convert mybook.epub -f mp3

# WAV (uncompressed)
ttsforge convert mybook.epub -f wav

# FLAC (lossless compression)
ttsforge convert mybook.epub -f flac

# OPUS (efficient compression)
ttsforge convert mybook.epub -f opus

Converting Specific Chapters

Preview chapter list:

ttsforge list mybook.epub

Convert specific chapters:

# Convert chapters 1 through 5
ttsforge convert mybook.epub --chapters 1-5

# Convert specific chapters
ttsforge convert mybook.epub --chapters 1,3,5,7

# Mixed selection
ttsforge convert mybook.epub --chapters 1-3,5,7-10

Speed Control

Adjust speech speed (0.5 to 2.0):

# Faster
ttsforge convert mybook.epub -s 1.2

# Slower
ttsforge convert mybook.epub -s 0.9

Resumable Conversions

ttsforge automatically saves progress during conversion. If interrupted:

# Simply re-run the same command
ttsforge convert mybook.epub

# Progress is resumed from the last completed compatible unit

To start fresh, discarding previous progress:

ttsforge convert mybook.epub --fresh

Paragraph output and resume

Use paragraph conversion for visible, independently resumable render-unit WAV artifacts:

ttsforge convert mybook.epub --conversion-unit paragraph --yes

This creates mybook_paragraphs/ with fixed-width globally sequenced WAV names, marker sidecars, manifest.json, and playlist.m3u8. A render unit is an optional announced chapter title followed by a spoken paragraph. The files sort in playback order and remain after the merged audiobook succeeds. --split-mode paragraph is a separate internal batching setting. The saved conversion unit, selected chapters, and generation fingerprint cannot be changed during resume; use --fresh to start a new workspace. A complete workspace supports merge-only recovery without ONNX.

The canonical interrupted paragraph workflow is:

ttsforge convert "Platform Decay - Martha Wells.epub" --fresh --conversion-unit paragraph
# Interrupt, then resume without repeating options:
ttsforge convert "Platform Decay - Martha Wells.epub"

Resume restores the saved chapter selection, paragraph mode, output path, and omitted audio-affecting settings. An explicit changed setting is rejected with its field name; use the saved value or choose --fresh for a new workspace.

Paragraph resume persists a per-chapter preparation seed before randomized processing, so a second process skips already finalized units even when the default short-sentence handling is enabled. Pass --seed 42 for an explicit reproducible seed. If saved state is incompatible, TTSForge reports the changed fields and stops; use --fresh to deliberately discard progress and begin again. Verifiable schema-6 state is migrated to schema 7, while unverifiable state and existing paragraph WAVs are preserved. See python examples/paragraph_resume.py --help for an example that cancels after a configurable number of units before restarting.

Inspect the retained output without loading TTS models:

python examples/paragraph_manifest.py mybook_paragraphs/manifest.json

Phoneme Pre-tokenization

For large books or batch processing, pre-tokenize text to phonemes:

# Step 1: Export to phonemes (fast, no TTS)
ttsforge phonemes export mybook.epub -o mybook.phonemes.json

# Step 2: Convert phonemes to audio (can be run on different machine)
ttsforge phonemes convert mybook.phonemes.json -v af_heart

Benefits:

  • Review phonemes before generating audio

  • Faster repeated conversions (skip phonemization)

  • Separate phonemization from audio generation

Testing TTS Settings

Generate a sample to test your settings:

# Default sample
ttsforge sample

# Custom text
ttsforge sample "Hello, this is a test of the voice."

# With specific voice and speed
ttsforge sample --voice am_adam --speed 1.1

# Play directly (requires audio extra)
ttsforge sample --play

Streaming Read (Optional)

Listen to an EPUB or text file in real-time with the read command. This requires the optional audio playback extra:

pip install "ttsforge[audio]"

# Read an EPUB aloud
ttsforge read mybook.epub

# Read a text file
ttsforge read story.txt

Voice Demo

Listen to all voices with a demo:

# Demo all voices
ttsforge demo

# Demo voices for a specific language
ttsforge demo -l a  # American English only

# Save individual voice files
ttsforge demo --separate -o ./voice_samples/

Mixed-Language Support

For books containing multiple languages (e.g., German text with English technical terms), ttsforge can automatically detect and handle different languages:

# Convert a book with German and English text
ttsforge convert mybook.epub \
    --use-mixed-language \
    --mixed-language-primary de \
    --mixed-language-allowed de,en-us

# Test with a sample
ttsforge sample \
    "Das ist ein deutscher Satz. This is an English sentence." \
    --use-mixed-language \
    --mixed-language-primary de \
    --mixed-language-allowed de,en-us

Requirements: Install the language detector:

pip install lingua-language-detector

Options:

  • --use-mixed-language - Enable automatic language detection

  • --mixed-language-primary LANG - Primary/fallback language (e.g., de, en-us)

  • --mixed-language-allowed LANGS - Comma-separated list of languages to detect

  • --mixed-language-confidence FLOAT - Detection confidence threshold (0.0-1.0, default: 0.7)

Supported languages: en-us, en-gb, de, fr-fr, es, it, pt, pl, tr, ru, ko, ja, zh/cmn

Configuration: Set defaults in config:

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

SSMD Editing

ttsforge uses SSMD (Speech Synthesis Markdown) as an intermediate format between EPUB and audio. This allows you to fine-tune pronunciation and pacing.

During conversion, .ssmd files are automatically generated for each chapter:

.{book_title}_chapters/
├── chapter_001_intro.ssmd
├── chapter_001_intro.wav
└── ...

Basic workflow:

# 1. Start conversion
ttsforge convert book.epub

# 2. Pause (Ctrl+C) and edit SSMD files
vim .book_chapters/chapter_001_intro.ssmd

# 3. Resume - auto-detects edits and regenerates audio
ttsforge convert book.epub

Common SSMD syntax:

...p                               # Paragraph break
...s                               # Sentence break
*text*                             # Moderate emphasis
**text**                           # Strong emphasis
[Hermione]{ph="hɝmˈIni"}          # Custom pronunciation

EPUB conversion has three layers: epub2text performs semantic Markdown extraction, TTSForge generates editable SSMD while preserving that structure, and the SSMD policy controls audible rendering. Markdown extraction and emphasis preservation are enabled by default, while emphasis is spoken plainly:

ttsforge convert book.epub

Use --no-detect-emphasis to unwrap italic/bold delimiters without removing headings or scene breaks. Use --epub-content-mode plain to compare against the legacy flattened source path. The persisted equivalents are epub_content_mode and detect_emphasis.

To control audible emphasis strength without changing the source semantics, use the friendly level option:

ttsforge convert book.epub --emphasis-level 2
ttsforge convert book.epub --emphasis-level 3

The levels are 0=Off, 1=Light, 2=Normal, and 3=Strong. Persist the normal level with ttsforge config --set emphasis_level 2; subsequent conversions need no emphasis flag. The old --enable-ssmd-emphasis remains as a deprecated alias for level 2, while --ssmd-emphasis remains an advanced policy control. Explicit SSMD prosody remains supported independently, and a resume with omitted emphasis options restores the saved policy.

Example SSMD file:

Chapter One ...p

[Harry]{ph="hæɹi"} Potter was a *highly unusual* boy. ...s
He **hated** the summer holidays. ...p

For complete SSMD documentation, see SSMD 0.8.

Configuration

Set default options:

# Set default voice
ttsforge config --set default_voice am_adam

# Set default format
ttsforge config --set default_format mp3

# Select an ONNX Runtime provider (Termux example)
ttsforge config --set model_source github --set onnx_provider nnapi

# View all settings
ttsforge config --show

Provider aliases include auto, cpu, nnapi, and xnnpack; full *ExecutionProvider names are also accepted. The legacy --gpu and --no-gpu flags map to auto and cpu respectively.

Complete Example

Full conversion with all options:

ttsforge convert mybook.epub \
    --voice af_sarah \
    --speed 1.1 \
    --format m4b \
    --chapters 1-10 \
    --title "My Audiobook" \
    --author "Author Name" \
    --cover cover.jpg \
    --output ./audiobooks/mybook.m4b

Next Steps