pipersynth 0.1.1__py3-none-any.whl

pipersynth/__init__.py

@@ -0,0 +1,120 @@
+"""Independent synthesis runtime for Piper-compatible ONNX voice models."""
+
+from piperg2p import VoiceConfig
+from utterplan import (
+    LinguisticsConfig,
+    PauseConfig,
+    PlannerConfig,
+    SSMDConfig,
+    UtterancePlan,
+    UtterancePlanner,
+)
+
+try:
+    from ._version import __version__, __version_tuple__
+except ImportError:
+    __version__ = "0.1.1"
+    __version_tuple__ = (0, 1, 1)
+from .asset_manager import CacheInfo, VoiceAssetManager, list_cached_voices, list_voices
+from .asset_progress import AssetProgressCallback, AssetProgressEvent, ConsoleAssetProgress
+from .assets import VoiceBundle, VoiceMetadata, load_catalog_voice
+from .config import GenerationConfig, PipelineConfig
+from .convenience import synthesize, synthesize_to_wav
+from .diagnostics import RuntimeDiagnostics, TimingDiagnostics
+from .errors import (
+    AssetCacheError,
+    AssetDownloadError,
+    AssetError,
+    CatalogUnavailableError,
+    ConfigFileNotFoundError,
+    InvalidSpeakerError,
+    InvalidSynthesisConfigError,
+    ModelFileNotFoundError,
+    ModelInferenceError,
+    ModelLoadError,
+    OfflineAssetError,
+    OptionalDependencyError,
+    PiperSynthError,
+    PlanRenderingError,
+    PlanSampleRateMismatchError,
+    SessionCreationError,
+    SynthesisError,
+    TextPreparationError,
+    UnsupportedModelError,
+    UnsupportedPlanDirectiveError,
+    UnsupportedPlanLanguageError,
+    VoiceBindingError,
+    VoiceClosedError,
+    VoiceNotFoundError,
+)
+from .pipeline import PiperPipeline, PreparedAudioUnits, build_pipeline
+from .preparation import IdentityTextPreparer, PreparedTextResult, SpokenformTextPreparer
+from .session import ProviderConfig, available_providers
+from .types import AudioChunk, AudioResult, AudioUnitDescriptor, AudioUnitResult, SynthesisConfig
+from .voice import PiperVoice
+
+__all__ = [
+    "AudioChunk",
+    "AudioResult",
+    "AudioUnitDescriptor",
+    "AudioUnitResult",
+    "AssetCacheError",
+    "AssetDownloadError",
+    "AssetError",
+    "AssetProgressCallback",
+    "AssetProgressEvent",
+    "GenerationConfig",
+    "LinguisticsConfig",
+    "PauseConfig",
+    "PlannerConfig",
+    "SSMDConfig",
+    "UtterancePlan",
+    "UtterancePlanner",
+    "CacheInfo",
+    "VoiceAssetManager",
+    "CatalogUnavailableError",
+    "ConsoleAssetProgress",
+    "IdentityTextPreparer",
+    "PiperPipeline",
+    "PiperSynthError",
+    "PlanRenderingError",
+    "PlanSampleRateMismatchError",
+    "ConfigFileNotFoundError",
+    "InvalidSpeakerError",
+    "InvalidSynthesisConfigError",
+    "ModelFileNotFoundError",
+    "ModelInferenceError",
+    "ModelLoadError",
+    "OptionalDependencyError",
+    "OfflineAssetError",
+    "PiperVoice",
+    "PipelineConfig",
+    "PreparedAudioUnits",
+    "PreparedTextResult",
+    "ProviderConfig",
+    "RuntimeDiagnostics",
+    "SessionCreationError",
+    "SynthesisError",
+    "TextPreparationError",
+    "TimingDiagnostics",
+    "UnsupportedModelError",
+    "UnsupportedPlanDirectiveError",
+    "UnsupportedPlanLanguageError",
+    "VoiceBindingError",
+    "VoiceClosedError",
+    "SpokenformTextPreparer",
+    "SynthesisConfig",
+    "VoiceBundle",
+    "VoiceConfig",
+    "VoiceMetadata",
+    "VoiceNotFoundError",
+    "available_providers",
+    "build_pipeline",
+    "list_cached_voices",
+    "load_catalog_voice",
+    "list_voices",
+    "synthesize",
+    "synthesize_to_wav",
+    "__version__",
+    "__version_tuple__",
+]

pipersynth/__main__.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from .asset_manager import VoiceAssetManager
+from .config import GenerationConfig, PipelineConfig
+from .convenience import synthesize_to_wav
+from .pipeline import PiperPipeline
+
+
+def _speaker(value: str) -> int | str:
+    try:
+        return int(value)
+    except ValueError:
+        return value
+
+
+def _legacy_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Synthesize speech with a Piper-compatible ONNX voice without the Piper runtime"
+    )
+    parser.add_argument("model", help="Path to .onnx voice model")
+    parser.add_argument("text", help="Text to synthesize")
+    parser.add_argument("-o", "--output", default="output.wav")
+    parser.add_argument("--config", default=None, help="Path to .onnx.json config")
+    parser.add_argument("--speaker", type=_speaker, default=None)
+    parser.add_argument("--length-scale", type=float, default=None)
+    parser.add_argument("--noise-scale", type=float, default=None)
+    parser.add_argument("--noise-w-scale", type=float, default=None)
+    parser.add_argument("--noise-w", type=float, default=None, help="Deprecated noise width alias")
+    parser.add_argument("--sentence-silence", type=float, default=0.0)
+    parser.add_argument("--volume", type=float, default=1.0)
+    parser.add_argument(
+        "--provider", action="append", default=None, help="ONNX provider; repeat for priority"
+    )
+    parser.add_argument(
+        "--language", default=None, help="Language for optional written-text preparation"
+    )
+    preparation = parser.add_mutually_exclusive_group()
+    preparation.add_argument(
+        "--prepare-text", action="store_true", help="Use spokenform preparation"
+    )
+    preparation.add_argument(
+        "--no-prepare-text", action="store_true", help="Use identity preparation"
+    )
+    parser.add_argument("--no-normalize", action="store_true")
+    return parser
+
+
+def _add_managed_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--cache-dir", default=None)
+    parser.add_argument("--offline", action="store_true")
+    parser.add_argument("--refresh-catalog", action="store_true")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Synthesize speech with PiperSynth catalog voices")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    voices = commands.add_parser("voices")
+    voice_commands = voices.add_subparsers(dest="voice_command", required=True)
+    listing = voice_commands.add_parser("list")
+    _add_managed_options(listing)
+    listing.add_argument("--language")
+    listing.add_argument("--quality")
+    show = voice_commands.add_parser("show")
+    _add_managed_options(show)
+    show.add_argument("voice")
+    for name in ("download", "path", "remove", "license"):
+        command = voice_commands.add_parser(name)
+        _add_managed_options(command)
+        command.add_argument("voice")
+    download = voice_commands.choices["download"]
+    download.add_argument("--force-download", action="store_true")
+
+    speak = commands.add_parser("speak")
+    _add_managed_options(speak)
+    speak.add_argument("--voice", required=True)
+    speak.add_argument("text")
+    speak.add_argument("-o", "--output", default="output.wav")
+    speak.add_argument("--speaker", type=_speaker, default=None)
+    speak.add_argument("--length-scale", type=float, default=None)
+    speak.add_argument("--noise-scale", type=float, default=None)
+    speak.add_argument("--noise-w-scale", type=float, default=None)
+    speak.add_argument("--sentence-silence", type=float, default=0.0)
+    speak.add_argument("--volume", type=float, default=1.0)
+    speak.add_argument("--provider", action="append", default=None)
+    speak.add_argument("--prepare-text", action="store_true")
+    speak.add_argument("--language", default=None)
+    speak.add_argument("--no-normalize", action="store_true")
+    speak.add_argument("--force-download", action="store_true")
+
+    cache = commands.add_parser("cache")
+    cache_commands = cache.add_subparsers(dest="cache_command", required=True)
+    for name in ("info", "list", "prune", "clear"):
+        command = cache_commands.add_parser(name)
+        command.add_argument("--cache-dir", default=None)
+    cache_commands.choices["clear"].add_argument("--voices", action="store_true")
+    return parser
+
+
+def _run_legacy(args: argparse.Namespace) -> None:
+    noise_w_scale = args.noise_w_scale
+    if args.noise_w is not None:
+        if noise_w_scale is not None:
+            raise ValueError("--noise-w and --noise-w-scale cannot both be set")
+        noise_w_scale = args.noise_w
+    generation = GenerationConfig(
+        speaker=args.speaker,
+        length_scale=args.length_scale,
+        noise_scale=args.noise_scale,
+        noise_w_scale=noise_w_scale,
+        normalize_audio=not args.no_normalize,
+        volume=args.volume,
+        sentence_silence=args.sentence_silence,
+    )
+    config = PipelineConfig(
+        model_path=args.model,
+        config_path=args.config,
+        generation=generation,
+        providers=tuple(args.provider) if args.provider is not None else None,
+        text_preparation="spokenform" if args.prepare_text else "identity",
+        language=args.language,
+    )
+    with PiperPipeline(config) as pipeline:
+        pipeline.run(args.text).save_wav(args.output)
+    print(args.output)
+
+
+def _run_managed(args: argparse.Namespace) -> None:
+    offline = True if args.offline else None
+    manager = VoiceAssetManager(args.cache_dir, offline=offline)
+    if args.command == "voices":
+        if args.voice_command == "list":
+            for voice in manager.list_voices(
+                language=args.language, quality=args.quality, refresh=args.refresh_catalog
+            ):
+                print(f"{voice.id}\t{voice.name}")
+        elif args.voice_command == "show":
+            voice = manager.get_voice_metadata(args.voice, refresh=args.refresh_catalog)
+            print(f"id: {voice.id}")
+            print(f"name: {voice.name}")
+            print(f"language: {voice.language_code}")
+            print(f"quality: {voice.quality}")
+            print(f"speakers: {voice.num_speakers}")
+            print(f"aliases: {', '.join(voice.aliases)}")
+        elif args.voice_command == "download":
+            bundle = manager.resolve_voice(
+                args.voice,
+                refresh_catalog=args.refresh_catalog,
+                force_download=args.force_download,
+            )
+            print(bundle.directory)
+        elif args.voice_command == "path":
+            print(manager.voice_cache_path(args.voice))
+        elif args.voice_command == "remove":
+            manager.remove_voice(args.voice)
+        elif args.voice_command == "license":
+            print(
+                manager.resolve_voice(
+                    args.voice, refresh_catalog=args.refresh_catalog
+                ).model_card_text
+            )
+        return
+    if args.command == "speak":
+        output = synthesize_to_wav(
+            args.text,
+            args.output,
+            voice=args.voice,
+            speaker=args.speaker,
+            length_scale=args.length_scale,
+            noise_scale=args.noise_scale,
+            noise_w_scale=args.noise_w_scale,
+            sentence_silence=args.sentence_silence,
+            volume=args.volume,
+            normalize_audio=not args.no_normalize,
+            providers=args.provider,
+            cache_dir=args.cache_dir,
+            offline=offline,
+            refresh_catalog=args.refresh_catalog,
+            force_download=args.force_download,
+            text_preparation="spokenform" if args.prepare_text else "identity",
+            language=args.language,
+        )
+        print(output)
+        return
+    if args.cache_command == "info":
+        info = manager.cache_info()
+        print(f"directory: {info.directory}")
+        print(f"catalog: {info.catalog_path}")
+        print(f"cached voices: {', '.join(info.cached_voices)}")
+    elif args.cache_command == "list":
+        for bundle in manager.cached_voices():
+            print(bundle.directory)
+    elif args.cache_command == "prune":
+        for path in manager.prune():
+            print(path)
+    elif args.cache_command == "clear":
+        manager.clear(voices=args.voices)
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    arguments = list(argv) if argv is not None else None
+    if arguments is None:
+        import sys
+
+        arguments = sys.argv[1:]
+    if not arguments or arguments[0] not in {"voices", "speak", "cache"}:
+        _run_legacy(_legacy_parser().parse_args(arguments))
+    else:
+        _run_managed(_build_parser().parse_args(arguments))
+
+
+if __name__ == "__main__":
+    main()

pipersynth/_onnxvoice.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+from .asset_progress import AssetProgressEvent, AssetProgressPhase
+from .errors import (
+    AssetCacheError,
+    AssetDownloadError,
+    AssetError,
+    CatalogUnavailableError,
+    ModelInferenceError,
+    OptionalDependencyError,
+    SessionCreationError,
+    UnsupportedModelError,
+    VoiceNotFoundError,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedPiperVoice:
+    """PiperSynth's read-only view of an OnnxVoice installation."""
+
+    ref: str | None
+    voice_id: str | None
+    model_path: Path
+    config_path: Path
+    model_card_path: Path | None
+    language_code: str | None
+    source_revision: str | None
+    metadata: Mapping[str, Any]
+    installation: Any | None = None
+
+
+def _onnxvoice() -> Any:
+    try:
+        import onnxvoice
+    except ModuleNotFoundError as exc:
+        raise OptionalDependencyError(
+            "OnnxVoice is required for Piper model loading. Install pipersynth[cpu] or "
+            "pipersynth[gpu]."
+        ) from exc
+    return onnxvoice
+
+
+def normalize_piper_ref(ref: str) -> str:
+    if not isinstance(ref, str) or not ref.strip():
+        raise VoiceNotFoundError("Piper voice reference must not be empty")
+    value = ref.strip()
+    if ":" not in value:
+        return f"piper:{value}"
+    system, item_id = value.split(":", 1)
+    if system.casefold() != "piper" or not item_id:
+        raise VoiceNotFoundError(f"Not a Piper voice reference: {ref!r}")
+    return f"piper:{item_id}"
+
+
+def normalize_provider_request(
+    providers: Sequence[Any] | str | None,
+    provider_options: Mapping[str, Any] | None,
+) -> tuple[str | Sequence[str] | None, Any | None]:
+    """Translate PiperSynth provider compatibility values to OnnxVoice values."""
+
+    if providers is None:
+        return "CPUExecutionProvider", provider_options
+    if isinstance(providers, str):
+        return providers, provider_options
+
+    names: list[str] = []
+    options: list[dict[str, Any]] = []
+    has_explicit_options = False
+    for provider in providers:
+        if hasattr(provider, "name"):
+            name = str(provider.name)
+            value = dict(getattr(provider, "options", {}) or {})
+            has_explicit_options = has_explicit_options or bool(value)
+        elif isinstance(provider, tuple):
+            name, raw_options = provider
+            value = dict(raw_options or {})
+            has_explicit_options = True
+        else:
+            name = str(provider)
+            value = dict(provider_options or {})
+        names.append(name)
+        options.append(value)
+    if not names:
+        raise ValueError("providers must not be empty")
+    return names, options if has_explicit_options else provider_options
+
+
+def adapt_progress(
+    callback: Callable[[AssetProgressEvent], None] | None,
+) -> Callable[[Any], None] | None:
+    if callback is None:
+        return None
+
+    def emit(event: Any) -> None:
+        phase = str(getattr(event, "phase", "asset"))
+        phase_map = {
+            "catalog_started": "catalog-refresh",
+            "catalog_cached": "catalog-load",
+            "catalog_completed": "catalog-load",
+            "install_started": "voice-resolve",
+            "install_completed": "download-complete",
+            "download_started": "download-start",
+            "download_progress": "download-start",
+            "download_completed": "download-complete",
+            "artifact_cached": "cache-hit",
+        }
+        raw_ref = getattr(event, "ref", None)
+        voice_id = (
+            raw_ref.split(":", 1)[1] if isinstance(raw_ref, str) and ":" in raw_ref else raw_ref
+        )
+        callback(
+            AssetProgressEvent(
+                cast(AssetProgressPhase, phase_map.get(phase, "voice-resolve")),
+                voice_id=voice_id,
+                message=getattr(event, "message", None),
+            )
+        )
+
+    return emit
+
+
+def _map_error(exc: Exception, *, operation: str) -> Exception:
+    name = type(exc).__name__
+    if name in {"OptionalDependencyError", "ImportError"}:
+        return OptionalDependencyError(str(exc))
+    if name in {"AssetNotFoundError", "NotInstalledError"}:
+        return VoiceNotFoundError(str(exc))
+    if name in {"OfflineError"}:
+        from .errors import OfflineAssetError
+
+        return OfflineAssetError(str(exc))
+    if name in {"IntegrityError", "ManifestError", "UnsafePathError", "LockError"}:
+        return AssetCacheError(str(exc))
+    if name in {"CatalogError"}:
+        return CatalogUnavailableError(str(exc))
+    if name in {"RuntimeContractError", "CapabilityError", "UnsupportedSystemError"}:
+        return UnsupportedModelError(str(exc))
+    if operation == "infer":
+        return ModelInferenceError("ONNX model inference failed")
+    if operation == "open":
+        return SessionCreationError("Could not open Piper ONNX runtime")
+    return AssetDownloadError(str(exc)) if operation == "install" else AssetError(str(exc))
+
+
+def _call(operation: str, function: Callable[[], Any]) -> Any:
+    try:
+        return function()
+    except (FileNotFoundError, ValueError, TypeError):
+        raise
+    except Exception as exc:
+        mapped = _map_error(exc, operation=operation)
+        raise mapped from exc
+
+
+def open_local_voice(
+    model_path: str | Path,
+    config_path: str | Path,
+    *,
+    providers: Sequence[Any] | str | None = None,
+    provider_options: Mapping[str, Any] | None = None,
+    session_options: Any | None = None,
+) -> Any:
+    requested, options = normalize_provider_request(providers, provider_options)
+    module = _onnxvoice()
+    return _call(
+        "open",
+        lambda: module.open_local(
+            system="piper",
+            model=model_path,
+            config=config_path,
+            providers=requested,
+            provider_options=options,
+            session_options=session_options,
+        ),
+    )
+
+
+def install_pretrained_voice(
+    ref: str,
+    *,
+    cache_dir: str | Path | None = None,
+    offline: bool | None = None,
+    refresh_catalog: bool = False,
+    force_download: bool = False,
+    progress: Callable[[AssetProgressEvent], None] | None = None,
+) -> ResolvedPiperVoice:
+    normalized = normalize_piper_ref(ref)
+    module = _onnxvoice()
+    manager = module.OnnxVoice(cache_dir=cache_dir, offline=bool(offline))
+    installation = _call(
+        "install",
+        lambda: manager.install(
+            normalized,
+            refresh=refresh_catalog,
+            force=force_download,
+            progress=adapt_progress(progress),
+        ),
+    )
+    return installation_to_voice_info(installation, ref=normalized)
+
+
+def open_installed_voice(
+    resolved: ResolvedPiperVoice,
+    *,
+    providers: Sequence[Any] | str | None = None,
+    provider_options: Mapping[str, Any] | None = None,
+    session_options: Any | None = None,
+) -> Any:
+    requested, options = normalize_provider_request(providers, provider_options)
+    module = _onnxvoice()
+    manager = module.OnnxVoice()
+    return _call(
+        "open",
+        lambda: manager.open(
+            resolved.installation,
+            providers=requested,
+            provider_options=options,
+            session_options=session_options,
+        ),
+    )
+
+
+def installation_to_voice_info(installation: Any, *, ref: str | None = None) -> ResolvedPiperVoice:
+    try:
+        model = installation.artifact("model").path
+        config = installation.artifact("config").path
+    except (KeyError, AttributeError) as exc:
+        raise UnsupportedModelError(
+            "Piper installation must contain model and config artifacts"
+        ) from exc
+    try:
+        model_card = installation.artifact("model_card").path
+    except KeyError:
+        model_card = None
+    raw_metadata = dict(getattr(installation, "metadata", {}) or {})
+    language = raw_metadata.get("language") or {}
+    language_code = language.get("code") if isinstance(language, Mapping) else None
+    return ResolvedPiperVoice(
+        ref=ref or getattr(installation, "ref", None),
+        voice_id=getattr(installation, "id", None),
+        model_path=Path(model),
+        config_path=Path(config),
+        model_card_path=Path(model_card) if model_card is not None else None,
+        language_code=str(language_code) if language_code is not None else None,
+        source_revision=(
+            str(raw_metadata["source_revision"])
+            if raw_metadata.get("source_revision") is not None
+            else None
+        ),
+        metadata=raw_metadata,
+        installation=installation,
+    )
+
+
+def runtime_diagnostics(runtime: Any) -> dict[str, Any]:
+    installation = getattr(runtime, "installation", None)
+    model_path = None
+    config_path = None
+    if installation is not None:
+        try:
+            model_path = str(installation.artifact("model").path)
+        except (KeyError, AttributeError):
+            pass
+        try:
+            config_path = str(installation.artifact("config").path)
+        except (KeyError, AttributeError):
+            pass
+    session = getattr(runtime, "session", None)
+    return {
+        "model_path": model_path,
+        "config_path": config_path,
+        "providers_requested": tuple(getattr(session, "provider_request", ()) or ()),
+        "providers_active": tuple(getattr(session, "resolved_providers", ()) or ()),
+        "model_inputs": tuple(getattr(session, "input_names", ()) or ()),
+        "model_outputs": tuple(getattr(session, "output_names", ()) or ()),
+    }
+
+
+def summarize_array(value: Any) -> dict[str, Any]:
+    import numpy as np
+
+    array = np.asarray(value)
+    return {"shape": [int(size) for size in array.shape], "dtype": str(array.dtype)}
+
+
+def summarize_inference(result: Any) -> tuple[dict[str, Any] | None, dict[str, Any]]:
+    timing = getattr(result, "timings", None)
+    timings = summarize_array(timing) if timing is not None else None
+    outputs = {
+        str(name): summarize_array(value)
+        for name, value in dict(getattr(result, "outputs", {}) or {}).items()
+    }
+    return timings, outputs
+
+
+def available_providers() -> tuple[str, ...]:
+    return tuple(_call("open", lambda: _onnxvoice().available_providers()))
+
+
+__all__ = [
+    "ResolvedPiperVoice",
+    "adapt_progress",
+    "available_providers",
+    "installation_to_voice_info",
+    "install_pretrained_voice",
+    "normalize_piper_ref",
+    "normalize_provider_request",
+    "open_installed_voice",
+    "open_local_voice",
+    "runtime_diagnostics",
+    "summarize_inference",
+]

pipersynth/_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 = 'g5927e1531'