openspeechapi 0.2.0__tar.gz → 0.2.3__tar.gz

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

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

{openspeechapi-0.2.0 → 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.0 → 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.0 → openspeechapi-0.2.3}/openspeechapi/providers/tts/iflytek.py

@@ -28,6 +28,28 @@ class IflytekTTSSettings(BaseSettings):
     api_secret: str = ""
     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).
+    # Default stays "lame" for backward-compat; deployments that need
+    # PCM (wallex / direct hardware playback) 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
+    # default both expect; left configurable so an 8 kHz device or
+    # a 24 kHz studio path doesn't have to fork the provider.
+    auf_rate: int = 16000
+    # Volume (0-100). iFlytek default is 50; making it explicit so
+    # the parameter parity with Java's TtsConfig is complete.
+    volume: int = 50
+    # Pitch (0-100). Same rationale as volume.
+    pitch: int = 50
 
 class IflytekTTS(TTSProvider):
     name = "iflytek-tts"
@@ -35,12 +57,17 @@ class IflytekTTS(TTSProvider):
     execution_mode = ExecMode.IN_PROCESS
     settings_cls = IflytekTTSSettings
     capabilities = {Capability.BATCH, Capability.STREAMING, Capability.MULTILINGUAL}
-    field_options = {"voice": [
-        "xiaoyan", "aisjiuxu", "aisxping", "aisjinger", "aisbabyxu",
-        "x4_lingxiaolu_em", "x4_lingfeizhe_em", "xiaoyu", "xiaoqi",
-        "xiaofeng", "xiaomei", "xiaolin", "xiaorong", "xiaoqian",
-        "catherine", "john", "laura", "yuka", "xiaoqiukor",
-    ]}
+    field_options = {
+        "voice": [
+            "xiaoyan", "aisjiuxu", "aisxping", "aisjinger", "aisbabyxu",
+            "x4_lingxiaolu_em", "x4_lingfeizhe_em", "xiaoyu", "xiaoqi",
+            "xiaofeng", "xiaomei", "xiaolin", "xiaorong", "xiaoqian",
+            "catherine", "john", "laura", "yuka", "xiaoqiukor",
+            # English assistant-style voices used by wallex deployments.
+            "x4_enuk_ashleigh_assist",
+        ],
+        "aue": ["lame", "raw"],
+    }
 
     _WS_HOST = "tts-api.xfyun.cn"
     _WS_PATH = "/v2/tts"
@@ -107,12 +134,21 @@ class IflytekTTS(TTSProvider):
         async for chunk in self.synthesize_stream(text, opts):
             parts.append(chunk.data)
         audio_bytes = b"".join(parts)
-        logger.info("iFlytek TTS: {} chunks, {} MP3 bytes total", len(parts), len(audio_bytes))
+        # Format / sample_rate must reflect what iFlytek actually returned —
+        # 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
+        logger.info(
+            "iFlytek TTS: {} chunks, {} bytes total, format={}, sample_rate={}",
+            len(parts), len(audio_bytes), fmt, sr,
+        )
         return AudioData(
             data=audio_bytes,
-            sample_rate=16000,
+            sample_rate=sr,
             channels=1,
-            format="mp3",
+            format=fmt,
         )
 
     # iFlytek voice catalog — vcn → (display name, language, group)
@@ -147,15 +183,30 @@ class IflytekTTS(TTSProvider):
         vcn = voice or self.settings.voice
         spd = int(speed * 50) if speed and speed != 1.0 else self.settings.speed
         text_b64 = base64.b64encode(text.encode("utf-8")).decode("utf-8")
+        business: dict[str, Any] = {
+            "aue": self.settings.aue,
+            "vcn": vcn,
+            "speed": spd,
+            "volume": self.settings.volume,
+            "pitch": self.settings.pitch,
+            "tte": "UTF8",
+        }
+        if self.settings.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
+            # always streamed as 40 ms slices) and iFlytek rejects the
+            # combo with a code 10005 "invalid parameter" — so we only
+            # send it on the lame path.
+            business["sfl"] = 1
+        else:
+            # 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}"
         return {
             "common": {"app_id": self.settings.app_id},
-            "business": {
-                "aue": "lame",
-                "sfl": 1,
-                "vcn": vcn,
-                "speed": spd,
-                "tte": "UTF8",
-            },
+            "business": business,
             "data": {
                 "status": 2,
                 "text": text_b64,

{openspeechapi-0.2.0 → openspeechapi-0.2.3}/pyproject.toml

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