Metadata-Version: 2.4
Name: ttsforge
Version: 0.4.1
Summary: User-friendly audiobook conversion powered by Readio.
Author-email: Holger Nahrstaedt <nahrstaedt@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Holger Nahrstaedt
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/buchwandler/ttsforge
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: readio>=0.3.4
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.20.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Dynamic: license-file

[![PyPI - Version](https://img.shields.io/pypi/v/ttsforge)](https://pypi.org/project/ttsforge/)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ttsforge)
![PyPI - Downloads](https://img.shields.io/pypi/dm/ttsforge)
[![codecov](https://codecov.io/gh/buchwandler/ttsforge/graph/badge.svg?token=iCHXwbjAXG)](https://codecov.io/gh/buchwandler/ttsforge)

# TTSForge

**TTSForge is an audiobook-focused command-line frontend for
[Readio](https://github.com/buchwandler/readio).** It gives EPUB audiobook workflows a
concise CLI; Readio owns the persistent project, speech planning, synthesis,
composition, progress, and export.

TTSForge does not implement or bundle a parallel speech engine. Use Readio's public
application API and its engine integrations; TTSForge maps audiobook choices to those
services.

TTSForge requires Readio `>=0.3.4`, which provides the public audiobook API, expanded
synthesis-resolution contract, and persisted project settings used by guided setup.
Install TTSForge normally, then add a Readio engine integration as needed; see
[Installation](docs/installation.md) for setup and development instructions.

## What it does

- Inspect EPUB metadata and chapter structure.
- Create or reuse a persistent Readio project for an audiobook.
- Select chapters, preview speech, plan a project, and check authoritative project
  status.
- Export M4B audiobooks or formats supported by Readio's generic export service.
- Discover voices, models, engines, and formats through Readio.
- Use Readio's configuration and SSMD authoring/checking services.

## Quick start

Install TTSForge and a Readio engine integration using the Readio extra for your
platform; see [Installation](docs/installation.md) for details. Then run:

```bash
ttsforge convert novel.epub
```

In an interactive terminal, a new project shows the detected chapters and prompts for a
selection, then guides you through synthesis settings not supplied by CLI or already
saved in the project. Readio's model and voice choices appear only when a choice is
needed. The resolved setup is saved to the Readio project before confirmation or build.
Later runs reuse those values, so a failed build can be retried without repeating setup
prompts. Use `--reconfigure` to review saved choices with their current values as
defaults; explicit CLI options pin and update their corresponding settings. Build
progress updates live by chapter.

For automation, specify `--chapters` and any synthesis options that should override the
project. `--yes` skips only final confirmation; `--non-interactive` and `--json` never
prompt and reuse saved setup when available. Without an explicit chapter selection,
non-interactive runs include all chapters for a new project. Useful follow-up commands:

```bash
ttsforge list novel.epub
ttsforge convert novel.epub --chapters 5-17 --fresh
ttsforge status novel.readio
ttsforge preview novel.epub
ttsforge voices --language en-us
ttsforge doctor
```

By default, the project is `novel.readio` beside `novel.epub`; the default output is
`novel.m4b`. Re-running the command reuses that Readio project's chapter scope and saved
synthesis/export settings. See [Projects and outputs](docs/projects.md) for reuse, fresh
projects, and legacy workspaces.

## Readio engines and configuration

Engine availability and voices depend on Readio's installed optional engine integrations
and local configuration. Discover the active catalog and diagnose the environment with:

```bash
ttsforge engines
ttsforge models
ttsforge voices --engine kokoro
ttsforge formats
ttsforge doctor
```

TTSForge reads and updates Readio configuration rather than keeping a separate TTSForge
backend configuration:

```bash
ttsforge config show
ttsforge config set reader.voice af_heart
ttsforge config set reader.speed 1.1
```

## Migration notes

This is a breaking change from the former TTSForge-owned Kokoro conversion pipeline. Old
renderer workspaces are not Readio projects and cannot be resumed by this frontend. They
are left untouched; use `--fresh` or an explicit new `--project` path to start
separately. Backend-specific commands such as `read`, `sample`, `demo`, `download`, and
`phonemes` are no longer part of TTSForge. See the
[migration guide](docs/migration-readio.md) before switching an existing setup.

## Documentation

- [Installation](docs/installation.md)
- [Quick start](docs/quickstart.md)
- [CLI reference](docs/cli.md)
- [Project and output lifecycle](docs/projects.md)
- [Readio configuration](docs/configuration.md)
- [Voices and discovery](docs/voices.md)
- [SSMD tools](docs/ssmd.md)
- [Migration guide](docs/migration-readio.md)
- [Python API boundary](docs/api/index.md)
- [Command-line examples](examples/README.md)

Implementation details and the public service contracts are documented in
[Readio's API guide](https://github.com/buchwandler/readio/blob/main/docs/api.md) and
[project guide](https://github.com/buchwandler/readio/blob/main/docs/projects.md).
