Quick start

Inspect and convert

List the chapters Readio detects in an EPUB:

ttsforge list novel.epub
ttsforge info novel.epub

Create or reuse its audiobook project and export the default M4B:

ttsforge convert novel.epub

The default project is novel.readio beside the source EPUB, and the default output is novel.m4b. Re-running the command uses the existing project’s saved chapter scope and reusable work. In an interactive terminal, TTSForge then guides you through synthesis choices and displays the resolved Readio settings before confirmation.

Select chapters

For a new project, an interactive terminal automatically displays the detected chapters and prompts for a selection; no extra flag is required. Use --chapters to select explicitly and skip that prompt:

ttsforge convert novel.epub --chapters 1-5

The selected scope is saved with the project. Reusing it does not ask for chapters again, and a conflicting --chapters value is rejected rather than silently ignored. Use --project or --fresh to create another project with a different selection. --interactive-chapters is deprecated; normal TTY behavior is automatic.

Guided synthesis setup

On a TTY, ttsforge convert novel.epub continues after chapter selection with a guided setup for omitted synthesis values. Readio catalogs are shown for available models and voices; choose a row number or enter its exact identifier. The prompts include language, runnable engine selection when needed, model and voice, speed and supported quality, spaCy and short-sentence policies, lexicon/G2P choices, capability-gated voice level, pause handling, and sentence-versus-paragraph units. The final setup displays Readio’s effective resolution before confirmation. The resolved setup is saved through Readio’s public project-settings API before confirmation or build, so a failed build can be retried and later runs do not repeat the same questions. Use --reconfigure to revisit saved choices with their saved values as defaults. Explicit CLI options pin and update only their corresponding settings.

Use explicit options to pin settings and skip matching questions, for example:

ttsforge convert novel.epub --language en-us --model MODEL_ID --voice VOICE_ID --unit paragraph

--yes skips only the final confirmation. --non-interactive and --json disable prompts and reuse settings already saved on the project. For a new or unconfigured project, Readio resolves unspecified values from its defaults; CLI options override them.

When stdin, stdout, and stderr are not all terminals, or when --non-interactive is supplied, no chapter or synthesis setup prompts appear. A new project selects all chapters unless --chapters was provided. --json also disables human-readable progress. TTY build progress updates live by chapter. See Projects and outputs for project scope and reuse details.

Preview, plan, and status

A preview uses the same Readio project pipeline as a full conversion:

ttsforge preview novel.epub --selection first:3
ttsforge plan novel.readio
ttsforge status novel.readio

preview creates or reuses the default project if necessary. status reports Readio’s current stage state and next actions.

Choose an output and synthesis settings

M4B is the default audiobook export. Readio also provides generic audio exports; inspect formats and availability for the current environment:

ttsforge formats
ttsforge convert novel.epub --format mp3 --output ./novel.mp3

You can set voice, language, engine, model, model source, quality, and speed, plus export bitrate, loudness, metadata, and cover. Readio resolves effective synthesis values; the preflight view shows those resolved values before you commit to the build. Model selectors and quality values are forwarded opaquely to Readio and installed engines:

ttsforge voices --language en-us
ttsforge convert novel.epub --voice af_heart --model kokoro-v1 --model-source github --quality fp32 --speed 1.1 --cover cover.jpg

Run ttsforge convert --help for the complete options available in this build.

Configuration and troubleshooting

TTSForge accesses Readio’s persistent configuration directly:

ttsforge config show
ttsforge config set reader.voice af_heart
ttsforge config set reader.speed 1.1
ttsforge doctor

The frontend does not create a parallel configuration file. For engine setup and project semantics, see the Readio documentation.