UtterPlan

UtterPlan is an engine-independent TTS planning compiler and interchange format. It converts text and SSMD into deterministic semantic speech plans containing prepared spoken text, language runs, segments, pauses, directives, markers, and render units. It stops before G2P and produces no audio.

CLI

Compile literal text directly:

utterplan compile "Doctor Smith bought 5 kg." --lang en-us --json

Compile a file to a plan file:

utterplan compile chapter.ssmd --lang en-us -o chapter.utterplan.json

Use stdin and shell pipelines:

cat chapter.ssmd | utterplan compile --lang en-us --input-format ssmd | jq .

The CLI also provides:

utterplan --version
utterplan validate chapter.utterplan.json
utterplan inspect chapter.utterplan.json --segment 0
utterplan explain chapter.utterplan.json

explain presents the compiled plan as a human-readable speech plan, while inspect exposes lower-level diagnostic fields. Compile JSON is written to stdout when no output file is supplied. Status messages use stderr, and existing output files require --force.

Planning defaults

The minimal CLI defaults are explicit: spokenform is the default text-preparation backend, tts is the default pause mode, and spacy off is the default linguistic-resource policy. With spacy off, UtterPlan uses its deterministic fallback tokenizer and analysis and does not depend on an installed spaCy model.

spacy auto is opt-in. When enabled and a compatible local model is available, UtterPlan may expose richer tokenization, POS tags, lemmas, and tags; auto is not the default.

Python API

from utterplan import PlannerConfig, UtterancePlan, UtterancePlanner

planner = UtterancePlanner(PlannerConfig(language="en-us"))
plan = planner.plan("Doctor Smith bought 5 kg of apples.")
plan.save("example.utterplan.json")
assert UtterancePlan.load("example.utterplan.json") == plan

The stable in-process boundary is PlannerConfig, UtterancePlanner, and the immutable UtterancePlan object. JSON is the portable persistence and interchange format; an in-process renderer can consume the Python object directly.

Renderer-consumer boundary

Renderers consume PlanSegment.text, which is prepared/spoken text, and use spoken_start/spoken_end for spoken-text coordinates. Resolved segment pauses, language, directives, annotations, boundaries, markers, units, and document metadata are public plan fields. Plans contain no phonemes, model tokens, model sessions, renderer configuration, provider documents, or audio.

The intended dependency direction is:

PyKokoro or another renderer -> UtterPlan

UtterPlan does not depend on PyKokoro, G2P engines, ONNX Runtime, or audio packages. PyKokoro remains an optional read-only parity reference during UtterPlan development.

Documentation

• Getting started
• CLI
• Format and schema
• Consumer guide
• Architecture
• Coordinates
• PyKokoro integration
• Changelog

Versions

The package version is dynamically derived from Git tags by setuptools-scm. The first public alpha package release is 0.1.0. The package version and UtterPlan schema_version are independent: this release uses schema version 1.

Schema v1 is frozen and packaged under a versioned schema-history path. UtterPlan can inspect and migrate supported historical plan JSON before constructing the current UtterancePlan; migration is representation conversion, not replanning. The utterplan migrate command supports --check and refuses output overwrite unless --force is supplied.

Development

python -m pip install -e '.[dev,docs]'
python -m pytest -q -m 'not reference'
ruff check .
mypy utterplan
python -m build
sphinx-build -W --keep-going -b html docs docs/_build/html