syscon-tts 0.0.1__py3-none-any.whl

syscon_tts/__init__.py

@@ -0,0 +1,65 @@
+"""Syscon TTS - offline text-to-speech for the PlantStar APU.
+
+Wraps the Piper neural TTS engine (CPU-only, fully offline) behind a small
+library, a command-line tool, and an optional HTTP server.
+
+Piper only installs on Linux, which is where every APU runs. Importing this
+package is nonetheless safe on Windows and macOS: the Piper import is deferred
+until synthesis is attempted, so developers on those platforms can install the
+package, inspect voices, and replay audio generated elsewhere. Attempting to
+generate new audio there raises
+:class:`~syscon_tts.engine.SynthesisUnavailableError`.
+
+Typical APU usage -- resolve alert text to a WAV, synthesizing only on a cache
+miss::
+
+    from syscon_tts import AlertSynthesizer
+
+    synth = AlertSynthesizer()          # build once, keep it: caches models
+    result = synth.ensure("Press 4 cavity pressure exceeded.")
+    print(result.path, result.cached)
+"""
+
+from .alerts import (
+    AlertAudio,
+    AlertSynthesizer,
+    InvalidAlertNameError,
+    ensure_alert_wav,
+    sanitize_file_name,
+)
+from .config import Settings, load_settings
+from .engine import (
+    SynthesisError,
+    SynthesisUnavailableError,
+    TTSEngine,
+    piper_available,
+)
+from .voices import (
+    UnknownVoiceError,
+    VoiceError,
+    VoiceNotInstalledError,
+    VoiceProfile,
+    VoiceRegistry,
+)
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "AlertAudio",
+    "AlertSynthesizer",
+    "InvalidAlertNameError",
+    "Settings",
+    "SynthesisError",
+    "SynthesisUnavailableError",
+    "TTSEngine",
+    "UnknownVoiceError",
+    "VoiceError",
+    "VoiceNotInstalledError",
+    "VoiceProfile",
+    "VoiceRegistry",
+    "__version__",
+    "ensure_alert_wav",
+    "load_settings",
+    "piper_available",
+    "sanitize_file_name",
+]

syscon_tts/alerts.py

@@ -0,0 +1,181 @@
+"""Cache-first alert audio.
+
+This is the module the PlantStar APU integrates against. It encapsulates the
+one contract the rest of the APU actually depends on: a WAV file exists at
+``<alerts_dir>/<file_name>.wav``. Everything downstream -- the websocket push,
+``/media/`` serving, and the file-cleanup pass -- is agnostic about how that
+file got there.
+
+The lookup is deliberately **cache first**:
+
+* If the WAV already exists, it is returned immediately. This path needs no
+  Piper, so it works on Windows and macOS exactly as it does on Linux.
+* Only on a cache miss is synthesis attempted, which requires Piper and
+  therefore Linux. On other platforms this raises
+  :class:`~syscon_tts.engine.SynthesisUnavailableError`, which callers can
+  catch to degrade gracefully.
+
+That split is what lets developers on Windows/macOS exercise the full alert
+pipeline against audio generated on a Linux box, without installing Piper.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .config import Settings, load_settings
+from .engine import TTSEngine
+from .voices import VoiceRegistry
+
+
+class InvalidAlertNameError(ValueError):
+    """Text reduced to a file name that would be unsafe to write."""
+
+
+# Django's ``get_valid_filename`` strips everything outside [-\w.] after
+# collapsing spaces to underscores. Reproduced here (rather than imported) so
+# the package has no Django dependency, while still computing byte-identical
+# names to the APU's existing ``get_valid_filename(message)[:50]``.
+_UNSAFE_CHARS = re.compile(r"(?u)[^-\w.]")
+
+#: The APU truncates alert file names to this length.
+MAX_FILE_NAME_LEN = 50
+
+
+def sanitize_file_name(text: str, max_length: int = MAX_FILE_NAME_LEN) -> str:
+    """Derive an alert file name (no extension) from message text.
+
+    Matches ``django.utils.text.get_valid_filename(text)[:max_length]``.
+    """
+    name = str(text).strip().replace(" ", "_")
+    name = _UNSAFE_CHARS.sub("", name)
+    name = name[:max_length]
+    if name in ("", ".", ".."):
+        raise InvalidAlertNameError(
+            f"Text {text!r} does not yield a usable file name."
+        )
+    return name
+
+
+@dataclass(frozen=True)
+class AlertAudio:
+    """Result of resolving an alert to a playable WAV file."""
+
+    path: Path
+    file_name: str
+    cached: bool          # True when the file already existed
+    voice: Optional[str]  # None when served from cache without synthesis
+
+    def __fspath__(self) -> str:
+        """Allow the result to be used anywhere a path is accepted."""
+        return str(self.path)
+
+
+class AlertSynthesizer:
+    """Resolves alert text to a WAV file on disk, synthesizing only on a miss.
+
+    Holds a :class:`~syscon_tts.engine.TTSEngine`, so loaded voice models stay
+    cached in memory across calls. Construct one and keep it -- building a new
+    instance per alert throws away the model cache and reintroduces the
+    multi-second cold-load cost on every message.
+    """
+
+    def __init__(
+        self,
+        settings: Optional[Settings] = None,
+        registry: Optional[VoiceRegistry] = None,
+        engine: Optional[TTSEngine] = None,
+    ):
+        self.settings = settings or load_settings()
+        self.registry = registry or VoiceRegistry.from_manifest(
+            self.settings.voices_manifest, self.settings.voices_dir
+        )
+        self.engine = engine or TTSEngine(self.registry)
+
+    # -- lookup ------------------------------------------------------------
+
+    def alerts_dir(self, override: Optional[Path] = None) -> Path:
+        return Path(override) if override else self.settings.alerts_dir
+
+    def path_for(
+        self, file_name: str, alerts_dir: Optional[Path] = None
+    ) -> Path:
+        """Absolute path the WAV for ``file_name`` would occupy."""
+        return self.alerts_dir(alerts_dir) / f"{file_name}.wav"
+
+    def exists(self, text: str, alerts_dir: Optional[Path] = None) -> bool:
+        """True if ``text`` already has generated audio on disk."""
+        return self.path_for(sanitize_file_name(text), alerts_dir).is_file()
+
+    # -- resolution --------------------------------------------------------
+
+    def ensure(
+        self,
+        text: str,
+        file_name: Optional[str] = None,
+        voice: Optional[str] = None,
+        alerts_dir: Optional[Path] = None,
+        speed: float = 1.0,
+        sentence_silence: float = 0.2,
+        force: bool = False,
+    ) -> AlertAudio:
+        """Return the WAV for ``text``, synthesizing it only if absent.
+
+        ``file_name`` overrides the derived name -- pass the APU's own
+        ``get_valid_filename(message)[:50]`` result to guarantee both sides
+        agree on the path. Set ``force`` to regenerate even on a cache hit.
+
+        Raises :class:`~syscon_tts.engine.SynthesisUnavailableError` when the
+        file is missing and this machine cannot run Piper.
+        """
+        name = file_name or sanitize_file_name(text)
+        directory = self.alerts_dir(alerts_dir)
+        dest = directory / f"{name}.wav"
+
+        if dest.is_file() and not force:
+            return AlertAudio(path=dest, file_name=name, cached=True, voice=None)
+
+        voice_id = voice or self.settings.default_voice
+        audio = self.engine.synthesize_wav(
+            text,
+            voice_id,
+            speed=speed,
+            sentence_silence=sentence_silence,
+        )
+        directory.mkdir(parents=True, exist_ok=True)
+        _atomic_write(dest, audio)
+        return AlertAudio(path=dest, file_name=name, cached=False, voice=voice_id)
+
+
+def _atomic_write(dest: Path, payload: bytes) -> None:
+    """Write ``payload`` to ``dest`` without exposing a partial file.
+
+    The APU's websocket handler checks ``path.exists()`` before pushing the
+    audio URL to clients, so a half-written file would be served as a truncated
+    alert. Writing to a sibling temp file and renaming makes the file appear
+    only once it is complete.
+    """
+    fd, tmp_name = tempfile.mkstemp(dir=str(dest.parent), suffix=".part")
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp, dest)
+    except BaseException:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+# Module-level convenience wrapper. Builds a fresh synthesizer per call, so it
+# is fine for one-off scripts and the CLI but wasteful in a long-running
+# process -- construct an AlertSynthesizer there instead.
+def ensure_alert_wav(text: str, **kwargs) -> AlertAudio:
+    """One-shot :meth:`AlertSynthesizer.ensure`."""
+    return AlertSynthesizer().ensure(text, **kwargs)

syscon_tts/api.py

@@ -0,0 +1,137 @@
+"""HTTP API (FastAPI).
+
+Optional -- install with ``pip install 'syscon-tts[server]'``. The APU does not
+need it: it imports :class:`~syscon_tts.alerts.AlertSynthesizer` in-process, so
+Django never inherits a web-framework dependency it does not use. The server
+exists for local operation and smoke-testing a provisioned host.
+
+Endpoints:
+    GET  /health              liveness/readiness probe
+    GET  /voices              list available voice profiles
+    POST /synthesize          render text to an audio file
+    GET  /                    service info
+
+Build the app with :func:`create_app`; ``app`` at module level is the default
+instance used by uvicorn / the CLI ``serve`` command.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import Response
+from pydantic import BaseModel, Field
+
+from . import __version__
+from .config import Settings, load_settings
+from .engine import (
+    SynthesisError,
+    SynthesisUnavailableError,
+    TTSEngine,
+    piper_available,
+)
+from .voices import UnknownVoiceError, VoiceNotInstalledError, VoiceRegistry
+
+
+class SynthesizeRequest(BaseModel):
+    text: str = Field(..., description="Text to speak.")
+    voice: Optional[str] = Field(
+        None, description="Voice id. Defaults to the server's default voice."
+    )
+    format: str = Field("wav", description="Output format: 'wav' or 'mp3'.")
+    speed: float = Field(
+        1.0, gt=0, le=4.0, description="Speed multiplier (1.0 = normal)."
+    )
+    sentence_silence: float = Field(
+        0.2, ge=0, le=5.0, description="Seconds of silence between sentences."
+    )
+
+
+def create_app(settings: Optional[Settings] = None) -> FastAPI:
+    settings = settings or load_settings()
+    registry = VoiceRegistry.from_manifest(
+        settings.voices_manifest, settings.voices_dir
+    )
+    engine = TTSEngine(registry)
+
+    app = FastAPI(
+        title="Syscon TTS",
+        version=__version__,
+        description="Offline text-to-speech service with selectable voice profiles.",
+    )
+    app.state.settings = settings
+    app.state.registry = registry
+    app.state.engine = engine
+
+    @app.get("/")
+    def info():
+        return {
+            "service": "Syscon TTS",
+            "version": __version__,
+            "engine": "piper",
+            "default_voice": settings.default_voice,
+            "endpoints": ["/health", "/voices", "/synthesize"],
+        }
+
+    @app.get("/health")
+    def health():
+        installed = sum(1 for p in registry.all() if registry.is_installed(p))
+        return {
+            "status": "ok",
+            "can_synthesize": piper_available(),
+            "voices_total": len(registry.all()),
+            "voices_installed": installed,
+        }
+
+    @app.get("/voices")
+    def list_voices():
+        return {
+            "default": settings.default_voice,
+            "voices": [
+                p.to_public_dict(registry.is_installed(p)) for p in registry.all()
+            ],
+        }
+
+    @app.post("/synthesize")
+    def synthesize(req: SynthesizeRequest):
+        if len(req.text) > settings.max_text_chars:
+            raise HTTPException(
+                status_code=413,
+                detail=f"Text exceeds max length of {settings.max_text_chars} chars.",
+            )
+        voice_id = req.voice or settings.default_voice
+        try:
+            audio, media_type = engine.synthesize(
+                req.text,
+                voice_id,
+                fmt=req.format,
+                speed=req.speed,
+                sentence_silence=req.sentence_silence,
+            )
+        except UnknownVoiceError as exc:
+            raise HTTPException(status_code=404, detail=str(exc)) from exc
+        except VoiceNotInstalledError as exc:
+            raise HTTPException(status_code=503, detail=str(exc)) from exc
+        except SynthesisUnavailableError as exc:
+            # 501: this host will never be able to serve the request, as
+            # opposed to 503's "try again once the models are installed".
+            raise HTTPException(status_code=501, detail=str(exc)) from exc
+        except SynthesisError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+        ext = "mp3" if media_type == "audio/mpeg" else "wav"
+        return Response(
+            content=audio,
+            media_type=media_type,
+            headers={
+                "Content-Disposition": f'attachment; filename="speech.{ext}"',
+                "X-Voice": voice_id,
+            },
+        )
+
+    return app
+
+
+# Default application instance for `uvicorn syscon_tts.api:app`.
+app = create_app()

syscon_tts/cli.py

@@ -0,0 +1,278 @@
+"""Command-line interface.
+
+Usage examples::
+
+    syscon-tts doctor
+    syscon-tts download-voices                    # fetch every voice
+    syscon-tts download-voices en_us_amy          # or just one
+    syscon-tts list-voices
+    syscon-tts speak --voice en_us_amy --output hello.wav "Hello from PlantStar"
+    syscon-tts alert "Press 4 cavity pressure exceeded."
+    syscon-tts serve --host 127.0.0.1 --port 5002
+
+Every command except ``download-voices`` runs fully offline. ``doctor``,
+``list-voices``, and cache hits from ``alert`` work on any platform; ``speak``
+and cache misses need Piper, and therefore Linux.
+"""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import shutil
+import sys
+from pathlib import Path
+
+from . import __version__
+from .alerts import AlertSynthesizer, InvalidAlertNameError
+from .config import load_settings
+from .download import DownloadError, download_voices
+from .engine import SynthesisError, SynthesisUnavailableError, TTSEngine, piper_available
+from .voices import VoiceError, VoiceRegistry
+
+
+def _build_registry_and_engine():
+    settings = load_settings()
+    registry = VoiceRegistry.from_manifest(settings.voices_manifest, settings.voices_dir)
+    return settings, registry, TTSEngine(registry)
+
+
+def _cmd_list_voices(args: argparse.Namespace) -> int:
+    settings, registry, _ = _build_registry_and_engine()
+    print(f"Default voice: {settings.default_voice}")
+    print(f"Voices dir:    {settings.voices_dir}\n")
+    header = f"{'ID':<22} {'LANGUAGE':<8} {'GENDER':<10} {'INSTALLED':<9} NAME"
+    print(header)
+    print("-" * len(header))
+    for p in registry.all():
+        installed = "yes" if registry.is_installed(p) else "no"
+        print(f"{p.id:<22} {p.language:<8} {p.gender:<10} {installed:<9} {p.name}")
+    return 0
+
+
+def _cmd_doctor(args: argparse.Namespace) -> int:
+    """Report whether this machine can generate audio, and why not if it can't."""
+    settings = load_settings()
+    print(f"syscon-tts {__version__}")
+    print(f"  platform          {platform.system()} {platform.machine()}")
+    print(f"  python            {platform.python_version()}")
+    print(f"  manifest          {settings.voices_manifest}")
+    print(f"  voices dir        {settings.voices_dir}")
+    print(f"  alerts dir        {settings.alerts_dir}")
+    print(f"  ffmpeg (mp3)      {'yes' if shutil.which('ffmpeg') else 'no'}")
+
+    has_piper = piper_available()
+    print(f"  piper (synthesis) {'yes' if has_piper else 'no'}")
+
+    try:
+        registry = VoiceRegistry.from_manifest(
+            settings.voices_manifest, settings.voices_dir
+        )
+    except VoiceError as exc:
+        print(f"\nERROR: {exc}", file=sys.stderr)
+        return 1
+
+    installed = [p for p in registry.all() if registry.is_installed(p)]
+    print(f"  voices installed  {len(installed)}/{len(registry.all())}")
+
+    problems = []
+    if not has_piper:
+        if platform.system() == "Linux":
+            problems.append(
+                "Piper is missing on a Linux host. Reinstall with "
+                "'pip install syscon-tts[piper]' using Python 3.9-3.11."
+            )
+        else:
+            print(
+                f"\nNote: {platform.system()} cannot generate audio -- Piper ships "
+                "Linux-only wheels. Previously generated WAVs still play and serve "
+                "normally from the alerts directory."
+            )
+    if not installed:
+        problems.append(
+            "No voice models on disk. Run 'syscon-tts download-voices'."
+        )
+
+    if problems:
+        # stdout is block-buffered when piped while stderr is not, so the
+        # report would otherwise appear after the problems it refers to.
+        sys.stdout.flush()
+        print("\nProblems:", file=sys.stderr)
+        for problem in problems:
+            print(f"  - {problem}", file=sys.stderr)
+        return 1
+
+    print("\nReady.")
+    return 0
+
+
+def _cmd_download_voices(args: argparse.Namespace) -> int:
+    settings, registry, _ = _build_registry_and_engine()
+    print(f"Downloading into {settings.voices_dir}")
+    try:
+        results = download_voices(
+            registry,
+            settings.voices_dir,
+            voice_ids=args.voice_ids,
+            force=args.force,
+            on_progress=print,
+        )
+    except (DownloadError, VoiceError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    fetched = sum(1 for r in results if not r.skipped)
+    total_mb = sum(r.size for r in results if not r.skipped) / (1024 * 1024)
+    print(f"Done. {fetched} file(s) downloaded ({total_mb:.1f} MB).")
+    return 0
+
+
+def _read_text(args: argparse.Namespace) -> str:
+    if args.text_file:
+        return Path(args.text_file).read_text(encoding="utf-8")
+    if args.text:
+        return args.text
+    # Fall back to stdin (allows piping: `echo hi | syscon-tts speak ...`).
+    if not sys.stdin.isatty():
+        return sys.stdin.read()
+    raise SystemExit("No text provided. Pass TEXT, --text-file, or pipe via stdin.")
+
+
+def _cmd_speak(args: argparse.Namespace) -> int:
+    settings, _, engine = _build_registry_and_engine()
+    text = _read_text(args)
+    voice_id = args.voice or settings.default_voice
+    fmt = args.format or ("mp3" if args.output.lower().endswith(".mp3") else "wav")
+    try:
+        audio, _ = engine.synthesize(
+            text,
+            voice_id,
+            fmt=fmt,
+            speed=args.speed,
+            sentence_silence=args.sentence_silence,
+        )
+    except (VoiceError, SynthesisError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    Path(args.output).write_bytes(audio)
+    print(f"Wrote {len(audio)} bytes to {args.output} (voice={voice_id}, format={fmt})")
+    return 0
+
+
+def _cmd_alert(args: argparse.Namespace) -> int:
+    """Resolve alert text the same way the APU does: cache first, then synthesize."""
+    try:
+        synth = AlertSynthesizer()
+        result = synth.ensure(
+            args.text,
+            file_name=args.file_name,
+            voice=args.voice,
+            alerts_dir=Path(args.alerts_dir) if args.alerts_dir else None,
+            force=args.force,
+        )
+    except InvalidAlertNameError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except SynthesisUnavailableError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except (VoiceError, SynthesisError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    state = "cached" if result.cached else f"generated (voice={result.voice})"
+    print(f"{result.path}  [{state}]")
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    try:
+        import uvicorn
+    except ImportError:
+        print(
+            "error: the HTTP server needs extra dependencies. "
+            "Install them with: pip install 'syscon-tts[server]'",
+            file=sys.stderr,
+        )
+        return 1
+    settings = load_settings()
+    host = args.host or settings.host
+    port = args.port or settings.port
+    print(f"Starting Syscon TTS on http://{host}:{port}")
+    uvicorn.run("syscon_tts.api:app", host=host, port=port, workers=args.workers)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="syscon-tts",
+        description="Offline text-to-speech for the PlantStar APU.",
+    )
+    parser.add_argument("--version", action="version",
+                        version=f"syscon-tts {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_doctor = sub.add_parser(
+        "doctor", help="Report platform, Piper, and voice-model status."
+    )
+    p_doctor.set_defaults(func=_cmd_doctor)
+
+    p_list = sub.add_parser("list-voices", help="List available voice profiles.")
+    p_list.set_defaults(func=_cmd_list_voices)
+
+    p_dl = sub.add_parser(
+        "download-voices", help="Download voice models (needs internet)."
+    )
+    p_dl.add_argument("voice_ids", nargs="*",
+                      help="Voice ids to fetch (default: all in the manifest).")
+    p_dl.add_argument("--force", action="store_true",
+                      help="Re-download even if the file is already present.")
+    p_dl.set_defaults(func=_cmd_download_voices)
+
+    p_speak = sub.add_parser("speak", help="Synthesize text to an audio file.")
+    p_speak.add_argument("text", nargs="?", help="Text to speak.")
+    p_speak.add_argument("-v", "--voice", help="Voice id (see list-voices).")
+    p_speak.add_argument("-o", "--output", required=True, help="Output file path.")
+    p_speak.add_argument("-f", "--format", choices=["wav", "mp3"],
+                         help="Output format (default: inferred from --output).")
+    p_speak.add_argument("--text-file", help="Read text from a file instead of arg.")
+    p_speak.add_argument("--speed", type=float, default=1.0,
+                         help="Speed multiplier (1.0 = normal).")
+    p_speak.add_argument("--sentence-silence", type=float, default=0.2,
+                         help="Seconds of silence between sentences.")
+    p_speak.set_defaults(func=_cmd_speak)
+
+    p_alert = sub.add_parser(
+        "alert",
+        help="Resolve alert text to a WAV in the alerts dir (cache first).",
+    )
+    p_alert.add_argument("text", help="Alert message text.")
+    p_alert.add_argument("-v", "--voice", help="Voice id (see list-voices).")
+    p_alert.add_argument("--file-name",
+                         help="Override the derived file name (no extension).")
+    p_alert.add_argument("--alerts-dir",
+                         help="Override the configured alerts directory.")
+    p_alert.add_argument("--force", action="store_true",
+                         help="Regenerate even if the WAV already exists.")
+    p_alert.set_defaults(func=_cmd_alert)
+
+    p_serve = sub.add_parser("serve", help="Run the HTTP API server.")
+    p_serve.add_argument("--host", help="Bind host (default from config).")
+    p_serve.add_argument("--port", type=int, help="Bind port (default from config).")
+    p_serve.add_argument("--workers", type=int, default=1,
+                         help="Number of worker processes.")
+    p_serve.set_defaults(func=_cmd_serve)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except VoiceError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())