cheap-tts 0.1.0__tar.gz

cheap_tts-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Cheap TTS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

cheap_tts-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: cheap-tts
+Version: 0.1.0
+Summary: Cheap TTS Python SDK with local ONNX voice inference
+Author: Cheap TTS
+License-Expression: MIT
+Project-URL: Homepage, https://www.cheap-tts.com/api-docs/
+Project-URL: Documentation, https://www.cheap-tts.com/api-docs/
+Project-URL: Repository, https://github.com/supperking03/cheap-tts
+Project-URL: Issues, https://github.com/supperking03/cheap-tts/issues
+Keywords: text-to-speech,tts,onnx,voice,vietnamese
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: <3.14,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: onnxruntime>=1.17
+Dynamic: license-file
+
+# Cheap TTS Python SDK
+
+Generate multilingual speech with server-side text preparation and local ONNX inference. An active Cheap TTS subscription and a server secret key are required.
+
+```bash
+pip install cheap-tts
+```
+
+```python
+from cheap_tts import CheapTTS
+
+with CheapTTS(secret_key="sk_live_your_project") as tts:
+    result = tts.synthesize(
+        text="Xin chào từ Cheap TTS.",
+        voice="vi-entertainment",
+    )
+    result.save("audio.wav")
+```
+
+Async usage:
+
+```python
+from cheap_tts import AsyncCheapTTS
+
+async with AsyncCheapTTS(secret_key="sk_live_your_project") as tts:
+    result = await tts.synthesize("Hello from Cheap TTS.", "en-narration")
+    result.save("audio.wav")
+```
+
+## API
+
+- `voices()` returns the available voices.
+- `load_voice()` downloads, validates, caches, and loads one voice.
+- `synthesize()` prepares text through API v1 and performs ONNX inference locally.
+- `clear_cache()` removes locally cached voice assets.
+- `close()` releases the active model.
+
+`load_voice()` and `synthesize()` accept `on_progress` and a cancellation object with an `is_set()` method, such as `threading.Event`.
+
+```python
+from threading import Event
+
+cancel = Event()
+result = tts.synthesize(
+    "A long document",
+    "en-narration",
+    rate=1.25,
+    on_progress=lambda event: print(event.stage, event.progress),
+    cancel_event=cancel,
+)
+```
+
+Voice models are cached in `~/.cache/cheap-tts/models`. Set `cache_dir` or `CHEAP_TTS_CACHE_DIR` to change the location.
+
+The SDK sends operational health telemetry containing success/failure stage, latency, character count, voice ID, and audio duration. It never sends TTS text or credentials through telemetry. Pass `telemetry=False` to disable it.
+
+API errors are raised as `CheapTTSAPIError` with stable `status`, `code`, and `request_id` fields.
+

cheap_tts-0.1.0/README.md

@@ -0,0 +1,58 @@
+# Cheap TTS Python SDK
+
+Generate multilingual speech with server-side text preparation and local ONNX inference. An active Cheap TTS subscription and a server secret key are required.
+
+```bash
+pip install cheap-tts
+```
+
+```python
+from cheap_tts import CheapTTS
+
+with CheapTTS(secret_key="sk_live_your_project") as tts:
+    result = tts.synthesize(
+        text="Xin chào từ Cheap TTS.",
+        voice="vi-entertainment",
+    )
+    result.save("audio.wav")
+```
+
+Async usage:
+
+```python
+from cheap_tts import AsyncCheapTTS
+
+async with AsyncCheapTTS(secret_key="sk_live_your_project") as tts:
+    result = await tts.synthesize("Hello from Cheap TTS.", "en-narration")
+    result.save("audio.wav")
+```
+
+## API
+
+- `voices()` returns the available voices.
+- `load_voice()` downloads, validates, caches, and loads one voice.
+- `synthesize()` prepares text through API v1 and performs ONNX inference locally.
+- `clear_cache()` removes locally cached voice assets.
+- `close()` releases the active model.
+
+`load_voice()` and `synthesize()` accept `on_progress` and a cancellation object with an `is_set()` method, such as `threading.Event`.
+
+```python
+from threading import Event
+
+cancel = Event()
+result = tts.synthesize(
+    "A long document",
+    "en-narration",
+    rate=1.25,
+    on_progress=lambda event: print(event.stage, event.progress),
+    cancel_event=cancel,
+)
+```
+
+Voice models are cached in `~/.cache/cheap-tts/models`. Set `cache_dir` or `CHEAP_TTS_CACHE_DIR` to change the location.
+
+The SDK sends operational health telemetry containing success/failure stage, latency, character count, voice ID, and audio duration. It never sends TTS text or credentials through telemetry. Pass `telemetry=False` to disable it.
+
+API errors are raised as `CheapTTSAPIError` with stable `status`, `code`, and `request_id` fields.
+

cheap_tts-0.1.0/cheap_tts/__init__.py

@@ -0,0 +1,26 @@
+from .async_client import AsyncCheapTTS
+from .client import CheapTTS
+from .errors import (
+    CheapTTSAPIError,
+    CheapTTSCancelledError,
+    CheapTTSDownloadError,
+    CheapTTSError,
+    CheapTTSModelError,
+)
+from .models import Progress, SynthesisResult, Voice
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncCheapTTS",
+    "CheapTTS",
+    "CheapTTSAPIError",
+    "CheapTTSCancelledError",
+    "CheapTTSDownloadError",
+    "CheapTTSError",
+    "CheapTTSModelError",
+    "Progress",
+    "SynthesisResult",
+    "Voice",
+    "__version__",
+]

cheap_tts-0.1.0/cheap_tts/async_client.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+import threading
+
+from .client import CheapTTS, DEFAULT_API_BASE
+from .models import CancellationEvent, ProgressCallback, SynthesisResult, Voice
+
+
+class _CombinedCancellation:
+    def __init__(
+        self, internal: threading.Event, external: CancellationEvent | None
+    ) -> None:
+        self._internal = internal
+        self._external = external
+
+    def is_set(self) -> bool:
+        return self._internal.is_set() or bool(
+            self._external and self._external.is_set()
+        )
+
+
+class AsyncCheapTTS:
+    """Async facade over the same tested local runtime used by :class:`CheapTTS`."""
+
+    def __init__(
+        self,
+        *,
+        secret_key: str,
+        api_base: str = DEFAULT_API_BASE,
+        cache_dir: str | Path | None = None,
+        telemetry: bool = True,
+        timeout: float = 30.0,
+    ) -> None:
+        self._client = CheapTTS(
+            secret_key=secret_key,
+            api_base=api_base,
+            cache_dir=cache_dir,
+            telemetry=telemetry,
+            timeout=timeout,
+        )
+
+    async def voices(self) -> list[Voice]:
+        return await asyncio.to_thread(self._client.voices)
+
+    async def load_voice(
+        self,
+        voice: str,
+        *,
+        on_progress: ProgressCallback | None = None,
+        cancel_event: CancellationEvent | None = None,
+    ) -> Voice:
+        internal = threading.Event()
+        combined = _CombinedCancellation(internal, cancel_event)
+        try:
+            return await asyncio.to_thread(
+                self._client.load_voice,
+                voice,
+                on_progress=on_progress,
+                cancel_event=combined,
+            )
+        except asyncio.CancelledError:
+            internal.set()
+            raise
+
+    async def synthesize(
+        self,
+        text: str,
+        voice: str,
+        *,
+        rate: float = 1.0,
+        on_progress: ProgressCallback | None = None,
+        cancel_event: CancellationEvent | None = None,
+    ) -> SynthesisResult:
+        internal = threading.Event()
+        combined = _CombinedCancellation(internal, cancel_event)
+        try:
+            return await asyncio.to_thread(
+                self._client.synthesize,
+                text,
+                voice,
+                rate=rate,
+                on_progress=on_progress,
+                cancel_event=combined,
+            )
+        except asyncio.CancelledError:
+            internal.set()
+            raise
+
+    async def clear_cache(self) -> None:
+        await asyncio.to_thread(self._client.clear_cache)
+
+    async def close(self) -> None:
+        await asyncio.to_thread(self._client.close)
+
+    async def __aenter__(self) -> "AsyncCheapTTS":
+        return self
+
+    async def __aexit__(
+        self, _type: object, _value: object, _traceback: object
+    ) -> None:
+        await self.close()

cheap_tts-0.1.0/cheap_tts/audio.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from io import BytesIO
+import wave
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+FloatAudio = NDArray[np.float32]
+
+
+def encode_wav(samples: FloatAudio, sample_rate: int) -> bytes:
+    clipped = np.clip(np.asarray(samples, dtype=np.float32), -1.0, 1.0)
+    scaled = np.where(clipped < 0, clipped * 32768.0, clipped * 32767.0)
+    pcm = scaled.astype("<i2", copy=False)
+    output = BytesIO()
+    with wave.open(output, "wb") as wav:
+        wav.setnchannels(1)
+        wav.setsampwidth(2)
+        wav.setframerate(sample_rate)
+        wav.writeframes(pcm.tobytes())
+    return output.getvalue()
+
+
+def stretch_time(input_audio: FloatAudio, rate: float, sample_rate: int) -> FloatAudio:
+    """Pitch-preserving WSOLA time stretch, matching the Node SDK behavior."""
+    source = np.asarray(input_audio, dtype=np.float32).reshape(-1)
+    if rate <= 0 or abs(rate - 1.0) < 1e-3 or source.size == 0:
+        return source
+    frame = round(sample_rate * 0.03)
+    if source.size <= frame * 3:
+        return source
+    overlap = frame // 2
+    hop_out = frame - overlap
+    tolerance = round(sample_rate * 0.008)
+    output = np.zeros(max(frame, round(source.size / rate)), dtype=np.float32)
+    window = np.hanning(frame).astype(np.float32)
+    output[:frame] = source[:frame] * window
+    output[:overlap] += source[:overlap] * (1.0 - window[:overlap])
+
+    previous_input = 0
+    iteration = 1
+    while True:
+        output_position = iteration * hop_out
+        if output_position + frame > output.size:
+            break
+        center = round(output_position * rate)
+        if center + frame + tolerance >= source.size:
+            break
+        target = previous_input + hop_out
+        reference = source[target : target + overlap : 2]
+        best = center
+        best_score = float("-inf")
+        for start in range(max(0, center - tolerance), center + tolerance + 1):
+            candidate = source[start : start + overlap : 2]
+            energy = float(np.dot(candidate, candidate)) + 1e-9
+            score = float(np.dot(candidate, reference)) / energy**0.5
+            if score > best_score:
+                best_score = score
+                best = start
+        output[output_position : output_position + frame] += (
+            source[best : best + frame] * window
+        )
+        previous_input = best
+        iteration += 1
+    return output

cheap_tts-0.1.0/cheap_tts/cache.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+import hashlib
+import json
+import os
+from pathlib import Path
+import secrets
+import time
+from typing import Iterator
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .errors import CheapTTSCancelledError, CheapTTSDownloadError
+from .models import CancellationEvent, Progress, ProgressCallback
+
+
+LOCK_STALE_SECONDS = 10 * 60
+LOCK_WAIT_SECONDS = 0.25
+
+
+def default_cache_dir() -> Path:
+    configured = os.environ.get("CHEAP_TTS_CACHE_DIR")
+    return (
+        Path(configured).expanduser()
+        if configured
+        else Path.home() / ".cache" / "cheap-tts" / "models"
+    )
+
+
+def cache_paths(cache_dir: Path, model_base: str, asset: str) -> tuple[Path, Path]:
+    key = hashlib.sha256(f"{model_base.rstrip('/')}/{asset}".encode()).hexdigest()[:20]
+    return cache_dir / f"{key}.onnx", cache_dir / f"{key}.json"
+
+
+def check_cancelled(cancel_event: CancellationEvent | None) -> None:
+    if cancel_event is not None and cancel_event.is_set():
+        raise CheapTTSCancelledError("operation cancelled")
+
+
+@contextmanager
+def file_lock(
+    path: Path, cancel_event: CancellationEvent | None = None
+) -> Iterator[None]:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    while True:
+        check_cancelled(cancel_event)
+        try:
+            descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            os.close(descriptor)
+            break
+        except FileExistsError:
+            try:
+                if time.time() - path.stat().st_mtime > LOCK_STALE_SECONDS:
+                    path.unlink(missing_ok=True)
+                    continue
+            except FileNotFoundError:
+                continue
+            time.sleep(LOCK_WAIT_SECONDS)
+    try:
+        yield
+    finally:
+        path.unlink(missing_ok=True)
+
+
+def _atomic_download(
+    url: str,
+    destination: Path,
+    *,
+    on_progress: ProgressCallback | None = None,
+    cancel_event: CancellationEvent | None = None,
+    timeout: float = 60.0,
+) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary = destination.with_name(
+        f"{destination.name}.{os.getpid()}.{secrets.token_hex(6)}.tmp"
+    )
+    loaded = 0
+    try:
+        request = Request(url, headers={"User-Agent": "cheap-tts-python/0.1.0"})
+        with (
+            urlopen(request, timeout=timeout) as response,
+            temporary.open("xb") as output,
+        ):
+            raw_total = response.headers.get("content-length")
+            total = int(raw_total) if raw_total and raw_total.isdigit() else None
+            while True:
+                check_cancelled(cancel_event)
+                chunk = response.read(256 * 1024)
+                if not chunk:
+                    break
+                output.write(chunk)
+                loaded += len(chunk)
+                if on_progress:
+                    on_progress(
+                        Progress(
+                            "voice", loaded / total if total else None, loaded, total
+                        )
+                    )
+            output.flush()
+            os.fsync(output.fileno())
+        if loaded == 0:
+            raise CheapTTSDownloadError("voice asset download was empty")
+        os.replace(temporary, destination)
+        if on_progress:
+            on_progress(Progress("voice", 1.0, loaded, total))
+    except CheapTTSCancelledError:
+        raise
+    except (HTTPError, URLError, OSError) as exc:
+        raise CheapTTSDownloadError(
+            f"voice asset download failed: {type(exc).__name__}"
+        ) from exc
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def ensure_voice_files(
+    cache_dir: Path,
+    model_base: str,
+    asset: str,
+    *,
+    on_progress: ProgressCallback | None = None,
+    cancel_event: CancellationEvent | None = None,
+    timeout: float = 60.0,
+) -> tuple[Path, dict]:
+    model_path, config_path = cache_paths(cache_dir, model_base, asset)
+    with file_lock(model_path.with_suffix(".lock"), cancel_event):
+        if not config_path.is_file():
+            _atomic_download(
+                f"{model_base.rstrip('/')}/{asset}.onnx.json",
+                config_path,
+                cancel_event=cancel_event,
+                timeout=timeout,
+            )
+        try:
+            config = json.loads(config_path.read_text("utf-8"))
+        except (OSError, ValueError):
+            config_path.unlink(missing_ok=True)
+            _atomic_download(
+                f"{model_base.rstrip('/')}/{asset}.onnx.json",
+                config_path,
+                cancel_event=cancel_event,
+                timeout=timeout,
+            )
+            try:
+                config = json.loads(config_path.read_text("utf-8"))
+            except (OSError, ValueError) as exc:
+                config_path.unlink(missing_ok=True)
+                raise CheapTTSDownloadError("voice configuration is invalid") from exc
+        if not model_path.is_file() or model_path.stat().st_size < 1024:
+            model_path.unlink(missing_ok=True)
+            _atomic_download(
+                f"{model_base.rstrip('/')}/{asset}.onnx",
+                model_path,
+                on_progress=on_progress,
+                cancel_event=cancel_event,
+                timeout=timeout,
+            )
+        elif on_progress:
+            on_progress(
+                Progress(
+                    "voice", 1.0, model_path.stat().st_size, model_path.stat().st_size
+                )
+            )
+    return model_path, config
+
+
+def refresh_voice_model(
+    cache_dir: Path,
+    model_base: str,
+    asset: str,
+    *,
+    on_progress: ProgressCallback | None = None,
+    cancel_event: CancellationEvent | None = None,
+    timeout: float = 60.0,
+) -> tuple[Path, dict]:
+    """Atomically replace a cached model after the runtime rejects it."""
+    model_path, config_path = cache_paths(cache_dir, model_base, asset)
+    with file_lock(model_path.with_suffix(".lock"), cancel_event):
+        model_path.unlink(missing_ok=True)
+        _atomic_download(
+            f"{model_base.rstrip('/')}/{asset}.onnx",
+            model_path,
+            on_progress=on_progress,
+            cancel_event=cancel_event,
+            timeout=timeout,
+        )
+        try:
+            config = json.loads(config_path.read_text("utf-8"))
+        except (OSError, ValueError) as exc:
+            raise CheapTTSDownloadError("voice configuration is invalid") from exc
+    return model_path, config