Projects and outputs

Default project and reuse

For novel.epub, TTSForge uses a sibling project directory named novel.readio unless --project supplies another path:

ttsforge convert novel.epub
ttsforge status novel.readio

The first conversion creates the project and records its chapter scope. Later conversions open the same project and ask Readio to build/export from its authoritative state. Completed compatible work can be reused; Readio determines what needs to be planned, synthesized, composed, or exported again. Consult Readio’s project guide for stage and invalidation details.

Guided synthesis setup

Chapter selection remains persistent project scope. TTSForge loads saved choices from Readio’s public project-settings API. During initial setup, the resolved synthesis and export settings are saved to the Readio project before final confirmation or build; TTSForge does not create a parallel settings file.

On normal reuse, valid saved choices suppress their setup questions, and model/voice catalogs appear only when a selection is needed. If an existing or legacy project has no saved setup, Readio resolves the defaults and TTSForge saves the resulting choices. A failed build can be retried with the saved setup and original chapter scope.

Use --reconfigure to revisit unpinned synthesis choices with saved values as defaults. Explicit CLI options pin and update only their corresponding settings. When language, engine, or model changes, dependent unpinned choices are reconsidered; explicitly pinned dependent options remain unchanged.

--yes skips only final confirmation, not setup questions. --non-interactive and --json never prompt: they use saved project setup and let Readio resolve unspecified values, with explicit CLI options taking precedence.

Use --project to choose an explicit project location. This is useful for multiple audiobook variants or when project files should live outside the source directory:

ttsforge convert novel.epub --project novel-en.readio

Chapter selection is project scope

A chapter selection is applied when creating a project. For example:

ttsforge convert novel.epub --chapters 2-8

That scope is persistent. Opening the project again does not silently replace its selected chapters with a new --chapters value. To work on a different selection, create another project with --project or use --fresh:

ttsforge convert novel.epub --chapters 1-3 --fresh

When an interactive terminal creates a new project without explicit --chapters, TTSForge shows the detected chapters and prompts for the initial selection automatically. In non-TTY or --non-interactive mode, it defaults to all chapters unless a selection was provided. The deprecated --interactive-chapters flag is no longer needed.

A reused project keeps its persisted chapter scope and does not prompt again. If you pass --chapters when reusing a project, the selection must match the saved scope; TTSForge rejects a conflict rather than silently changing or ignoring it. Use another --project path or --fresh to create a project for a different selection. The preflight view shows the exact persisted chapters. list and info inspect the source EPUB without creating a project.

Fresh projects and outputs

--fresh preserves the current project and chooses a new sibling project path. If novel.readio already exists, the fresh project is typically novel.fresh.readio; if that path exists, TTSForge chooses another available numbered path. Use --project when an exact path is required.

The default output for the default M4B format is novel.m4b. Supply --output to choose another path, or --format to select a generic Readio export format. ttsforge formats reports formats available in the current installation. M4B uses Readio’s audiobook export service; it is not treated as a generic audio format.

Output replacement is deliberately explicit. --force requests replacement of an existing output according to Readio’s ownership rules. TTSForge does not remove a project’s source, state, or unrelated output files as a side effect of starting a fresh project.

Former TTSForge workspaces

Workspaces created by the previous TTSForge-owned Kokoro renderer are not Readio projects. This migration does not convert their state, completed audio, SSMD files, or resume metadata. If the default project path collides with an old workspace, TTSForge stops with migration guidance instead of overwriting or attempting to resume it.

Keep the old directory as-is. To start separately, choose a new --project path or use --fresh. Existing final audio files are also left in place unless an explicit output replacement is requested.

Status and planning

Use Readio-backed commands to inspect and advance project state:

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

status reports stage states and next actions. plan creates or refreshes Readio speech plans. preview creates or reuses the project and renders a small selection through the same Readio project pipeline used by conversion.