nava-fa-speech 1.0.4__tar.gz

nava_fa_speech-1.0.4/.gitignore

@@ -0,0 +1,8 @@
+models/**
+!models/voices/.gitkeep
+__pycache__/
+*.pyc
+.env
+.env.bak
+.pytest_cache/
+.venv/

nava_fa_speech-1.0.4/.pypirc

@@ -0,0 +1,3 @@
+[pypi]
+  username = __token__
+  password = pypi-AgEIcHlwaS5vcmcCJGNhOTQ0ODc5LTU1YTktNDI3YS1iYmI1LTU0OWNlNGMxMGY4YwACKlszLCI0MzZhY2YxMy03ZWIzLTQwM2EtOWExZS1iYmFhNGU2NzBiYzgiXQAABiB7p3KXJvMb-AdPLN9lKB8TRlmrHgE0KNZ8RcsbHdrpiQ

nava_fa_speech-1.0.4/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: nava-fa-speech
+Version: 1.0.4
+Summary: Python SDK for Nava offline Persian speech services
+Project-URL: Homepage, https://github.com/mhosseinifar8/nava
+Project-URL: Repository, https://github.com/mhosseinifar8/nava
+Project-URL: Documentation, https://github.com/mhosseinifar8/nava/tree/main/docs
+Project-URL: Issues, https://github.com/mhosseinifar8/nava/issues
+Keywords: asr,farsi,offline,persian,speech,speech-to-text,stt,text-to-speech,tts,whisper
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Persian
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: websockets<16,>=15
+Description-Content-Type: text/markdown
+
+# Nava — Python SDK for Offline Persian Speech
+
+**Nava** (نوا — "melody" in Persian) is the official Python client for the
+[Nava speech platform](https://github.com/mhosseinifar8/nava) — an **offline, CPU-only Persian
+speech service**:
+
+- 🗣️ **Speech-to-Text** — Whisper `large-v3` (faster-whisper) tuned for Persian,
+  with standard orthography (ZWNJ, punctuation), VAD, and hot-word support.
+- 🔊 **Text-to-Speech** — three engines: `pocket` (voice-cloning style prompts),
+  `mana` and `piper` (Piper ONNX voices), all running on CPU.
+- 🔒 **Fully offline** — your audio and text never leave your machine. No cloud,
+  no API keys, no telemetry.
+
+This SDK wraps both services behind a tiny, typed Python API:
+
+| Client | Transport | Methods |
+|---|---|---|
+| `NavaClient` | REST (sync) | `transcribe`, `synthesize` |
+| `AsyncNavaClient` | REST + WebSocket (async) | `transcribe`, `synthesize`, `transcribe_ws`, `stream_speech_ws` |
+
+- `transcribe_ws` streams your audio in frames (long recordings work without
+  hitting per-frame size limits) and reuses the connection protocol efficiently.
+- `stream_speech_ws` yields PCM chunks **as they are synthesized** — start
+  playing audio before the whole clip is ready.
+- All failures raise a single, clear `NavaServiceError`.
+
+---
+
+## Requirements
+
+- Python **3.10+**
+- A running Nava server (see [Start the server](#start-the-server)) — the SDK
+  defaults to `http://127.0.0.1:8001` (STT) and `http://127.0.0.1:8002` (TTS).
+
+---
+
+## Start the server
+
+Nava is self-hosted from [its repository](https://github.com/mhosseinifar8/nava) — clone it, then:
+
+```bash
+# 1. Download all models (~10 GB, one time — needs internet)
+./scripts/download_models.sh
+
+# 2. Generate a .env tuned to THIS machine (cores/RAM auto-detected)
+./scripts/configure_infra.sh auto
+
+# 3. Build and run both services (offline from here on)
+docker compose up --build -d
+```
+
+Verify:
+
+```bash
+curl -s http://127.0.0.1:8001/api/v1/health
+# {"status":"ok","service":"nava-stt"}
+curl -s http://127.0.0.1:8002/api/v1/health
+# {"status":"ok","service":"nava-tts","engines":["pocket","mana","piper"]}
+```
+
+> Models are downloaded into `./models` and mounted read-only into the
+> containers. `configure_infra.sh` picks `low` / `medium` / `high` profiles
+> automatically (or force one: `./scripts/configure_infra.sh low`).
+
+---
+
+## Installation
+
+```bash
+pip install nava-speech
+```
+
+Or from source:
+
+```bash
+pip install -e ./nava_sdk
+```
+
+> The PyPI package is **`nava-speech`**, but you import it as `nava`:
+> `from nava import NavaClient` (same convention as `pillow` → `PIL`).
+
+Dependencies: `httpx` and `websockets` (installed automatically).
+
+---
+
+## Quick start
+
+### Speech-to-text
+
+Input must be raw PCM: **signed 16-bit little-endian, mono, 16 000 Hz**.
+
+```python
+from nava import NavaClient
+
+with NavaClient() as nava:
+    with open("speech.pcm", "rb") as f:
+        result = nava.transcribe(f.read(), hotwords="نوا")
+
+    print(result.text)            # متن تشخیص داده شده
+    print(result.language_prob)   # 0.99
+    for segment in result.segments:
+        print(segment["start"], segment["end"], segment["text"])
+```
+
+Convert any audio file to the required format with ffmpeg:
+
+```bash
+ffmpeg -i input.mp3 -ar 16000 -ac 1 -f s16le speech.pcm
+```
+
+### Text-to-speech
+
+```python
+from nava import NavaClient
+
+with NavaClient() as nava:
+    speech = nava.synthesize("سلام دنیا", engine="piper", speed=1.1)
+
+    print(speech.sample_rate)     # read this — it differs per engine
+    with open("out.pcm", "wb") as f:
+        f.write(speech.pcm)       # raw PCM, signed 16-bit LE, mono
+```
+
+Play the result (use the engine's sample rate):
+
+```bash
+ffplay -f s16le -ar 22050 -ch_layout mono out.pcm
+```
+
+**Engines**
+
+| Engine | Voice | Speed | Notes |
+|---|---|---|---|
+| `pocket` (default) | any wav prompt in `models/voices/` (`voice_prompt=`) | — | expressive, voice-cloning style |
+| `mana` | fixed | 0.5–2.0 | Piper ONNX |
+| `piper` | fixed | 0.5–2.0 | fastest |
+
+---
+
+## Async & streaming
+
+```python
+import asyncio
+from nava import AsyncNavaClient
+
+async def main():
+    async with AsyncNavaClient() as nava:
+        # REST
+        result = await nava.transcribe(pcm_bytes)
+        speech = await nava.synthesize("سلام", engine="mana")
+
+        # WebSocket STT — long audio is auto-chunked into 1 MB frames
+        result = await nava.transcribe_ws(pcm_bytes, hotwords="نوا")
+
+        # WebSocket TTS — play chunks as they are synthesized
+        async for chunk in nava.stream_speech_ws("این یک آزمایش است", engine="pocket"):
+            play(chunk.pcm)          # chunk.sample_rate for your audio sink
+
+asyncio.run(main())
+```
+
+---
+
+## Error handling
+
+```python
+from nava import NavaClient, NavaServiceError
+
+try:
+    with NavaClient() as nava:
+        nava.transcribe(b"\x00" * 10)   # too short
+except NavaServiceError as exc:
+    print(exc)
+    # Nava returned HTTP 422: audio is shorter than 100 ms at 16 kHz
+```
+
+---
+
+## API reference
+
+```python
+NavaClient(stt_url="http://127.0.0.1:8001",
+           tts_url="http://127.0.0.1:8002", *, timeout=120.0)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `transcribe(pcm, *, hotwords=None, initial_prompt=None)` | `TranscriptionResult(text, segments, language_prob)` | REST STT |
+| `synthesize(text, *, engine="pocket", voice_prompt="default", speed=1.0)` | `SpeechResult(pcm, sample_rate, engine)` | REST TTS |
+| `AsyncNavaClient.transcribe_ws(pcm, *, hotwords=None, initial_prompt=None)` | `TranscriptionResult` | WebSocket STT (frame-chunked) |
+| `AsyncNavaClient.stream_speech_ws(text, *, engine, voice_prompt, speed)` | async iterator of `SpeechResult` | WebSocket TTS streaming |
+
+Both clients are context managers (`with` / `async with`) and share one pooled
+HTTP connection across calls. Point them at remote hosts by passing
+`stt_url=` / `tts_url=`.
+
+---
+
+## Links
+
+- [Architecture guide](https://github.com/mhosseinifar8/nava/blob/main/docs/ARCHITECTURE.md) ·
+  [User manual](https://github.com/mhosseinifar8/nava/blob/main/docs/USER_MANUAL.md)
+- Report issues on the [project tracker](https://github.com/mhosseinifar8/nava/issues).

nava_fa_speech-1.0.4/README.md

@@ -0,0 +1,203 @@
+# Nava — Python SDK for Offline Persian Speech
+
+**Nava** (نوا — "melody" in Persian) is the official Python client for the
+[Nava speech platform](https://github.com/mhosseinifar8/nava) — an **offline, CPU-only Persian
+speech service**:
+
+- 🗣️ **Speech-to-Text** — Whisper `large-v3` (faster-whisper) tuned for Persian,
+  with standard orthography (ZWNJ, punctuation), VAD, and hot-word support.
+- 🔊 **Text-to-Speech** — three engines: `pocket` (voice-cloning style prompts),
+  `mana` and `piper` (Piper ONNX voices), all running on CPU.
+- 🔒 **Fully offline** — your audio and text never leave your machine. No cloud,
+  no API keys, no telemetry.
+
+This SDK wraps both services behind a tiny, typed Python API:
+
+| Client | Transport | Methods |
+|---|---|---|
+| `NavaClient` | REST (sync) | `transcribe`, `synthesize` |
+| `AsyncNavaClient` | REST + WebSocket (async) | `transcribe`, `synthesize`, `transcribe_ws`, `stream_speech_ws` |
+
+- `transcribe_ws` streams your audio in frames (long recordings work without
+  hitting per-frame size limits) and reuses the connection protocol efficiently.
+- `stream_speech_ws` yields PCM chunks **as they are synthesized** — start
+  playing audio before the whole clip is ready.
+- All failures raise a single, clear `NavaServiceError`.
+
+---
+
+## Requirements
+
+- Python **3.10+**
+- A running Nava server (see [Start the server](#start-the-server)) — the SDK
+  defaults to `http://127.0.0.1:8001` (STT) and `http://127.0.0.1:8002` (TTS).
+
+---
+
+## Start the server
+
+Nava is self-hosted from [its repository](https://github.com/mhosseinifar8/nava) — clone it, then:
+
+```bash
+# 1. Download all models (~10 GB, one time — needs internet)
+./scripts/download_models.sh
+
+# 2. Generate a .env tuned to THIS machine (cores/RAM auto-detected)
+./scripts/configure_infra.sh auto
+
+# 3. Build and run both services (offline from here on)
+docker compose up --build -d
+```
+
+Verify:
+
+```bash
+curl -s http://127.0.0.1:8001/api/v1/health
+# {"status":"ok","service":"nava-stt"}
+curl -s http://127.0.0.1:8002/api/v1/health
+# {"status":"ok","service":"nava-tts","engines":["pocket","mana","piper"]}
+```
+
+> Models are downloaded into `./models` and mounted read-only into the
+> containers. `configure_infra.sh` picks `low` / `medium` / `high` profiles
+> automatically (or force one: `./scripts/configure_infra.sh low`).
+
+---
+
+## Installation
+
+```bash
+pip install nava-speech
+```
+
+Or from source:
+
+```bash
+pip install -e ./nava_sdk
+```
+
+> The PyPI package is **`nava-speech`**, but you import it as `nava`:
+> `from nava import NavaClient` (same convention as `pillow` → `PIL`).
+
+Dependencies: `httpx` and `websockets` (installed automatically).
+
+---
+
+## Quick start
+
+### Speech-to-text
+
+Input must be raw PCM: **signed 16-bit little-endian, mono, 16 000 Hz**.
+
+```python
+from nava import NavaClient
+
+with NavaClient() as nava:
+    with open("speech.pcm", "rb") as f:
+        result = nava.transcribe(f.read(), hotwords="نوا")
+
+    print(result.text)            # متن تشخیص داده شده
+    print(result.language_prob)   # 0.99
+    for segment in result.segments:
+        print(segment["start"], segment["end"], segment["text"])
+```
+
+Convert any audio file to the required format with ffmpeg:
+
+```bash
+ffmpeg -i input.mp3 -ar 16000 -ac 1 -f s16le speech.pcm
+```
+
+### Text-to-speech
+
+```python
+from nava import NavaClient
+
+with NavaClient() as nava:
+    speech = nava.synthesize("سلام دنیا", engine="piper", speed=1.1)
+
+    print(speech.sample_rate)     # read this — it differs per engine
+    with open("out.pcm", "wb") as f:
+        f.write(speech.pcm)       # raw PCM, signed 16-bit LE, mono
+```
+
+Play the result (use the engine's sample rate):
+
+```bash
+ffplay -f s16le -ar 22050 -ch_layout mono out.pcm
+```
+
+**Engines**
+
+| Engine | Voice | Speed | Notes |
+|---|---|---|---|
+| `pocket` (default) | any wav prompt in `models/voices/` (`voice_prompt=`) | — | expressive, voice-cloning style |
+| `mana` | fixed | 0.5–2.0 | Piper ONNX |
+| `piper` | fixed | 0.5–2.0 | fastest |
+
+---
+
+## Async & streaming
+
+```python
+import asyncio
+from nava import AsyncNavaClient
+
+async def main():
+    async with AsyncNavaClient() as nava:
+        # REST
+        result = await nava.transcribe(pcm_bytes)
+        speech = await nava.synthesize("سلام", engine="mana")
+
+        # WebSocket STT — long audio is auto-chunked into 1 MB frames
+        result = await nava.transcribe_ws(pcm_bytes, hotwords="نوا")
+
+        # WebSocket TTS — play chunks as they are synthesized
+        async for chunk in nava.stream_speech_ws("این یک آزمایش است", engine="pocket"):
+            play(chunk.pcm)          # chunk.sample_rate for your audio sink
+
+asyncio.run(main())
+```
+
+---
+
+## Error handling
+
+```python
+from nava import NavaClient, NavaServiceError
+
+try:
+    with NavaClient() as nava:
+        nava.transcribe(b"\x00" * 10)   # too short
+except NavaServiceError as exc:
+    print(exc)
+    # Nava returned HTTP 422: audio is shorter than 100 ms at 16 kHz
+```
+
+---
+
+## API reference
+
+```python
+NavaClient(stt_url="http://127.0.0.1:8001",
+           tts_url="http://127.0.0.1:8002", *, timeout=120.0)
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `transcribe(pcm, *, hotwords=None, initial_prompt=None)` | `TranscriptionResult(text, segments, language_prob)` | REST STT |
+| `synthesize(text, *, engine="pocket", voice_prompt="default", speed=1.0)` | `SpeechResult(pcm, sample_rate, engine)` | REST TTS |
+| `AsyncNavaClient.transcribe_ws(pcm, *, hotwords=None, initial_prompt=None)` | `TranscriptionResult` | WebSocket STT (frame-chunked) |
+| `AsyncNavaClient.stream_speech_ws(text, *, engine, voice_prompt, speed)` | async iterator of `SpeechResult` | WebSocket TTS streaming |
+
+Both clients are context managers (`with` / `async with`) and share one pooled
+HTTP connection across calls. Point them at remote hosts by passing
+`stt_url=` / `tts_url=`.
+
+---
+
+## Links
+
+- [Architecture guide](https://github.com/mhosseinifar8/nava/blob/main/docs/ARCHITECTURE.md) ·
+  [User manual](https://github.com/mhosseinifar8/nava/blob/main/docs/USER_MANUAL.md)
+- Report issues on the [project tracker](https://github.com/mhosseinifar8/nava/issues).

nava_fa_speech-1.0.4/nava/__init__.py

@@ -0,0 +1,2 @@
+from .client import AsyncNavaClient, NavaClient, NavaServiceError, SpeechResult, TranscriptionResult
+__all__ = ["AsyncNavaClient", "NavaClient", "NavaServiceError", "SpeechResult", "TranscriptionResult"]

nava_fa_speech-1.0.4/nava/client.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+
+import httpx
+from websockets.asyncio.client import connect
+from websockets.exceptions import ConnectionClosed
+
+WS_FRAME_CHUNK = 1_000_000  # stay well under server per-frame limits
+
+class NavaServiceError(RuntimeError): pass
+@dataclass(frozen=True)
+class TranscriptionResult:
+    text: str
+    segments: list[dict]
+    language_prob: float
+@dataclass(frozen=True)
+class SpeechResult:
+    pcm: bytes
+    sample_rate: int
+    engine: str
+def check(response: httpx.Response) -> None:
+    if response.is_success: return
+    try: detail=response.json().get("detail",response.text)
+    except ValueError: detail=response.text
+    raise NavaServiceError(f"Nava returned HTTP {response.status_code}: {detail}")
+def ws_url(url: str, path: str) -> str:
+    return ("wss://"+url[8:] if url.startswith("https://") else "ws://"+url[7:] if url.startswith("http://") else url)+path
+async def _recv_or_raise(socket) -> str | bytes:
+    try:
+        return await socket.recv()
+    except ConnectionClosed as exc:
+        raise NavaServiceError(f"connection closed before the result arrived: {exc}") from exc
+async def _send_chunked(socket, payload: bytes) -> None:
+    for i in range(0, len(payload), WS_FRAME_CHUNK):
+        await socket.send(payload[i:i + WS_FRAME_CHUNK])
+
+class NavaClient:
+    def __init__(self,stt_url="http://127.0.0.1:8001",tts_url="http://127.0.0.1:8002",*,timeout=120.0): self.stt_url=stt_url.rstrip("/"); self.tts_url=tts_url.rstrip("/"); self.http=httpx.Client(timeout=timeout)
+    def __enter__(self): return self
+    def __exit__(self,*_): self.close()
+    def close(self): self.http.close()
+    def transcribe(self,pcm:bytes,*,hotwords:str|None=None,initial_prompt:str|None=None)->TranscriptionResult:
+        r=self.http.post(self.stt_url+"/api/v1/transcriptions",content=pcm,headers={"Content-Type":"application/octet-stream"},params={k:v for k,v in {"hotwords":hotwords,"initial_prompt":initial_prompt}.items() if v}); check(r); b=r.json(); return TranscriptionResult(b["text"],b["segments"],b["language_prob"])
+    def synthesize(self,text:str,*,engine="pocket",voice_prompt="default",speed=1.0)->SpeechResult:
+        r=self.http.post(self.tts_url+"/api/v1/speech",json={"text":text,"engine":engine,"voice_prompt":voice_prompt,"speed":speed}); check(r); return SpeechResult(r.content,int(r.headers["X-Nava-Sample-Rate"]),r.headers["X-Nava-Engine"])
+class AsyncNavaClient:
+    def __init__(self,stt_url="http://127.0.0.1:8001",tts_url="http://127.0.0.1:8002",*,timeout=120.0): self.stt_url=stt_url.rstrip("/"); self.tts_url=tts_url.rstrip("/"); self.http=httpx.AsyncClient(timeout=timeout)
+    async def __aenter__(self): return self
+    async def __aexit__(self,*_): await self.aclose()
+    async def aclose(self): await self.http.aclose()
+    async def transcribe(self,pcm:bytes,*,hotwords:str|None=None,initial_prompt:str|None=None)->TranscriptionResult:
+        r=await self.http.post(self.stt_url+"/api/v1/transcriptions",content=pcm,headers={"Content-Type":"application/octet-stream"},params={k:v for k,v in {"hotwords":hotwords,"initial_prompt":initial_prompt}.items() if v}); check(r); b=r.json(); return TranscriptionResult(b["text"],b["segments"],b["language_prob"])
+    async def synthesize(self,text:str,*,engine="pocket",voice_prompt="default",speed=1.0)->SpeechResult:
+        r=await self.http.post(self.tts_url+"/api/v1/speech",json={"text":text,"engine":engine,"voice_prompt":voice_prompt,"speed":speed}); check(r); return SpeechResult(r.content,int(r.headers["X-Nava-Sample-Rate"]),r.headers["X-Nava-Engine"])
+    async def transcribe_ws(self,pcm:bytes,*,hotwords:str|None=None,initial_prompt:str|None=None)->TranscriptionResult:
+        async with connect(ws_url(self.stt_url,"/ws/stt"),max_size=None) as socket:
+            config={k:v for k,v in {"hotwords":hotwords,"initial_prompt":initial_prompt}.items() if v}
+            if config: await socket.send(json.dumps(config,ensure_ascii=False))
+            await _send_chunked(socket, pcm)
+            await socket.send('{"action":"eos"}')
+            while True:
+                frame=await _recv_or_raise(socket)
+                if isinstance(frame,bytes): continue
+                body=json.loads(frame)
+                if body.get("status")=="error": raise NavaServiceError(body["error"])
+                if "text" in body: return TranscriptionResult(body["text"],body["segments"],body["language_prob"])
+    async def stream_speech_ws(self,text:str,*,engine="pocket",voice_prompt="default",speed=1.0)->AsyncIterator[SpeechResult]:
+        async with connect(ws_url(self.tts_url,"/ws/tts"),max_size=None) as socket:
+            await socket.send(json.dumps({"text":text,"engine":engine,"voice_prompt":voice_prompt,"speed":speed},ensure_ascii=False)); rate=None
+            while True:
+                frame=await _recv_or_raise(socket)
+                if isinstance(frame,bytes):
+                    if rate is None: raise NavaServiceError("TTS sent audio before metadata")
+                    yield SpeechResult(frame,rate,engine); continue
+                body=json.loads(frame)
+                if body.get("status")=="error": raise NavaServiceError(body["error"])
+                if body.get("status")=="streaming": rate=int(body["sample_rate"]); engine=body["engine"]
+                if body.get("status")=="completed": return

nava_fa_speech-1.0.4/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nava-fa-speech"
+version = "1.0.4"
+description = "Python SDK for Nava offline Persian speech services"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["persian", "farsi", "speech", "tts", "stt", "asr", "whisper", "offline", "speech-to-text", "text-to-speech"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Natural Language :: Persian",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["httpx>=0.27,<1", "websockets>=15,<16"]
+
+[project.urls]
+Homepage = "https://github.com/mhosseinifar8/nava"
+Repository = "https://github.com/mhosseinifar8/nava"
+Documentation = "https://github.com/mhosseinifar8/nava/tree/main/docs"
+Issues = "https://github.com/mhosseinifar8/nava/issues"
+
+[tool.hatch.build.targets.wheel]
+# PyPI distribution name is "nava-speech"; the importable package stays "nava"
+packages = ["nava"]