inflectsynth 0.1.0__py3-none-any.whl

inflectsynth/__init__.py

@@ -0,0 +1,92 @@
+"""Inflect v2 prepared-text synthesis backed by ONNXVoice and InflectG2P."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _distribution_version
+
+from .api_contract import REQUEST_API_VERSION, request_api_contract
+from .catalog import list_models
+from .config import SynthesisConfig
+from .discovery import DescribedVoice, DiscoveredModel, discover_models
+from .errors import (
+    ArtifactIntegrityError,
+    CatalogDiscoveryError,
+    CatalogError,
+    CatalogUnavailableError,
+    EmptyTextError,
+    InflectSynthError,
+    InvalidSeedError,
+    InvalidSpeedError,
+    InvalidSynthesisConfigError,
+    InvalidVariationError,
+    InvalidVoiceError,
+    ModelInferenceError,
+    ModelNotFoundError,
+    OfflineModelError,
+    OnnxVoiceContractError,
+    ProviderUnavailableError,
+    UnsupportedModelError,
+)
+from .identity import runtime_identity
+from .types import ModelInfo, SynthesisResult, VoiceInfo
+from .voice import InflectVoice
+from .voice_level import (
+    CalibrationDataError,
+    VoiceCalibrationCatalog,
+    VoiceCalibrationKey,
+    VoiceLevelApplication,
+    VoiceLevelCalibration,
+    VoiceLevelConfig,
+    VoiceLevelMode,
+    apply_voice_level_calibration,
+    default_voice_calibration,
+    load_voice_calibration,
+)
+
+try:
+    __version__ = _distribution_version("inflectsynth")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+__all__ = [
+    "__version__",
+    "REQUEST_API_VERSION",
+    "request_api_contract",
+    "runtime_identity",
+    "discover_models",
+    "DescribedVoice",
+    "DiscoveredModel",
+    "InflectVoice",
+    "SynthesisConfig",
+    "SynthesisResult",
+    "VoiceInfo",
+    "VoiceLevelConfig",
+    "VoiceLevelMode",
+    "VoiceCalibrationKey",
+    "VoiceLevelCalibration",
+    "VoiceCalibrationCatalog",
+    "VoiceLevelApplication",
+    "CalibrationDataError",
+    "apply_voice_level_calibration",
+    "default_voice_calibration",
+    "load_voice_calibration",
+    "InflectSynthError",
+    "EmptyTextError",
+    "InvalidSpeedError",
+    "InvalidVariationError",
+    "InvalidSeedError",
+    "InvalidVoiceError",
+    "InvalidSynthesisConfigError",
+    "UnsupportedModelError",
+    "OnnxVoiceContractError",
+    "ModelInferenceError",
+    "CatalogDiscoveryError",
+    "CatalogUnavailableError",
+    # Transitional prototype aliases, not part of the v0.1.0 request contract.
+    "list_models",
+    "ModelInfo",
+    "CatalogError",
+    "ModelNotFoundError",
+    "ArtifactIntegrityError",
+    "OfflineModelError",
+    "ProviderUnavailableError",
+]

inflectsynth/__main__.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+
+from .catalog import list_models
+from .voice import InflectVoice
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Synthesize speech with Inflect v2 ONNX models")
+    parser.add_argument("text", nargs="?")
+    parser.add_argument("--model", default="nano-v2")
+    parser.add_argument("--voice", default="default")
+    parser.add_argument("--speed", type=float, default=1.0)
+    parser.add_argument("--variation", type=float, default=0.667)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument("--provider", default="cpu")
+    parser.add_argument("--cache-dir")
+    parser.add_argument("--catalog-url")
+    parser.add_argument("--offline", action="store_true")
+    parser.add_argument("--force-download", action="store_true")
+    parser.add_argument("--list-models", action="store_true")
+    parser.add_argument("-o", "--output", default="inflect.wav")
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    if args.list_models:
+        for model in list_models(catalog_url=args.catalog_url):
+            print(f"{model.id}\t{model.name}\tvoices={','.join(v.id for v in model.voices)}")
+        return 0
+    if not args.text:
+        raise SystemExit("text is required unless --list-models is used")
+    with InflectVoice.from_pretrained(
+        args.model,
+        cache_dir=args.cache_dir,
+        catalog_url=args.catalog_url,
+        offline=args.offline,
+        force_download=args.force_download,
+        providers=args.provider,
+    ) as engine:
+        result = engine.synthesize(
+            args.text,
+            voice=args.voice,
+            speed=args.speed,
+            variation=args.variation,
+            seed=args.seed,
+        )
+        result.save_wav(args.output)
+    print(args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inflectsynth/_onnxvoice.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import importlib
+import os
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from .errors import (
+    CatalogDiscoveryError,
+    CatalogUnavailableError,
+    InflectSynthError,
+    OnnxVoiceContractError,
+    UnsupportedModelError,
+)
+
+DEFAULT_CATALOG_URL = (
+    "https://raw.githubusercontent.com/buchwandler/inflect-onnx-bundles/main/catalog/models.json"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedInflectModel:
+    ref: str | None
+    model_id: str
+    duration_path: Path
+    decode_path: Path
+    sample_rate: int
+    metadata: dict[str, Any]
+    installation: Any
+
+
+def normalize_ref(value: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise OnnxVoiceContractError("Inflect model reference must not be empty")
+    return value if ":" in value else f"inflect:{value}"
+
+
+def _module() -> ModuleType:
+    """Import ONNXVoice only when an operation needs its managed runtime."""
+    try:
+        module = importlib.import_module("onnxvoice")
+    except Exception as exc:
+        raise OnnxVoiceContractError(
+            "ONNXVoice with the Inflect adapter is required; install a compatible onnxvoice release"
+        ) from exc
+
+    manager_type = getattr(module, "OnnxVoice", None)
+    systems = getattr(module, "registered_systems", None)
+    try:
+        available_systems = systems() if callable(systems) else ()
+    except Exception as exc:
+        raise OnnxVoiceContractError("Could not inspect the ONNXVoice adapter registry") from exc
+    if manager_type is None or "inflect" not in available_systems:
+        raise OnnxVoiceContractError(
+            "Installed ONNXVoice does not expose the required Inflect adapter contract"
+        )
+    return module
+
+
+def _manager(
+    *,
+    cache_dir: str | Path | None,
+    offline: bool,
+    catalog_url: str | None,
+) -> Any:
+    module = _module()
+    source = catalog_url or os.environ.get("INFLECTSYNTH_CATALOG_URL") or DEFAULT_CATALOG_URL
+    try:
+        return module.OnnxVoice(
+            cache_dir=cache_dir,
+            catalog_sources={"inflect": source},
+            offline=offline,
+        )
+    except TypeError as exc:
+        raise OnnxVoiceContractError(
+            "Installed ONNXVoice does not support the Inflect catalog_sources manager contract"
+        ) from exc
+
+
+def _translate_onnxvoice_error(exc: Exception, operation: str) -> Exception:
+    """Translate ONNXVoice's public error families to stable InflectSynth errors."""
+    try:
+        errors = importlib.import_module("onnxvoice.errors")
+    except Exception:
+        return OnnxVoiceContractError(f"ONNXVoice {operation} operation failed")
+
+    def is_error(name: str) -> bool:
+        error_type = getattr(errors, name, None)
+        return isinstance(error_type, type) and isinstance(exc, error_type)
+
+    message = f"ONNXVoice {operation} operation failed: {exc}"
+    if is_error("OfflineError"):
+        return CatalogUnavailableError(message)
+    if is_error("CatalogError"):
+        return CatalogDiscoveryError(message)
+    if is_error("AssetNotFoundError") or is_error("IntegrityError"):
+        return UnsupportedModelError(message)
+    if is_error("AssetDownloadError"):
+        return UnsupportedModelError(message)
+    if is_error("RuntimeContractError") or is_error("OptionalDependencyError"):
+        return OnnxVoiceContractError(message)
+    if is_error("UnsupportedSystemError"):
+        return UnsupportedModelError(message)
+    if operation == "catalog":
+        return CatalogUnavailableError(message)
+    if operation == "install":
+        return UnsupportedModelError(message)
+    return OnnxVoiceContractError(message)
+
+
+def installation_to_model(installation: Any) -> ResolvedInflectModel:
+    """Validate the public ONNXVoice installation shape required by InflectSynth."""
+    if getattr(installation, "system", None) != "inflect":
+        raise OnnxVoiceContractError("ONNXVoice installation system must be 'inflect'")
+    require_artifact = getattr(installation, "require_artifact", None)
+    if not callable(require_artifact):
+        raise OnnxVoiceContractError("ONNXVoice installation must support require_artifact(role)")
+    try:
+        duration = require_artifact("duration")
+        decode = require_artifact("decode")
+    except (KeyError, TypeError, ValueError) as exc:
+        raise OnnxVoiceContractError(
+            "ONNXVoice Inflect installation must contain duration and decode artifacts"
+        ) from exc
+
+    try:
+        duration_path = Path(duration.path)
+        decode_path = Path(decode.path)
+        metadata_value = installation.metadata
+        metadata = dict(metadata_value) if isinstance(metadata_value, Mapping) else {}
+        model_id = installation.id
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise OnnxVoiceContractError("ONNXVoice returned an invalid Inflect installation") from exc
+    if not isinstance(model_id, str) or not model_id:
+        raise OnnxVoiceContractError("ONNXVoice Inflect installation must have a model id")
+
+    sample_rate = getattr(installation, "sample_rate", None)
+    if sample_rate is None:
+        sample_rate = metadata.get("sample_rate")
+    if sample_rate is None:
+        sample_rate = 24_000
+    if isinstance(sample_rate, bool) or not isinstance(sample_rate, int) or sample_rate <= 0:
+        raise OnnxVoiceContractError("ONNXVoice Inflect sample rate must be a positive integer")
+
+    metadata.setdefault("id", model_id)
+    metadata.setdefault("sample_rate", sample_rate)
+    metadata.setdefault("default_voice", getattr(installation, "default_voice", None) or "default")
+    if "voices" not in metadata:
+        voice_details = metadata.get("voice_details")
+        if isinstance(voice_details, Mapping):
+            metadata["voices"] = {key: dict(value) for key, value in voice_details.items()}
+
+    ref_value = getattr(installation, "ref", None)
+    ref = ref_value if isinstance(ref_value, str) else normalize_ref(model_id)
+    return ResolvedInflectModel(
+        ref=ref,
+        model_id=model_id,
+        duration_path=duration_path,
+        decode_path=decode_path,
+        sample_rate=sample_rate,
+        metadata=metadata,
+        installation=installation,
+    )
+
+
+def install_pretrained_model(
+    model: str,
+    *,
+    cache_dir: str | Path | None = None,
+    offline: bool = False,
+    refresh_catalog: bool = False,
+    force_download: bool = False,
+    catalog_url: str | None = None,
+    progress: Any | None = None,
+) -> ResolvedInflectModel:
+    manager = _manager(cache_dir=cache_dir, offline=offline, catalog_url=catalog_url)
+    ref = normalize_ref(model)
+    try:
+        installation = manager.install(
+            ref,
+            refresh=refresh_catalog,
+            force=force_download,
+            progress=progress,
+        )
+    except TypeError as exc:
+        raise OnnxVoiceContractError(
+            "Installed ONNXVoice does not support the Inflect install contract"
+        ) from exc
+    except InflectSynthError:
+        raise
+    except Exception as exc:
+        raise _translate_onnxvoice_error(exc, "install") from exc
+    return installation_to_model(installation)
+
+
+def open_installed_model(
+    model: ResolvedInflectModel,
+    *,
+    cache_dir: str | Path | None = None,
+    offline: bool = False,
+    catalog_url: str | None = None,
+    providers: Sequence[Any] | str | None = None,
+    provider_options: Sequence[dict[str, Any]] | dict[str, dict[str, Any]] | None = None,
+    session_options: Any | None = None,
+) -> Any:
+    manager = _manager(cache_dir=cache_dir, offline=offline, catalog_url=catalog_url)
+    try:
+        return manager.open(
+            model.installation,
+            providers=providers,
+            provider_options=provider_options,
+            session_options=session_options,
+        )
+    except TypeError as exc:
+        raise OnnxVoiceContractError(
+            "Installed ONNXVoice does not support provider/session options for Inflect models"
+        ) from exc
+    except InflectSynthError:
+        raise
+    except Exception as exc:
+        raise _translate_onnxvoice_error(exc, "open") from exc
+
+
+def open_local_model(
+    *,
+    duration_path: str | Path,
+    decode_path: str | Path,
+    sample_rate: int = 24_000,
+    metadata: Mapping[str, Any] | None = None,
+    providers: Sequence[Any] | str | None = None,
+    provider_options: Sequence[dict[str, Any]] | dict[str, dict[str, Any]] | None = None,
+    session_options: Any | None = None,
+) -> Any:
+    module = _module()
+    try:
+        return module.OnnxVoice.open_local(
+            system="inflect",
+            artifacts={"duration": duration_path, "decode": decode_path},
+            sample_rate=sample_rate,
+            metadata=dict(metadata or {}),
+            providers=providers,
+            provider_options=provider_options,
+            session_options=session_options,
+        )
+    except TypeError as exc:
+        raise OnnxVoiceContractError(
+            "Installed ONNXVoice does not support local Inflect split-artifact opening"
+        ) from exc
+    except InflectSynthError:
+        raise
+    except Exception as exc:
+        raise _translate_onnxvoice_error(exc, "open_local") from exc
+
+
+def catalog_items(
+    *,
+    language: str | None = None,
+    offline: bool = False,
+    refresh: bool = False,
+    cache_dir: str | Path | None = None,
+    catalog_url: str | None = None,
+) -> tuple[Any, ...]:
+    """Return catalog records only; never install or open model artifacts."""
+    manager = _manager(cache_dir=cache_dir, offline=offline, catalog_url=catalog_url)
+    try:
+        return tuple(manager.list("inflect", language=language, refresh=refresh))
+    except TypeError as exc:
+        raise OnnxVoiceContractError(
+            "Installed ONNXVoice does not support Inflect catalog discovery"
+        ) from exc
+    except InflectSynthError:
+        raise
+    except Exception as exc:
+        raise _translate_onnxvoice_error(exc, "catalog") from exc
+
+
+def catalog_voices(
+    *,
+    language: str | None = None,
+    offline: bool = False,
+    refresh: bool = False,
+    cache_dir: str | Path | None = None,
+    catalog_url: str | None = None,
+) -> tuple[Any, ...]:
+    manager = _manager(cache_dir=cache_dir, offline=offline, catalog_url=catalog_url)
+    try:
+        return tuple(manager.list_voices("inflect", language=language, refresh=refresh))
+    except TypeError as exc:
+        raise OnnxVoiceContractError(
+            "Installed ONNXVoice does not support Inflect voice discovery"
+        ) from exc
+    except InflectSynthError:
+        raise
+    except Exception as exc:
+        raise _translate_onnxvoice_error(exc, "catalog") from exc

inflectsynth/api_contract.py

@@ -0,0 +1,29 @@
+"""Versioned, dependency-light declaration of the Readio request contract."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+REQUEST_API_VERSION = 1
+
+_REQUEST_API_CONTRACT: Mapping[str, str | bool] = MappingProxyType(
+    {
+        "entrypoint": "InflectVoice.synthesize_prepared",
+        "supports_linguistic_tokens": False,
+        "supports_pronunciation_overrides": False,
+        "supports_whole_request_phonemes": False,
+        "supports_speakers": False,
+        "supports_word_timings": False,
+        "supports_voice_level": True,
+        "caller_owns_text_boundaries": True,
+    }
+)
+
+
+def request_api_contract() -> Mapping[str, str | bool]:
+    """Return an immutable declaration without catalog or model access."""
+    return _REQUEST_API_CONTRACT
+
+
+__all__ = ["REQUEST_API_VERSION", "request_api_contract"]

inflectsynth/catalog.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ._onnxvoice import catalog_items, catalog_voices
+from .types import ModelInfo, VoiceInfo
+
+
+def list_models(
+    *,
+    language: str | None = None,
+    offline: bool = False,
+    refresh: bool = False,
+    cache_dir: str | Path | None = None,
+    catalog_url: str | None = None,
+) -> tuple[ModelInfo, ...]:
+    """Compatibility discovery adapter backed exclusively by ONNXVoice."""
+    items = catalog_items(
+        language=language,
+        offline=offline,
+        refresh=refresh,
+        cache_dir=cache_dir,
+        catalog_url=catalog_url,
+    )
+    voices = catalog_voices(
+        language=language,
+        offline=offline,
+        refresh=refresh,
+        cache_dir=cache_dir,
+        catalog_url=catalog_url,
+    )
+    voices_by_model: dict[str, list[Any]] = {}
+    for record in voices:
+        voices_by_model.setdefault(record.asset_id, []).append(record)
+
+    models: list[ModelInfo] = []
+    for item in items:
+        metadata = item.metadata if isinstance(item.metadata, dict) else {}
+        upstream = metadata.get("upstream")
+        upstream = upstream if isinstance(upstream, dict) else {}
+        voice_details = metadata.get("voice_details")
+        voice_details = voice_details if isinstance(voice_details, dict) else {}
+        model_voices = tuple(
+            VoiceInfo(
+                id=record.voice_id,
+                name=str(voice_details.get(record.voice_id, {}).get("name", record.voice_id)),
+                language=record.metadata.locale,
+                gender=record.gender,
+                synthetic=bool(voice_details.get(record.voice_id, {}).get("synthetic", True)),
+            )
+            for record in voices_by_model.get(item.id, [])
+        )
+        models.append(
+            ModelInfo(
+                id=item.id,
+                name=str(metadata.get("name", item.id)),
+                aliases=tuple(item.aliases),
+                language=str(metadata.get("language", "en-US")),
+                sample_rate=int(item.sample_rate or 24_000),
+                default_voice=item.default_voice or "default",
+                voices=model_voices,
+                revision=str(
+                    metadata.get("source_revision")
+                    or upstream.get("source_revision")
+                    or upstream.get("revision")
+                    or ""
+                ),
+            )
+        )
+    return tuple(models)

inflectsynth/config.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from numbers import Real
+
+from .errors import (
+    InvalidSeedError,
+    InvalidSpeedError,
+    InvalidSynthesisConfigError,
+    InvalidVariationError,
+)
+from .voice_level import VoiceLevelConfig
+
+
+@dataclass(frozen=True, slots=True)
+class SynthesisConfig:
+    speed: float = 1.0
+    variation: float = 0.667
+    seed: int = 0
+    voice_level: VoiceLevelConfig = field(default_factory=VoiceLevelConfig)
+
+    def validated(self) -> SynthesisConfig:
+        speed = _finite_control(self.speed, "speed", InvalidSpeedError)
+        if not 0.5 <= speed <= 2.0:
+            raise InvalidSpeedError("speed must be between 0.5 and 2.0")
+        variation = _finite_control(self.variation, "variation", InvalidVariationError)
+        if not 0.0 <= variation <= 1.0:
+            raise InvalidVariationError("variation must be between 0.0 and 1.0")
+        if isinstance(self.seed, bool) or not isinstance(self.seed, int) or self.seed < 0:
+            raise InvalidSeedError("seed must be a non-negative integer")
+        if not isinstance(self.voice_level, VoiceLevelConfig):
+            raise InvalidSynthesisConfigError("voice_level must be a VoiceLevelConfig")
+        return SynthesisConfig(
+            speed=speed,
+            variation=variation,
+            seed=self.seed,
+            voice_level=self.voice_level,
+        )
+
+
+def _finite_control(
+    value: object,
+    name: str,
+    error_type: type[InvalidSynthesisConfigError],
+) -> float:
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise error_type(f"{name} must be a finite real number")
+    try:
+        number = float(value)
+    except (OverflowError, ValueError):
+        raise error_type(f"{name} must be a finite real number") from None
+    if not math.isfinite(number):
+        raise error_type(f"{name} must be finite")
+    return number

inflectsynth/data/voice_level_calibration.json

@@ -0,0 +1,32 @@
+{
+  "corpus": "inflectsynth-prepared-speech-v1",
+  "generated_with": {
+    "audiosig": "0.1.6",
+    "inflectg2p": "0.1.0",
+    "inflectsynth": "0.1.dev2+gaed518a21",
+    "onnxvoice": "0.2.5"
+  },
+  "method": "bs1770",
+  "reference_lufs": -24.0,
+  "schema": 1,
+  "voices": {
+    "inflect:micro-v2:default": {
+      "corpus_version": "inflectsynth-prepared-speech-v1",
+      "gain_db": -0.3353773192815517,
+      "mad_lu": 0.28835105130528405,
+      "measured_lufs": -23.66462268071845,
+      "method": "bs1770",
+      "reference_lufs": -24.0,
+      "samples": 9
+    },
+    "inflect:nano-v2:default": {
+      "corpus_version": "inflectsynth-prepared-speech-v1",
+      "gain_db": -0.042377569773361046,
+      "mad_lu": 0.2913390390127759,
+      "measured_lufs": -23.95762243022664,
+      "method": "bs1770",
+      "reference_lufs": -24.0,
+      "samples": 9
+    }
+  }
+}