espeakng-runtime 0.1.0__py3-none-any.whl

espeakng_runtime/__init__.py

@@ -0,0 +1,39 @@
+"""Reliable native/CLI access to eSpeak NG phonemization."""
+
+from __future__ import annotations
+
+from .discovery import EspeakInspection, LibraryCandidate, LibraryProbe, inspect_espeak
+from .errors import (
+    CapabilityError,
+    EspeakConflictError,
+    EspeakError,
+    EspeakUnavailableError,
+    PhonemizationError,
+    VoiceNotFoundError,
+)
+from .runtime import EspeakRuntime
+from .types import Clause, FallbackCode, RuntimeInfo, Voice
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover - editable tree before build hook runs
+    __version__ = "0.1.dev0"
+
+__all__ = [
+    "CapabilityError",
+    "Clause",
+    "FallbackCode",
+    "EspeakConflictError",
+    "EspeakInspection",
+    "LibraryCandidate",
+    "LibraryProbe",
+    "inspect_espeak",
+    "EspeakError",
+    "EspeakRuntime",
+    "EspeakUnavailableError",
+    "PhonemizationError",
+    "RuntimeInfo",
+    "Voice",
+    "VoiceNotFoundError",
+    "__version__",
+]

espeakng_runtime/_text.py

@@ -0,0 +1,29 @@
+"""Internal text helpers."""
+
+from __future__ import annotations
+
+import re
+
+_CLAUSE_RE = re.compile(r"(.*?)([.!?]+|[,;:]+|$)", re.DOTALL)
+
+
+def split_best_effort_clauses(text: str) -> list[tuple[str, str | None, bool]]:
+    """Split punctuation for CLI/non-exact fallback.
+
+    This is intentionally labeled best-effort: it is not a replacement for
+    eSpeak NG's native terminator API.
+    """
+    result: list[tuple[str, str | None, bool]] = []
+    position = 0
+    for match in _CLAUSE_RE.finditer(text):
+        if match.start() != position:
+            continue
+        body, terminator = match.groups()
+        if not body and not terminator:
+            break
+        token = terminator or None
+        result.append((body, token, bool(token and set(token) & {".", "!", "?"})))
+        position = match.end()
+        if position >= len(text):
+            break
+    return result

espeakng_runtime/_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.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'ga7b5c0781'

espeakng_runtime/_voices.py

@@ -0,0 +1,89 @@
+"""Voice request normalization and deterministic inventory selection."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from .errors import VoiceNotFoundError
+from .types import Voice
+
+
+def normalize_voice_code(value: str) -> str:
+    """Normalize an eSpeak voice code for comparison."""
+    return value.strip().lower().replace("\\", "/").replace("_", "-")
+
+
+def is_mbrola_identifier(value: str) -> bool:
+    """Return whether an inventory identifier denotes an MBROLA voice."""
+    return normalize_voice_code(value).startswith("mb/")
+
+
+def is_explicit_mbrola_request(value: str) -> bool:
+    """Return whether a request explicitly asks for an MBROLA voice."""
+    code = normalize_voice_code(value)
+    return code.startswith(("mb/", "mb-", "mbrola"))
+
+
+def _standard_rank(requested: str, voice: Voice) -> int | None:
+    identifier = normalize_voice_code(voice.identifier)
+    language = normalize_voice_code(voice.language)
+    identifier_name = identifier.rsplit("/", 1)[-1]
+    requested_base = requested.split("-", 1)[0]
+
+    if language == requested:
+        return 0
+    if identifier == requested:
+        return 1
+    if identifier_name == requested:
+        return 2
+    if language.split("-", 1)[0] == requested_base:
+        return 3
+    return None
+
+
+def choose_voice(
+    voices: Sequence[Voice],
+    request: str,
+    *,
+    allow_mbrola: bool = False,
+) -> Voice:
+    """Select the best compatible voice from an eSpeak inventory."""
+    requested = normalize_voice_code(request)
+    if not requested:
+        raise VoiceNotFoundError("eSpeak voice request must not be empty")
+
+    explicit_mbrola = is_explicit_mbrola_request(requested)
+    ranked: list[tuple[int, int, Voice]] = []
+    for index, voice in enumerate(voices):
+        identifier = normalize_voice_code(voice.identifier)
+        mbrola = is_mbrola_identifier(identifier)
+        rank: int | None
+
+        if explicit_mbrola:
+            if not mbrola:
+                continue
+            if identifier == requested:
+                rank = 0
+            elif identifier.rsplit("/", 1)[-1] == requested:
+                rank = 1
+            else:
+                continue
+        else:
+            if mbrola:
+                if not allow_mbrola:
+                    continue
+                rank = _standard_rank(requested, voice)
+                if rank is None:
+                    continue
+                rank += 10
+            else:
+                rank = _standard_rank(requested, voice)
+                if rank is None:
+                    continue
+
+        if rank is not None:
+            ranked.append((rank, index, voice))
+
+    if not ranked:
+        raise VoiceNotFoundError(f"eSpeak voice {request!r} was not found")
+    return min(ranked, key=lambda item: (item[0], item[1]))[2]

espeakng_runtime/backends/__init__.py

@@ -0,0 +1,6 @@
+"""Backend implementations."""
+
+from .cli import CliBackend
+from .native import NativeBackend
+
+__all__ = ["CliBackend", "NativeBackend"]

espeakng_runtime/backends/base.py

@@ -0,0 +1,39 @@
+"""Backend protocol."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol
+
+from ..types import Clause, RuntimeInfo, Voice
+
+
+class EspeakBackend(Protocol):
+    @property
+    def info(self) -> RuntimeInfo: ...
+
+    def phonemize(
+        self,
+        text: str,
+        *,
+        voice: str,
+        separator: str | None = None,
+        use_tie: bool = False,
+        tie_char: str = "͡",
+    ) -> str: ...
+
+    def phonemize_many(
+        self,
+        texts: Sequence[str],
+        *,
+        voice: str,
+        separator: str | None = None,
+        use_tie: bool = False,
+        tie_char: str = "͡",
+    ) -> list[str]: ...
+
+    def clauses(self, text: str, *, voice: str, exact: bool = False) -> list[Clause]: ...
+
+    def list_voices(self, filter_name: str | None = None) -> list[Voice]: ...
+
+    def close(self) -> None: ...

espeakng_runtime/backends/cli.py

@@ -0,0 +1,199 @@
+"""Command-line eSpeak backend."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from collections.abc import Sequence
+
+from .._text import split_best_effort_clauses
+from ..discovery import data_parent_for_espeak
+from ..errors import CapabilityError, PhonemizationError
+from ..types import Clause, FallbackCode, RuntimeInfo, Voice
+
+_VERSION_RE = re.compile(r"(?:eSpeak NG|eSpeak)[^0-9]*([0-9]+(?:\.[0-9]+)+)", re.I)
+
+
+class CliBackend:
+    def __init__(
+        self,
+        *,
+        executable: str,
+        data: str | None,
+        timeout: float | None,
+        requested_mode: str,
+        fallback_reason: str | None = None,
+        fallback_code: FallbackCode | None = None,
+    ) -> None:
+        self.executable = executable
+        self.data = data
+        self.timeout = timeout
+        self.requested_mode = requested_mode
+        self.fallback_reason = fallback_reason
+        self.fallback_code = fallback_code
+        self._version: str | None = None
+
+    def _run(
+        self,
+        args: list[str],
+        *,
+        input_text: str | None = None,
+    ) -> subprocess.CompletedProcess[str]:
+        command = [self.executable, *args]
+        if self.data:
+            command.append(f"--path={data_parent_for_espeak(self.data)}")
+        try:
+            process = subprocess.run(
+                command,
+                input=input_text,
+                text=True,
+                encoding="utf-8",
+                errors="strict",
+                capture_output=True,
+                check=False,
+                timeout=self.timeout,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            raise PhonemizationError(f"eSpeak CLI invocation failed: {exc}") from exc
+        if process.returncode:
+            raise PhonemizationError(
+                f"eSpeak failed ({process.returncode}): {process.stderr.strip()}"
+            )
+        return process
+
+    @property
+    def version(self) -> str | None:
+        if self._version is None:
+            process = self._run(["--version"])
+            output = f"{process.stdout}\n{process.stderr}"
+            match = _VERSION_RE.search(output)
+            self._version = match.group(1) if match else output.strip().splitlines()[0]
+        return self._version
+
+    @property
+    def info(self) -> RuntimeInfo:
+        return RuntimeInfo(
+            requested_mode=self.requested_mode,  # type: ignore[arg-type]
+            implementation="cli",
+            executable=self.executable,
+            data=self.data,
+            source="cli",
+            version=self.version,
+            exact_clause_api=False,
+            parity="best-effort",
+            fallback_reason=self.fallback_reason,
+            fallback_code=self.fallback_code,
+        )
+
+    @staticmethod
+    def _phoneme_args(
+        *,
+        voice: str,
+        separator: str | None,
+        use_tie: bool,
+        tie_char: str,
+    ) -> list[str]:
+        args = ["-q", "-x", "--ipa", f"-v{voice}"]
+        if use_tie:
+            if not tie_char:
+                raise ValueError("tie_char must not be empty")
+            args.append(f"--tie={tie_char[0]}")
+        elif separator:
+            args.append(f"--sep={separator[0]}")
+        return args
+
+    def phonemize(
+        self,
+        text: str,
+        *,
+        voice: str,
+        separator: str | None = None,
+        use_tie: bool = False,
+        tie_char: str = "͡",
+    ) -> str:
+        if not text or not text.strip():
+            return ""
+        process = self._run(
+            self._phoneme_args(
+                voice=voice,
+                separator=separator,
+                use_tie=use_tie,
+                tie_char=tie_char,
+            ),
+            input_text=text if text.endswith("\n") else f"{text}\n",
+        )
+        return re.sub(r"\s+", " ", process.stdout.strip())
+
+    def phonemize_many(
+        self,
+        texts: Sequence[str],
+        *,
+        voice: str,
+        separator: str | None = None,
+        use_tie: bool = False,
+        tie_char: str = "͡",
+    ) -> list[str]:
+        values = list(texts)
+        nonempty = [text for text in values if text and text.strip()]
+        if not nonempty:
+            return [""] * len(values)
+        if any("\n" in text or "\r" in text for text in nonempty):
+            raise ValueError("phonemize_many inputs must not contain line breaks")
+        process = self._run(
+            self._phoneme_args(
+                voice=voice,
+                separator=separator,
+                use_tie=use_tie,
+                tie_char=tie_char,
+            ),
+            input_text="\n".join(nonempty) + "\n",
+        )
+        lines = process.stdout.splitlines()
+        if len(lines) != len(nonempty):
+            raise PhonemizationError(
+                f"eSpeak returned {len(lines)} lines for {len(nonempty)} inputs"
+            )
+        iterator = iter(lines)
+        result: list[str] = []
+        for text in values:
+            if not text or not text.strip():
+                result.append("")
+            else:
+                result.append(re.sub(r"\s+", " ", next(iterator).strip()))
+        return result
+
+    def clauses(self, text: str, *, voice: str, exact: bool = False) -> list[Clause]:
+        if exact:
+            raise CapabilityError("CLI eSpeak does not expose exact clause terminator codes")
+        return [
+            Clause(
+                phonemes=self.phonemize(body, voice=voice),
+                terminator=terminator,
+                terminator_code=None,
+                sentence_end=sentence_end,
+            )
+            for body, terminator, sentence_end in split_best_effort_clauses(text)
+        ]
+
+    def list_voices(self, filter_name: str | None = None) -> list[Voice]:
+        args = [f"--voices={filter_name}"] if filter_name else ["--voices"]
+        process = self._run(args)
+        voices: list[Voice] = []
+        for line in process.stdout.splitlines():
+            line = line.strip()
+            if not line or line.lower().startswith("pty"):
+                continue
+            parts = line.split()
+            if len(parts) < 5:
+                continue
+            voices.append(
+                Voice(
+                    name=parts[3].replace("_", " "),
+                    language=parts[1],
+                    identifier=parts[4].replace("\\", "/"),
+                )
+            )
+        return voices
+
+    def close(self) -> None:
+        return None