piper-tts-server 0.1.0__tar.gz

piper_tts_server-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 ICT Innovations (https://www.ictinnovations.com), Tahir Almas
+
+Portions derived from ICTContact (https://www.ictcontact.com).
+
+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.

piper_tts_server-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: piper-tts-server
+Version: 0.1.0
+Summary: Paced, streaming Piper (+ElevenLabs) TTS microservice for real-time voice pipelines (Asterisk AudioSocket, RTP, WebSocket).
+Author-email: Tahir Almas <tahir@ictinnovations.com>
+Maintainer-email: ICT Innovations <info@ictinnovations.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ictinnovations/piper-tts-server
+Project-URL: Repository, https://github.com/ictinnovations/piper-tts-server
+Project-URL: Derived From, https://www.ictcontact.com
+Keywords: piper,tts,text-to-speech,asterisk,audiosocket,voice,streaming,realtime,voip
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Provides-Extra: piper
+Requires-Dist: piper-tts>=1.2; extra == "piper"
+Provides-Extra: server
+Requires-Dist: aiohttp>=3.8; extra == "server"
+Provides-Extra: elevenlabs
+Requires-Dist: httpx>=0.24; extra == "elevenlabs"
+Provides-Extra: all
+Requires-Dist: piper-tts>=1.2; extra == "all"
+Requires-Dist: aiohttp>=3.8; extra == "all"
+Requires-Dist: httpx>=0.24; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: aiohttp>=3.8; extra == "dev"
+Dynamic: license-file
+
+# piper-tts-server
+
+**Paced, streaming [Piper](https://github.com/OHF-Voice/piper1-gpl) TTS for real-time voice pipelines** — Asterisk AudioSocket, RTP, or a browser WebSocket. Optional ElevenLabs cloud voices with automatic local fallback.
+
+[![CI](https://github.com/ictinnovations/piper-tts-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ictinnovations/piper-tts-server/actions)
+[![PyPI](https://img.shields.io/pypi/v/piper-tts-server.svg)](https://pypi.org/project/piper-tts-server/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+If you have tried to bolt Piper onto a phone call and hit **dead air before the greeting**, **the first few words clipped**, or **the caller only hearing the tail of each sentence** — this library is the fix. It packages the three things that make Piper work in a real-time loop:
+
+1. **Process-wide voice cache.** `PiperVoice.load()` costs 2.5–5.5 s. Loading per request means that much dead air before every utterance. Voices load once and are reused.
+2. **A single synthesis lock.** Piper phonemizes via espeak-ng, whose C API is **not thread-safe**. All synthesis is serialized behind one lock so concurrent calls don't corrupt each other.
+3. **Deadline-based frame pacing.** Real-time transports forward each frame the instant it arrives; bursting a whole utterance overruns the far end's jitter buffer. `PacedWriter` releases exactly one frame per interval on a monotonic deadline — and **re-clamps every frame** so a synthesis stall never turns into a catch-up burst that clips the next words.
+
+## Install
+
+```bash
+pip install "piper-tts-server[all]"     # library + server + piper + elevenlabs
+# or minimal:
+pip install piper-tts-server            # library core (numpy only)
+pip install "piper-tts-server[piper,server]"
+```
+
+Download a Piper voice (`.onnx` + `.onnx.json`) into a `voices/` directory — see the [Piper voices list](https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/voices.md).
+
+## Run the service
+
+```bash
+PIPER_TTS_VOICES_DIR=voices PIPER_TTS_DEFAULT_VOICE=en_US-amy-medium \
+  piper-tts-server            # listens on 127.0.0.1:8080
+```
+
+```bash
+# one-shot WAV
+curl -X POST localhost:8080/synthesize \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"Hello from Piper."}' --output hello.wav
+
+# paced streaming slin16 frames (feed straight to AudioSocket/RTP)
+curl -N -X POST localhost:8080/synthesize/stream \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"Your call is being connected.","paced":true}' --output frames.slin
+```
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /health` | status + cached voices |
+| `POST /warm` `{voice_id}` | preload a voice into the cache |
+| `POST /synthesize` `{text, voice_id, provider, format}` | one-shot `wav` (default) or raw `pcm` |
+| `POST /synthesize/stream` `{text, …, paced}` | chunked frames; `paced:true` = deadline-clocked |
+
+## Use as a library (no HTTP in the media path)
+
+```python
+from piper_tts_server import StreamingTTS, PacedWriter, tts_sanitize
+
+tts = StreamingTTS(voices_dir="voices", default_voice_path="voices/en_US-amy-medium.onnx")
+await tts.start()
+
+writer = PacedWriter(my_audiosocket_write, frame_ms=20)   # sink: async fn(bytes)
+async for frame in tts.synthesise(tts_sanitize(text)):
+    await writer.write(frame)                              # 320 bytes / 20 ms, paced
+```
+
+See [`examples/asterisk_audiosocket.md`](examples/asterisk_audiosocket.md) for the full AudioSocket wiring and streaming-LLM sentence chunking.
+
+## Configuration
+
+All via env (or `ServerConfig`): `PIPER_TTS_HOST`, `PIPER_TTS_PORT`, `PIPER_TTS_VOICES_DIR`, `PIPER_TTS_DEFAULT_VOICE`, `PIPER_TTS_PROVIDER` (`piper`|`elevenlabs`), `PIPER_TTS_ELEVENLABS_API_KEY`, `PIPER_TTS_SAMPLE_RATE` (default `8000`), `PIPER_TTS_FRAME_MS` (default `20`), `PIPER_TTS_WARM_ON_START`.
+
+Default output is **8 kHz slin16 / 20 ms frames** (telephony). Set `PIPER_TTS_SAMPLE_RATE=16000` for wideband.
+
+### ElevenLabs with local fallback
+
+Set `PIPER_TTS_PROVIDER=elevenlabs` + `PIPER_TTS_ELEVENLABS_API_KEY` and pass a `voice_id`. Any failure falls back to the local Piper default voice so the stream never goes silent; a `401/403` disables further cloud attempts for that engine.
+
+## Development
+
+```bash
+pip install "piper-tts-server[dev]"
+pytest          # pure-DSP, sanitize, and pacing tests run without Piper installed
+```
+
+## Licensing
+
+This package is **MIT licensed** and contains no Piper source code. Piper is an optional extra, imported lazily only when the local engine is used — the core library installs with numpy alone, and the test suite runs without Piper present.
+
+Piper itself is a separate project under a different licence. The maintained release ([`OHF-Voice/piper1-gpl`](https://github.com/OHF-Voice/piper1-gpl), PyPI [`piper-tts`](https://pypi.org/project/piper-tts/)) is **GPL-3.0-or-later**; the older MIT `rhasspy/piper` is archived. If you install the `[piper]` or `[all]` extra, the resulting combined installation is subject to GPL-3.0 terms. The ElevenLabs provider, and the pacing and sanitising helpers on their own, pull in no GPL code.
+
+**Not affiliated with, or endorsed by, the Open Home Foundation or the Piper project.** This is an independent server and library that drives Piper as one of several backends.
+
+## Provenance & credits
+
+Extracted and generalized from the TTS layer of **[ICTContact](https://www.ictcontact.com)**'s AI Voice Agent, by **[ICT Innovations](https://www.ictinnovations.com)** / **[ICT Vision](https://ict.vision)**. Author: **Tahir Almas**. Companion project: [`asterisk-ai-voice-agent`](https://github.com/ictinnovations/asterisk-ai-voice-agent).
+
+MIT licensed — see [LICENSE](LICENSE).

piper_tts_server-0.1.0/README.md

@@ -0,0 +1,96 @@
+# piper-tts-server
+
+**Paced, streaming [Piper](https://github.com/OHF-Voice/piper1-gpl) TTS for real-time voice pipelines** — Asterisk AudioSocket, RTP, or a browser WebSocket. Optional ElevenLabs cloud voices with automatic local fallback.
+
+[![CI](https://github.com/ictinnovations/piper-tts-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ictinnovations/piper-tts-server/actions)
+[![PyPI](https://img.shields.io/pypi/v/piper-tts-server.svg)](https://pypi.org/project/piper-tts-server/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+If you have tried to bolt Piper onto a phone call and hit **dead air before the greeting**, **the first few words clipped**, or **the caller only hearing the tail of each sentence** — this library is the fix. It packages the three things that make Piper work in a real-time loop:
+
+1. **Process-wide voice cache.** `PiperVoice.load()` costs 2.5–5.5 s. Loading per request means that much dead air before every utterance. Voices load once and are reused.
+2. **A single synthesis lock.** Piper phonemizes via espeak-ng, whose C API is **not thread-safe**. All synthesis is serialized behind one lock so concurrent calls don't corrupt each other.
+3. **Deadline-based frame pacing.** Real-time transports forward each frame the instant it arrives; bursting a whole utterance overruns the far end's jitter buffer. `PacedWriter` releases exactly one frame per interval on a monotonic deadline — and **re-clamps every frame** so a synthesis stall never turns into a catch-up burst that clips the next words.
+
+## Install
+
+```bash
+pip install "piper-tts-server[all]"     # library + server + piper + elevenlabs
+# or minimal:
+pip install piper-tts-server            # library core (numpy only)
+pip install "piper-tts-server[piper,server]"
+```
+
+Download a Piper voice (`.onnx` + `.onnx.json`) into a `voices/` directory — see the [Piper voices list](https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/voices.md).
+
+## Run the service
+
+```bash
+PIPER_TTS_VOICES_DIR=voices PIPER_TTS_DEFAULT_VOICE=en_US-amy-medium \
+  piper-tts-server            # listens on 127.0.0.1:8080
+```
+
+```bash
+# one-shot WAV
+curl -X POST localhost:8080/synthesize \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"Hello from Piper."}' --output hello.wav
+
+# paced streaming slin16 frames (feed straight to AudioSocket/RTP)
+curl -N -X POST localhost:8080/synthesize/stream \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"Your call is being connected.","paced":true}' --output frames.slin
+```
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /health` | status + cached voices |
+| `POST /warm` `{voice_id}` | preload a voice into the cache |
+| `POST /synthesize` `{text, voice_id, provider, format}` | one-shot `wav` (default) or raw `pcm` |
+| `POST /synthesize/stream` `{text, …, paced}` | chunked frames; `paced:true` = deadline-clocked |
+
+## Use as a library (no HTTP in the media path)
+
+```python
+from piper_tts_server import StreamingTTS, PacedWriter, tts_sanitize
+
+tts = StreamingTTS(voices_dir="voices", default_voice_path="voices/en_US-amy-medium.onnx")
+await tts.start()
+
+writer = PacedWriter(my_audiosocket_write, frame_ms=20)   # sink: async fn(bytes)
+async for frame in tts.synthesise(tts_sanitize(text)):
+    await writer.write(frame)                              # 320 bytes / 20 ms, paced
+```
+
+See [`examples/asterisk_audiosocket.md`](examples/asterisk_audiosocket.md) for the full AudioSocket wiring and streaming-LLM sentence chunking.
+
+## Configuration
+
+All via env (or `ServerConfig`): `PIPER_TTS_HOST`, `PIPER_TTS_PORT`, `PIPER_TTS_VOICES_DIR`, `PIPER_TTS_DEFAULT_VOICE`, `PIPER_TTS_PROVIDER` (`piper`|`elevenlabs`), `PIPER_TTS_ELEVENLABS_API_KEY`, `PIPER_TTS_SAMPLE_RATE` (default `8000`), `PIPER_TTS_FRAME_MS` (default `20`), `PIPER_TTS_WARM_ON_START`.
+
+Default output is **8 kHz slin16 / 20 ms frames** (telephony). Set `PIPER_TTS_SAMPLE_RATE=16000` for wideband.
+
+### ElevenLabs with local fallback
+
+Set `PIPER_TTS_PROVIDER=elevenlabs` + `PIPER_TTS_ELEVENLABS_API_KEY` and pass a `voice_id`. Any failure falls back to the local Piper default voice so the stream never goes silent; a `401/403` disables further cloud attempts for that engine.
+
+## Development
+
+```bash
+pip install "piper-tts-server[dev]"
+pytest          # pure-DSP, sanitize, and pacing tests run without Piper installed
+```
+
+## Licensing
+
+This package is **MIT licensed** and contains no Piper source code. Piper is an optional extra, imported lazily only when the local engine is used — the core library installs with numpy alone, and the test suite runs without Piper present.
+
+Piper itself is a separate project under a different licence. The maintained release ([`OHF-Voice/piper1-gpl`](https://github.com/OHF-Voice/piper1-gpl), PyPI [`piper-tts`](https://pypi.org/project/piper-tts/)) is **GPL-3.0-or-later**; the older MIT `rhasspy/piper` is archived. If you install the `[piper]` or `[all]` extra, the resulting combined installation is subject to GPL-3.0 terms. The ElevenLabs provider, and the pacing and sanitising helpers on their own, pull in no GPL code.
+
+**Not affiliated with, or endorsed by, the Open Home Foundation or the Piper project.** This is an independent server and library that drives Piper as one of several backends.
+
+## Provenance & credits
+
+Extracted and generalized from the TTS layer of **[ICTContact](https://www.ictcontact.com)**'s AI Voice Agent, by **[ICT Innovations](https://www.ictinnovations.com)** / **[ICT Vision](https://ict.vision)**. Author: **Tahir Almas**. Companion project: [`asterisk-ai-voice-agent`](https://github.com/ictinnovations/asterisk-ai-voice-agent).
+
+MIT licensed — see [LICENSE](LICENSE).

piper_tts_server-0.1.0/piper_tts_server/__init__.py

@@ -0,0 +1,16 @@
+"""piper-tts-server: a paced, streaming Piper (+ElevenLabs) TTS microservice."""
+
+from .tts import StreamingTTS, resample_linear, resolve_voice_path, warm, pcm_to_wav_bytes
+from .pacing import PacedWriter, make_silence_frame
+from .sanitize import tts_sanitize, split_for_tts
+from .config import ServerConfig
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "StreamingTTS", "resample_linear", "resolve_voice_path", "warm", "pcm_to_wav_bytes",
+    "PacedWriter", "make_silence_frame",
+    "tts_sanitize", "split_for_tts",
+    "ServerConfig",
+    "__version__",
+]

piper_tts_server-0.1.0/piper_tts_server/__main__.py

@@ -0,0 +1,4 @@
+from .server import run
+
+if __name__ == "__main__":
+    run()

piper_tts_server-0.1.0/piper_tts_server/config.py

@@ -0,0 +1,44 @@
+"""Runtime configuration, sourced from constructor args or environment."""
+
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ServerConfig:
+    host: str = "127.0.0.1"
+    port: int = 8080
+    voices_dir: str = "voices"
+    default_voice: Optional[str] = None          # basename without .onnx, or a path
+    provider: str = "piper"                       # piper | elevenlabs
+    elevenlabs_api_key: str = ""
+    target_sample_rate: int = 8000
+    frame_ms: int = 20
+    warm_on_start: bool = True                    # preload default voice at boot
+
+    @classmethod
+    def from_env(cls) -> "ServerConfig":
+        def _b(name: str, default: bool) -> bool:
+            v = os.environ.get(name)
+            return default if v is None else v.strip().lower() in ("1", "true", "yes", "on")
+        return cls(
+            host=os.environ.get("PIPER_TTS_HOST", cls.host),
+            port=int(os.environ.get("PIPER_TTS_PORT", cls.port)),
+            voices_dir=os.environ.get("PIPER_TTS_VOICES_DIR", cls.voices_dir),
+            default_voice=os.environ.get("PIPER_TTS_DEFAULT_VOICE") or None,
+            provider=os.environ.get("PIPER_TTS_PROVIDER", cls.provider),
+            elevenlabs_api_key=os.environ.get("PIPER_TTS_ELEVENLABS_API_KEY", ""),
+            target_sample_rate=int(os.environ.get("PIPER_TTS_SAMPLE_RATE", cls.target_sample_rate)),
+            frame_ms=int(os.environ.get("PIPER_TTS_FRAME_MS", cls.frame_ms)),
+            warm_on_start=_b("PIPER_TTS_WARM_ON_START", cls.warm_on_start),
+        )
+
+    def default_voice_path(self) -> Optional[str]:
+        """Resolve default_voice (basename or path) to a filesystem path."""
+        if not self.default_voice:
+            return None
+        if os.path.isfile(self.default_voice):
+            return self.default_voice
+        cand = os.path.join(self.voices_dir, f"{self.default_voice}.onnx")
+        return cand if os.path.isfile(cand) else None

piper_tts_server-0.1.0/piper_tts_server/pacing.py

@@ -0,0 +1,71 @@
+"""
+Deadline-based frame pacing.
+
+Why pace at all
+---------------
+When TTS output is forwarded to a real-time transport (Asterisk AudioSocket,
+an RTP leg, a WebSocket to a browser), each frame is sent onward the instant
+it arrives. Bursting a whole utterance overruns the far end's ~100-200 ms
+jitter buffer and the listener hears only the tail of each chunk.
+
+The fix is to release exactly one frame per frame-interval on a *deadline*
+clock, never faster. The subtle bug this solves (and re-solves every frame):
+if synthesis latency stalls the loop, the deadline goes stale and the next
+frames would burst to "catch up". `PacedWriter.write` re-clamps the deadline to
+`now` every frame, so a stall never produces a burst -- pacing resumes cleanly
+from the present instant.
+"""
+
+import asyncio
+import time
+from typing import Awaitable, Callable, Optional
+
+
+class PacedWriter:
+    """Releases frames at a fixed cadence on a monotonic deadline clock.
+
+    Parameters
+    ----------
+    sink:
+        async callable invoked with each frame's bytes (write to socket, etc.).
+    frame_ms:
+        frame interval in milliseconds (default 20).
+    clock:
+        monotonic time source in seconds. Defaults to a loop-relative clock;
+        pass ``time.monotonic`` for a loop-independent one.
+    """
+
+    def __init__(self, sink: Callable[[bytes], Awaitable[None]],
+                 frame_ms: int = 20,
+                 clock: Optional[Callable[[], float]] = None):
+        self._sink = sink
+        self._frame_sec = frame_ms / 1000.0
+        self._clock = clock
+        self._deadline = 0.0
+        self.frames_out = 0
+
+    def _now(self) -> float:
+        if self._clock is not None:
+            return self._clock()
+        return asyncio.get_event_loop().time()
+
+    def reset(self) -> None:
+        """Drop the accumulated deadline (call before a fresh talk-spurt)."""
+        self._deadline = 0.0
+
+    async def write(self, frame: bytes) -> None:
+        """Send one frame, then sleep until its pacing deadline."""
+        now = self._now()
+        # Re-clamp: never let a stalled deadline cause a burst.
+        self._deadline = max(self._deadline, now)
+        await self._sink(frame)
+        self.frames_out += 1
+        self._deadline += self._frame_sec
+        delay = self._deadline - self._now()
+        if delay > 0:
+            await asyncio.sleep(delay)
+
+
+def make_silence_frame(sample_rate: int = 8000, frame_ms: int = 20) -> bytes:
+    """A single silent mono 16-bit PCM frame (useful for pre-roll / keepalive)."""
+    return b"\x00" * (int(sample_rate * (frame_ms / 1000.0)) * 2)

piper_tts_server-0.1.0/piper_tts_server/sanitize.py

@@ -0,0 +1,56 @@
+"""
+Text preparation for TTS.
+
+LLM output is written for chat: markdown emphasis and emoji that a TTS engine
+would try to pronounce ("asterisk asterisk...") or garble. `tts_sanitize`
+strips to plain speakable text. `split_for_tts` chunks streaming LLM output at
+sentence boundaries so synthesis can start before the full reply arrives --
+including Urdu full stop (U+06D4), Arabic question mark (U+061F), and
+Devanagari danda (U+0964), which the ASCII-only default would miss.
+"""
+
+import re
+from typing import List, Tuple
+
+# Sentence end: latin/urdu/devanagari terminators, or a clause break (comma,
+# semicolon, colon) followed by more text -- lets synthesis start mid-reply.
+_SENT_END = re.compile(r"([.!?؟।۔]\s|[,;:]\s(?=\S))")
+
+_MD_STRIP = re.compile(r"[*_`#~]+")
+_NON_SPEAKABLE = re.compile(
+    "["
+    "\U0001F000-\U0001FAFF"   # emoji & symbols
+    "\U00002190-\U000021FF"   # arrows
+    "\U00002600-\U000027BF"   # misc symbols / dingbats
+    "\U0001F1E6-\U0001F1FF"   # regional indicators
+    "️‍"            # variation selector / zero-width joiner
+    "]+"
+)
+
+
+def tts_sanitize(text: str) -> str:
+    """Strip markdown and non-speakable glyphs; collapse whitespace."""
+    text = _MD_STRIP.sub("", text)
+    text = _NON_SPEAKABLE.sub("", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def split_for_tts(buf: str, force_flush: bool = False) -> Tuple[List[str], str]:
+    """Return (complete chunks ready for TTS, remaining buffer).
+
+    Feed streaming LLM deltas in; emit each completed sentence/clause as soon
+    as it closes. Pass force_flush=True at end-of-stream to flush the tail.
+    """
+    chunks: List[str] = []
+    remaining = buf
+    while True:
+        m = _SENT_END.search(remaining)
+        if not m:
+            break
+        end = m.end()
+        chunks.append(remaining[:end].strip())
+        remaining = remaining[end:]
+    if force_flush and remaining.strip():
+        chunks.append(remaining.strip())
+        remaining = ""
+    return chunks, remaining

piper_tts_server-0.1.0/piper_tts_server/server.py

@@ -0,0 +1,169 @@
+"""
+HTTP microservice around StreamingTTS (aiohttp).
+
+Endpoints
+---------
+GET  /health
+    -> {"status":"ok","provider":..,"sample_rate":..,"cached_voices":[..]}
+
+POST /warm            {"voice_id": "en_US-amy-medium"}
+    Preload a voice into the process-wide cache. Returns {"warmed": path}.
+
+POST /synthesize      {"text": "...", "voice_id": "...", "provider": "...",
+                       "format": "wav"|"pcm"}
+    One-shot synthesis. Returns audio/wav (default) or raw slin16 PCM
+    (application/octet-stream) at the configured sample rate.
+
+POST /synthesize/stream   same body, plus optional "paced": true
+    Chunked transfer of fixed-size frames (frame_ms). With "paced": true the
+    frames are released on the pacing deadline clock -- feed this straight to
+    a real-time transport. Without it, frames are sent as fast as synthesized.
+
+A per-voice StreamingTTS is cached and reused; the underlying PiperVoice is
+shared process-wide via tts._VOICE_CACHE.
+"""
+
+import asyncio
+import logging
+from typing import Dict
+
+from aiohttp import web
+
+from .config import ServerConfig
+from .pacing import PacedWriter
+from . import tts as tts_mod
+
+log = logging.getLogger("piper_tts_server.server")
+
+
+class TTSService:
+    def __init__(self, cfg: ServerConfig):
+        self.cfg = cfg
+        self._engines: Dict[str, tts_mod.StreamingTTS] = {}
+        self._lock = asyncio.Lock()
+
+    async def engine_for(self, voice_id: str, provider: str) -> tts_mod.StreamingTTS:
+        key = f"{provider}:{voice_id}"
+        eng = self._engines.get(key)
+        if eng is not None:
+            return eng
+        async with self._lock:
+            eng = self._engines.get(key)
+            if eng is None:
+                eng = tts_mod.StreamingTTS(
+                    provider=provider,
+                    voice_id=voice_id or self.cfg.default_voice,
+                    api_key=self.cfg.elevenlabs_api_key,
+                    voices_dir=self.cfg.voices_dir,
+                    default_voice_path=self.cfg.default_voice_path(),
+                    target_sample_rate=self.cfg.target_sample_rate,
+                    frame_ms=self.cfg.frame_ms,
+                )
+                await eng.start()
+                self._engines[key] = eng
+        return eng
+
+
+async def health(request: web.Request) -> web.Response:
+    cfg: ServerConfig = request.app["cfg"]
+    return web.json_response({
+        "status": "ok",
+        "provider": cfg.provider,
+        "sample_rate": cfg.target_sample_rate,
+        "frame_ms": cfg.frame_ms,
+        "cached_voices": sorted(tts_mod._VOICE_CACHE.keys()),
+    })
+
+
+async def warm(request: web.Request) -> web.Response:
+    cfg: ServerConfig = request.app["cfg"]
+    body = await request.json()
+    voice_id = body.get("voice_id") or cfg.default_voice
+    path = tts_mod.resolve_voice_path(voice_id, cfg.voices_dir, cfg.default_voice_path())
+    await tts_mod.warm(path)
+    return web.json_response({"warmed": path})
+
+
+async def synthesize(request: web.Request) -> web.Response:
+    cfg: ServerConfig = request.app["cfg"]
+    svc: TTSService = request.app["svc"]
+    body = await request.json()
+    text = (body.get("text") or "").strip()
+    if not text:
+        return web.json_response({"error": "text required"}, status=400)
+    provider = body.get("provider") or cfg.provider
+    voice_id = body.get("voice_id") or cfg.default_voice
+    fmt = (body.get("format") or "wav").lower()
+
+    eng = await svc.engine_for(voice_id, provider)
+    pcm = await eng.synthesise_pcm(text)
+
+    if fmt == "pcm":
+        return web.Response(body=pcm.tobytes(), content_type="application/octet-stream",
+                            headers={"X-Sample-Rate": str(cfg.target_sample_rate)})
+    wav = tts_mod.pcm_to_wav_bytes(pcm, cfg.target_sample_rate)
+    return web.Response(body=wav, content_type="audio/wav")
+
+
+async def synthesize_stream(request: web.Request) -> web.StreamResponse:
+    cfg: ServerConfig = request.app["cfg"]
+    svc: TTSService = request.app["svc"]
+    body = await request.json()
+    text = (body.get("text") or "").strip()
+    if not text:
+        return web.json_response({"error": "text required"}, status=400)
+    provider = body.get("provider") or cfg.provider
+    voice_id = body.get("voice_id") or cfg.default_voice
+    paced = bool(body.get("paced", False))
+
+    eng = await svc.engine_for(voice_id, provider)
+
+    resp = web.StreamResponse(status=200, headers={
+        "Content-Type": "application/octet-stream",
+        "X-Sample-Rate": str(cfg.target_sample_rate),
+        "X-Frame-Ms": str(cfg.frame_ms),
+    })
+    await resp.prepare(request)
+
+    if paced:
+        writer = PacedWriter(resp.write, frame_ms=cfg.frame_ms)
+        async for frame in eng.synthesise(text):
+            await writer.write(frame)
+    else:
+        async for frame in eng.synthesise(text):
+            await resp.write(frame)
+    await resp.write_eof()
+    return resp
+
+
+def build_app(cfg: ServerConfig) -> web.Application:
+    app = web.Application()
+    app["cfg"] = cfg
+    app["svc"] = TTSService(cfg)
+    app.add_routes([
+        web.get("/health", health),
+        web.post("/warm", warm),
+        web.post("/synthesize", synthesize),
+        web.post("/synthesize/stream", synthesize_stream),
+    ])
+
+    async def _on_start(app: web.Application) -> None:
+        if cfg.warm_on_start and cfg.provider == "piper":
+            path = cfg.default_voice_path()
+            if path:
+                try:
+                    await tts_mod.warm(path)
+                except Exception as exc:  # pragma: no cover
+                    log.warning("warm_on_start failed: %s", exc)
+
+    app.on_startup.append(_on_start)
+    return app
+
+
+def run(cfg: ServerConfig = None) -> None:
+    logging.basicConfig(level=logging.INFO,
+                        format="%(asctime)s %(name)s %(levelname)s %(message)s")
+    cfg = cfg or ServerConfig.from_env()
+    log.info("piper-tts-server on %s:%d (provider=%s, %d Hz, voices=%s)",
+             cfg.host, cfg.port, cfg.provider, cfg.target_sample_rate, cfg.voices_dir)
+    web.run_app(build_app(cfg), host=cfg.host, port=cfg.port, print=None)

piper_tts_server-0.1.0/piper_tts_server/tts.py

@@ -0,0 +1,266 @@
+"""
+Streaming TTS engine: Piper (local, ONNX) + optional ElevenLabs (cloud).
+
+Synthesizes text to PCM, resamples to the target sample rate, and yields
+fixed-size frames (default 20 ms @ 8 kHz slin16 -- the Asterisk AudioSocket
+format) so callers can stream them straight into a paced writer, an
+AudioSocket connection, a WebSocket, or a WAV file.
+
+Why this exists as a standalone package
+---------------------------------------
+Two hard-won details make Piper usable in a real-time voice pipeline, and
+both are baked in here:
+
+  1. Process-wide voice cache. `PiperVoice.load()` takes 2.5-5.5 s (ONNX
+     model load). Loading per request means every call starts with that
+     much dead air. Voices are cached process-wide, keyed by path.
+
+  2. A single synthesis lock. Piper phonemizes via espeak-ng, whose C API
+     is NOT thread-safe, and a cached PiperVoice is shared across requests.
+     All synthesis is serialized behind one asyncio.Lock.
+
+Providers (see StreamingTTS.provider):
+  piper       -- local ONNX voice under `voices_dir`. Default voice is
+                 configurable; resolution prefers `{voices_dir}/{voice_id}.onnx`.
+  elevenlabs  -- cloud API (needs api_key + voice_id). Audio is requested as
+                 pcm_16000 and resampled. Any failure falls back to the local
+                 Piper default voice so the stream never goes silent; a
+                 401/403 disables further ElevenLabs attempts for the session.
+"""
+
+import asyncio
+import io
+import logging
+import os
+import wave
+from typing import AsyncIterator, Optional
+
+import numpy as np
+
+log = logging.getLogger("piper_tts_server.tts")
+
+# ---- Defaults (all overridable via TTSConfig / constructor) ----------------
+DEFAULT_TARGET_SAMPLE_RATE = 8000   # slin16 / Asterisk AudioSocket
+DEFAULT_FRAME_MS           = 20
+
+ELEVEN_URL_TMPL      = "https://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream"
+ELEVEN_DEFAULT_MODEL = "eleven_flash_v2_5"
+ELEVEN_SAMPLE_RATE   = 16000  # we request output_format=pcm_16000
+
+# Process-wide voice cache + a single synthesis lock (espeak-ng phonemizer is
+# not thread-safe; a cached PiperVoice is shared across requests).
+_VOICE_CACHE: dict = {}
+_VOICE_LOCK: Optional[asyncio.Lock] = None
+
+
+def _frame_bytes(sample_rate: int, frame_ms: int) -> int:
+    """Bytes in one mono 16-bit PCM frame of `frame_ms` at `sample_rate`."""
+    return int(sample_rate * (frame_ms / 1000.0)) * 2
+
+
+def resolve_voice_path(voice_id: Optional[str], voices_dir: str,
+                       default_voice_path: Optional[str] = None) -> str:
+    """
+    Pick a voice .onnx file. Priority:
+      1. {voices_dir}/{voice_id}.onnx   if voice_id given and the file exists
+      2. default_voice_path             if it exists
+      3. the single .onnx in voices_dir if exactly one is present
+    Raises RuntimeError if nothing resolves.
+    """
+    if voice_id:
+        candidate = os.path.join(voices_dir, f"{voice_id}.onnx")
+        if os.path.isfile(candidate):
+            return candidate
+        log.warning("voice_id=%r requested but %s not found", voice_id, candidate)
+    if default_voice_path and os.path.isfile(default_voice_path):
+        return default_voice_path
+    if os.path.isdir(voices_dir):
+        onnx = [f for f in os.listdir(voices_dir) if f.endswith(".onnx")]
+        if len(onnx) == 1:
+            return os.path.join(voices_dir, onnx[0])
+    raise RuntimeError(
+        f"no Piper voice available (voice_id={voice_id}, "
+        f"default={default_voice_path}, voices_dir={voices_dir})")
+
+
+def resample_linear(pcm16: np.ndarray, src_sr: int, dst_sr: int) -> np.ndarray:
+    """Cheap linear resampler. Aliasing acceptable for <=16 kHz phone audio."""
+    if src_sr == dst_sr:
+        return pcm16
+    ratio = dst_sr / src_sr
+    out_len = int(len(pcm16) * ratio)
+    if out_len <= 1:
+        return np.zeros(0, dtype=np.int16)
+    src_idx = np.linspace(0, len(pcm16) - 1, out_len, dtype=np.float32)
+    lo = src_idx.astype(np.int32)
+    hi = np.minimum(lo + 1, len(pcm16) - 1)
+    frac = src_idx - lo
+    out = (1.0 - frac) * pcm16[lo].astype(np.float32) + frac * pcm16[hi].astype(np.float32)
+    return out.astype(np.int16)
+
+
+def iter_frames(pcm: np.ndarray, frame_bytes: int) -> AsyncIterator[bytes]:
+    """Yield PCM as fixed-size frames, padding the final partial frame with
+    silence to keep a constant cadence."""
+    view = pcm.tobytes()
+    for off in range(0, len(view), frame_bytes):
+        chunk = view[off:off + frame_bytes]
+        if len(chunk) < frame_bytes:
+            chunk = chunk + b"\x00" * (frame_bytes - len(chunk))
+        yield chunk
+
+
+def pcm_to_wav_bytes(pcm: np.ndarray, sample_rate: int) -> bytes:
+    """Wrap slin16 mono PCM in a WAV container (for the non-streaming API)."""
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(sample_rate)
+        wf.writeframes(pcm.tobytes())
+    return buf.getvalue()
+
+
+class StreamingTTS:
+    """One synthesis context. Reusable across many synthesise() calls."""
+
+    def __init__(self, provider: str = "piper", voice_id: Optional[str] = None,
+                 model: str = "", api_key: Optional[str] = None,
+                 voices_dir: str = "voices",
+                 default_voice_path: Optional[str] = None,
+                 target_sample_rate: int = DEFAULT_TARGET_SAMPLE_RATE,
+                 frame_ms: int = DEFAULT_FRAME_MS):
+        self.provider   = (provider or "piper").strip().lower()
+        self.voice_id   = voice_id
+        self.model      = model
+        self.api_key    = api_key or ""
+        self.voices_dir = voices_dir
+        self.default_voice_path = default_voice_path
+        self.target_sr  = int(target_sample_rate)
+        self.frame_ms   = int(frame_ms)
+        self.frame_bytes = _frame_bytes(self.target_sr, self.frame_ms)
+        self.voice_path = default_voice_path
+        self._voice     = None
+        self._native_sr = None
+        self._eleven          = False
+        self._eleven_disabled = False
+        self._client          = None
+
+    async def start(self) -> None:
+        if self.provider == "elevenlabs":
+            if self.api_key and self.voice_id:
+                import httpx  # lazy: only needed for cloud TTS
+                self._client = httpx.AsyncClient(timeout=httpx.Timeout(15.0, connect=5.0))
+                self._eleven = True
+                log.info("TTS ready: elevenlabs voice=%s model=%s (piper fallback armed)",
+                         self.voice_id, self.model or ELEVEN_DEFAULT_MODEL)
+                return
+            log.warning("provider=elevenlabs but %s missing; using piper",
+                        "api_key" if not self.api_key else "voice_id")
+        elif self.provider != "piper":
+            log.warning("provider=%s not implemented; using piper", self.provider)
+        await self._ensure_piper()
+        log.info("TTS ready: voice=%s native_sr=%d -> %d Hz",
+                 os.path.basename(self.voice_path), self._native_sr, self.target_sr)
+
+    async def _ensure_piper(self) -> None:
+        """Load (or fetch from cache) the local Piper voice."""
+        global _VOICE_LOCK
+        if self._voice is not None:
+            return
+        piper_voice_id = None if self._eleven else self.voice_id
+        self.voice_path = resolve_voice_path(piper_voice_id, self.voices_dir,
+                                             self.default_voice_path)
+        log.info("TTS voice file resolved: %s", self.voice_path)
+        if _VOICE_LOCK is None:
+            _VOICE_LOCK = asyncio.Lock()
+        async with _VOICE_LOCK:
+            voice = _VOICE_CACHE.get(self.voice_path)
+            if voice is None:
+                from piper import PiperVoice  # lazy: clean import without piper installed
+                voice = await asyncio.to_thread(PiperVoice.load, self.voice_path)
+                _VOICE_CACHE[self.voice_path] = voice
+                log.info("TTS voice loaded + cached: %s", os.path.basename(self.voice_path))
+        self._voice = voice
+        self._native_sr = self._voice.config.sample_rate
+
+    async def _eleven_pcm(self, text: str) -> np.ndarray:
+        url = ELEVEN_URL_TMPL.format(voice_id=self.voice_id)
+        model = self.model if (self.model or "").startswith("eleven") else ELEVEN_DEFAULT_MODEL
+        resp = await self._client.post(
+            url,
+            params={"output_format": f"pcm_{ELEVEN_SAMPLE_RATE}"},
+            headers={"xi-api-key": self.api_key},
+            json={"text": text, "model_id": model},
+        )
+        resp.raise_for_status()
+        raw = resp.content
+        pcm = np.frombuffer(raw[: len(raw) // 2 * 2], dtype=np.int16)
+        return resample_linear(pcm, ELEVEN_SAMPLE_RATE, self.target_sr)
+
+    async def _piper_pcm(self, text: str) -> np.ndarray:
+        await self._ensure_piper()
+
+        def _synth() -> bytes:
+            buf = io.BytesIO()
+            with wave.open(buf, "wb") as wf:
+                self._voice.synthesize(text, wf)
+            buf.seek(0)
+            with wave.open(buf) as wf:
+                return wf.readframes(wf.getnframes())
+
+        # Serialize synthesis: espeak-ng phonemizer is not thread-safe and the
+        # PiperVoice is shared across requests.
+        async with _VOICE_LOCK:
+            pcm_bytes = await asyncio.to_thread(_synth)
+        pcm = np.frombuffer(pcm_bytes, dtype=np.int16)
+        if self._native_sr != self.target_sr:
+            pcm = resample_linear(pcm, self._native_sr, self.target_sr)
+        return pcm
+
+    async def synthesise_pcm(self, text: str) -> np.ndarray:
+        """Return the whole utterance as one slin16 PCM array at target_sr."""
+        if not text.strip():
+            return np.zeros(0, dtype=np.int16)
+        pcm = None
+        if self._eleven and not self._eleven_disabled:
+            try:
+                pcm = await self._eleven_pcm(text)
+            except Exception as exc:
+                status = getattr(getattr(exc, "response", None), "status_code", None)
+                if status in (401, 403):
+                    self._eleven_disabled = True
+                    log.error("elevenlabs auth failed (%s); piper fallback for the session", status)
+                else:
+                    log.warning("elevenlabs synthesis failed (%s); piper fallback for this utterance", exc)
+        if pcm is None:
+            pcm = await self._piper_pcm(text)
+        return pcm
+
+    async def synthesise(self, text: str) -> AsyncIterator[bytes]:
+        """Yield slin16 PCM bytes as fixed-size (frame_ms) chunks."""
+        pcm = await self.synthesise_pcm(text)
+        for chunk in iter_frames(pcm, self.frame_bytes):
+            yield chunk
+
+    async def close(self) -> None:
+        self._voice = None
+        if self._client is not None:
+            try:
+                await self._client.aclose()
+            except Exception:
+                pass
+            self._client = None
+
+
+async def warm(voice_path: str) -> None:
+    """Preload a Piper voice into the process-wide cache (call at startup)."""
+    global _VOICE_LOCK
+    if _VOICE_LOCK is None:
+        _VOICE_LOCK = asyncio.Lock()
+    async with _VOICE_LOCK:
+        if voice_path in _VOICE_CACHE:
+            return
+        from piper import PiperVoice
+        _VOICE_CACHE[voice_path] = await asyncio.to_thread(PiperVoice.load, voice_path)
+        log.info("warmed voice: %s", os.path.basename(voice_path))

piper_tts_server-0.1.0/piper_tts_server.egg-info/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: piper-tts-server
+Version: 0.1.0
+Summary: Paced, streaming Piper (+ElevenLabs) TTS microservice for real-time voice pipelines (Asterisk AudioSocket, RTP, WebSocket).
+Author-email: Tahir Almas <tahir@ictinnovations.com>
+Maintainer-email: ICT Innovations <info@ictinnovations.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ictinnovations/piper-tts-server
+Project-URL: Repository, https://github.com/ictinnovations/piper-tts-server
+Project-URL: Derived From, https://www.ictcontact.com
+Keywords: piper,tts,text-to-speech,asterisk,audiosocket,voice,streaming,realtime,voip
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Communications :: Telephony
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Provides-Extra: piper
+Requires-Dist: piper-tts>=1.2; extra == "piper"
+Provides-Extra: server
+Requires-Dist: aiohttp>=3.8; extra == "server"
+Provides-Extra: elevenlabs
+Requires-Dist: httpx>=0.24; extra == "elevenlabs"
+Provides-Extra: all
+Requires-Dist: piper-tts>=1.2; extra == "all"
+Requires-Dist: aiohttp>=3.8; extra == "all"
+Requires-Dist: httpx>=0.24; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: aiohttp>=3.8; extra == "dev"
+Dynamic: license-file
+
+# piper-tts-server
+
+**Paced, streaming [Piper](https://github.com/OHF-Voice/piper1-gpl) TTS for real-time voice pipelines** — Asterisk AudioSocket, RTP, or a browser WebSocket. Optional ElevenLabs cloud voices with automatic local fallback.
+
+[![CI](https://github.com/ictinnovations/piper-tts-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ictinnovations/piper-tts-server/actions)
+[![PyPI](https://img.shields.io/pypi/v/piper-tts-server.svg)](https://pypi.org/project/piper-tts-server/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+If you have tried to bolt Piper onto a phone call and hit **dead air before the greeting**, **the first few words clipped**, or **the caller only hearing the tail of each sentence** — this library is the fix. It packages the three things that make Piper work in a real-time loop:
+
+1. **Process-wide voice cache.** `PiperVoice.load()` costs 2.5–5.5 s. Loading per request means that much dead air before every utterance. Voices load once and are reused.
+2. **A single synthesis lock.** Piper phonemizes via espeak-ng, whose C API is **not thread-safe**. All synthesis is serialized behind one lock so concurrent calls don't corrupt each other.
+3. **Deadline-based frame pacing.** Real-time transports forward each frame the instant it arrives; bursting a whole utterance overruns the far end's jitter buffer. `PacedWriter` releases exactly one frame per interval on a monotonic deadline — and **re-clamps every frame** so a synthesis stall never turns into a catch-up burst that clips the next words.
+
+## Install
+
+```bash
+pip install "piper-tts-server[all]"     # library + server + piper + elevenlabs
+# or minimal:
+pip install piper-tts-server            # library core (numpy only)
+pip install "piper-tts-server[piper,server]"
+```
+
+Download a Piper voice (`.onnx` + `.onnx.json`) into a `voices/` directory — see the [Piper voices list](https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/voices.md).
+
+## Run the service
+
+```bash
+PIPER_TTS_VOICES_DIR=voices PIPER_TTS_DEFAULT_VOICE=en_US-amy-medium \
+  piper-tts-server            # listens on 127.0.0.1:8080
+```
+
+```bash
+# one-shot WAV
+curl -X POST localhost:8080/synthesize \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"Hello from Piper."}' --output hello.wav
+
+# paced streaming slin16 frames (feed straight to AudioSocket/RTP)
+curl -N -X POST localhost:8080/synthesize/stream \
+  -H 'Content-Type: application/json' \
+  -d '{"text":"Your call is being connected.","paced":true}' --output frames.slin
+```
+
+| Endpoint | Purpose |
+|----------|---------|
+| `GET /health` | status + cached voices |
+| `POST /warm` `{voice_id}` | preload a voice into the cache |
+| `POST /synthesize` `{text, voice_id, provider, format}` | one-shot `wav` (default) or raw `pcm` |
+| `POST /synthesize/stream` `{text, …, paced}` | chunked frames; `paced:true` = deadline-clocked |
+
+## Use as a library (no HTTP in the media path)
+
+```python
+from piper_tts_server import StreamingTTS, PacedWriter, tts_sanitize
+
+tts = StreamingTTS(voices_dir="voices", default_voice_path="voices/en_US-amy-medium.onnx")
+await tts.start()
+
+writer = PacedWriter(my_audiosocket_write, frame_ms=20)   # sink: async fn(bytes)
+async for frame in tts.synthesise(tts_sanitize(text)):
+    await writer.write(frame)                              # 320 bytes / 20 ms, paced
+```
+
+See [`examples/asterisk_audiosocket.md`](examples/asterisk_audiosocket.md) for the full AudioSocket wiring and streaming-LLM sentence chunking.
+
+## Configuration
+
+All via env (or `ServerConfig`): `PIPER_TTS_HOST`, `PIPER_TTS_PORT`, `PIPER_TTS_VOICES_DIR`, `PIPER_TTS_DEFAULT_VOICE`, `PIPER_TTS_PROVIDER` (`piper`|`elevenlabs`), `PIPER_TTS_ELEVENLABS_API_KEY`, `PIPER_TTS_SAMPLE_RATE` (default `8000`), `PIPER_TTS_FRAME_MS` (default `20`), `PIPER_TTS_WARM_ON_START`.
+
+Default output is **8 kHz slin16 / 20 ms frames** (telephony). Set `PIPER_TTS_SAMPLE_RATE=16000` for wideband.
+
+### ElevenLabs with local fallback
+
+Set `PIPER_TTS_PROVIDER=elevenlabs` + `PIPER_TTS_ELEVENLABS_API_KEY` and pass a `voice_id`. Any failure falls back to the local Piper default voice so the stream never goes silent; a `401/403` disables further cloud attempts for that engine.
+
+## Development
+
+```bash
+pip install "piper-tts-server[dev]"
+pytest          # pure-DSP, sanitize, and pacing tests run without Piper installed
+```
+
+## Licensing
+
+This package is **MIT licensed** and contains no Piper source code. Piper is an optional extra, imported lazily only when the local engine is used — the core library installs with numpy alone, and the test suite runs without Piper present.
+
+Piper itself is a separate project under a different licence. The maintained release ([`OHF-Voice/piper1-gpl`](https://github.com/OHF-Voice/piper1-gpl), PyPI [`piper-tts`](https://pypi.org/project/piper-tts/)) is **GPL-3.0-or-later**; the older MIT `rhasspy/piper` is archived. If you install the `[piper]` or `[all]` extra, the resulting combined installation is subject to GPL-3.0 terms. The ElevenLabs provider, and the pacing and sanitising helpers on their own, pull in no GPL code.
+
+**Not affiliated with, or endorsed by, the Open Home Foundation or the Piper project.** This is an independent server and library that drives Piper as one of several backends.
+
+## Provenance & credits
+
+Extracted and generalized from the TTS layer of **[ICTContact](https://www.ictcontact.com)**'s AI Voice Agent, by **[ICT Innovations](https://www.ictinnovations.com)** / **[ICT Vision](https://ict.vision)**. Author: **Tahir Almas**. Companion project: [`asterisk-ai-voice-agent`](https://github.com/ictinnovations/asterisk-ai-voice-agent).
+
+MIT licensed — see [LICENSE](LICENSE).

piper_tts_server-0.1.0/piper_tts_server.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+piper_tts_server/__init__.py
+piper_tts_server/__main__.py
+piper_tts_server/config.py
+piper_tts_server/pacing.py
+piper_tts_server/sanitize.py
+piper_tts_server/server.py
+piper_tts_server/tts.py
+piper_tts_server.egg-info/PKG-INFO
+piper_tts_server.egg-info/SOURCES.txt
+piper_tts_server.egg-info/dependency_links.txt
+piper_tts_server.egg-info/entry_points.txt
+piper_tts_server.egg-info/requires.txt
+piper_tts_server.egg-info/top_level.txt
+tests/test_dsp.py
+tests/test_pacing.py
+tests/test_sanitize.py

piper_tts_server-0.1.0/piper_tts_server.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

piper_tts_server-0.1.0/piper_tts_server.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+piper-tts-server = piper_tts_server.server:run

piper_tts_server-0.1.0/piper_tts_server.egg-info/requires.txt

@@ -0,0 +1,19 @@
+numpy>=1.21
+
+[all]
+piper-tts>=1.2
+aiohttp>=3.8
+httpx>=0.24
+
+[dev]
+pytest>=7
+aiohttp>=3.8
+
+[elevenlabs]
+httpx>=0.24
+
+[piper]
+piper-tts>=1.2
+
+[server]
+aiohttp>=3.8

piper_tts_server-0.1.0/piper_tts_server.egg-info/top_level.txt

@@ -0,0 +1 @@
+piper_tts_server

piper_tts_server-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "piper-tts-server"
+version = "0.1.0"
+description = "Paced, streaming Piper (+ElevenLabs) TTS microservice for real-time voice pipelines (Asterisk AudioSocket, RTP, WebSocket)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Tahir Almas", email = "tahir@ictinnovations.com" }]
+maintainers = [{ name = "ICT Innovations", email = "info@ictinnovations.com" }]
+keywords = ["piper", "tts", "text-to-speech", "asterisk", "audiosocket", "voice", "streaming", "realtime", "voip"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Communications :: Telephony",
+]
+dependencies = [
+    "numpy>=1.21",
+]
+
+[project.optional-dependencies]
+piper = ["piper-tts>=1.2"]
+server = ["aiohttp>=3.8"]
+elevenlabs = ["httpx>=0.24"]
+all = ["piper-tts>=1.2", "aiohttp>=3.8", "httpx>=0.24"]
+dev = ["pytest>=7", "aiohttp>=3.8"]
+
+[project.urls]
+Homepage = "https://github.com/ictinnovations/piper-tts-server"
+Repository = "https://github.com/ictinnovations/piper-tts-server"
+"Derived From" = "https://www.ictcontact.com"
+
+[project.scripts]
+piper-tts-server = "piper_tts_server.server:run"
+
+[tool.setuptools]
+packages = ["piper_tts_server"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

piper_tts_server-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

piper_tts_server-0.1.0/tests/test_dsp.py

@@ -0,0 +1,32 @@
+import numpy as np
+from piper_tts_server.tts import resample_linear, iter_frames, pcm_to_wav_bytes, _frame_bytes
+
+
+def test_resample_identity():
+    pcm = np.arange(100, dtype=np.int16)
+    out = resample_linear(pcm, 8000, 8000)
+    assert np.array_equal(out, pcm)
+
+
+def test_resample_downsamples_length():
+    pcm = np.zeros(2205, dtype=np.int16)          # 0.1 s @ 22050
+    out = resample_linear(pcm, 22050, 8000)
+    assert abs(len(out) - 800) <= 1               # ~0.1 s @ 8000
+
+
+def test_frame_bytes():
+    assert _frame_bytes(8000, 20) == 320          # 160 samples * 2 bytes
+    assert _frame_bytes(16000, 20) == 640
+
+
+def test_iter_frames_pads_tail():
+    pcm = np.zeros(170, dtype=np.int16)           # 340 bytes -> 2 frames (320 + padded)
+    frames = list(iter_frames(pcm, 320))
+    assert len(frames) == 2
+    assert all(len(f) == 320 for f in frames)
+
+
+def test_wav_roundtrip_header():
+    pcm = np.zeros(160, dtype=np.int16)
+    wav = pcm_to_wav_bytes(pcm, 8000)
+    assert wav[:4] == b"RIFF" and wav[8:12] == b"WAVE"

piper_tts_server-0.1.0/tests/test_pacing.py

@@ -0,0 +1,44 @@
+import asyncio
+from piper_tts_server.pacing import PacedWriter, make_silence_frame
+
+
+def test_silence_frame_size():
+    assert len(make_silence_frame(8000, 20)) == 320
+    assert make_silence_frame(8000, 20) == b"\x00" * 320
+
+
+def test_paced_writer_uses_deadline_clock():
+    # A virtual clock that does not advance on its own: proves pacing is driven
+    # by the deadline, and that a stalled clock never causes negative sleeps.
+    t = {"now": 0.0}
+    sleeps = []
+
+    async def sink(_frame):
+        pass
+
+    async def fake_sleep(d):
+        sleeps.append(d)
+        t["now"] += d               # advance virtual time by the slept amount
+
+    async def run():
+        w = PacedWriter(sink, frame_ms=20, clock=lambda: t["now"])
+        orig_sleep = asyncio.sleep
+        asyncio.sleep = fake_sleep   # type: ignore
+        try:
+            for _ in range(5):
+                await w.write(b"\x00" * 320)
+        finally:
+            asyncio.sleep = orig_sleep  # type: ignore
+        return w
+
+    w = asyncio.get_event_loop().run_until_complete(run())
+    assert w.frames_out == 5
+    # every scheduled delay is one frame interval, never a burst / negative
+    assert all(abs(d - 0.02) < 1e-9 for d in sleeps)
+
+
+def test_reset_clears_deadline():
+    w = PacedWriter(lambda _f: None, frame_ms=20)
+    w._deadline = 123.0
+    w.reset()
+    assert w._deadline == 0.0

piper_tts_server-0.1.0/tests/test_sanitize.py

@@ -0,0 +1,33 @@
+from piper_tts_server.sanitize import tts_sanitize, split_for_tts
+
+
+def test_strips_markdown_and_emoji():
+    assert tts_sanitize("**Hello** _world_ `code`") == "Hello world code"
+    assert tts_sanitize("Great news 🎉🚀 done") == "Great news done"
+
+
+def test_collapses_whitespace():
+    assert tts_sanitize("a\n\n b   c\t") == "a b c"
+
+
+def test_split_on_sentence_end():
+    chunks, rem = split_for_tts("Hello there. How are")
+    assert chunks == ["Hello there."]
+    assert rem == "How are"
+
+
+def test_split_urdu_full_stop():
+    chunks, rem = split_for_tts("سلام ۔ ")
+    assert chunks == ["سلام ۔"]
+
+
+def test_force_flush_tail():
+    chunks, rem = split_for_tts("no terminator here", force_flush=True)
+    assert chunks == ["no terminator here"]
+    assert rem == ""
+
+
+def test_clause_break_lets_synthesis_start_early():
+    chunks, rem = split_for_tts("First part, and the rest")
+    assert chunks == ["First part,"]
+    assert rem == "and the rest"