mimic-tts 0.0.1__tar.gz

mimic_tts-0.0.1/.gitignore

@@ -0,0 +1,32 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Voice reference samples (personal data — don't commit recordings)
+server/reference/*
+!server/reference/.gitkeep
+reference/*
+!reference/.gitkeep
+
+# Build artifacts
+dist/
+*.egg-info/
+
+# Local secrets / env
+.env
+.env.local
+
+# IDE / OS junk
+.DS_Store
+.idea/
+.vscode/
+
+# Audio recordings outside the reference dir
+/*.wav

mimic_tts-0.0.1/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: mimic-tts
+Version: 0.0.1
+Summary: Client for mimic-tts (Qwen3-TTS voice cloning + synthesis)
+Author: Jim Vogel
+License: MIT
+Requires-Python: <3.14,>=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=1.26
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: sounddevice>=0.4
+Requires-Dist: soundfile>=0.12
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# mimic-tts
+
+Python client and CLI for the [mimic-tts](https://github.com/voglster/mimic-tts) server.
+
+```bash
+pip install mimic-tts
+```
+
+Full documentation: <https://github.com/voglster/mimic-tts>

mimic_tts-0.0.1/README.md

@@ -0,0 +1,9 @@
+# mimic-tts
+
+Python client and CLI for the [mimic-tts](https://github.com/voglster/mimic-tts) server.
+
+```bash
+pip install mimic-tts
+```
+
+Full documentation: <https://github.com/voglster/mimic-tts>

mimic_tts-0.0.1/mimic/__init__.py

@@ -0,0 +1,7 @@
+"""mimic-tts — Python client for the mimic-tts server."""
+
+from mimic._version import __version__
+from mimic.async_client import AsyncClient
+from mimic.client import Client
+
+__all__ = ["AsyncClient", "Client", "__version__"]

mimic_tts-0.0.1/mimic/_base.py

@@ -0,0 +1,66 @@
+"""Shared request-building and error-translation logic."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import httpx
+
+from mimic.errors import (
+    MimicAPIError,
+    MimicAuthError,
+    MimicNotFoundError,
+    MimicValidationError,
+)
+
+
+@dataclass
+class RequestSpec:
+    method: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    data: dict[str, Any] | None = None
+    files: dict[str, Any] | None = None
+
+
+def build_request_spec(
+    *,
+    base_url: str,
+    method: str,
+    path: str,
+    token: str | None,
+    data: dict[str, Any] | None = None,
+    files: dict[str, Any] | None = None,
+) -> RequestSpec:
+    if not path.startswith("/"):
+        raise ValueError(f"path must start with '/': {path!r}")
+    url = base_url.rstrip("/") + path
+    headers: dict[str, str] = {}
+    if token is not None:
+        headers["Authorization"] = f"Bearer {token}"
+    return RequestSpec(method=method, url=url, headers=headers, data=data, files=files)
+
+
+def _extract_detail(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+        if isinstance(body, dict) and "detail" in body:
+            return str(body["detail"])
+    except Exception:  # noqa: S110
+        pass
+    return response.text or response.reason_phrase or ""
+
+
+def raise_for_response(response: httpx.Response) -> None:
+    if response.status_code < 400:
+        return
+    detail = _extract_detail(response)
+    if response.status_code == 401:
+        raise MimicAuthError(response.status_code, detail)
+    if response.status_code == 404:
+        raise MimicNotFoundError(response.status_code, detail)
+    if 400 <= response.status_code < 500:
+        raise MimicValidationError(response.status_code, detail)
+    raise MimicAPIError(response.status_code, detail)

mimic_tts-0.0.1/mimic/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

mimic_tts-0.0.1/mimic/async_client.py

@@ -0,0 +1,147 @@
+"""Asynchronous client for the mimic-tts server."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import httpx
+
+if TYPE_CHECKING:
+    from io import BufferedReader
+
+from mimic._base import build_request_spec, raise_for_response
+from mimic.client import _as_upload
+
+
+class AsyncClient:
+    """Async client. Use as `async with AsyncClient(...) as c:`."""
+
+    def __init__(
+        self,
+        server_url: str | None = None,
+        token: str | None = None,
+        timeout: float = 60.0,
+        transport: httpx.AsyncBaseTransport | httpx.BaseTransport | None = None,
+    ) -> None:
+        self._base_url = server_url or os.environ.get("MIMIC_SERVER_URL") or "http://localhost:8000"
+        self._token = token if token is not None else os.environ.get("MIMIC_API_TOKEN")
+        self._http = httpx.AsyncClient(timeout=timeout, transport=transport)  # type: ignore[arg-type]
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def _request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        spec = build_request_spec(
+            base_url=self._base_url,
+            method=method,
+            path=path,
+            token=self._token,
+            **kwargs,
+        )
+        r = await self._http.request(
+            spec.method,
+            spec.url,
+            headers=spec.headers,
+            data=spec.data,
+            files=spec.files,
+        )
+        raise_for_response(r)
+        return r.json()
+
+    async def _request_audio(self, method: str, path: str, **kwargs: Any) -> bytes:
+        spec = build_request_spec(
+            base_url=self._base_url,
+            method=method,
+            path=path,
+            token=self._token,
+            **kwargs,
+        )
+        r = await self._http.request(
+            spec.method,
+            spec.url,
+            headers=spec.headers,
+            data=spec.data,
+            files=spec.files,
+        )
+        raise_for_response(r)
+        return r.content
+
+    async def health(self) -> dict[str, Any]:
+        return await self._request_json("GET", "/health")
+
+    async def list_voices(self) -> list[dict[str, str]]:
+        return (await self._request_json("GET", "/voices"))["voices"]
+
+    async def list_clones(self) -> list[str]:
+        return (await self._request_json("GET", "/clone/voices"))["voices"]
+
+    async def tts(
+        self,
+        text: str,
+        *,
+        language: str = "English",
+        speaker: str = "Ryan",
+        instruct: str = "",
+    ) -> bytes:
+        return await self._request_audio(
+            "POST",
+            "/tts",
+            data={"text": text, "language": language, "speaker": speaker, "instruct": instruct},
+        )
+
+    async def tts_to_file(self, text: str, out: Path | str, **kwargs: Any) -> Path:
+        audio = await self.tts(text, **kwargs)
+        out_path = Path(out)
+        out_path.write_bytes(audio)
+        return out_path
+
+    async def clone_register(
+        self,
+        name: str,
+        audio: Path | str | bytes | BufferedReader,
+        transcript: str,
+    ) -> dict[str, str]:
+        files = {"ref_audio": _as_upload(audio)}
+        return await self._request_json(
+            "POST",
+            "/clone/register",
+            data={"name": name, "ref_text": transcript},
+            files=files,
+        )
+
+    async def clone_tts(
+        self,
+        name: str,
+        text: str,
+        *,
+        language: str = "English",
+    ) -> bytes:
+        return await self._request_audio(
+            "POST",
+            "/clone/tts",
+            data={"text": text, "language": language, "name": name},
+        )
+
+    async def clone_oneshot(
+        self,
+        text: str,
+        audio: Path | str | bytes | BufferedReader,
+        transcript: str,
+        *,
+        language: str = "English",
+    ) -> bytes:
+        files = {"ref_audio": _as_upload(audio)}
+        return await self._request_audio(
+            "POST",
+            "/clone/oneshot",
+            data={"text": text, "language": language, "ref_text": transcript},
+            files=files,
+        )

mimic_tts-0.0.1/mimic/cli.py

@@ -0,0 +1,157 @@
+"""`mimic` CLI — typer-based command-line interface."""
+
+from __future__ import annotations
+
+import io
+import sys
+import threading
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from mimic.client import Client
+from mimic.config import load_config
+from mimic.recorder import (
+    DEFAULT_SAMPLE_RATE,
+    pick_script,
+    play,
+    record_until_enter,
+    save_wav,
+)
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, help="mimic-tts CLI")
+clone_app = typer.Typer(no_args_is_help=True, help="Clone voice operations")
+app.add_typer(clone_app, name="clone")
+
+
+def _client() -> Client:
+    cfg = load_config()
+    return Client(server_url=cfg.server_url, token=cfg.token)
+
+
+@app.command()
+def say(
+    text: Annotated[str, typer.Argument(help="Text to synthesize.")],
+    voice: Annotated[str | None, typer.Option(help="Speaker name.")] = None,
+    out: Annotated[Path, typer.Option(help="Output wav path.")] = Path("out.wav"),
+    language: Annotated[str, typer.Option()] = "English",
+) -> None:
+    """Synthesize speech with a built-in voice."""
+    cfg = load_config()
+    speaker = voice or cfg.default_voice
+    with _client() as c:
+        c.tts_to_file(text, out, speaker=speaker, language=language)
+    typer.echo(f"wrote {out}")
+
+
+@app.command()
+def voices() -> None:
+    """List built-in voices."""
+    with _client() as c:
+        for v in c.list_voices():
+            typer.echo(f"{v['name']:12s} {v['language']}")
+
+
+@app.command()
+def clones() -> None:
+    """List registered clone voices."""
+    with _client() as c:
+        for name in c.list_clones():
+            typer.echo(name)
+
+
+@app.command()
+def health() -> None:
+    """Show server health and currently loaded models."""
+    with _client() as c:
+        info = c.health()
+    typer.echo(info)
+
+
+@app.command(name="config")
+def show_config() -> None:
+    """Print the resolved client configuration."""
+    cfg = load_config()
+    typer.echo(f"server_url    {cfg.server_url}")
+    typer.echo(f"token         {'<set>' if cfg.token else '<none>'}")
+    typer.echo(f"default_voice {cfg.default_voice}")
+
+
+@app.command()
+def record(
+    name: Annotated[str, typer.Argument(help="Name to register the clone under.")],
+    audio: Annotated[Path | None, typer.Option(help="Skip the recorder; use this file.")] = None,
+    text: Annotated[str | None, typer.Option(help="Transcript for --audio.")] = None,
+) -> None:
+    """Record a reference voice and register it on the server."""
+    if audio is not None:
+        if text is None:
+            typer.echo("--text is required when --audio is provided", err=True)
+            raise typer.Exit(2)
+        with _client() as c:
+            result = c.clone_register(name, audio, text)
+        typer.echo(f"registered '{result['name']}'")
+        return
+
+    _interactive_record_and_register(name)
+
+
+@clone_app.command(name="say")
+def clone_say(
+    name: Annotated[str, typer.Argument(help="Registered clone name.")],
+    text: Annotated[str, typer.Argument()],
+    out: Annotated[Path, typer.Option(help="Output wav path.")] = Path("out.wav"),
+    language: Annotated[str, typer.Option()] = "English",
+) -> None:
+    """Synthesize speech using a registered clone voice."""
+    with _client() as c:
+        audio = c.clone_tts(name, text, language=language)
+    out.write_bytes(audio)
+    typer.echo(f"wrote {out}")
+
+
+def _interactive_record_and_register(name: str) -> None:
+    """Drive the guided recorder. Kept thin; primitives live in `mimic.recorder`."""
+    script = pick_script()
+    typer.echo(f"\nRead this script when ready:\n\n  {script}\n")
+    typer.prompt("Press Enter to start recording", default="", show_default=False)
+
+    typer.echo("Recording… press Enter to stop.")
+    stop = threading.Event()
+
+    def _wait_for_enter() -> None:
+        sys.stdin.readline()
+        stop.set()
+
+    waiter = threading.Thread(target=_wait_for_enter)
+    waiter.daemon = True
+    waiter.start()
+
+    result = record_until_enter(
+        sample_rate=DEFAULT_SAMPLE_RATE,
+        channels=1,
+        max_seconds=30.0,
+        stop_event=stop,
+    )
+
+    typer.echo("Playing back…")
+    play(result.audio, result.sample_rate)
+
+    keep = typer.prompt("Keep this take? [y/N/r=retry]", default="N").strip().lower()
+    if keep == "r":
+        _interactive_record_and_register(name)
+        return
+    if not keep.startswith("y"):
+        typer.echo("discarded.")
+        raise typer.Exit(0)
+
+    transcript = typer.prompt("Transcript", default=script)
+
+    buf = io.BytesIO()
+    save_wav(buf, result.audio, sample_rate=result.sample_rate)
+    buf.seek(0)
+
+    with _client() as c:
+        out = c.clone_register(name, buf.read(), transcript)
+    typer.echo(f"registered '{out['name']}'")

mimic_tts-0.0.1/mimic/client.py

@@ -0,0 +1,148 @@
+"""Synchronous client for the mimic-tts server."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from io import BufferedReader
+
+import httpx
+
+from mimic._base import build_request_spec, raise_for_response
+
+
+class Client:
+    """Sync client. Use as a context manager to ensure the transport closes."""
+
+    def __init__(
+        self,
+        server_url: str | None = None,
+        token: str | None = None,
+        timeout: float = 60.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._base_url = server_url or os.environ.get("MIMIC_SERVER_URL") or "http://localhost:8000"
+        self._token = token if token is not None else os.environ.get("MIMIC_API_TOKEN")
+        self._http = httpx.Client(timeout=timeout, transport=transport)
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request_json(self, method: str, path: str, **kwargs: Any) -> Any:
+        spec = build_request_spec(
+            base_url=self._base_url,
+            method=method,
+            path=path,
+            token=self._token,
+            **kwargs,
+        )
+        r = self._http.request(
+            spec.method, spec.url, headers=spec.headers, data=spec.data, files=spec.files
+        )
+        raise_for_response(r)
+        return r.json()
+
+    def _request_audio(self, method: str, path: str, **kwargs: Any) -> bytes:
+        spec = build_request_spec(
+            base_url=self._base_url,
+            method=method,
+            path=path,
+            token=self._token,
+            **kwargs,
+        )
+        r = self._http.request(
+            spec.method, spec.url, headers=spec.headers, data=spec.data, files=spec.files
+        )
+        raise_for_response(r)
+        return r.content
+
+    def health(self) -> dict[str, Any]:
+        return self._request_json("GET", "/health")
+
+    def list_voices(self) -> list[dict[str, str]]:
+        return self._request_json("GET", "/voices")["voices"]
+
+    def list_clones(self) -> list[str]:
+        return self._request_json("GET", "/clone/voices")["voices"]
+
+    def tts(
+        self,
+        text: str,
+        *,
+        language: str = "English",
+        speaker: str = "Ryan",
+        instruct: str = "",
+    ) -> bytes:
+        return self._request_audio(
+            "POST",
+            "/tts",
+            data={"text": text, "language": language, "speaker": speaker, "instruct": instruct},
+        )
+
+    def tts_to_file(self, text: str, out: Path | str, **kwargs: Any) -> Path:
+        audio = self.tts(text, **kwargs)
+        out_path = Path(out)
+        out_path.write_bytes(audio)
+        return out_path
+
+    def clone_register(
+        self,
+        name: str,
+        audio: Path | str | bytes | BufferedReader,
+        transcript: str,
+    ) -> dict[str, str]:
+        files = {"ref_audio": _as_upload(audio)}
+        return self._request_json(
+            "POST",
+            "/clone/register",
+            data={"name": name, "ref_text": transcript},
+            files=files,
+        )
+
+    def clone_tts(
+        self,
+        name: str,
+        text: str,
+        *,
+        language: str = "English",
+    ) -> bytes:
+        return self._request_audio(
+            "POST",
+            "/clone/tts",
+            data={"text": text, "language": language, "name": name},
+        )
+
+    def clone_oneshot(
+        self,
+        text: str,
+        audio: Path | str | bytes | BufferedReader,
+        transcript: str,
+        *,
+        language: str = "English",
+    ) -> bytes:
+        files = {"ref_audio": _as_upload(audio)}
+        return self._request_audio(
+            "POST",
+            "/clone/oneshot",
+            data={"text": text, "language": language, "ref_text": transcript},
+            files=files,
+        )
+
+
+def _as_upload(audio: Path | str | bytes | BufferedReader) -> tuple[str, Any, str]:
+    """Normalize audio inputs to a (filename, fileobj-or-bytes, content-type) tuple."""
+    if isinstance(audio, (str, Path)):
+        path = Path(audio)
+        return (path.name, path.read_bytes(), "audio/wav")
+    if isinstance(audio, bytes):
+        return ("ref.wav", audio, "audio/wav")
+    return ("ref.wav", audio, "audio/wav")

mimic_tts-0.0.1/mimic/config.py

@@ -0,0 +1,71 @@
+"""Client configuration: kwarg → env → TOML → defaults."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from platformdirs import user_config_path
+
+DEFAULT_SERVER_URL = "http://localhost:8000"
+DEFAULT_VOICE = "Ryan"
+
+_KNOWN_TOML_KEYS = frozenset({"server_url", "token", "default_voice"})
+
+
+@dataclass
+class ClientConfig:
+    server_url: str
+    token: str | None
+    default_voice: str
+
+
+def _config_dir() -> Path:
+    override = os.environ.get("MIMIC_CONFIG_DIR")
+    if override:
+        return Path(override)
+    return user_config_path("mimic", appauthor=False)
+
+
+def _read_toml(config_dir: Path) -> dict[str, object]:
+    path = config_dir / "config.toml"
+    if not path.exists():
+        return {}
+    try:
+        with path.open("rb") as f:
+            data = tomllib.load(f)
+    except tomllib.TOMLDecodeError as e:
+        raise ValueError(f"invalid TOML at {path}: {e}") from e
+    return {k: v for k, v in data.items() if k in _KNOWN_TOML_KEYS}
+
+
+def load_config(
+    *,
+    server_url: str | None = None,
+    token: str | None = None,
+    default_voice: str | None = None,
+    config_dir: Path | None = None,
+) -> ClientConfig:
+    """Resolve config: kwarg → env → TOML → defaults."""
+    file_data = _read_toml(config_dir or _config_dir())
+
+    resolved_url = (
+        server_url
+        or os.environ.get("MIMIC_SERVER_URL")
+        or file_data.get("server_url")
+        or DEFAULT_SERVER_URL
+    )
+    resolved_token = (
+        token
+        if token is not None
+        else os.environ.get("MIMIC_API_TOKEN") or file_data.get("token") or None
+    )
+    resolved_voice = default_voice or file_data.get("default_voice") or DEFAULT_VOICE
+
+    return ClientConfig(
+        server_url=str(resolved_url),
+        token=str(resolved_token) if resolved_token is not None else None,
+        default_voice=str(resolved_voice),
+    )

mimic_tts-0.0.1/mimic/errors.py

@@ -0,0 +1,28 @@
+"""Exception hierarchy for mimic-tts client errors."""
+
+from __future__ import annotations
+
+
+class MimicError(Exception):
+    """Base class for all mimic-tts client errors."""
+
+
+class MimicAPIError(MimicError):
+    """Server returned a non-2xx response."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        super().__init__(f"HTTP {status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+
+
+class MimicAuthError(MimicAPIError):
+    """401: missing or invalid bearer token."""
+
+
+class MimicNotFoundError(MimicAPIError):
+    """404: requested resource (e.g. clone voice) does not exist."""
+
+
+class MimicValidationError(MimicAPIError):
+    """4xx other than 401/404: request was rejected as invalid."""