openspeechapi 0.2.1__tar.gz → 0.2.3__tar.gz

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

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

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

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

{openspeechapi-0.2.1 → openspeechapi-0.2.3}/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,23 @@ 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)
+                    business = {
+                        "language": canon,
+                        "domain": "iat",
+                        "vad_eos": self.settings.vad_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",
@@ -263,15 +342,20 @@ 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)
+                            business = {
+                                "language": canon,
+                                "domain": "iat",
+                                "dwa": "wpgs",
+                                "vad_eos": self.settings.vad_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.3}/pyproject.toml

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