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 for the installation guide, quickstart, and workflows.

The interchange boundary is the SSMD artifact:

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:

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

Install

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:

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:

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. See examples/basic_preview.py for a complete runnable example.

Review workflow

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

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:

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:

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:

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:

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:

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

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():

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 for the full text.