tts-pace 0.3.0__py3-none-any.whl

tts_pace/__init__.py

@@ -0,0 +1,32 @@
+"""tts-pace: measure speaking rate and fit TTS output to a target pace.
+
+Public API: count_syllables, measure, retime, fit, fit_audio, AudioClip, the engine adapters
+(MockEngine, CallableEngine, SayEngine, PiperEngine), Limiter and the error classes.
+Everything else (modules with a leading underscore, helpers inside modules) is internal.
+"""
+
+from .audio import AudioClip
+from .count import SyllableCount, UnsupportedCharsWarning, count_syllables
+from .engines import CallableEngine, EngineInfo, MockEngine, PiperEngine, SayEngine, SpeedEngine
+from .errors import (
+    AudioFormatError,
+    BusyError,
+    EngineError,
+    MeasurementError,
+    TtsPaceError,
+    UnsupportedTextError,
+)
+from .fit import Candidate, FitResult, fit, fit_audio
+from .measure import Measurement, measure
+from .runtime import Limiter
+from .tempo import retime
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "AudioClip", "AudioFormatError", "BusyError", "CallableEngine", "Candidate", "EngineError",
+    "EngineInfo", "FitResult", "Limiter", "Measurement", "MeasurementError", "MockEngine",
+    "PiperEngine", "SayEngine", "SpeedEngine", "SyllableCount", "TtsPaceError",
+    "UnsupportedCharsWarning", "UnsupportedTextError", "__version__", "count_syllables", "fit",
+    "fit_audio", "measure", "retime",
+]

tts_pace/audio.py

@@ -0,0 +1,96 @@
+"""Mono float audio and WAV reading/writing (standard library `wave` + numpy)."""
+
+from __future__ import annotations
+
+import wave
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from .errors import AudioFormatError, EngineError
+from .runtime import find_ffmpeg, run_command, run_dir
+
+
+@dataclass(frozen=True)
+class AudioClip:
+    """Mono audio: ``samples`` is float32 in [-1, 1]."""
+
+    samples: np.ndarray
+    sample_rate: int
+
+    def __post_init__(self) -> None:
+        if self.sample_rate <= 0:
+            raise ValueError("sample_rate must be positive")
+        if self.samples.ndim != 1:
+            raise ValueError("samples must be a 1-D (mono) array")
+        if self.samples.dtype != np.float32:
+            object.__setattr__(self, "samples", self.samples.astype(np.float32))
+
+    @property
+    def duration(self) -> float:
+        return len(self.samples) / self.sample_rate
+
+    @classmethod
+    def from_wav(cls, path: str | Path) -> AudioClip:
+        """Read a WAV (8/16/24/32-bit PCM). Other formats are decoded with ffmpeg when available."""
+        p = Path(path)
+        if not p.exists():
+            raise AudioFormatError(f"Audio file not found: {p}")
+        try:
+            return _read_pcm_wav(p)
+        except (wave.Error, EOFError):
+            return _decode_with_ffmpeg(p)
+
+    def to_wav(self, path: str | Path) -> Path:
+        """Write 16-bit PCM WAV and return the path."""
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        pcm = np.clip(self.samples, -1.0, 1.0)
+        data = (pcm * 32767.0).round().astype("<i2").tobytes()
+        with wave.open(str(p), "wb") as w:
+            w.setnchannels(1)
+            w.setsampwidth(2)
+            w.setframerate(self.sample_rate)
+            w.writeframes(data)
+        return p
+
+
+def _read_pcm_wav(p: Path) -> AudioClip:
+    with wave.open(str(p), "rb") as w:
+        ch, width, rate, n = w.getnchannels(), w.getsampwidth(), w.getframerate(), w.getnframes()
+        raw = w.readframes(n)
+    if n == 0:
+        raise AudioFormatError(f"{p} has no audio frames.")
+    if width == 1:
+        x = (np.frombuffer(raw, dtype=np.uint8).astype(np.float32) - 128.0) / 128.0
+    elif width == 2:
+        x = np.frombuffer(raw, dtype="<i2").astype(np.float32) / 32768.0
+    elif width == 3:
+        b = np.frombuffer(raw, dtype=np.uint8).reshape(-1, 3).astype(np.int32)
+        v = b[:, 0] | (b[:, 1] << 8) | (b[:, 2] << 16)
+        v = np.where(v >= 1 << 23, v - (1 << 24), v)
+        x = v.astype(np.float32) / float(1 << 23)
+    elif width == 4:
+        x = np.frombuffer(raw, dtype="<i4").astype(np.float32) / float(1 << 31)
+    else:
+        raise AudioFormatError(f"Unsupported sample width {width} bytes in {p}.")
+    if ch > 1:
+        x = x.reshape(-1, ch).mean(axis=1)  # mix down to mono
+    return AudioClip(x.astype(np.float32), rate)
+
+
+def _decode_with_ffmpeg(p: Path) -> AudioClip:
+    ffmpeg = find_ffmpeg()
+    if ffmpeg is None:
+        raise AudioFormatError(
+            f"{p} is not a PCM WAV file and ffmpeg was not found to decode it. "
+            "Convert it to 16-bit WAV, or install ffmpeg (or set TTS_PACE_FFMPEG)."
+        )
+    with run_dir() as tmp:
+        out = tmp / "decoded.wav"
+        try:
+            run_command([ffmpeg, "-v", "error", "-y", "-i", str(p), "-ac", "1", "-c:a", "pcm_s16le", str(out)])
+        except EngineError as exc:
+            raise AudioFormatError(f"{p} is not an audio file ffmpeg can read; convert it to 16-bit WAV. (ffmpeg said: {exc})") from exc
+        return _read_pcm_wav(out)

tts_pace/cache.py

@@ -0,0 +1,85 @@
+"""Deterministic result cache: key = hash of everything that changes the output."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+from pathlib import Path
+
+from .audio import AudioClip
+
+CACHE_VERSION = "1"
+
+
+def default_cache_dir() -> Path:
+    """``$TTS_PACE_CACHE_DIR``, else ``$XDG_CACHE_HOME/tts-pace``, else ``~/.cache/tts-pace``.
+
+    Never inside the current directory, so the cache cannot leak into a git work tree.
+    """
+    explicit = os.environ.get("TTS_PACE_CACHE_DIR")
+    if explicit:
+        return Path(explicit).expanduser()
+    base = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(base) / "tts-pace"
+
+
+def make_key(parts: dict[str, object]) -> str:
+    """sha256 over canonical JSON of ``parts`` (plus the cache format version)."""
+    blob = json.dumps({"v": CACHE_VERSION, **parts}, sort_keys=True, ensure_ascii=False, default=str)
+    return hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+
+def audio_hash(clip: AudioClip) -> str:
+    """Hash of the audio content (used as the key for engines that are not deterministic)."""
+    h = hashlib.sha256()
+    h.update(str(clip.sample_rate).encode())
+    h.update(clip.samples.tobytes())
+    return h.hexdigest()
+
+
+class ResultCache:
+    """Stores the best WAV and the report JSON per key. Oldest entries are removed beyond ``max_entries``."""
+
+    def __init__(self, directory: str | Path, max_entries: int = 256) -> None:
+        if max_entries < 1:
+            raise ValueError("max_entries must be >= 1")
+        self.directory = Path(directory)
+        self.max_entries = max_entries
+
+    def _paths(self, key: str) -> tuple[Path, Path]:
+        return self.directory / f"{key}.json", self.directory / f"{key}.wav"
+
+    def get(self, key: str) -> tuple[dict[str, object], Path] | None:
+        report_path, wav_path = self._paths(key)
+        if not (report_path.exists() and wav_path.exists()):
+            return None
+        try:
+            return json.loads(report_path.read_text(encoding="utf-8")), wav_path
+        except (OSError, ValueError):
+            return None  # a damaged entry counts as a miss and is rewritten
+
+    def put(self, key: str, report: dict[str, object], clip: AudioClip) -> Path:
+        self.directory.mkdir(parents=True, exist_ok=True)
+        report_path, wav_path = self._paths(key)
+        tmp_wav = wav_path.with_suffix(".wav.tmp")
+        clip.to_wav(tmp_wav)
+        os.replace(tmp_wav, wav_path)
+        tmp_json = report_path.with_suffix(".json.tmp")
+        tmp_json.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+        os.replace(tmp_json, report_path)  # the json appears last: it marks a complete entry
+        self._evict()
+        return wav_path
+
+    def _evict(self) -> None:
+        entries = sorted(self.directory.glob("*.json"), key=lambda p: p.stat().st_mtime)
+        for old in entries[: max(0, len(entries) - self.max_entries)]:
+            old.unlink(missing_ok=True)
+            old.with_suffix(".wav").unlink(missing_ok=True)
+
+    def copy_wav(self, key: str, dest: str | Path) -> Path:
+        d = Path(dest)
+        d.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(self._paths(key)[1], d)
+        return d

tts_pace/cli.py

@@ -0,0 +1,194 @@
+"""Command line interface: demo, count, measure, retime, fit."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .cache import default_cache_dir
+from .count import count_syllables
+from .demo import MOCK_BANNER, format_table, run_demo
+from .engines import MockEngine, PiperEngine, SayEngine
+from .errors import TtsPaceError
+from .fit import FitResult, fit, fit_audio
+from .measure import measure
+
+
+def _text_arg(args: argparse.Namespace) -> str:
+    if getattr(args, "text", None) is not None:
+        return args.text
+    if getattr(args, "text_file", None):
+        try:
+            return Path(args.text_file).read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ValueError(f"Cannot read --text-file {args.text_file}: {exc}") from exc
+    raise ValueError("Give the script with --text TEXT or --text-file FILE.")
+
+
+def _add_text(p: argparse.ArgumentParser, required: bool = True) -> None:
+    g = p.add_mutually_exclusive_group(required=required)
+    g.add_argument("--text", help="the spoken text")
+    g.add_argument("--text-file", help="file containing the spoken text (UTF-8)")
+
+
+def _add_target(p: argparse.ArgumentParser) -> None:
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument("--target", type=float, help="target syllables per second")
+    g.add_argument("--target-duration", type=float, metavar="SECONDS",
+                   help="target total length in seconds, pauses included")
+
+
+def _print_result(r: FitResult, out: str | None) -> None:
+    print(f"base      {r.base.measurement.sps:.2f} sps")
+    for c in r.candidates[1:]:
+        print(f"{c.kind:<13} speed x{c.speed:.3f}  tempo x{c.tempo:.3f}  -> {c.measurement.sps:.2f} sps  err {c.err_pct:.2f}%")
+    print(f"best      {r.route}: {r.best.measurement.sps:.2f} sps (target {r.target_sps:g}, err {r.best.err_pct:.2f}%)")
+    if r.target_duration is not None:  # length mode only
+        print(f"length    {r.best.measurement.total_s:.2f}s (target {r.target_duration:.2f}s, err {r.length_err_pct:.2f}%)")
+    print(f"cache     {'hit' if r.cache_hit else 'miss'}")
+    if out:
+        print(f"wrote     {out}")
+    for w, a in zip(r.warnings, r.advice):
+        print(f"warning: {w} - {a}", file=sys.stderr)
+
+
+def cmd_demo(args: argparse.Namespace) -> int:
+    print(MOCK_BANNER)
+    results, report_path = run_demo(args.out)
+    print(format_table(results))
+    print(f"\nwrote {args.out}/ (WAV files + report.json: {report_path})")
+    return 0
+
+
+def cmd_count(args: argparse.Namespace) -> int:
+    c = count_syllables(args.text, args.lang)
+    if args.json:
+        print(json.dumps(c.to_dict(), ensure_ascii=False))
+    else:
+        print(f"spoken form : {c.normalized_text}")
+        print(f"syllables   : {c.total}  {c.by_script}")
+        if c.unsupported:
+            print(f"unsupported : {' '.join(c.unsupported)}")
+    return 0
+
+
+def cmd_measure(args: argparse.Namespace) -> int:
+    text = _text_arg(args) if (args.text is not None or args.text_file) else None
+    m = measure(args.wav, text, silence_db=args.silence_db, min_silence=args.min_silence, backend=args.backend)
+    if args.json:
+        print(json.dumps(m.to_dict()))
+    else:
+        print(f"total {m.total_s:.2f}s  silence {m.silence_s:.2f}s ({m.gaps} gaps)  speech {m.net_s:.2f}s")
+        if m.sps is not None:
+            print(f"{m.syllables} syllables -> {m.sps:.2f} syllables/second of pure speech")
+    return 0
+
+
+def cmd_retime(args: argparse.Namespace) -> int:
+    r = fit_audio(args.wav, _text_arg(args), args.target, out=args.out, target_duration=args.target_duration)
+    if args.json:
+        print(json.dumps(r.report(), ensure_ascii=False))
+    else:
+        _print_result(r, args.out)
+        return 0
+    for w, a in zip(r.warnings, r.advice):
+        print(f"warning: {w} - {a}", file=sys.stderr)
+    return 0  # reaching the tempo limit is a warning, not a failure
+
+
+def cmd_fit(args: argparse.Namespace) -> int:
+    text = _text_arg(args)
+    if args.engine == "mock":
+        preset = args.lang or ("ko" if any("가" <= ch <= "힣" for ch in text) else "en")
+        engine = MockEngine(preset)
+        # With --json stdout must hold the JSON only, so the practice-mode notice goes to stderr.
+        print(MOCK_BANNER, file=sys.stderr if args.json else sys.stdout)
+    elif args.engine == "say":
+        engine = SayEngine(args.voice)
+    else:
+        engine = PiperEngine(args.voice)
+    cache_dir = args.cache_dir if args.cache_dir else (False if args.no_cache else default_cache_dir())
+    r = fit(text, args.target, engine, out=args.out, cache_dir=cache_dir, target_duration=args.target_duration)
+    if args.json:
+        print(json.dumps(r.report(), ensure_ascii=False))
+        for w, a in zip(r.warnings, r.advice):
+            print(f"warning: {w} - {a}", file=sys.stderr)
+        if args.report:
+            r.save_report(args.report)
+        return 0
+    _print_result(r, args.out)
+    if args.report:
+        r.save_report(args.report)
+        print(f"report    {args.report}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="tts-pace", description="Measure and fit TTS speaking rate (syllables/second).")
+    p.add_argument("--version", action="version", version=f"tts-pace {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    d = sub.add_parser("demo", help="run four fits with the practice (mock) engine")
+    d.add_argument("--out", default="tts-pace-demo", help="output folder (default: ./tts-pace-demo)")
+    d.set_defaults(func=cmd_demo)
+
+    c = sub.add_parser("count", help="show the spoken form and syllable count of a text")
+    c.add_argument("text")
+    c.add_argument("--lang", choices=["auto", "ko", "en", "ja"], default="auto")
+    c.add_argument("--json", action="store_true")
+    c.set_defaults(func=cmd_count)
+
+    m = sub.add_parser("measure", help="measure a WAV file")
+    m.add_argument("wav")
+    _add_text(m, required=False)
+    m.add_argument("--silence-db", type=float, default=-60.0)
+    m.add_argument("--min-silence", type=float, default=0.6)
+    m.add_argument("--backend", choices=["auto", "numpy", "ffmpeg"], default="auto")
+    m.add_argument("--json", action="store_true")
+    m.set_defaults(func=cmd_measure)
+
+    r = sub.add_parser("retime", help="change an existing recording's tempo toward a target rate (0.85-1.15 limit)")
+    r.add_argument("wav")
+    _add_text(r)
+    _add_target(r)
+    r.add_argument("-o", "--out", required=True)
+    r.add_argument("--json", action="store_true")
+    r.set_defaults(func=cmd_retime)
+
+    f = sub.add_parser("fit", help="synthesize with an engine and fit to a target rate")
+    f.add_argument("--engine", choices=["mock", "say", "piper"], default="mock")
+    _add_text(f)
+    _add_target(f)
+    f.add_argument("-o", "--out", required=True)
+    f.add_argument("--voice", help="say voice name, or Piper .onnx path")
+    f.add_argument("--lang", choices=["ko", "en"], help="mock engine preset (default: guessed from the text)")
+    f.add_argument("--cache-dir", help=f"result cache folder (default: {default_cache_dir()})")
+    f.add_argument("--no-cache", action="store_true")
+    f.add_argument("--report", help="write the report JSON here")
+    f.add_argument("--json", action="store_true", help="print the report JSON to stdout (notices go to stderr)")
+    f.set_defaults(func=cmd_fit)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return int(args.func(args))
+    except (TtsPaceError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        # File-system problems (unwritable output path, missing folder, ...) get a short hint, not a traceback.
+        target = exc.filename if exc.filename is not None else "the output path"
+        print(
+            f"error: cannot write {target}: {exc.strerror or exc}. Choose a writable folder with -o.",
+            file=sys.stderr,
+        )
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tts_pace/count.py

@@ -0,0 +1,99 @@
+"""Syllable counting from text: Korean blocks, English heuristic, Japanese morae."""
+
+from __future__ import annotations
+
+import re
+import warnings
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from .en_syllables import count_en_word
+from .errors import UnsupportedTextError
+from .normalize import normalize_text
+
+_SMALL_KANA = set("ゃゅょぁぃぅぇぉゎャュョァィゥェォヮ")  # glue onto the previous kana (1 mora together)
+
+
+@dataclass(frozen=True)
+class SyllableCount:
+    """Result of count_syllables().
+
+    total: syllables (Korean/English) plus morae (Japanese) that were counted.
+    by_script: counts per script, keys 'ko', 'en', 'ja'.
+    normalized_text: the spoken form that was counted (digits and acronyms expanded).
+    unsupported: characters or tokens that could not be counted (e.g. kanji).
+    """
+
+    total: int
+    by_script: dict[str, int] = field(default_factory=lambda: {"ko": 0, "en": 0, "ja": 0})
+    normalized_text: str = ""
+    unsupported: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "total": self.total,
+            "by_script": dict(self.by_script),
+            "normalized_text": self.normalized_text,
+            "unsupported": list(self.unsupported),
+        }
+
+
+class UnsupportedCharsWarning(UserWarning):
+    """Some characters (kanji, digits in Japanese text) were not counted."""
+
+
+def count_normalized(spoken: str) -> tuple[dict[str, int], list[str]]:
+    """Count an already normalized text. Returns (by_script, unsupported characters)."""
+    by = {"ko": 0, "en": 0, "ja": 0}
+    unsupported: list[str] = []
+    for m in re.finditer(r"[가-힣]|[A-Za-z][A-Za-z'’]*|[぀-ヿ]|[一-鿿㐀-䶿]", spoken):
+        tok = m.group(0)
+        c = tok[0]
+        if "가" <= c <= "힣":
+            by["ko"] += 1
+        elif c.isascii() and c.isalpha():
+            by["en"] += count_en_word(tok)
+        elif "぀" <= c <= "ヿ":
+            if c in _SMALL_KANA or c in "・゛゜゠":
+                continue  # part of the previous mora (きょ = 1) or punctuation
+            by["ja"] += 1  # a kana, っ, ん and the long-vowel mark ー each count as one mora
+        else:
+            unsupported.append(tok)
+    return by, unsupported
+
+
+def count_syllables(
+    text: str,
+    lang: str = "auto",
+    normalize: Mapping[str, str] | None = None,
+) -> SyllableCount:
+    """Count the syllables of ``text`` the way a TTS engine would read it.
+
+    ``lang`` ('auto', 'ko', 'en', 'ja') only decides how digits and ACRONYMS are read;
+    letters are always counted by their own script. ``normalize`` maps text to a spoken
+    form before anything else, e.g. ``{"2026": "twenty twenty six"}``.
+
+    Raises UnsupportedTextError when nothing countable remains.
+    """
+    if not isinstance(text, str):
+        raise TypeError(f"text must be str, got {type(text).__name__}")
+    spoken, bad_tokens = normalize_text(text, lang, normalize)
+    by, bad_chars = count_normalized(spoken)
+    unsupported = tuple(bad_tokens + bad_chars)
+    total = sum(by.values())
+    if total == 0:
+        raise UnsupportedTextError(
+            "No countable syllables found in the text"
+            + (f" (unsupported: {', '.join(unsupported)})" if unsupported else "")
+            + ". Provide Hangul, kana or Latin letters, or map the text to a spoken form "
+            "with normalize={...}."
+        )
+    if unsupported:
+        warnings.warn(
+            f"{len(unsupported)} unsupported token(s) were not counted: {', '.join(unsupported[:5])}"
+            f"{'...' if len(unsupported) > 5 else ''}. Counts will be low; use normalize={{...}} "
+            "to give a kana/Hangul reading.",
+            UnsupportedCharsWarning,
+            stacklevel=2,
+        )
+    return SyllableCount(total, by, spoken, unsupported)

tts_pace/demo.py

@@ -0,0 +1,60 @@
+"""`tts-pace demo`: four fits with the practice (mock) engine, no keys or real TTS needed."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .engines.mock import MockEngine
+from .fit import FitResult, fit
+
+MOCK_BANNER = "[mock] 연습용 목(mock) 엔진 — 실제 TTS 아님 (practice engine, not a real TTS)"
+
+EN_TEXT = ("Today we learn how to match the speaking rate of a synthetic voice. "
+           "It is a short lesson about pace and silence.")
+KO_TEXT = ("오늘은 말하기 속도를 맞추는 방법을 알아봅니다. "
+           "목표 속도에 가깝게 음성을 다시 만들고 마지막에 조금만 다듬습니다.")
+
+# (name, text, mock preset, target syllables/second, what it shows)
+CASES = [
+    ("en far", EN_TEXT, "en", 4.0, "far target: re-synthesize, then tempo"),
+    ("en near", EN_TEXT, "en", 4.9, "near target: tempo only"),
+    ("ko near", KO_TEXT, "ko", 5.7, "near target: tempo only"),
+    ("ko floor", KO_TEXT, "ko", 4.0, "knob stops at its floor: limit shown"),
+]
+
+
+def run_demo(out_dir: str | Path = "tts-pace-demo") -> tuple[list[tuple[str, FitResult]], Path]:
+    """Run the four cases, write WAVs and report.json, return the results."""
+    out = Path(out_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    (out / "en.txt").write_text(EN_TEXT, encoding="utf-8")
+    (out / "ko.txt").write_text(KO_TEXT, encoding="utf-8")
+    results: list[tuple[str, FitResult]] = []
+    for name, text, preset, target, _ in CASES:
+        engine = MockEngine(preset)
+        slug = name.replace(" ", "_")
+        # numpy backends: same result whether or not ffmpeg is installed
+        result = fit(text, target, engine, out=out / f"{slug}.wav", tempo_backend="numpy",
+                     measure_backend="numpy", cache_dir=False, keep_candidates=True)
+        results.append((name, result))
+
+    report = {
+        "mock": True,
+        "mock_note": "practice (mock) engine, not a real TTS",
+        "cases": [{"name": n, **r.report()} for n, r in results],
+    }
+    report_path = out / "report.json"
+    report_path.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    return results, report_path
+
+
+def format_table(results: list[tuple[str, FitResult]]) -> str:
+    head = f"{'case':<9} {'base sps':>8}  {'route':<14} {'final sps':>9} {'target':>6} {'err':>7}  warnings"
+    lines = [head, "-" * len(head)]
+    for name, r in results:
+        lines.append(
+            f"{name:<9} {r.base.measurement.sps:>8.2f}  {r.route:<14} {r.best.measurement.sps:>9.2f} "
+            f"{r.target_sps:>6.1f} {r.best.err_pct:>6.2f}%  {', '.join(r.warnings) or '-'}"
+        )
+    return "\n".join(lines)

tts_pace/en_syllables.py

@@ -0,0 +1,99 @@
+"""English syllable estimate: vowel-group heuristic plus a small exception dictionary.
+
+This is an approximation (see README, limits). The exception dictionary below is
+hand-written (< 300 words) and was NOT extracted from the evaluation fixture.
+"""
+
+from __future__ import annotations
+
+import re
+
+# Words the rules get wrong that are common in narration, plus spelled-out letter names
+# (used for acronyms like "TTS" -> "tee tee ess").
+EXCEPTIONS: dict[str, int] = {
+    # letter names used when acronyms are spelled out
+    "ay": 1, "bee": 1, "see": 1, "dee": 1, "ee": 1, "eff": 1, "jee": 1, "aitch": 1,
+    "eye": 1, "jay": 1, "kay": 1, "ell": 1, "em": 1, "en": 1, "oh": 1, "pee": 1,
+    "cue": 1, "ar": 1, "ess": 1, "tee": 1, "you": 1, "vee": 1, "ex": 1, "why": 1, "zee": 1,
+    # numbers and very common irregular words
+    "one": 1, "two": 1, "three": 1, "four": 1, "five": 1, "six": 1, "seven": 2, "eight": 1,
+    "nine": 1, "ten": 1, "eleven": 3, "twelve": 1, "thirteen": 2, "fourteen": 2, "fifteen": 2,
+    "sixteen": 2, "seventeen": 3, "eighteen": 2, "nineteen": 2, "twenty": 2, "thirty": 2,
+    "forty": 2, "fifty": 2, "sixty": 2, "seventy": 3, "eighty": 2, "ninety": 2, "hundred": 2,
+    "thousand": 2, "million": 2, "billion": 2, "zero": 2, "point": 1, "percent": 2,
+    "the": 1, "a": 1, "i": 1, "area": 3, "idea": 3, "real": 1, "really": 2, "being": 2,
+    "doing": 2, "going": 2, "seeing": 2, "people": 2, "business": 2, "every": 2, "everyone": 3,
+    "everything": 3, "different": 3, "interesting": 3, "favorite": 3, "comfortable": 3,
+    "vegetable": 3, "camera": 3, "family": 3, "chocolate": 3, "evening": 2, "usually": 3,
+    "actually": 4, "especially": 4, "beautiful": 3, "science": 2, "scientist": 3, "quiet": 2,
+    "poem": 2, "poet": 2, "create": 2, "creating": 3, "creative": 3, "video": 3, "audio": 3,
+    "radio": 3, "studio": 3, "ratio": 3, "piano": 3, "violin": 3, "diet": 2, "client": 2,
+    "giant": 2, "lion": 2, "iron": 2, "fire": 1, "hour": 1, "our": 1, "flower": 2, "power": 2,
+    "tower": 2, "shower": 2, "wear": 1, "where": 1, "there": 1, "were": 1, "here": 1,
+    "queue": 1, "league": 1, "tongue": 1, "ocean": 2, "island": 2, "stomach": 2, "orange": 2,
+    "average": 3, "aware": 2, "someone": 2, "anyone": 3, "anything": 3, "something": 2,
+    "nothing": 2, "everybody": 4, "somebody": 3, "anybody": 4, "nobody": 3, "maybe": 2,
+    "already": 3, "also": 2, "always": 2, "again": 2, "against": 2, "because": 2, "before": 2,
+    "between": 2, "become": 2, "behind": 2, "below": 2, "beyond": 2, "world": 1, "word": 1,
+    "work": 1, "year": 1, "years": 1, "your": 1, "yours": 1, "speech": 1, "speaking": 2,
+    "rate": 1, "speed": 1, "pace": 1, "tempo": 2, "pitch": 1, "voice": 1, "voices": 2,
+    "engine": 2, "engines": 3, "synthesize": 3, "synthesis": 3, "syllable": 3, "syllables": 3,
+    "measure": 2, "measures": 2, "measured": 2, "text": 1, "texts": 1, "narration": 3,
+    "tutorial": 4, "lesson": 2, "learn": 1, "learning": 2, "listen": 2, "listening": 3,
+    "language": 3, "english": 2, "korean": 3, "japanese": 3, "welcome": 2, "today": 2,
+    "tomorrow": 3, "yesterday": 3, "morning": 2, "night": 1, "hello": 2, "thanks": 1,
+    "okay": 2, "ok": 2, "yes": 1, "no": 1, "quick": 1, "quickly": 2, "slow": 1, "slowly": 2,
+    "fast": 1, "faster": 2, "slower": 2, "target": 2, "closer": 2, "close": 1, "closed": 1,
+    "loop": 1, "result": 2, "results": 2, "silence": 2, "silent": 2, "pause": 1, "pauses": 2,
+    "sentence": 2, "sentences": 3, "word": 1, "words": 1, "minute": 2, "minutes": 2,
+    "second": 2, "seconds": 2, "average": 3, "per": 1, "per-second": 3, "over": 2, "under": 2,
+    "using": 2, "used": 1, "uses": 2, "use": 1, "make": 1, "makes": 1, "made": 1, "making": 2,
+    "take": 1, "takes": 1, "taken": 2, "give": 1, "gives": 1, "given": 2, "have": 1, "has": 1,
+    "are": 1, "is": 1, "was": 1, "be": 1, "been": 1, "to": 1, "of": 1, "and": 1, "or": 1,
+    "in": 1, "on": 1, "at": 1, "it": 1, "its": 1, "this": 1, "that": 1, "these": 2, "those": 1,
+}
+
+_VOWELS = "aeiouy"
+# ti/ci/si before a vowel sound make a "sh" consonant (nation, social, passion).
+_SH = re.compile(r"(?:[tcs]i)(?=o|a[ln]|ou|en)")
+# Vowel pairs that are normally two syllables (create, radio, duo).
+_HIATUS = ("ia", "io", "iu", "eo", "ua", "uo", "ii", "ao")
+
+
+def count_en_word(word: str) -> int:
+    """Estimate the syllable count of one English word (letters and apostrophes only)."""
+    w = re.sub(r"[^a-z]", "", word.lower())
+    if not w:
+        return 0
+    if w in EXCEPTIONS:
+        return EXCEPTIONS[w]
+    return max(_heuristic(w), 1)
+
+
+def _heuristic(w: str) -> int:
+    s = w
+    s = s.replace("qu", "q")  # u after q is a consonant glide
+    s = re.sub(r"gu(?=[aeiy])", "g", s)
+    if s.startswith("y") and len(s) > 1 and s[1] in _VOWELS:
+        s = "j" + s[1:]  # initial y is a consonant (yes, young)
+    s = _SH.sub("sh", s)
+    # Silent endings: -e (but not consonant+le), -es, -ed.
+    if re.search(r"[^aeiouy]le$", s):
+        pass  # table, little: "le" is a syllable
+    elif re.search(r"(?:sh|ch|[sxzcg])es$", s):
+        pass  # boxes, watches: "es" is pronounced
+    elif re.search(r"[^aeiouy]es$", s) and len(s) > 3:
+        s = s[:-2]
+    elif re.search(r"[td]ed$", s):
+        pass  # wanted, needed
+    elif re.search(r"[^aeiouy]ed$", s) and len(s) > 3:
+        s = s[:-2]
+    elif re.search(r"[^aeiouy]e$", s) and len(s) > 2:
+        s = s[:-1]
+    groups = re.findall(r"[aeiouy]+", s)
+    count = len(groups)
+    for g in groups:
+        for pair in _HIATUS:
+            if pair in g:
+                count += 1
+    return count