API Reference

This section documents the Python API for ttsforge, allowing programmatic use of the library.

Module Overview

ttsforge is organized into the following modules:

Core Modules

ttsforge.cli

Command-line interface implementation using Click.

ttsforge.conversion

Main conversion logic for EPUB to audiobook conversion.

ttsforge.phoneme_conversion

Conversion logic for pre-tokenized phoneme files.

TTS Backend

ttsforge.kokoro_runner

Shared Kokoro ONNX runner used by conversion paths.

ttsforge.kokoro_lang

Language code helpers for Kokoro.

ttsforge.phonemes

Data structures for phoneme book representation.

Utilities

ttsforge.constants

Configuration defaults, voice definitions, and language mappings.

ttsforge.utils

Utility functions for file handling, configuration, and formatting.

ttsforge.audio_merge

Audio concatenation and chapter marker handling.

ttsforge.chapter_selection

Parsing helpers for chapter selection strings.

ttsforge.ssmd_generator

SSMD generation and validation helpers.

ttsforge.input_reader

EPUB/text input parsing helpers.

ttsforge.name_extractor

Name extraction utilities for dictionary building.

ttsforge.vocab

Vocabulary utilities and metadata.

Quick API Examples

Basic Text-to-Speech

from ttsforge.kokoro_lang import get_onnx_lang_code
from ttsforge.kokoro_runner import KokoroRunOptions, KokoroRunner

# Initialize runner
opts = KokoroRunOptions(
    voice="af_heart",
    speed=1.0,
    use_gpu=False,
    pause_clause=0.3,
    pause_sentence=0.5,
    pause_paragraph=0.9,
    pause_variance=0.05,
)
runner = KokoroRunner(opts, log=print)
runner.ensure_ready()

# Generate audio
audio = runner.synthesize(
    "Hello, world!",
    lang_code=get_onnx_lang_code("en-us"),
    pause_mode="tts",
    is_phonemes=False,
)

# Save to file
import soundfile as sf
sf.write("output.wav", audio, 24000)

Converting an EPUB

from pathlib import Path
from ttsforge.conversion import ConversionOptions, TTSConverter

# Configure conversion
options = ConversionOptions(
    voice="am_adam",
    language="a",
    speed=1.0,
    output_format="m4b",
    use_gpu=False,
)

# Create converter
converter = TTSConverter(options=options)

# Convert EPUB
result = converter.convert_epub(
    epub_path=Path("book.epub"),
    output_path=Path("book.m4b"),
)

if result.success:
    print(f"Created: {result.output_path}")
else:
    print(f"Error: {result.error_message}")

Working with Phonemes

from pykokoro.tokenizer import Tokenizer

# Initialize tokenizer
tokenizer = Tokenizer()

# Convert text to phonemes
text = "Hello, world!"
phonemes = tokenizer.phonemize(text, lang="en-us")
print(f"Phonemes: {phonemes}")

# Get token IDs
tokens = tokenizer.tokenize(phonemes)
print(f"Tokens: {tokens}")

# Human-readable format
readable = tokenizer.format_readable(text, lang="en-us")
print(f"Readable: {readable}")

Loading Configuration

from ttsforge.utils import load_config, save_config

# Load current config
config = load_config()
print(f"Default voice: {config['default_voice']}")

# Modify and save
config['default_voice'] = 'am_adam'
save_config(config)

Auto-generated API Documentation