CLI reference

convert

Inspect an EPUB, create or reuse its Readio project, and build/export an audiobook:

ttsforge convert novel.epub

Conversion interaction and progress

When stdin, stdout, and stderr are terminals, conversion is interactive unless --json or --non-interactive is selected. A new project without --chapters shows the detected chapter table and prompts for a selection. An existing project uses its saved chapter scope and does not prompt again.

Before preflight, convert merges saved project settings with explicitly supplied CLI values and guides you through missing synthesis settings. Normal reuse skips valid saved choices and opens catalogs only when a choice is needed. A project without saved settings—including a legacy project—gets Readio’s resolved defaults; TTSForge saves the complete resolved setup through Readio’s public project-settings API before confirmation or build. A failed build can be retried without repeating setup. Readio remains the sole owner of persisted project state.

Use --reconfigure to revisit unpinned setup fields with saved values as defaults. Explicit CLI values pin and update only their corresponding settings. Changing language, engine, or model causes dependent unpinned choices to be selected again; CLI-pinned dependents remain.

TTSForge asks for language, runnable engine selection where applicable, and model/voice catalog choices when needed. These catalogs render as compact vertical lists. Voice choices show canonical Readio voice IDs first and stable selectors as aliases; guided voice prompts accept a row number, canonical ID, selector, or qualified ID and store the selected catalog row’s canonical ID. Remaining questions cover supported quality, speed, spaCy and short-sentence policies, lexicons, G2P fallback and lexicon data, supported voice-level calibration, pause mode, and synthesis unit. Readio owns catalogs, capabilities, and resolution rules; the Audiobook Setup table shows the effective values used.

Explicit synthesis options pin and update their corresponding saved settings. --yes skips only final confirmation; it does not skip any setup questions still needed. --reconfigure reopens unpinned saved setup questions with their current values as defaults.

For a new project in non-interactive mode, chapter selection defaults to all unless --chapters is explicit. Non-interactive runs reuse valid project settings and let Readio resolve any unspecified values without prompting; CLI options override saved values. JSON mode never prompts or emits progress prose on stdout; its single result includes settings_source and settings_saved metadata. Existing projects keep their persisted chapter scope. If an explicit --chapters value conflicts with that saved scope, conversion fails with guidance to use --fresh or another --project path.

A TTY conversion uses a live, chapter-aware progress display. Redirected/non-interactive runs print milestone lines rather than every segment; JSON mode has no human-readable progress.

Chapter selection is project scope: it is persisted when the project is first created. Reusing a project does not replace its saved chapter scope. Use another --project or --fresh for a different selection. See Projects and outputs.

M4B is exported through Readio’s audiobook service; generic formats use Readio’s project export. TTSForge does not encode audio itself. Readio’s public API determines output reuse and replacement safety.

Inspecting and managing projects

ttsforge list novel.epub
ttsforge info novel.epub
ttsforge status novel.readio
ttsforge plan novel.readio

• list EPUB displays chapters and character counts.

• info EPUB displays EPUB metadata and chapter count.

• status [PROJECT] reports Readio’s stage states and next actions. The argument defaults to the current directory.

• plan PROJECT creates or updates speech plans through Readio.

preview

Render a small preview through the project pipeline:

ttsforge preview novel.epub --selection first:3

Options include --project, --chapters, --selection, --voice, --language, --engine, --speed, --target-lufs, and --json. The default selection is first:3. If no project exists, preview creates the default project; subsequent conversion reuses it. preview has a smaller option set and does not run the guided convert setup wizard.

Readio discovery

ttsforge voices [--engine ENGINE] [--language LANG] [--model MODEL] [--gender GENDER]
ttsforge models [--engine ENGINE] [--language LANG] [--status STATUS]
ttsforge engines
ttsforge formats
ttsforge doctor

voices and models accept --offline, --refresh, and --json. Catalog contents and runtime availability depend on the installed Readio engines and local environment. doctor reports Readio version, configuration, engines, dependencies, formats, and paths.

config

All configuration operations use Readio’s persisted settings; TTSForge does not maintain a duplicate settings file:

ttsforge config path
ttsforge config show
ttsforge config set reader.voice af_heart
ttsforge config init
ttsforge config languages
ttsforge config language en-us

config set KEY VALUE accepts one value; JSON values such as numbers, booleans, arrays, and objects are parsed as JSON, otherwise the value is stored as text. --path PATH selects an alternate configuration file on show and set.

ssmd

Readio-backed SSMD commands are:

ttsforge ssmd check FILE [--roundtrip]
ttsforge ssmd validate FILE [--roundtrip]
ttsforge ssmd analyze FILE
ttsforge ssmd roundtrip FILE
ttsforge ssmd materialize FILE --bindings '{"narrator":"af_heart"}' [--output OUT]

validate additionally requires resolvable voice references. materialize writes explicit bindings to a new file by default; --in-place opts into updating the source file. These commands use Readio’s SSMD authoring API; see SSMD tools.

Removed commands

read, sample, demo, download, and phonemes belonged to the former TTSForge rendering backend and are no longer registered. TTSForge does not maintain compatibility aliases or a parallel engine implementation. See the migration guide.