Metadata-Version: 2.4
Name: ttsready
Version: 0.2.0
Summary: A source-neutral API for preparing text for speech.
Author: Holger Nahrstaedt
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/buchwandler/ttsready
Project-URL: Repository, https://github.com/buchwandler/ttsready
Project-URL: Issues, https://github.com/buchwandler/ttsready/issues
Keywords: tts,text-to-speech,spokenform,speech-preparation,reproducibility
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: spokenform<1,>=0.4.5
Requires-Dist: phrasplit<1,>=0.3.9
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: setuptools>=80; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.16; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Provides-Extra: lexical
Requires-Dist: lexhint<0.3.0,>=0.1.2; extra == "lexical"
Dynamic: license-file

# ttsready

`ttsready` is a source-neutral Python library for preparing caller-owned text for speech. It accepts text units with explicit language and returns spoken text, exact source-relative changes, issues, context, statistics, and reproducibility fingerprints.

The library does **not** read or write files, parse SSMD or other formats, expose a CLI, generate audio, or own a document workflow. Callers adapt their source format to `TextUnit` values and decide what to do with the returned data.

## Install

Python 3.10 or newer is required.

```bash
python -m pip install ttsready
```

The runtime dependencies are `spokenform>=0.4.5,<1` and `phrasplit>=0.3.9,<1`. Install the optional lexical extra when you need its lexical-evidence integrations:

```bash
python -m pip install 'ttsready[lexical]'
```

## Quickstart

```python
from ttsready import prepare_text

prepared = prepare_text("A young reader opened a book.", language="en-US")
print(prepared.spoken_text)

for change in prepared.changes:
    print(change.source, "→", change.replacement, change.source_start, change.source_end)
```

`prepare_text()` prepares one unit and returns a `PreparedUnit`. Use `prepare_units()` when you have multiple caller-owned units, possibly with different languages, roles, protected spans, or metadata. See [docs/quickstart.md](docs/quickstart.md) and the runnable [API example](examples/basic_prepare.py).

## Core contract

- Inputs are immutable `TextUnit` records with caller-chosen IDs, text, explicit language, optional role, protected spans, and JSON-safe metadata.
- `SpeechOverride` values express global, unit-scoped, or exact-occurrence pronunciation policy.
- Results expose exact half-open source and output spans, stable IDs, warnings and residual QA issues, sentence context, and aggregate statistics.
- JSON serialization and fingerprints are pure; persistence and storage are caller responsibilities.

```python
from ttsready import TextUnit, prepare_units

result = prepare_units(
    (
        TextUnit("chapter-1", "2 kg", "en-US", role="body"),
        TextUnit("caption-1", "Bonjour.", "fr-FR", role="caption"),
    )
)

for unit in result.units:
    print(unit.unit_id, unit.spoken_text)
```

## Documentation

- [Installation](docs/installation.md)
- [Quickstart](docs/quickstart.md)
- [Python API](docs/python-api.md)
- [Overrides](docs/overrides.md)
- [Residual QA](docs/qa.md)
- [Reproducibility and serialization](docs/reproducibility.md)
- [Ownership boundary](docs/ownership-boundary.md)
- [Migration from 0.1.x](docs/migration.md)

## Migrating from 0.1.x

Version 0.2 is a breaking, API-only release. SSMD/document APIs, the CLI, file and cache I/O, writers, planning, speaker/JEV workflows, and their application-owned models were removed. Convert or read source data in your application, pass text units to `prepare_text()` or `prepare_units()`, then persist or render results in your application. See the [migration guide](docs/migration.md).

## License

`ttsready` is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for the full text.
