openspeechapi 0.2.1__tar.gz → 0.2.4__tar.gz

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

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

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

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

{openspeechapi-0.2.1 → openspeechapi-0.2.4}/openspeechapi/core/models.py

@@ -50,6 +50,16 @@ class STTOptions:
     beam_size: int | None = None
     compute_type: str | None = None
     fp16: bool | None = None
+    # Per-call override for the trailing-silence threshold (ms) before
+    # the provider treats utterance as ended. ``None`` means "use the
+    # provider's configured default" (e.g. iflytek's ``settings.vad_eos``
+    # populated from speech_providers.yaml). Wallex passes the
+    # panel-supplied ``parameter.iat.eos`` here when the panel needs a
+    # different value than the deployment default — for instance a
+    # kiosk that wants more responsive cut-off than a slow-paced
+    # voice assistant. Providers that don't support VAD finalization
+    # (Whisper, Faster-Whisper) silently ignore this field.
+    vad_eos: int | None = None
 
 
 @dataclass

{openspeechapi-0.2.1 → openspeechapi-0.2.4}/openspeechapi/dispatch/dispatcher.py

@@ -114,9 +114,17 @@ class _STTNamespace:
         self,
         provider: str,
         stream: "AsyncIterator[bytes]",
+        opts: "STTOptions | None" = None,
     ) -> "AsyncIterator[Transcription]":
-        """Stream audio chunks to the named provider and yield transcriptions."""
-        async for item in self._dispatcher._transcribe_stream(provider, stream):
+        """Stream audio chunks to the named provider and yield transcriptions.
+
+        ``opts`` is optional and forwarded to the provider's
+        ``transcribe_stream`` if it declares the parameter (current users:
+        iFlytek STT honors ``opts.vad_eos`` for per-call silence-threshold
+        override). Providers that don't declare ``opts`` raise TypeError;
+        callers that don't need the override should leave it ``None``.
+        """
+        async for item in self._dispatcher._transcribe_stream(provider, stream, opts):
             yield item
 
     async def fanout(
@@ -479,8 +487,14 @@ class ServiceDispatcher:
         self,
         provider: str,
         stream: AsyncIterator[bytes],
+        opts: STTOptions | None = None,
     ) -> AsyncIterator[Transcription]:
-        """Stream audio chunks to the provider and yield Transcription results."""
+        """Stream audio chunks to the provider and yield Transcription results.
+
+        ``opts`` is forwarded to the provider only when non-None — keeps
+        the call site backward-compatible with providers whose
+        ``transcribe_stream`` predates the ``opts`` parameter.
+        """
         handle = self._get_handle(provider)
         await self._lifecycle.ensure_ready(provider)
         ctx = InvokeContext(
@@ -488,6 +502,11 @@ class ServiceDispatcher:
             method="transcribe_stream",
             exec_mode=handle.exec_mode,
         )
+        # Build kwargs conditionally so providers without ``opts`` in
+        # their signature don't get a surprise unexpected-keyword error.
+        invoke_kwargs: dict[str, Any] = {"stream": stream}
+        if opts is not None:
+            invoke_kwargs["opts"] = opts
         with bind_context(
             provider=provider, engine=provider, request_id=ctx.request_id
         ):
@@ -500,7 +519,7 @@ class ServiceDispatcher:
                 count = 0
                 try:
                     async for item in handle.executor.invoke_stream(
-                        "transcribe_stream", stream=stream
+                        "transcribe_stream", **invoke_kwargs
                     ):
                         count += 1
                         yield item

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

@@ -29,7 +29,58 @@ class IflytekSTTSettings(BaseSettings):
     app_id: str = ""
     api_key: str = ""
     api_secret: str = ""
+    # iFlytek-canonical language code. Acceptable values per iFlytek
+    # IAT docs: ``zh_cn``, ``en_us``, ``ja_jp``, ``ko_kr``, ``ru-ru``.
+    # Common ISO short codes (``en``, ``zh``, ``ja``, ``ko``, ``ru``)
+    # are accepted here and mapped on the request hop — see
+    # ``_canonical_language``. iFlytek silently falls back to ``zh_cn``
+    # when given an unrecognised value, so the alias mapping prevents
+    # English audio from being transcribed by the Chinese model
+    # (caught 04-28 by an "english only" deployment that had set
+    # ``language: en`` and got hanzi back).
     language: str = "zh_cn"
+    # ``vad_eos`` — milliseconds of trailing silence iFlytek treats as
+    # end-of-sentence before emitting the final result (``status == 2``).
+    # iFlytek's documented default is 2000; lower values give faster
+    # finalization at the cost of cutting off slow speakers mid-thought.
+    # The 04-28 17:00 audit found vad_eos=2000 contributed ~89% of the
+    # user-perceived latency budget — the speech itself only used ~3 s
+    # but iFlytek waited an additional 2 s of silence before declaring
+    # final. Common production values: 800-1000 (responsive),
+    # 1500 (conservative), 2000 (default, slow). Below ~500 risks
+    # premature finalization on natural pauses. Per-deployment override
+    # via ``speech_providers.yaml`` so different sites can pick their
+    # own latency-vs-tolerance trade-off.
+    vad_eos: int = 2000
+
+
+# iFlytek expects the full locale tag; common ISO short codes need to
+# be translated. Keys are casefolded for tolerant matching. Values are
+# the iFlytek-canonical strings the WS request will carry.
+_LANGUAGE_ALIASES: dict[str, str] = {
+    # Canonical pass-through (allow case variation)
+    "zh_cn": "zh_cn", "en_us": "en_us", "ja_jp": "ja_jp",
+    "ko_kr": "ko_kr", "ru-ru": "ru-ru", "ru_ru": "ru-ru",
+    # ISO 639-1 short codes — most config sources use these
+    "zh": "zh_cn", "zh-cn": "zh_cn", "zh-hans": "zh_cn",
+    "en": "en_us", "en-us": "en_us", "en-gb": "en_us",
+    "ja": "ja_jp", "ja-jp": "ja_jp",
+    "ko": "ko_kr", "ko-kr": "ko_kr",
+    "ru": "ru-ru",
+}
+
+
+def _canonical_language(raw: str | None) -> str:
+    """Translate a configured language string to iFlytek's canonical form.
+
+    Returns the iFlytek-canonical code (e.g. ``en_us``). Unknown inputs
+    pass through unchanged so iFlytek surfaces a real protocol error
+    instead of silently falling back to Chinese.
+    """
+    if not raw:
+        return "zh_cn"
+    return _LANGUAGE_ALIASES.get(raw.casefold().strip(), raw)
+
 
 class IflytekSTT(STTProvider):
     name = "iflytek-stt"
@@ -37,7 +88,9 @@ class IflytekSTT(STTProvider):
     execution_mode = ExecMode.IN_PROCESS
     settings_cls = IflytekSTTSettings
     capabilities = {Capability.BATCH, Capability.STREAMING, Capability.MULTILINGUAL}
-    field_options = {"language": ["zh_cn", "en_us"]}
+    field_options = {
+        "language": ["zh_cn", "en_us", "ja_jp", "ko_kr", "ru-ru"],
+    }
 
     _WS_HOST = "iat-api.xfyun.cn"
     _WS_PATH = "/v2/iat"
@@ -55,7 +108,25 @@ class IflytekSTT(STTProvider):
         if self._client is None:
             self._client = httpx.AsyncClient(timeout=60.0)
             self._owns_client = True
-        logger.info("{} provider started", self.name)
+        # Surface the effective language (after alias mapping) and
+        # vad_eos at startup so deployments can verify the iFlytek model
+        # and silence-finalization threshold that will actually run.
+        # The 04-28 audit caught a deployment shipping ``language: en``
+        # (invalid) which silently routed every request to the Chinese
+        # model; an analogous oversight on vad_eos would silently
+        # double the user-perceived latency. Logging both makes
+        # mis-config obvious from the first request.
+        effective = _canonical_language(self.settings.language)
+        if effective != self.settings.language:
+            logger.info(
+                "{} provider started, language={!r} (canonicalized from {!r}), vad_eos={}ms",
+                self.name, effective, self.settings.language, self.settings.vad_eos,
+            )
+        else:
+            logger.info(
+                "{} provider started, language={!r}, vad_eos={}ms",
+                self.name, effective, self.settings.vad_eos,
+            )
 
     async def stop(self) -> None:
         if self._client and self._owns_client:
@@ -138,15 +209,31 @@ class IflytekSTT(STTProvider):
                 frame_data = base64.b64encode(chunk).decode("utf-8")
 
                 if status == 0:
-                    # First frame includes common and business params
+                    # First frame includes common and business params.
+                    # ``accent="mandarin"`` is only meaningful for the
+                    # Chinese model; sending it on en_us / ja_jp / etc.
+                    # is a wire-level no-op on iFlytek's side but
+                    # confuses anyone reading the request body, so
+                    # gate it on the canonical language.
+                    canon = _canonical_language(self.settings.language)
+                    # Per-call override (``opts.vad_eos``) trumps the
+                    # provider default. Wallex routes the panel's
+                    # ``parameter.iat.eos`` through here so a kiosk
+                    # can ship a tighter or looser silence threshold
+                    # than the deployment yaml.
+                    eos = (opts.vad_eos
+                           if opts is not None and opts.vad_eos is not None
+                           else self.settings.vad_eos)
+                    business = {
+                        "language": canon,
+                        "domain": "iat",
+                        "vad_eos": eos,
+                    }
+                    if canon == "zh_cn":
+                        business["accent"] = "mandarin"
                     msg = {
                         "common": {"app_id": self.settings.app_id},
-                        "business": {
-                            "language": self.settings.language,
-                            "domain": "iat",
-                            "accent": "mandarin",
-                            "vad_eos": 2000,
-                        },
+                        "business": business,
                         "data": {
                             "status": 0,
                             "format": "audio/L16;rate=16000",
@@ -209,7 +296,7 @@ class IflytekSTT(STTProvider):
         return "".join(parts)
 
     async def transcribe_stream(
-        self, stream: AsyncIterator[bytes]
+        self, stream: AsyncIterator[bytes], opts: STTOptions | None = None,
     ) -> AsyncIterator[Transcription]:
         """Stream audio chunks to iFlytek via WebSocket and yield transcriptions.
 
@@ -263,15 +350,26 @@ class IflytekSTT(STTProvider):
                             break
                         frame_data = base64.b64encode(chunk).decode("utf-8")
                         if is_first:
+                            # See transcribe() for rationale on
+                            # canonicalizing language and gating accent.
+                            canon = _canonical_language(self.settings.language)
+                            # Per-call ``opts.vad_eos`` (e.g. wallex
+                            # forwarding the panel's ``parameter.iat.eos``)
+                            # trumps the provider's configured default.
+                            eos = (opts.vad_eos
+                                   if opts is not None and opts.vad_eos is not None
+                                   else self.settings.vad_eos)
+                            business = {
+                                "language": canon,
+                                "domain": "iat",
+                                "dwa": "wpgs",
+                                "vad_eos": eos,
+                            }
+                            if canon == "zh_cn":
+                                business["accent"] = "mandarin"
                             msg = {
                                 "common": {"app_id": self.settings.app_id},
-                                "business": {
-                                    "language": self.settings.language,
-                                    "domain": "iat",
-                                    "accent": "mandarin",
-                                    "dwa": "wpgs",
-                                    "vad_eos": 2000,
-                                },
+                                "business": business,
                                 "data": {
                                     "status": 0,
                                     "format": "audio/L16;rate=16000",

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

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