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 users through missing synthesis settings. Catalog discovery is allowed while engine, target, and voice choices are incomplete. Readio strictly resolves the completed synthesis target only after those selections are gathered. Project settings are saved through Readio’s public API only after that resolution succeeds, 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.

Interactive catalogs provide choices for the selected engine. Kokoro uses model then voice; Piper uses a target-bound voice bundle, and its matching canonical voice is selected automatically; Pocket uses a bundle followed by a predefined named voice. TTSForge stores these choices in Readio’s neutral model and voice request fields. The wizard gathers catalog selections before strict resolution of the complete synthesis target.

Remaining questions cover supported quality and speed, spaCy and short-sentence policies, lexicons, G2P fallback and lexicon data, supported voice-level calibration, pause mode, and synthesis unit. Pocket speed defaults automatically to 1.0. An explicit --speed value is preserved and may be rejected by Readio’s final resolution. Readio owns catalogs, capabilities, and resolution rules; the Audiobook Setup table shows the effective values used.

Interactive catalog discovery happens before strict synthesis resolution. TTSForge collects the required engine, target, and voice choices first, then strictly resolves the complete request through Readio before saving synthesis settings. If that resolution fails, the incomplete or invalid setup is not persisted. Piper is target-bound: choose its voice bundle once, and the matching canonical voice is selected automatically. Pocket uses bundle then predefined named voice; unpinned speed is 1.0. An explicit --speed pin is preserved for Readio to validate.

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.ssmdbook
ttsforge plan novel.ssmdbook

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