openspeechapi 0.1.0__py3-none-any.whl

openspeech/providers/stt/google_cloud.py

@@ -0,0 +1,106 @@
+"""Google Cloud STT provider adapter (batch, httpx)."""
+from __future__ import annotations
+
+import base64
+from openspeech.logging_config import logger
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from openspeech.core.base import STTProvider
+
+from openspeech.core.enums import Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioData, STTOptions, Transcription
+from openspeech.core.settings import BaseSettings
+
+@dataclass
+class GoogleCloudSTTSettings(BaseSettings):
+    api_key: str = ""
+    model: str = "latest_long"
+    language: str = "en-US"
+
+class GoogleCloudSTT(STTProvider):
+    name = "google-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.REMOTE
+    settings_cls = GoogleCloudSTTSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"model": ["latest_long", "latest_short", "telephony", "command_and_search"], "language": ["en-US", "zh-CN", "ja-JP", "ko-KR", "es-ES", "fr-FR", "de-DE", "pt-BR", "it-IT", "ru-RU", "ar-SA", "hi-IN"]}
+
+    def __init__(self, settings: GoogleCloudSTTSettings | None = None) -> None:
+        self.settings = settings or GoogleCloudSTTSettings()
+        self._client: httpx.AsyncClient | None = None
+        self._owns_client: bool = True
+
+    def set_http_client(self, client) -> None:
+        self._client = client
+        self._owns_client = False
+
+    async def start(self) -> None:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=60.0)
+            self._owns_client = True
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        if self._client and self._owns_client:
+            await self._client.aclose()
+        self._client = None
+        logger.info("{} provider stopped", self.name)
+
+    async def health_check(self) -> bool:
+        return bool(self.settings.api_key)
+
+    async def transcribe(
+        self, audio: AudioData, opts: STTOptions | None = None
+    ) -> Transcription:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: request received, audio={} bytes", self.name, len(audio.data))
+        _t0 = time.perf_counter()
+        opts = opts or STTOptions()
+        language = opts.language or self.settings.language
+        model = self.settings.model
+
+        b64_audio = base64.b64encode(audio.data).decode("utf-8")
+        url = (
+            "https://speech.googleapis.com/v1/speech:recognize"
+            f"?key={self.settings.api_key}"
+        )
+        body = {
+            "config": {
+                "encoding": "LINEAR16",
+                "sampleRateHertz": audio.sample_rate,
+                "languageCode": language,
+                "model": model,
+            },
+            "audio": {"content": b64_audio},
+        }
+        response = await self._client.post(url, json=body)
+        if response.status_code != 200:
+            raise RuntimeError(
+                f"Google Cloud STT API error {response.status_code}: {response.text}"
+            )
+        data = response.json()
+        results = data.get("results", [])
+        if not results:
+            return Transcription(text="", language=language)
+        alternative = results[0]["alternatives"][0]
+        result = Transcription(
+            text=alternative.get("transcript", ""),
+            language=language,
+            confidence=alternative.get("confidence"),
+        )
+        logger.info("{}: completed in {:.0f}ms, result={} chars", self.name, (time.perf_counter() - _t0) * 1000, len(result.text))
+        return result
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        raise NotImplementedError(
+            "Google Cloud STT batch provider does not support streaming input"
+        )
+        yield  # pragma: no cover

openspeech/providers/stt/iflytek.py

@@ -0,0 +1,427 @@
+"""iFlytek (讯飞) STT provider adapter — WebSocket-based."""
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import json
+from openspeech.logging_config import logger
+import time
+import urllib.parse
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import formatdate
+from typing import Any
+
+import httpx
+import websockets
+
+from openspeech.core.base import STTProvider
+
+from openspeech.core.enums import Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioData, STTOptions, Transcription
+from openspeech.core.settings import BaseSettings
+
+@dataclass
+class IflytekSTTSettings(BaseSettings):
+    app_id: str = ""
+    api_key: str = ""
+    api_secret: str = ""
+    language: str = "zh_cn"
+
+class IflytekSTT(STTProvider):
+    name = "iflytek-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = IflytekSTTSettings
+    capabilities = {Capability.BATCH, Capability.STREAMING, Capability.MULTILINGUAL}
+    field_options = {"language": ["zh_cn", "en_us"]}
+
+    _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
+        self._owns_client: bool = True
+
+    def set_http_client(self, client) -> None:
+        self._client = client
+        self._owns_client = False
+
+    async def start(self) -> None:
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=60.0)
+            self._owns_client = True
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        if self._client and self._owns_client:
+            await self._client.aclose()
+        self._client = None
+        logger.info("{} provider stopped", self.name)
+
+    async def health_check(self) -> bool:
+        return bool(self.settings.app_id) and bool(self.settings.api_key) and bool(self.settings.api_secret)
+
+    def _build_auth_url(self) -> str:
+        """Build HMAC-SHA256 signed WebSocket URL."""
+        now = datetime.now(tz=timezone.utc)
+        date = formatdate(timeval=now.timestamp(), localtime=False, usegmt=True)
+
+        signature_origin = (
+            f"host: {self._WS_HOST}\n"
+            f"date: {date}\n"
+            f"GET {self._WS_PATH} HTTP/1.1"
+        )
+        signature_sha = hmac.new(
+            self.settings.api_secret.encode("utf-8"),
+            signature_origin.encode("utf-8"),
+            hashlib.sha256,
+        ).digest()
+        signature = base64.b64encode(signature_sha).decode("utf-8")
+
+        authorization_origin = (
+            f'api_key="{self.settings.api_key}", '
+            f'algorithm="hmac-sha256", '
+            f'headers="host date request-line", '
+            f'signature="{signature}"'
+        )
+        authorization = base64.b64encode(
+            authorization_origin.encode("utf-8")
+        ).decode("utf-8")
+
+        params = urllib.parse.urlencode(
+            {"authorization": authorization, "date": date, "host": self._WS_HOST}
+        )
+        return f"wss://{self._WS_HOST}{self._WS_PATH}?{params}"
+
+    async def transcribe(
+        self, audio: AudioData, opts: STTOptions | None = None
+    ) -> Transcription:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: request received, audio={} bytes", self.name, len(audio.data))
+        _t0 = time.perf_counter()
+
+        url = self._build_auth_url()
+        audio_bytes = audio.data
+        # iFlytek recommends ~40ms per frame at 16kHz 16bit mono = 1280 bytes.
+        # Use larger frames (8000 bytes = ~250ms) with pacing to avoid server
+        # read-timeout when sending pre-recorded audio faster than real-time.
+        frame_size = 8000  # bytes per chunk (~250ms of 16kHz 16bit mono)
+        # Pacing: small delay between frames to avoid server read-timeout
+        # when sending pre-recorded audio faster than real-time.
+        # 8000 bytes = 250ms of audio; 10ms interval = ~25x real-time.
+        frame_interval = 0.01  # 10ms between frames (~25x real-time)
+
+        result_texts: list[str] = []
+
+        async with websockets.connect(url) as ws:
+            # Send audio in chunks with interleaved receive
+            total = len(audio_bytes)
+            offset = 0
+            status = 0  # 0=first frame
+            frames_sent = 0
+
+            while offset < total:
+                end = min(offset + frame_size, total)
+                chunk = audio_bytes[offset:end]
+
+                if end >= total:
+                    status = 2  # last frame
+                elif offset > 0:
+                    status = 1  # continue
+
+                frame_data = base64.b64encode(chunk).decode("utf-8")
+
+                if status == 0:
+                    # First frame includes common and business params
+                    msg = {
+                        "common": {"app_id": self.settings.app_id},
+                        "business": {
+                            "language": self.settings.language,
+                            "domain": "iat",
+                            "accent": "mandarin",
+                            "vad_eos": 2000,
+                        },
+                        "data": {
+                            "status": 0,
+                            "format": "audio/L16;rate=16000",
+                            "encoding": "raw",
+                            "audio": frame_data,
+                        },
+                    }
+                else:
+                    msg = {
+                        "data": {
+                            "status": status,
+                            "format": "audio/L16;rate=16000",
+                            "encoding": "raw",
+                            "audio": frame_data,
+                        }
+                    }
+
+                await ws.send(json.dumps(msg))
+                frames_sent += 1
+                offset = end
+
+                # Pacing: small delay between frames to avoid server timeout
+                if status != 2 and frame_interval > 0:
+                    await asyncio.sleep(frame_interval)
+
+            logger.debug("{}: sent {} frames in {:.0f}ms", self.name, frames_sent,
+                         (time.perf_counter() - _t0) * 1000)
+
+            # Receive results
+            async for message in ws:
+                resp = json.loads(message)
+                code = resp.get("code", -1)
+                if code != 0:
+                    raise RuntimeError(
+                        f"iFlytek STT error [{code}]: {resp.get('message', 'unknown')}"
+                    )
+
+                data = resp.get("data", {})
+                result = data.get("result", {})
+                ws_items = result.get("ws", [])
+                for ws_item in ws_items:
+                    cw_list = ws_item.get("cw", [])
+                    for cw in cw_list:
+                        result_texts.append(cw.get("w", ""))
+
+                if data.get("status") == 2:
+                    break
+
+        result = Transcription(text="".join(result_texts))
+        logger.info("{}: completed in {:.0f}ms, result={} chars", self.name, (time.perf_counter() - _t0) * 1000, len(result.text))
+        return result
+
+    @staticmethod
+    def _extract_segment_text(ws_items: list[dict]) -> str:
+        """Extract text from a single response's ws array."""
+        parts: list[str] = []
+        for ws_item in ws_items:
+            for cw in ws_item.get("cw", []):
+                parts.append(cw.get("w", ""))
+        return "".join(parts)
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Transcription]:
+        """Stream audio chunks to iFlytek via WebSocket and yield transcriptions.
+
+        Each bytes chunk from *stream* is a raw PCM frame (16kHz 16bit mono).
+        A ``None`` or empty chunk signals end-of-stream (VAD end).
+
+        The implementation uses two concurrent coroutines:
+        - **sender**: reads chunks from *stream* and forwards them to iFlytek
+          with natural pacing (frames arrive at ~real-time from the mic).
+        - **receiver**: reads iFlytek responses, parses ``dwa=wpgs`` dynamic
+          correction fields (``pgs``/``rg``), maintains a segment array, and
+          yields partial ``Transcription`` on every response plus a final one
+          on ``status == 2``.
+
+        wpgs protocol:
+        - ``pgs="apd"``: append — new segment at index ``sn``
+        - ``pgs="rpl"``: replace — replace segments ``rg[0]..rg[1]`` with
+          new content, effectively a correction of earlier partial results
+        - No ``pgs`` field: legacy mode (no dynamic correction) — accumulate
+        """
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+
+        url = self._build_auth_url()
+        results: asyncio.Queue[Transcription | None] = asyncio.Queue()
+        _t0 = time.perf_counter()
+        _frames_sent = 0
+
+        # Event to signal sender to stop (set by receiver when iFlytek
+        # returns status=2 or the connection closes). This handles the case
+        # where the user doesn't click stop — iFlytek's VAD triggers a final
+        # result, and we need the sender to stop consuming the frame queue.
+        _sender_stop = asyncio.Event()
+
+        logger.debug("{}: connecting to iFlytek WebSocket...", self.name)
+        async with websockets.connect(url) as ws:
+            _t_connected = time.perf_counter()
+            logger.info("{}: WS connected in {:.0f}ms", self.name,
+                        (_t_connected - _t0) * 1000)
+
+            async def sender() -> None:
+                nonlocal _frames_sent
+                is_first = True
+                try:
+                    async for chunk in stream:
+                        # Check if receiver signaled us to stop
+                        if _sender_stop.is_set():
+                            break
+                        if chunk is None or len(chunk) == 0:
+                            # End-of-stream sentinel — send last frame
+                            break
+                        frame_data = base64.b64encode(chunk).decode("utf-8")
+                        if is_first:
+                            msg = {
+                                "common": {"app_id": self.settings.app_id},
+                                "business": {
+                                    "language": self.settings.language,
+                                    "domain": "iat",
+                                    "accent": "mandarin",
+                                    "dwa": "wpgs",
+                                    "vad_eos": 2000,
+                                },
+                                "data": {
+                                    "status": 0,
+                                    "format": "audio/L16;rate=16000",
+                                    "encoding": "raw",
+                                    "audio": frame_data,
+                                },
+                            }
+                            is_first = False
+                        else:
+                            msg = {
+                                "data": {
+                                    "status": 1,
+                                    "format": "audio/L16;rate=16000",
+                                    "encoding": "raw",
+                                    "audio": frame_data,
+                                }
+                            }
+                        await ws.send(json.dumps(msg))
+                        _frames_sent += 1
+                        if _frames_sent == 1:
+                            logger.debug("{}: first frame sent at {:.0f}ms",
+                                         self.name, (time.perf_counter() - _t0) * 1000)
+
+                    # Send empty last frame to signal end (only if WS still open)
+                    if not _sender_stop.is_set():
+                        last_msg = {
+                            "data": {
+                                "status": 2,
+                                "format": "audio/L16;rate=16000",
+                                "encoding": "raw",
+                                "audio": "",
+                            }
+                        }
+                        await ws.send(json.dumps(last_msg))
+                except websockets.exceptions.ConnectionClosed:
+                    # iFlytek closed the connection (e.g. server read timeout
+                    # or VAD-triggered close). This is expected when the user
+                    # doesn't click stop — just exit silently.
+                    pass
+                finally:
+                    logger.debug(
+                        "{}: stream sender done, sent {} frames in {:.0f}ms",
+                        self.name, _frames_sent, (time.perf_counter() - _t0) * 1000,
+                    )
+
+            async def receiver() -> None:
+                # Segment array for wpgs dynamic correction.
+                # Index = sn (sentence number from iFlytek).
+                # Each element is the text for that segment.
+                segments: list[str] = []
+                _resp_count = 0
+
+                try:
+                    async for message in ws:
+                        resp = json.loads(message)
+                        code = resp.get("code", -1)
+                        if code != 0:
+                            raise RuntimeError(
+                                f"iFlytek STT error [{code}]: {resp.get('message', 'unknown')}"
+                            )
+
+                        _resp_count += 1
+                        data = resp.get("data", {})
+                        resp_status = data.get("status", 0)
+                        result = data.get("result", {})
+                        ws_items = result.get("ws", [])
+                        pgs = result.get("pgs", "")  # "apd" or "rpl"
+                        rg = result.get("rg", [])    # [start, end] for rpl
+                        sn = result.get("sn", 0)     # segment number
+
+                        seg_text = self._extract_segment_text(ws_items)
+
+                        if _resp_count == 1:
+                            logger.debug("{}: first response at {:.0f}ms  sn={}  pgs={}",
+                                         self.name, (time.perf_counter() - _t0) * 1000,
+                                         sn, pgs or "none")
+
+                        if pgs == "rpl" and len(rg) == 2:
+                            # Replace: clear segments rg[0]..rg[1], put new
+                            # text at rg[0], remove the rest in range.
+                            start, end = rg[0], rg[1]
+                            # Ensure segments list is large enough
+                            while len(segments) <= end:
+                                segments.append("")
+                            # Clear the replaced range
+                            for i in range(start, end + 1):
+                                segments[i] = ""
+                            # Put new text at start position
+                            segments[start] = seg_text
+                        elif pgs == "apd":
+                            # Append: add/overwrite segment at index sn
+                            while len(segments) <= sn:
+                                segments.append("")
+                            segments[sn] = seg_text
+                        else:
+                            # No pgs (legacy / non-wpgs fallback): append
+                            while len(segments) <= sn:
+                                segments.append("")
+                            segments[sn] = seg_text
+
+                        # Build current full text from all segments
+                        current_text = "".join(segments).strip()
+
+                        if resp_status == 2:
+                            # Final result — stop sender
+                            _sender_stop.set()
+                            logger.info("{}: final result at {:.0f}ms  responses={}  text='{}'",
+                                        self.name, (time.perf_counter() - _t0) * 1000,
+                                        _resp_count, current_text[:60])
+                            if current_text:
+                                await results.put(
+                                    Transcription(text=current_text, is_partial=False)
+                                )
+                            break
+                        else:
+                            # Partial result — yield for real-time display
+                            if current_text:
+                                await results.put(
+                                    Transcription(text=current_text, is_partial=True)
+                                )
+
+                except websockets.exceptions.ConnectionClosed:
+                    # Connection closed by server — stop sender, emit whatever we have
+                    _sender_stop.set()
+                    current_text = "".join(segments).strip()
+                    if current_text:
+                        await results.put(
+                            Transcription(text=current_text, is_partial=False)
+                        )
+                finally:
+                    _sender_stop.set()  # ensure sender stops in all cases
+                    await results.put(None)  # sentinel
+
+            send_task = asyncio.create_task(sender())
+            recv_task = asyncio.create_task(receiver())
+
+            while True:
+                item = await results.get()
+                if item is None:
+                    break
+                yield item
+
+            logger.info(
+                "{}: stream completed in {:.0f}ms, frames={}",
+                self.name, (time.perf_counter() - _t0) * 1000, _frames_sent,
+            )
+            # Wait for tasks; suppress sender errors (e.g. ConnectionClosed
+            # that slipped past the try/except if timing was tight).
+            for task in (send_task, recv_task):
+                try:
+                    await task
+                except websockets.exceptions.ConnectionClosed:
+                    pass