Metadata-Version: 2.4
Name: ttsready
Version: 0.1.1
Summary: Analyze canonical SSMD and materialize reviewed TTS semantics.
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,ssmd,spokenform,reproducibility
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
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: ssmd<0.10,>=0.9.2
Requires-Dist: ssmdconvert<0.2,>=0.1.1
Requires-Dist: phrasplit<1,>=0.3.9
Requires-Dist: spokenform<1,>=0.4.5
Requires-Dist: pyyaml<7,>=6
Requires-Dist: typer<1,>=0.20
Provides-Extra: dev
Requires-Dist: build<2,>=1; 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"
Provides-Extra: speakers
Requires-Dist: pyjev<1,>=0.1; extra == "speakers"
Dynamic: license-file

# ttsready

`ttsready` analyzes canonical SSMD 0.9 documents and `.ssmdbook` bundles, reviews speech decisions, and can materialize approved changes back into SSMD. It does not ingest EPUB, PDF, Markdown, HTML, or plain-text source files directly, and it does not generate audio.

Python 3.10 or newer is required. The CI matrix targets Python 3.10 through 3.14. See the [documentation](docs/index.md) for the installation guide, quickstart, and workflows.

The interchange boundary is the SSMD artifact:

```text
source formats -> ssmdconvert -> canonical SSMD -> ttsready review/materialization
                                                    |
                                                    v
                                         reviewed SSMD for downstream TTS
```

`ssmdconvert` owns source extraction, conversion, chapter identity, and book-bundle integrity. `ttsready` owns SSMD speech analysis, review, reproducibility, and reviewed SSMD changes. Downstream renderers consume the resulting SSMD document or book. There is no runtime API coupling between `ttsready` and a renderer.

## Supported inputs

`ttsready` accepts:

- standalone `.ssmd` and `.ssmd.md` documents;
- `.ssmdbook` directory bundles;
- `.ssmdbook.zip` bundles.

Inputs must contain valid SSMD 0.9. Convert EPUB, PDF, Markdown, HTML, text, or other supported sources with `ssmdconvert` first:

```bash
ssmdconvert book convert novel.epub -o novel.ssmdbook
ssmdconvert convert manuscript.md -o manuscript.ssmd
```

## Install

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

The package depends on `ssmd` and `ssmdconvert` for canonical parsing and book loading. It does not install independent EPUB or PDF readers. Optional extras provide lexical evidence and speaker suggestions:

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

## Quickstart

From the repository root, run the included example through the main CLI workflows:

```bash
python -m pip install -e .
ttsready preflight examples/basic.ssmd.md
ttsready report examples/basic.ssmd.md
ttsready preview examples/basic.ssmd.md
ttsready export examples/basic.ssmd.md --format txt -o /tmp/basic.txt
```

The same input can be loaded with the [Python API](docs/python-api.md). See [examples/basic_preview.py](examples/basic_preview.py) for a complete runnable example.

## Review workflow

Create a report to inspect Spokenform candidates and their SSMD source spans:

```bash
ttsready report novel.ssmdbook -c 5-17
ttsready report novel.ssmdbook --format json -o novel.report.json
```

Reports persist analysis snapshots. `context` looks up an existing cached finding and does not rerun conversion or Spokenform. Use `--refresh` on `report` to request fresh analysis:

```bash
ttsready context novel.ssmdbook chg:v1:8d1b2d540c6d995a51ac
ttsready report novel.ssmdbook -c 5 --refresh
```

An exact reviewed pronunciation can be materialized as an SSMD `sub` annotation. By default, the command writes a separate `.reviewed` artifact. Use `--write` only to explicitly replace the source:

```bash
ttsready override novel.ssmdbook chg:v1:8d1b2d540c6d995a51ac \
  --spoken 'habitat, commercial, industrial'
```

Speaker review uses logical IDs from the sidecar registry. Accepted or manual decisions can be materialized as SSMD `voice` annotations. Provider voice names remain a downstream rendering concern:

```bash
ttsready speakers novel.ssmdbook --config novel.ttsready.yaml --jev
ttsready speaker-set novel.ssmdbook --config novel.ttsready.yaml \
  --utterance utt:v1:0123456789abcdef0123 --speaker alice
ttsready speaker-materialize novel.ssmdbook --config novel.ttsready.yaml \
  --utterance utt:v1:0123456789abcdef0123
```

## Reproducibility and output

Create and verify a strict lock for canonical content, runtime, normalization profile, and prepared output. `freeze` writes a separate SSMD artifact with the selected automatic transformations materialized:

```bash
ttsready lock novel.ssmdbook -o novel.ssmdbook.ttsready.lock.json
ttsready verify novel.ssmdbook --lock novel.ssmdbook.ttsready.lock.json
ttsready freeze novel.ssmdbook -o novel.frozen.ssmdbook
```

`preview` prints prepared speech. `export` writes plain TXT from the same structured TTS plan. TXT applies speech substitutions but cannot preserve SSMD-only structure such as logical voice annotations:

```bash
ttsready preview novel.ssmdbook -c 5
ttsready export novel.ssmdbook --format txt --layout chapters -o novel-txt/
```

Use `ttsready --help` and command-specific `--help` for the complete CLI options.

## Python API

```python
from ttsready import load, prepare_tts_plan, render_preview

canonical = load("novel.ssmdbook")
plan = prepare_tts_plan(canonical, language="en")
preview = render_preview(plan)
```

For SSMD text already held in memory, use `load_ssmd()`:

```python
from ttsready import load_ssmd

document = load_ssmd(ssmd_text, section_id="chapter-0001")
```

`prepare_tts_plan()` returns structured segments and a report without rendering audio. `render_preview()` renders that plan as plain text. The report, preview, and TXT export share the same preparation result.

## Ownership boundary

- `ssmdconvert` converts supported source formats to canonical SSMD and owns `.ssmdbook` loading, validation, and writes.
- `ttsready` reviews canonical SSMD and writes explicit reviewed semantics such as `sub` and logical `voice` annotations into SSMD.
- Downstream tools consume canonical or reviewed SSMD. Tools exchange content through SSMD documents, not through a `ttsready` runtime integration API.
- The existing `ssmdconvert.speech` API remains available for compatibility. It is separate from the `ttsready` review and materialization workflow.

## License

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