openspeechapi 0.2.4__tar.gz → 0.2.6__tar.gz

{openspeechapi-0.2.4 → openspeechapi-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openspeechapi
-Version: 0.2.4
+Version: 0.2.6
 Summary: Unified speech interface for STT/TTS providers
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27

{openspeechapi-0.2.4 → openspeechapi-0.2.6}/openspeechapi/__init__.py

@@ -1,6 +1,6 @@
 """OpenSpeechAPI — Unified speech interface for STT/TTS providers."""
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"
 
 from openspeechapi.config import load_config
 from openspeechapi.core.base import SpeechProvider, STTProvider, TTSProvider

{openspeechapi-0.2.4 → openspeechapi-0.2.6}/openspeechapi/logging_config.py

@@ -185,10 +185,24 @@ def bind_context(
         if v is not None:
             bindings[k] = v
 
+    # NOTE: we drive logger.contextualize manually instead of using its
+    # ``with`` form so we can swallow the cleanup-time ValueError that
+    # loguru raises when bind_context wraps a ``yield`` in an async
+    # generator and that generator is closed from a different asyncio
+    # Context (e.g. the consumer task gets cancelled). The token loguru
+    # tries to reset was set in the original Context and Python forbids
+    # cross-context reset. The bindings are scoped to the closing
+    # Context anyway, so dropping the reset is harmless — Python GCs the
+    # vanishing Context's vars regardless.
+    contextualizer = logger.contextualize(**bindings)
+    contextualizer.__enter__()
     try:
-        with logger.contextualize(**bindings):
-            yield bindings
+        yield bindings
     finally:
+        try:
+            contextualizer.__exit__(None, None, None)
+        except ValueError:
+            pass
         for var, token in reversed(resets):
             try:
                 var.reset(token)

{openspeechapi-0.2.4 → openspeechapi-0.2.6}/openspeechapi/providers/stt/iflytek.py

@@ -52,6 +52,26 @@ class IflytekSTTSettings(BaseSettings):
     # via ``speech_providers.yaml`` so different sites can pick their
     # own latency-vs-tolerance trade-off.
     vad_eos: int = 2000
+    # ``ltc`` — sentence-level timestamp granularity sent in the
+    # business block of the IAT request (1 = sentence segments only;
+    # 2 = + word boundaries; 3 = + character boundaries). Java's
+    # ``AsrConfig.ltc`` defaults to 3; we mirror that so downstream
+    # consumers expecting per-character timing offsets keep working.
+    # Lower values shave a few bytes per response and slightly reduce
+    # post-processing work for callers that don't use the timestamps.
+    ltc: int = 3
+    # ``ws_host`` / ``ws_path`` — iFlytek IAT WebSocket endpoint. The
+    # default ``iat-api.xfyun.cn`` is the global endpoint; multi-region
+    # deployments (e.g. directed-domain endpoints such as
+    # ``ws-api-dx.xfyun.cn``) override these in yaml or via env var
+    # so the WS URL never requires a code change.
+    ws_host: str = "iat-api.xfyun.cn"
+    ws_path: str = "/v2/iat"
+    # ``timeout_secs`` — connect / read timeout for the underlying
+    # httpx AsyncClient. Java's AsrConfig defaults to 15s; we mirror
+    # that. Lower if the network has aggressive proxies, higher only
+    # if the iFlytek endpoint is consistently slow to handshake.
+    timeout_secs: int = 15
 
 
 # iFlytek expects the full locale tag; common ISO short codes need to
@@ -92,9 +112,6 @@ class IflytekSTT(STTProvider):
         "language": ["zh_cn", "en_us", "ja_jp", "ko_kr", "ru-ru"],
     }
 
-    _WS_HOST = "iat-api.xfyun.cn"
-    _WS_PATH = "/v2/iat"
-
     def __init__(self, settings: IflytekSTTSettings | None = None) -> None:
         self.settings = settings or IflytekSTTSettings()
         self._client: httpx.AsyncClient | None = None
@@ -106,7 +123,7 @@ class IflytekSTT(STTProvider):
 
     async def start(self) -> None:
         if self._client is None:
-            self._client = httpx.AsyncClient(timeout=60.0)
+            self._client = httpx.AsyncClient(timeout=float(self.settings.timeout_secs))
             self._owns_client = True
         # Surface the effective language (after alias mapping) and
         # vad_eos at startup so deployments can verify the iFlytek model
@@ -142,10 +159,12 @@ class IflytekSTT(STTProvider):
         now = datetime.now(tz=timezone.utc)
         date = formatdate(timeval=now.timestamp(), localtime=False, usegmt=True)
 
+        host = self.settings.ws_host
+        path = self.settings.ws_path
         signature_origin = (
-            f"host: {self._WS_HOST}\n"
+            f"host: {host}\n"
             f"date: {date}\n"
-            f"GET {self._WS_PATH} HTTP/1.1"
+            f"GET {path} HTTP/1.1"
         )
         signature_sha = hmac.new(
             self.settings.api_secret.encode("utf-8"),
@@ -165,9 +184,9 @@ class IflytekSTT(STTProvider):
         ).decode("utf-8")
 
         params = urllib.parse.urlencode(
-            {"authorization": authorization, "date": date, "host": self._WS_HOST}
+            {"authorization": authorization, "date": date, "host": host}
         )
-        return f"wss://{self._WS_HOST}{self._WS_PATH}?{params}"
+        return f"wss://{host}{path}?{params}"
 
     async def transcribe(
         self, audio: AudioData, opts: STTOptions | None = None
@@ -228,6 +247,7 @@ class IflytekSTT(STTProvider):
                         "language": canon,
                         "domain": "iat",
                         "vad_eos": eos,
+                        "ltc": self.settings.ltc,
                     }
                     if canon == "zh_cn":
                         business["accent"] = "mandarin"
@@ -364,6 +384,7 @@ class IflytekSTT(STTProvider):
                                 "domain": "iat",
                                 "dwa": "wpgs",
                                 "vad_eos": eos,
+                                "ltc": self.settings.ltc,
                             }
                             if canon == "zh_cn":
                                 business["accent"] = "mandarin"

{openspeechapi-0.2.4 → openspeechapi-0.2.6}/openspeechapi/providers/tts/iflytek.py

@@ -29,16 +29,22 @@ class IflytekTTSSettings(BaseSettings):
     voice: str = "xiaoyan"
     speed: int = 50
     # Audio output encoding requested from iFlytek.
-    #   - "lame": MP3 frames (default; smaller, but caller must decode)
-    #   - "raw":  16-bit PCM @ 16 kHz mono, big-endian L16 (drop-in
-    #             playable as raw PCM; required by callers that wrap the
-    #             bytes in a fixed-format wire envelope and assume PCM,
-    #             e.g. wallex's RESP_VOICE which advertises
-    #             encoding=raw/bitDepth=16/sampleRate=16000 to the
-    #             panel — feeding MP3 bytes through that envelope plays
-    #             back as pure noise on the speaker).
+    #   - "lame":  MP3 frames (default; smaller, but caller must decode)
+    #   - "raw":   16-bit PCM @ 16 kHz mono, big-endian L16 (drop-in
+    #              playable as raw PCM; required by callers that wrap the
+    #              bytes in a fixed-format wire envelope and assume PCM,
+    #              e.g. wallex's RESP_VOICE which advertises
+    #              encoding=raw/bitDepth=16/sampleRate=16000 to the
+    #              panel — feeding MP3 bytes through that envelope plays
+    #              back as pure noise on the speaker).
+    #   - "speex"/"speex-wb-7": Speex narrowband / wideband (low-bitrate,
+    #              used by some embedded Wallex panels with constrained
+    #              uplink). Requires ``speex_size`` to declare the frame
+    #              size iFlytek should produce. Caller must run a Speex
+    #              decoder; not auto-handled by browsers.
     # Default stays "lame" for backward-compat; deployments that need
-    # PCM (wallex / direct hardware playback) override via yaml.
+    # PCM (wallex / direct hardware playback) or Speex (embedded panels)
+    # override via yaml.
     aue: str = "lame"
     # Output sample rate for raw PCM mode (only meaningful when
     # aue="raw"). 16000 matches what the panel and the iFlytek
@@ -50,6 +56,22 @@ class IflytekTTSSettings(BaseSettings):
     volume: int = 50
     # Pitch (0-100). Same rationale as volume.
     pitch: int = 50
+    # Speex frame size (only meaningful when aue startswith "speex").
+    # iFlytek expects an integer that selects a Speex bitrate / frame
+    # mode; ``0`` is "auto-pick by aue tag". Leave 0 unless the client
+    # decoder requires a specific frame size. Mirrors Java
+    # ``AsrConfig.speex-size`` / ``TtsConfig`` parameter.
+    speex_size: int = 0
+    # ``ws_host`` / ``ws_path`` — iFlytek TTS WebSocket endpoint.
+    # Override in yaml (or via ``OPENSPEECH_IFLYTEK_TTS_HOST`` env var)
+    # for region-specific endpoints. Default is the global endpoint.
+    ws_host: str = "tts-api.xfyun.cn"
+    ws_path: str = "/v2/tts"
+    # ``timeout_secs`` — connect / read timeout for the underlying
+    # httpx AsyncClient. Java's TtsConfig defaults to 8s; we mirror
+    # that for parity. Increase only when the iFlytek endpoint is
+    # consistently slow to handshake.
+    timeout_secs: int = 8
 
 class IflytekTTS(TTSProvider):
     name = "iflytek-tts"
@@ -66,12 +88,9 @@ class IflytekTTS(TTSProvider):
             # English assistant-style voices used by wallex deployments.
             "x4_enuk_ashleigh_assist",
         ],
-        "aue": ["lame", "raw"],
+        "aue": ["lame", "raw", "speex", "speex-wb-7"],
     }
 
-    _WS_HOST = "tts-api.xfyun.cn"
-    _WS_PATH = "/v2/tts"
-
     def __init__(self, settings: IflytekTTSSettings | None = None) -> None:
         self.settings = settings or IflytekTTSSettings()
         self._client: httpx.AsyncClient | None = None
@@ -83,7 +102,7 @@ class IflytekTTS(TTSProvider):
 
     async def start(self) -> None:
         if self._client is None:
-            self._client = httpx.AsyncClient(timeout=60.0)
+            self._client = httpx.AsyncClient(timeout=float(self.settings.timeout_secs))
             self._owns_client = True
 
     async def stop(self) -> None:
@@ -99,10 +118,12 @@ class IflytekTTS(TTSProvider):
         now = datetime.now(tz=timezone.utc)
         date = formatdate(timeval=now.timestamp(), localtime=False, usegmt=True)
 
+        host = self.settings.ws_host
+        path = self.settings.ws_path
         signature_origin = (
-            f"host: {self._WS_HOST}\n"
+            f"host: {host}\n"
             f"date: {date}\n"
-            f"GET {self._WS_PATH} HTTP/1.1"
+            f"GET {path} HTTP/1.1"
         )
         signature_sha = hmac.new(
             self.settings.api_secret.encode("utf-8"),
@@ -122,9 +143,9 @@ class IflytekTTS(TTSProvider):
         ).decode("utf-8")
 
         params = urllib.parse.urlencode(
-            {"authorization": authorization, "date": date, "host": self._WS_HOST}
+            {"authorization": authorization, "date": date, "host": host}
         )
-        return f"wss://{self._WS_HOST}{self._WS_PATH}?{params}"
+        return f"wss://{host}{path}?{params}"
 
     async def synthesize(
         self, text: str, opts: TTSOptions | None = None
@@ -138,8 +159,17 @@ class IflytekTTS(TTSProvider):
         # callers downstream may set wire-protocol encoding metadata from
         # this field, and a wrong tag on the bytes plays back as noise on
         # raw-PCM consumers.
-        fmt = "pcm_s16le" if self.settings.aue == "raw" else "mp3"
-        sr = self.settings.auf_rate if self.settings.aue == "raw" else 16000
+        aue = self.settings.aue
+        if aue == "raw":
+            fmt = "pcm_s16le"
+            sr = self.settings.auf_rate
+        elif aue.startswith("speex"):
+            # Speex narrowband is 8 kHz, wideband ("speex-wb-*") is 16 kHz.
+            fmt = "speex"
+            sr = 16000 if "wb" in aue else 8000
+        else:
+            fmt = "mp3"
+            sr = 16000
         logger.info(
             "iFlytek TTS: {} chunks, {} bytes total, format={}, sample_rate={}",
             len(parts), len(audio_bytes), fmt, sr,
@@ -191,7 +221,8 @@ class IflytekTTS(TTSProvider):
             "pitch": self.settings.pitch,
             "tte": "UTF8",
         }
-        if self.settings.aue == "lame":
+        aue = self.settings.aue
+        if aue == "lame":
             # ``sfl=1`` (stream-frame-length) is an MP3-only knob that
             # tells iFlytek to emit per-frame audio rather than waiting
             # for the whole file. It has no meaning for raw PCM (raw is
@@ -199,11 +230,17 @@ class IflytekTTS(TTSProvider):
             # combo with a code 10005 "invalid parameter" — so we only
             # send it on the lame path.
             business["sfl"] = 1
-        else:
+        elif aue == "raw":
             # Raw / L16 mode requires ``auf`` to declare the PCM
             # sample-rate iFlytek should produce. Java wallex sends
             # ``audio/L16;rate=16000`` here; we mirror that exactly.
             business["auf"] = f"audio/L16;rate={self.settings.auf_rate}"
+        elif aue.startswith("speex"):
+            # Speex narrowband / wideband. ``speex_size`` is the iFlytek
+            # frame-size selector (0 = engine default; non-zero values
+            # match the Java ``TtsConfig.speex-size`` parameter).
+            if self.settings.speex_size:
+                business["speex_size"] = self.settings.speex_size
         return {
             "common": {"app_id": self.settings.app_id},
             "business": business,

{openspeechapi-0.2.4 → openspeechapi-0.2.6}/providers.example.yaml

@@ -123,7 +123,12 @@ engines:
   #   exec_mode: remote
   #   preload: true
   #   settings:
-  #     language: zh_cn
+  #     language: zh_cn        # zh_cn / en_us / ja_jp / ko_kr / ru-ru
+  #     vad_eos: 2000          # ms of trailing silence before final
+  #     ltc: 3                 # 1 sentence / 2 +word / 3 +char timestamps
+  #     ws_host: iat-api.xfyun.cn      # override for region-specific endpoints
+  #     ws_path: /v2/iat
+  #     timeout_secs: 15
 
   # # pip install 'openspeechapi[faster-whisper-stt]'
   # faster_whisper_stt:
@@ -190,7 +195,15 @@ engines:
   #   exec_mode: remote
   #   settings:
   #     voice: xiaoyan
-  #     speed: 50
+  #     speed: 50              # 0-100
+  #     volume: 50             # 0-100
+  #     pitch: 50              # 0-100
+  #     aue: lame              # lame / raw / speex / speex-wb-7
+  #     auf_rate: 16000        # only used when aue=raw (8000 / 16000 / 24000)
+  #     speex_size: 0          # only used when aue startswith speex (0 = auto)
+  #     ws_host: tts-api.xfyun.cn      # override for region-specific endpoints
+  #     ws_path: /v2/tts
+  #     timeout_secs: 8
 
   # # pip install 'openspeechapi[piper-tts]'
   # piper_tts:

{openspeechapi-0.2.4 → openspeechapi-0.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "openspeechapi"
-version = "0.2.4"
+version = "0.2.6"
 description = "Unified speech interface for STT/TTS providers"
 requires-python = ">=3.11"
 dependencies = [

{openspeechapi-0.2.4 → openspeechapi-0.2.6}/tests/unit/test_logging.py

@@ -96,6 +96,38 @@ def test_bind_context_sets_and_resets_request_id() -> None:
     assert get_request_id() is None
 
 
+def test_bind_context_aclose_from_different_asyncio_context_does_not_raise() -> None:
+    """When bind_context wraps a yield in an async generator and the generator
+    is later closed from a different asyncio Context, loguru's
+    contextualize.__exit__ raises
+    ``ValueError("<Token ...> was created in a different Context")``.
+
+    Production trace (2026-05-06): openspeechapi/dispatch/dispatcher.py
+    ``_synthesize_stream`` holds bind_context across ``yield chunk``; when
+    the consumer's task is cancelled, athrow runs the finally in a new
+    Context and the unhandled ValueError pollutes the log.
+
+    bind_context must swallow that cleanup error.
+    """
+    import asyncio
+
+    async def gen():
+        with bind_context(request_id="rid", provider="prov"):
+            for i in range(3):
+                yield i
+
+    async def driver():
+        g = gen()
+        first = await g.__anext__()
+        assert first == 0
+        # Closing from a freshly-created task puts aclose in a different
+        # asyncio Context than where bind_context was entered. This is the
+        # exact mismatch that production hit.
+        await asyncio.create_task(g.aclose())
+
+    asyncio.run(driver())
+
+
 def test_bind_context_decorates_log_records(tmp_path: Path) -> None:
     configure_logging(level="DEBUG", format="json", log_dir=str(tmp_path))
     captured: list[dict] = []