g-speech 0.1.0__py3-none-any.whl

g_speech-0.1.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.4
+Name: g-speech
+Version: 0.1.0
+Summary: Interruptible text-to-speech using the Google Translate TTS API.
+Author-email: Karim Aziiev <karim.aziiev@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KarimAziev/gspeech
+Project-URL: Issues, https://github.com/KarimAziev/gspeech/issues
+Project-URL: Repository, https://github.com/KarimAziev/gspeech
+Project-URL: Changelog, https://github.com/KarimAziev/gspeech/blob/main/CHANGELOG.md
+Keywords: speech,audio,synthesis,voice,google,tts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: miniaudio>=1.61
+Requires-Dist: platformdirs>=4.3
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: coverage[toml]>=7.10; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# About
+
+[![CI](https://github.com/KarimAziev/gspeech/actions/workflows/ci.yml/badge.svg)](https://github.com/KarimAziev/gspeech/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/KarimAziev/gspeech/graph/badge.svg)](https://codecov.io/gh/KarimAziev/gspeech)
+
+`gspeech` synthesizes speech with the Google Translate TTS endpoint and plays it
+through a small, cross-platform
+[Miniaudio](https://github.com/irmen/pyminiaudio) backend. Playback works on
+Raspberry Pi, Linux, macOS, and Windows.
+
+The Google Translate endpoint is undocumented and is not an official Google API.
+Applications should therefore handle synthesis failures and should not rely on
+the endpoint for safety-critical announcements.
+
+**Table of Contents**
+
+> - [About](#about)
+>   - [Installation](#installation)
+>   - [Usage](#usage)
+>     - [Command line](#command-line)
+>     - [Python API](#python-api)
+>       - [Interruption and queuing](#interruption-and-queuing)
+>       - [Synthesis and cache configuration](#synthesis-and-cache-configuration)
+>       - [Logging](#logging)
+>       - [Errors and shutdown](#errors-and-shutdown)
+>   - [Development](#development)
+
+## Installation
+
+```bash
+pip install g-speech
+```
+
+## Usage
+
+### Command line
+
+Speak text:
+
+```bash
+gspeech "Hello, world"
+```
+
+Select a language:
+
+```bash
+gspeech -l fr "Bonjour tout le monde"
+```
+
+Save MP3 data instead of playing it:
+
+```bash
+gspeech -o hello.mp3 "Hello, world"
+```
+
+Read and speak standard input one line at a time:
+
+```bash
+some-command | gspeech -
+```
+
+The module entry point is equivalent:
+
+```bash
+python -m gspeech "Hello, world"
+```
+
+Press `Ctrl+C` to interrupt CLI playback.
+
+Use `-v` for lifecycle messages, `-vv` for diagnostic logging, and `--version`
+to print the installed version:
+
+```bash
+gspeech -vv "Hello, world"
+gspeech --version
+```
+
+Only the CLI treats `-` as standard input. In the Python API,
+`Speech("-", "en")` synthesizes a literal hyphen.
+
+### Python API
+
+The familiar blocking API remains available:
+
+```python
+from gspeech import Speech
+
+result = Speech("Hello, world", "en").play()
+print(result.status)
+```
+
+Use a shared `SpeechPlayer` for interruptible application playback:
+
+```python
+from gspeech import SpeechPlayer
+
+with SpeechPlayer() as player:
+    first = player.speak("This announcement is no longer relevant.")
+
+    # The default "replace" policy interrupts first and plays second.
+    second = player.speak("Turn right now.")
+
+    print(first.wait().status)  # SpeechStatus.INTERRUPTED
+    print(second.wait().status)  # SpeechStatus.COMPLETED
+```
+
+#### Interruption and queuing
+
+`SpeechPlayer.speak()` is non-blocking and returns a thread-safe
+`SpeechHandle`. The default `replace` policy:
+
+- interrupts the active request;
+- discards older pending requests; and
+- starts the newest request as soon as a download worker is available.
+
+Cancellation is observed while downloading as well as during audio playback.
+Synchronous HTTP requests cannot be forcibly killed, so an abandoned download
+may continue in the bounded background download pool until its configured
+timeout. The pool is bounded to avoid unbounded thread growth on small systems.
+
+Stop active and pending speech explicitly:
+
+```python
+player.stop()
+```
+
+Wait until active playback acknowledges cancellation:
+
+```python
+player.stop(wait=True, timeout=1)
+```
+
+Queue speech instead of replacing it:
+
+```python
+from gspeech import SpeechPolicy
+
+player.speak("First", policy=SpeechPolicy.ENQUEUE)
+player.speak("Second", policy=SpeechPolicy.ENQUEUE)
+```
+
+Always close a long-lived player, either explicitly or with a context manager:
+
+```python
+player.close()
+```
+
+`SpeechPlayer` closes its audio backend and synthesizer, including injected
+implementations. `Speech.write_to()` does not close an injected synthesizer
+because the caller owns that standalone dependency.
+
+#### Synthesis and cache configuration
+
+`GoogleTranslateTTSClient` owns HTTP sessions, timeouts, and the persistent
+audio cache:
+
+```python
+from gspeech import GoogleTranslateTTSClient, SpeechPlayer
+
+client = GoogleTranslateTTSClient(
+    timeout=(3.05, 5.0),  # connect timeout, read timeout
+    cache_ttl_seconds=7 * 24 * 60 * 60,
+    cache_max_entries=500,
+)
+
+with SpeechPlayer(synthesizer=client) as player:
+    player.play("Hello", "en").raise_for_error()
+```
+
+Disable persistent caching:
+
+```python
+client = GoogleTranslateTTSClient(cache_enabled=False)
+```
+
+Choose another cache directory or clear it:
+
+```python
+client = GoogleTranslateTTSClient(cache_dir="/var/cache/my-robot/gspeech")
+client.clear_cache()
+client.close()
+```
+
+Cache keys are SHA-256 digests and do not contain the original speech text.
+Audio data is stored in a small SQLite database under the platform-specific user
+cache directory by default.
+
+#### Logging
+
+Library loggers use the `gspeech` namespace and do not configure application
+logging. Applications can enable them normally:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logging.getLogger("gspeech").setLevel(logging.DEBUG)
+```
+
+Lifecycle logs include request IDs, language, character counts, segment numbers,
+statuses, and elapsed times. They intentionally omit speech text and complete
+provider URLs.
+
+#### Errors and shutdown
+
+The public exception hierarchy is:
+
+```text
+GSpeechError
+├── SynthesisError
+├── PlaybackError
+└── PlayerClosedError
+```
+
+Asynchronous failures are recorded in `SpeechResult`:
+
+```python
+result = player.play("Hello")
+result.raise_for_error()
+```
+
+Interruption is a normal terminal status rather than an exception:
+
+```python
+from gspeech import SpeechStatus
+
+if result.status is SpeechStatus.INTERRUPTED:
+    ...
+```
+
+Use a context manager when possible. A long-lived service should call
+`player.close()` during application shutdown.
+
+Language choices for an API or user interface are available without exposing a
+mutable package-global list:
+
+```python
+from gspeech import available_languages
+
+options = available_languages()
+```
+
+## Development
+
+Create a virtual environment, install the development extra, and run the local
+CI-equivalent checks:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install --editable ".[dev]"
+make all
+python -m coverage run -m unittest discover
+python -m coverage report
+```
+
+The real provider test is opt-in and downloads audio without playing it:
+
+```bash
+GSPEECH_RUN_INTEGRATION_TESTS=1 python -m unittest tests.test_integration
+```

g_speech-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+g_speech-0.1.0.dist-info/licenses/LICENSE,sha256=N9DLsoErrYbT3HG24DVyxJbB2EUJZs4dxP-H5HlyLgg,1069
+gspeech/__init__.py,sha256=gwp3dJsmUdEQij1rE4c6pmrlL1p1o_QdNacGH8Lo3-0,1397
+gspeech/__main__.py,sha256=LHG3e3txRVEUzW0XVkbSP6W1bNKJWBPwGpc3D5gngMU,93
+gspeech/_cache.py,sha256=3a7sdsLaUZ6giwhkocPxAmipMMOlG3HQWW01YKpqkBg,4582
+gspeech/audio.py,sha256=FnIUP20ySU0gsdiDZgjPtSWOZX3zNvFqW5VGTkAH8ZQ,4283
+gspeech/cli.py,sha256=x-iLTkoX0BBg7yO_7Ep1jVsrTrB9_C9FPiLRG6-4lmg,2804
+gspeech/client.py,sha256=YD_X0r0tS2vV1IejlCS0K5_vObzPzjB10XPmKha_7eY,7692
+gspeech/config.py,sha256=75Xdkcf1wgZyN6K7TsGeTio8HHFADdmmJpBDDLpOU14,3392
+gspeech/exceptions.py,sha256=GAP9xIG_NKf76IdJuXx1afcBeEAPpOkW-O526OjDSfw,402
+gspeech/player.py,sha256=LHrbIy4QAl8AFz1_1UNvUZ69yuEd60iGq9adXhjpVl4,15674
+gspeech/preloader_thread.py,sha256=y9hkfmuCL2Pfack7ROAxS-zC57ujoGQTlysIsQ5jVM4,1690
+gspeech/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+gspeech/speech.py,sha256=nxqpuSa1h9DyVhMWtSdacqYtWOKudX0oy4H-VYo14bQ,4988
+gspeech/speech_segment.py,sha256=OPNy5UzdG4yTNfwktvtfkgJnZO-JonxrVftF89eVQHI,407
+gspeech/version.py,sha256=mz2dhmhl1m1JQj8ScOzgfl_mJYXZQwwaUCNMvuwCGZ4,528
+g_speech-0.1.0.dist-info/METADATA,sha256=nOSri4iUy5BypQ8p2BkZFdtCYd1EckyEuyZ1hkEI8TQ,7940
+g_speech-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+g_speech-0.1.0.dist-info/entry_points.txt,sha256=lWDP2cGJ0ZS8YCmo1ssVHJsZkbtDjSkzN4-Uas8qqzU,45
+g_speech-0.1.0.dist-info/top_level.txt,sha256=EG8pNeInM-XxgNgNhuK-kUdZkvrDChmUIl-sU_Vwv_k,8
+g_speech-0.1.0.dist-info/RECORD,,

g_speech-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

g_speech-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gspeech = gspeech.cli:main

g_speech-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karim Aziiev
+
+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.

g_speech-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gspeech

gspeech/__init__.py

@@ -0,0 +1,66 @@
+"""Interruptible text-to-speech synthesis and playback."""
+
+import logging
+
+from gspeech._cache import AudioCache
+from gspeech.audio import AudioBackend, MiniaudioBackend
+from gspeech.client import (
+    GoogleTranslateTTSClient,
+    HTTPResponse,
+    HTTPSession,
+    Synthesizer,
+)
+from gspeech.config import (
+    LANGUAGES_OPTIONS,
+    SUPPORTED_LANGUAGES,
+    LanguageCode,
+    LanguageOption,
+    available_languages,
+)
+from gspeech.exceptions import (
+    GSpeechError,
+    PlaybackError,
+    PlayerClosedError,
+    SynthesisError,
+)
+from gspeech.player import (
+    SpeechHandle,
+    SpeechPlayer,
+    SpeechPolicy,
+    SpeechResult,
+    SpeechStatus,
+)
+from gspeech.speech import Speech
+from gspeech.speech_segment import SpeechSegment
+from gspeech.version import version
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__version__ = version
+
+__all__ = [
+    "LANGUAGES_OPTIONS",
+    "SUPPORTED_LANGUAGES",
+    "AudioBackend",
+    "AudioCache",
+    "GSpeechError",
+    "GoogleTranslateTTSClient",
+    "HTTPResponse",
+    "HTTPSession",
+    "LanguageCode",
+    "LanguageOption",
+    "MiniaudioBackend",
+    "PlaybackError",
+    "PlayerClosedError",
+    "Speech",
+    "SpeechHandle",
+    "SpeechPlayer",
+    "SpeechPolicy",
+    "SpeechResult",
+    "SpeechSegment",
+    "SpeechStatus",
+    "SynthesisError",
+    "Synthesizer",
+    "__version__",
+    "available_languages",
+]

gspeech/__main__.py

@@ -0,0 +1,5 @@
+"""Support ``python -m gspeech``."""
+
+from gspeech.cli import main
+
+raise SystemExit(main())

gspeech/_cache.py

@@ -0,0 +1,149 @@
+"""Small, privacy-preserving audio caches used internally by gspeech."""
+
+from __future__ import annotations
+
+import sqlite3
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Protocol
+
+
+class AudioCache(Protocol):
+    """Storage interface used by the speech synthesizer."""
+
+    def get(self, key: str) -> bytes | None:
+        """Return cached audio, or ``None`` when the key is absent or expired."""
+        ...
+
+    def set(self, key: str, audio_data: bytes) -> None:
+        """Store encoded audio under an opaque key."""
+        ...
+
+    def clear(self) -> None:
+        """Remove every cached item."""
+        ...
+
+    def close(self) -> None:
+        """Release resources owned by the cache."""
+        ...
+
+
+class NullAudioCache:
+    """No-op cache used when persistence is disabled or unavailable."""
+
+    def get(self, key: str) -> None:
+        """Always report a cache miss."""
+        return None
+
+    def set(self, key: str, audio_data: bytes) -> None:
+        """Discard audio data."""
+
+    def clear(self) -> None:
+        """Do nothing."""
+
+    def close(self) -> None:
+        """Do nothing."""
+
+
+class SQLiteAudioCache:
+    """Thread-safe SQLite cache whose keys contain no original speech text."""
+
+    def __init__(
+        self,
+        path: Path,
+        *,
+        ttl_seconds: float,
+        max_entries: int,
+    ) -> None:
+        if ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be greater than zero")
+        if max_entries <= 0:
+            raise ValueError("max_entries must be greater than zero")
+
+        self.path = path
+        self.ttl_seconds = ttl_seconds
+        self.max_entries = max_entries
+        self._lock = threading.RLock()
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connection() as connection:
+            connection.execute("PRAGMA journal_mode=WAL")
+            connection.execute(
+                """
+                CREATE TABLE IF NOT EXISTS audio_cache (
+                    key TEXT PRIMARY KEY,
+                    audio BLOB NOT NULL,
+                    created_at REAL NOT NULL,
+                    accessed_at REAL NOT NULL
+                )
+                """
+            )
+
+    def _connect(self) -> sqlite3.Connection:
+        return sqlite3.connect(self.path, timeout=5)
+
+    @contextmanager
+    def _connection(self) -> Iterator[sqlite3.Connection]:
+        connection = self._connect()
+        try:
+            with connection:
+                yield connection
+        finally:
+            connection.close()
+
+    def get(self, key: str) -> bytes | None:
+        now = time.time()
+        with self._lock, self._connection() as connection:
+            row = connection.execute(
+                "SELECT audio, created_at FROM audio_cache WHERE key = ?",
+                (key,),
+            ).fetchone()
+            if row is None:
+                return None
+
+            audio_data, created_at = row
+            if now - float(created_at) > self.ttl_seconds:
+                connection.execute("DELETE FROM audio_cache WHERE key = ?", (key,))
+                return None
+
+            connection.execute(
+                "UPDATE audio_cache SET accessed_at = ? WHERE key = ?",
+                (now, key),
+            )
+            return bytes(audio_data)
+
+    def set(self, key: str, audio_data: bytes) -> None:
+        now = time.time()
+        with self._lock, self._connection() as connection:
+            connection.execute(
+                """
+                INSERT INTO audio_cache (key, audio, created_at, accessed_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(key) DO UPDATE SET
+                    audio = excluded.audio,
+                    created_at = excluded.created_at,
+                    accessed_at = excluded.accessed_at
+                """,
+                (key, audio_data, now, now),
+            )
+            connection.execute(
+                """
+                DELETE FROM audio_cache
+                WHERE key IN (
+                    SELECT key
+                    FROM audio_cache
+                    ORDER BY accessed_at DESC
+                    LIMIT -1 OFFSET ?
+                )
+                """,
+                (self.max_entries,),
+            )
+
+    def clear(self) -> None:
+        with self._lock, self._connection() as connection:
+            connection.execute("DELETE FROM audio_cache")
+
+    def close(self) -> None:
+        """Connections are short-lived, so there is nothing to release."""