utterplan 0.1.1__py3-none-any.whl

utterplan/__init__.py

@@ -0,0 +1,81 @@
+from ._version import __version__
+from .config import (
+    LinguisticsConfig,
+    PauseConfig,
+    PlannerConfig,
+    SSMDConfig,
+    parse_duration,
+)
+from .exceptions import (
+    ConfigurationError,
+    LanguagePlanError,
+    PlanFormatError,
+    PlanningError,
+    PlanValidationError,
+    SegmentationError,
+    TextPreparationError,
+    UnsupportedSchemaError,
+    UtterPlanError,
+)
+from .language import LanguageRun, build_language_runs, normalize_language
+from .model import (
+    AnnotationSpan,
+    AudioDirective,
+    BoundaryEvent,
+    Diagnostic,
+    EmphasisDirective,
+    Marker,
+    PlanSegment,
+    PlanSource,
+    PlanTexts,
+    PlanUnit,
+    PronunciationDirective,
+    ProsodyDirective,
+    ResolvedPause,
+    SegmentDirectives,
+    TextPreparationInfo,
+    TokenAnnotation,
+    UtterancePlan,
+    VoiceDirective,
+)
+from .planner import UtterancePlanner
+
+__all__ = [
+    "__version__",
+    "PlannerConfig",
+    "PauseConfig",
+    "LinguisticsConfig",
+    "SSMDConfig",
+    "parse_duration",
+    "UtterancePlanner",
+    "UtterancePlan",
+    "PlanSource",
+    "PlanTexts",
+    "PlanSegment",
+    "PlanUnit",
+    "LanguageRun",
+    "TokenAnnotation",
+    "AnnotationSpan",
+    "BoundaryEvent",
+    "ResolvedPause",
+    "SegmentDirectives",
+    "VoiceDirective",
+    "PronunciationDirective",
+    "ProsodyDirective",
+    "EmphasisDirective",
+    "AudioDirective",
+    "Marker",
+    "TextPreparationInfo",
+    "Diagnostic",
+    "normalize_language",
+    "build_language_runs",
+    "UtterPlanError",
+    "ConfigurationError",
+    "PlanFormatError",
+    "PlanValidationError",
+    "UnsupportedSchemaError",
+    "PlanningError",
+    "LanguagePlanError",
+    "TextPreparationError",
+    "SegmentationError",
+]

utterplan/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

utterplan/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = 'ga56a3513d'

utterplan/cli.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Literal, cast
+
+from . import PlannerConfig, UtterancePlan, UtterancePlanner, __version__
+from .config import LinguisticsConfig, PauseConfig
+from .exceptions import UtterPlanError
+
+InputFormat = Literal["plain", "ssmd"]
+
+
+_EXAMPLES = """examples:
+  utterplan compile "Hello world." --lang en-us
+  echo "Hello world." | utterplan compile --lang en-us | jq .
+  utterplan compile chapter.ssmd --lang en-us -o chapter.utterplan.json
+  utterplan validate chapter.utterplan.json
+  utterplan inspect chapter.utterplan.json --segment 0
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="utterplan",
+        description="Compile text or SSMD into deterministic, engine-independent TTS plans.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_EXAMPLES,
+    )
+    parser.add_argument("--version", action="version", version=f"utterplan {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    compile_parser = commands.add_parser(
+        "compile",
+        help="compile literal text, stdin, or a file into a TTS plan",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=_EXAMPLES,
+    )
+    compile_parser.add_argument(
+        "text",
+        nargs="*",
+        help="literal text, or one existing file path; omit to read stdin",
+    )
+    compile_parser.add_argument(
+        "--file",
+        type=Path,
+        help="read UTF-8 text from this file (cannot be combined with positional text)",
+    )
+    compile_parser.add_argument("--language", "--lang", required=True, dest="language")
+    compile_parser.add_argument(
+        "--input-format",
+        "--format",
+        dest="input_format",
+        choices=("auto", "text", "ssmd"),
+        default="auto",
+        help="input interpretation; auto infers SSMD from a .ssmd file suffix",
+    )
+    compile_parser.add_argument("--unit", choices=("paragraph", "sentence"), default="paragraph")
+    compile_parser.add_argument(
+        "--text-preparation",
+        choices=("spokenform", "identity"),
+        default="spokenform",
+    )
+    compile_parser.add_argument("--pause-mode", choices=("tts", "manual", "auto"), default="tts")
+    compile_parser.add_argument(
+        "--spacy",
+        choices=("auto", "off", "sm", "md", "lg", "trf"),
+        default="off",
+        help="linguistic-resource policy; default is the deterministic fallback",
+    )
+    compile_parser.add_argument("-o", "--output", type=Path, help="write the plan to this file")
+    compile_parser.add_argument(
+        "--force", action="store_true", help="replace an existing output file"
+    )
+    compile_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="also print the complete plan JSON when --output is used",
+    )
+
+    validate_parser = commands.add_parser("validate", help="validate a saved TTS plan")
+    validate_parser.add_argument("input", type=Path)
+
+    inspect_parser = commands.add_parser("inspect", help="inspect a saved TTS plan")
+    inspect_parser.add_argument("input", type=Path)
+    inspect_parser.add_argument("--unit", type=int)
+    inspect_parser.add_argument("--segment", type=int)
+    inspect_parser.add_argument("--warnings", action="store_true")
+    inspect_parser.add_argument("--boundaries", action="store_true")
+    inspect_parser.add_argument("--tokens", action="store_true")
+    inspect_parser.add_argument("--preparation", action="store_true")
+    return parser
+
+
+def _format_for_path(path: Path) -> InputFormat:
+    return "ssmd" if path.suffix.lower() == ".ssmd" else "plain"
+
+
+def _read_compile_input(args: argparse.Namespace) -> tuple[str, InputFormat]:
+    if args.file is not None:
+        if args.text:
+            raise ValueError("--file cannot be combined with positional text")
+        source = args.file.read_text(encoding="utf-8")
+        input_format = (
+            _format_for_path(args.file)
+            if args.input_format == "auto"
+            else _map_input_format(args.input_format)
+        )
+        return source, input_format
+
+    if not args.text:
+        if sys.stdin.isatty():
+            raise ValueError("no input text supplied; provide text or pipe data on stdin")
+        source = sys.stdin.read()
+        if not source.strip():
+            raise ValueError("stdin is empty; provide meaningful input text")
+        return source, _map_input_format(args.input_format, default="plain")
+
+    if args.input_format == "text":
+        return " ".join(args.text), "plain"
+
+    if len(args.text) == 1:
+        candidate = Path(args.text[0])
+        if candidate.is_file():
+            source = candidate.read_text(encoding="utf-8")
+            input_format = (
+                _format_for_path(candidate)
+                if args.input_format == "auto"
+                else _map_input_format(args.input_format)
+            )
+            return source, input_format
+
+    return " ".join(args.text), _map_input_format(args.input_format, default="plain")
+
+
+def _map_input_format(value: str, *, default: InputFormat = "plain") -> InputFormat:
+    if value == "text":
+        return "plain"
+    if value == "ssmd":
+        return "ssmd"
+    return default
+
+
+def _linguistics_config(policy: str) -> LinguisticsConfig:
+    if policy == "off":
+        return LinguisticsConfig(use_spacy=False)
+    if policy == "auto":
+        return LinguisticsConfig(use_spacy=True)
+    return LinguisticsConfig(
+        use_spacy=True,
+        spacy_model_size=cast(Literal["sm", "md", "lg", "trf"], policy),
+        require_spacy=True,
+    )
+
+
+def _compile(args: argparse.Namespace) -> int:
+    source, input_format = _read_compile_input(args)
+    if args.output is not None and args.output.exists() and not args.force:
+        raise ValueError(f"output exists: {args.output}; use --force to replace it")
+
+    config = PlannerConfig(
+        language=args.language,
+        document_format=input_format,
+        text_preparation=args.text_preparation,
+        unit=args.unit,
+        pauses=PauseConfig(mode=args.pause_mode),
+        linguistics=_linguistics_config(args.spacy),
+    )
+    plan = UtterancePlanner(config).plan(source)
+    payload = plan.to_json()
+    if args.output is None:
+        print(payload, end="")
+    else:
+        args.output.write_text(payload, encoding="utf-8")
+        if args.json:
+            print(payload, end="")
+        else:
+            print(
+                f"wrote {args.output} ({len(plan.segments)} segments, {len(plan.units)} units)",
+                file=sys.stderr,
+            )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "compile":
+            return _compile(args)
+        plan = UtterancePlan.load(args.input)
+        if args.command == "validate":
+            print("valid")
+            print(f"schema version: {plan.schema_version}")
+            print(f"plan ID: {plan.plan_id}")
+            print(f"segments: {len(plan.segments)}")
+            print(f"units: {len(plan.units)}")
+            print(f"warnings: {len(plan.warnings)}")
+            return 0
+        _inspect(plan, args)
+        return 0
+    except (OSError, UtterPlanError, ValueError, TypeError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    print(f"UtterPlan schema {plan.schema_version}")
+    print(f"Plan: {plan.plan_id}")
+
+
+def _inspect(plan: UtterancePlan, args: argparse.Namespace) -> None:
+    print(f"Default language: {plan.config.get('language', '')}")
+    print("\nTexts")
+    print(f"  source:      {len(plan.source.text)} characters")
+    print(f"  structural:  {len(plan.texts.structural)} characters")
+    print(f"  spoken:      {len(plan.texts.spoken)} characters")
+    print(f"\nUnits:     {len(plan.units)}")
+    print(f"Segments:  {len(plan.segments)}")
+    print(f"Languages: {len(plan.languages)}")
+    print(f"Warnings:  {len(plan.warnings)}")
+    if args.warnings:
+        for warning in plan.warnings:
+            print(f"warning: {warning}")
+    if args.preparation:
+        preparation = plan.preparation
+        version = f" {preparation.version}" if preparation.version else ""
+        print("\nPreparation")
+        print(f"  backend: {preparation.backend}{version}")
+        print(f"  source: {len(plan.texts.structural)} characters")
+        print(f"  spoken: {len(plan.texts.spoken)} characters")
+        print(f"  replacements: {len(preparation.replacements)}")
+        for replacement in preparation.replacements:
+            source_range = (
+                f"{replacement.get('source_start', 0)}:{replacement.get('source_end', 0)}"
+            )
+            output_range = (
+                f"{replacement.get('output_start', 0)}:{replacement.get('output_end', 0)}"
+            )
+            label = replacement.get("rule") or replacement.get("kind", "")
+            print(f"  {source_range} -> {output_range} {label}")
+            print(
+                f"    {replacement.get('source', '')!r} -> {replacement.get('replacement', '')!r}"
+            )
+    if args.boundaries:
+        print("\nBoundaries")
+        for boundary in plan.boundaries:
+            print(
+                f"  {boundary.id}: {boundary.kind} at {boundary.position}, "
+                f"{boundary.seconds}s, {boundary.origin}"
+            )
+    if args.tokens:
+        print("\nTokens")
+        for token in plan.tokens:
+            print(
+                f"  {token.spoken_start}:{token.spoken_end} {token.text!r} {token.language or ''}"
+            )
+    if args.unit is not None:
+        unit = plan.units[args.unit]
+        print(f"\nUnit {unit.index}: {unit.kind} {unit.spoken_start}:{unit.spoken_end}")
+        for segment_id in unit.segment_ids:
+            print(f"  {segment_id}")
+    if args.segment is not None:
+        segment = plan.segments[args.segment]
+        print(f"\nSegment {args.segment}")
+        print(f"  text:          {segment.text!r}")
+        print(f"  language:      {segment.language}")
+        print(f"  paragraph:     {segment.paragraph}")
+        print(f"  sentence:      {segment.sentence}")
+        print(f"  clause:        {segment.clause}")
+        print(f"  pause_before:  {segment.pause_before.seconds}s {segment.pause_before.events}")
+        print(f"  pause_after:   {segment.pause_after.seconds}s {segment.pause_after.events}")
+        print(f"  directives:    {segment.directives.to_dict()}")

utterplan/config.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field
+from typing import Literal
+
+from .exceptions import ConfigurationError
+
+_DURATION_RE = re.compile(r"^\s*([+-]?(?:\d+(?:\.\d*)?|\.\d+))\s*(ms|s)?\s*$", re.I)
+_PAUSE_KEYS = frozenset(
+    {"weak", "clause", "sentence", "paragraph", "parenthetical", "voice_change"}
+)
+
+
+def parse_duration(value: object, *, field_name: str = "duration") -> float:
+    """Parse a portable duration and return finite, non-negative seconds.
+
+    Numbers and unitless strings are seconds. Strings with ``ms`` or ``s`` are
+    normalized to seconds so equivalent spellings have identical semantics.
+    """
+    if isinstance(value, bool):
+        raise ConfigurationError(f"{field_name} must be a duration, not a boolean")
+    if isinstance(value, (int, float)):
+        seconds = float(value)
+    elif isinstance(value, str):
+        match = _DURATION_RE.fullmatch(value)
+        if match is None:
+            raise ConfigurationError(
+                f"{field_name} must be a finite non-negative number of seconds or use ms/s syntax"
+            )
+        seconds = float(match.group(1))
+        if match.group(2) and match.group(2).lower() == "ms":
+            seconds /= 1000.0
+    else:
+        raise ConfigurationError(f"{field_name} must be a number or duration string")
+    if not math.isfinite(seconds) or seconds < 0:
+        raise ConfigurationError(f"{field_name} must be finite and non-negative")
+    return seconds
+
+
+def _validate_bool(value: object, field_name: str) -> None:
+    if not isinstance(value, bool):
+        raise ConfigurationError(f"{field_name} must be a boolean")
+
+
+@dataclass(frozen=True, slots=True)
+class PauseConfig:
+    mode: Literal["tts", "manual", "auto"] = "tts"
+    weak: float = 0.15
+    clause: float = 0.30
+    sentence: float = 0.60
+    paragraph: float = 1.00
+    parenthetical: float = 0.15
+    voice_change: float = 0.15
+    enabled: bool = True
+
+    def __post_init__(self) -> None:
+        if self.mode not in {"tts", "manual", "auto"}:
+            raise ConfigurationError("pauses.mode must be one of 'tts', 'manual', or 'auto'")
+        _validate_bool(self.enabled, "pauses.enabled")
+        for name in ("weak", "clause", "sentence", "paragraph", "parenthetical", "voice_change"):
+            value = parse_duration(getattr(self, name), field_name=f"pauses.{name}")
+            object.__setattr__(self, name, value)
+
+
+@dataclass(frozen=True, slots=True)
+class LinguisticsConfig:
+    use_spacy: bool | None = None
+    spacy_model: str | None = None
+    spacy_model_size: Literal["sm", "md", "lg", "trf"] | None = None
+    require_spacy: bool = False
+
+    def __post_init__(self) -> None:
+        for name in ("use_spacy", "require_spacy"):
+            value = getattr(self, name)
+            if value is not None:
+                _validate_bool(value, f"linguistics.{name}")
+        if self.spacy_model_size is not None and self.spacy_model_size not in {
+            "sm",
+            "md",
+            "lg",
+            "trf",
+        }:
+            raise ConfigurationError("linguistics.spacy_model_size is unsupported")
+
+
+@dataclass(frozen=True, slots=True)
+class SSMDConfig:
+    parse_header: bool = True
+    strict_header: bool = True
+    unknown_header: Literal["warn", "error", "ignore"] = "warn"
+    pause_defaults: Mapping[str, object] | None = None
+
+    def __post_init__(self) -> None:
+        _validate_bool(self.parse_header, "ssmd.parse_header")
+        _validate_bool(self.strict_header, "ssmd.strict_header")
+        if self.unknown_header not in {"warn", "error", "ignore"}:
+            raise ConfigurationError("ssmd.unknown_header must be 'warn', 'error', or 'ignore'")
+        if self.pause_defaults is not None:
+            if not isinstance(self.pause_defaults, Mapping):
+                raise ConfigurationError("ssmd.pause_defaults must be a mapping")
+            for key, value in self.pause_defaults.items():
+                if key == "enabled":
+                    _validate_bool(value, "ssmd.pause_defaults.enabled")
+                elif key in _PAUSE_KEYS:
+                    parse_duration(value, field_name=f"ssmd.pause_defaults.{key}")
+                else:
+                    raise ConfigurationError(f"ssmd.pause_defaults.{key} is unsupported")
+
+
+@dataclass(frozen=True, slots=True)
+class PlannerConfig:
+    language: str
+    document_format: Literal["plain", "ssmd"] = "ssmd"
+    text_preparation: Literal["spokenform", "identity"] = "spokenform"
+    unit: Literal["paragraph", "sentence"] = "paragraph"
+    pauses: PauseConfig = field(default_factory=PauseConfig)
+    linguistics: LinguisticsConfig = field(default_factory=LinguisticsConfig)
+    ssmd: SSMDConfig = field(default_factory=SSMDConfig)
+    overlap_mode: Literal["snap", "strict"] = "snap"
+    language_aliases: Mapping[str, str] = field(default_factory=dict)
+    diagnostics: bool = True
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.language, str) or not self.language.strip():
+            raise ConfigurationError("language must be a non-empty string")
+        if self.document_format not in {"plain", "ssmd"}:
+            raise ConfigurationError("document_format must be 'plain' or 'ssmd'")
+        if self.text_preparation not in {"spokenform", "identity"}:
+            raise ConfigurationError("text_preparation must be 'spokenform' or 'identity'")
+        if self.unit not in {"paragraph", "sentence"}:
+            raise ConfigurationError("unit must be 'paragraph' or 'sentence'")
+        if self.overlap_mode not in {"snap", "strict"}:
+            raise ConfigurationError("overlap_mode must be 'snap' or 'strict'")
+        if not isinstance(self.language_aliases, Mapping):
+            raise ConfigurationError("language_aliases must be a string-to-string mapping")
+        if any(
+            not isinstance(key, str) or not isinstance(value, str)
+            for key, value in self.language_aliases.items()
+        ):
+            raise ConfigurationError("language_aliases must contain only string keys and values")
+        _validate_bool(self.diagnostics, "diagnostics")
+
+
+def semantic_config(config: PlannerConfig | Mapping[str, object]) -> dict[str, object]:
+    """Return only configuration fields that can change the planning result."""
+    value = asdict(config) if isinstance(config, PlannerConfig) else dict(config)
+    value.pop("diagnostics", None)
+    return value
+
+
+__all__ = [
+    "LinguisticsConfig",
+    "PauseConfig",
+    "PlannerConfig",
+    "SSMDConfig",
+    "parse_duration",
+    "semantic_config",
+]

utterplan/diagnostics.py

@@ -0,0 +1,3 @@
+from .model import Diagnostic
+
+__all__ = ["Diagnostic"]

utterplan/directives.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .model import (
+    AnnotationSpan,
+    AudioDirective,
+    EmphasisDirective,
+    PlanSegment,
+    PronunciationDirective,
+    ProsodyDirective,
+    SegmentDirectives,
+    VoiceDirective,
+)
+
+
+def resolve_directives(
+    segment: PlanSegment, annotations: tuple[AnnotationSpan, ...]
+) -> PlanSegment:
+    selected = sorted(
+        (
+            annotation
+            for annotation in annotations
+            if annotation.spoken_start is not None
+            and annotation.spoken_end is not None
+            and annotation.spoken_start <= segment.spoken_start
+            and segment.spoken_end <= annotation.spoken_end
+        ),
+        key=lambda annotation: (
+            (annotation.spoken_end or 0) - (annotation.spoken_start or 0),
+            annotation.spoken_start or 0,
+            annotation.id,
+        ),
+    )
+    voice = pronunciation = prosody = emphasis = audio = None
+    for annotation in selected:
+        attrs = annotation.attrs
+        if attrs.get("voice") or attrs.get("voice_name"):
+            voice = VoiceDirective(str(attrs.get("voice") or attrs.get("voice_name")))
+        phonemes = attrs.get("phonemes") or attrs.get("ph")
+        if phonemes:
+            pronunciation = PronunciationDirective(str(phonemes), str(attrs.get("alphabet", "ipa")))
+        if any(key in attrs for key in ("rate", "pitch", "volume", "speed")):
+            prosody = ProsodyDirective(
+                _first(attrs, "rate", "speed"),
+                _first(attrs, "pitch"),
+                _first(attrs, "volume", "loudness"),
+            )
+        if attrs.get("emphasis") or attrs.get("level"):
+            emphasis = EmphasisDirective(str(attrs.get("emphasis") or attrs.get("level")))
+        src = attrs.get("audio_src") or attrs.get("src")
+        if src:
+            audio = AudioDirective(
+                str(src),
+                _first(attrs, "alt_text", "audio_alt_text"),
+                _first(attrs, "clip_begin"),
+                _first(attrs, "clip_end"),
+                _first(attrs, "speed"),
+                _first(attrs, "repeat_duration"),
+                _int(attrs, "repeat_count"),
+                _first(attrs, "sound_level"),
+            )
+    return PlanSegment(
+        **{
+            **{name: getattr(segment, name) for name in segment.__dataclass_fields__},
+            "directives": SegmentDirectives(voice, pronunciation, prosody, emphasis, audio),
+        }
+    )
+
+
+def _first(attrs: Mapping[str, Any], *names: str) -> str | None:
+    for name in names:
+        value = attrs.get(name)
+        if value is not None:
+            return str(value)
+    return None
+
+
+def _int(attrs: Mapping[str, Any], name: str) -> int | None:
+    value = attrs.get(name)
+    return int(value) if value is not None else None

utterplan/exceptions.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+
+class UtterPlanError(Exception):
+    """Base exception for UtterPlan."""
+
+
+class ConfigurationError(UtterPlanError):
+    """A public planning configuration value is invalid."""
+
+
+class PlanFormatError(UtterPlanError):
+    """The serialized plan is not structurally valid."""
+
+    def __init__(self, message: str, *, code: str = "plan.invalid", path: str = "$") -> None:
+        self.code = code
+        self.path = path
+        super().__init__(f"{code} at {path}: {message}")
+
+
+class UnsupportedSchemaError(PlanFormatError):
+    def __init__(self, version: object) -> None:
+        super().__init__(
+            f"Unsupported UtterPlan schema version {version}. This version of utterplan supports schema version 1.",
+            code="schema.unsupported_version",
+            path="$.schema_version",
+        )
+
+
+class PlanValidationError(PlanFormatError):
+    """The plan has valid JSON shape but invalid planning semantics."""
+
+
+class PlanningError(UtterPlanError):
+    """Planning could not produce a plan."""
+
+
+class LanguagePlanError(PlanningError):
+    """Language spans cannot be resolved."""
+
+
+class TextPreparationError(PlanningError):
+    """Written-to-spoken preparation failed."""
+
+
+class SegmentationError(PlanningError):
+    """Segmentation failed."""