@agentunion/kite 1.0.6 → 1.2.0

package/extensions/services/web/vendor/conversation/asr.py

@@ -0,0 +1,936 @@
+"""ASR (Automatic Speech Recognition) abstraction and implementations."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import hashlib
+import hmac
+import io
+import json
+import logging
+import random
+import time
+import uuid
+from abc import ABC, abstractmethod
+from datetime import datetime
+from time import mktime
+from urllib.parse import quote, urlencode, urlparse
+from wsgiref.handlers import format_date_time
+
+import httpx
+import websockets
+
+from .. import config as cfg
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Abstract base
+# ---------------------------------------------------------------------------
+
+class ASRProvider(ABC):
+    """Base class for all ASR (speech-to-text) providers."""
+
+    @abstractmethod
+    async def start_stream(self, language: str = "zh") -> None:
+        """Prepare the provider for a new recognition stream."""
+        ...
+
+    @abstractmethod
+    async def feed_audio(self, chunk: bytes) -> None:
+        """Feed a chunk of PCM S16LE 16 kHz mono audio."""
+        ...
+
+    @abstractmethod
+    async def get_result(self) -> str:
+        """Return the transcribed text accumulated so far and reset the buffer."""
+        ...
+
+    @abstractmethod
+    async def stop_stream(self) -> None:
+        """Tear down the recognition stream and release resources."""
+        ...
+
+    async def get_interim_result(self) -> str:
+        """Return any interim/partial text without stopping the stream.
+
+        Default returns empty string. Streaming providers can override.
+        """
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# OpenAI Whisper API
+# ---------------------------------------------------------------------------
+
+class WhisperASR(ASRProvider):
+    """OpenAI Whisper API -- accumulates audio chunks, sends for transcription."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        model: str = "whisper-1",
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.model = model
+        self._buffer = bytearray()
+        self._language = "zh"
+        self._client: httpx.AsyncClient | None = None
+
+    async def start_stream(self, language: str = "zh") -> None:
+        self._language = language
+        self._buffer = bytearray()
+        self._client = httpx.AsyncClient(timeout=30.0)
+
+    async def feed_audio(self, chunk: bytes) -> None:
+        self._buffer.extend(chunk)
+
+    async def get_result(self) -> str:
+        if not self._buffer:
+            return ""
+
+        if self._client is None:
+            logger.warning("WhisperASR: client not initialized, call start_stream first")
+            return ""
+
+        # Build a minimal WAV header so Whisper can accept the raw PCM.
+        audio_data = self._build_wav(bytes(self._buffer))
+        self._buffer = bytearray()
+
+        url = f"{self.base_url}/audio/transcriptions"
+        files = {
+            "file": ("audio.wav", io.BytesIO(audio_data), "audio/wav"),
+        }
+        data = {
+            "model": self.model,
+            "language": self._language,
+            "response_format": "json",
+        }
+        headers = {"Authorization": f"Bearer {self.api_key}"}
+
+        try:
+            resp = await self._client.post(url, headers=headers, files=files, data=data)
+            resp.raise_for_status()
+            result = resp.json()
+            return result.get("text", "")
+        except Exception:
+            logger.exception("WhisperASR: transcription request failed")
+            return ""
+
+    async def stop_stream(self) -> None:
+        self._buffer = bytearray()
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    # -- helpers --
+
+    @staticmethod
+    def _build_wav(pcm: bytes, sample_rate: int = 16000, channels: int = 1, bits: int = 16) -> bytes:
+        """Wrap raw PCM S16LE data in a minimal WAV header."""
+        data_size = len(pcm)
+        byte_rate = sample_rate * channels * bits // 8
+        block_align = channels * bits // 8
+        header = bytearray(44)
+        # RIFF header
+        header[0:4] = b"RIFF"
+        header[4:8] = (data_size + 36).to_bytes(4, "little")
+        header[8:12] = b"WAVE"
+        # fmt chunk
+        header[12:16] = b"fmt "
+        header[16:20] = (16).to_bytes(4, "little")  # chunk size
+        header[20:22] = (1).to_bytes(2, "little")  # PCM format
+        header[22:24] = channels.to_bytes(2, "little")
+        header[24:28] = sample_rate.to_bytes(4, "little")
+        header[28:32] = byte_rate.to_bytes(4, "little")
+        header[32:34] = block_align.to_bytes(2, "little")
+        header[34:36] = bits.to_bytes(2, "little")
+        # data chunk
+        header[36:40] = b"data"
+        header[40:44] = data_size.to_bytes(4, "little")
+        return bytes(header) + pcm
+
+
+# ---------------------------------------------------------------------------
+# iFlytek (Xunfei) streaming ASR via WebSocket
+# ---------------------------------------------------------------------------
+
+class XunfeiASR(ASRProvider):
+    """iFlytek streaming ASR via WebSocket (wss://iat-api.xfyun.cn/v2/iat)."""
+
+    XUNFEI_IAT_URL = "wss://iat-api.xfyun.cn/v2/iat"
+    FRAME_SIZE = 8000  # 250ms at 16kHz S16LE
+
+    def __init__(self, app_id: str, api_key: str, api_secret: str) -> None:
+        self.app_id = app_id
+        self.api_key = api_key
+        self.api_secret = api_secret
+        self._ws: websockets.WebSocketClientProtocol | None = None
+        self._buffer = bytearray()
+        self._result_text = ""
+        self._language = "zh_cn"
+        self._stream_started = False
+
+    async def start_stream(self, language: str = "zh") -> None:
+        self._language = "zh_cn" if language.startswith("zh") else language
+        self._buffer = bytearray()
+        self._result_text = ""
+        self._stream_started = False
+        url = self._build_auth_url()
+        self._ws = await websockets.connect(url)
+        self._stream_started = True
+
+    async def feed_audio(self, chunk: bytes) -> None:
+        self._buffer.extend(chunk)
+
+        if not self._ws or not self._stream_started:
+            return
+
+        # Send accumulated frames when we have enough data
+        while len(self._buffer) >= self.FRAME_SIZE:
+            frame = bytes(self._buffer[: self.FRAME_SIZE])
+            self._buffer = self._buffer[self.FRAME_SIZE :]
+            await self._send_frame(frame, status=1)  # 1 = continue
+
+    async def get_result(self) -> str:
+        if not self._ws:
+            return ""
+
+        # Send remaining audio and end-of-stream marker
+        if self._buffer:
+            await self._send_frame(bytes(self._buffer), status=2)  # 2 = last frame
+            self._buffer = bytearray()
+        else:
+            await self._send_frame(b"", status=2)
+
+        # Receive results until the server closes
+        result_parts: list[str] = []
+        try:
+            async for message in self._ws:
+                data = json.loads(message)
+                code = data.get("code", -1)
+                if code != 0:
+                    logger.error("XunfeiASR: error code=%s, message=%s", code, data.get("message"))
+                    break
+                result = data.get("data", {}).get("result", {})
+                ws_list = result.get("ws", [])
+                for ws_item in ws_list:
+                    for cw in ws_item.get("cw", []):
+                        result_parts.append(cw.get("w", ""))
+                # Check if this is the final result
+                if result.get("status") == 2:
+                    break
+        except websockets.exceptions.ConnectionClosed:
+            pass
+
+        text = "".join(result_parts)
+        return text
+
+    async def stop_stream(self) -> None:
+        self._buffer = bytearray()
+        self._result_text = ""
+        self._stream_started = False
+        if self._ws:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+
+    # -- helpers --
+
+    async def _send_frame(self, audio: bytes, status: int) -> None:
+        """Send a single audio frame to the Xunfei WebSocket.
+
+        status: 0 = first frame, 1 = continue, 2 = last frame.
+        """
+        if not self._ws:
+            return
+
+        payload: dict = {
+            "data": {
+                "status": status,
+                "format": "audio/L16;rate=16000",
+                "encoding": "raw",
+                "audio": base64.b64encode(audio).decode("utf-8"),
+            },
+        }
+
+        # The first frame must also carry common and business params
+        if status == 0 or (status == 1 and not self._result_text):
+            payload["common"] = {"app_id": self.app_id}
+            payload["business"] = {
+                "language": self._language,
+                "domain": "iat",
+                "accent": "mandarin",
+                "vad_eos": 3000,
+                "dwa": "wpgs",
+            }
+
+        await self._ws.send(json.dumps(payload))
+
+    def _build_auth_url(self) -> str:
+        """Build the signed WebSocket URL for Xunfei authentication (HMAC-SHA256)."""
+        parsed = urlparse(self.XUNFEI_IAT_URL)
+        now = datetime.now()
+        date_str = format_date_time(mktime(now.timetuple()))
+
+        signature_origin = (
+            f"host: {parsed.hostname}\n"
+            f"date: {date_str}\n"
+            f"GET {parsed.path} HTTP/1.1"
+        )
+        signature_sha = hmac.new(
+            self.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.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 = {
+            "authorization": authorization,
+            "date": date_str,
+            "host": parsed.hostname,
+        }
+        return f"{self.XUNFEI_IAT_URL}?{urlencode(params)}"
+
+
+# ---------------------------------------------------------------------------
+# Volcengine (ByteDance) streaming ASR via WebSocket binary protocol
+# ---------------------------------------------------------------------------
+
+class VolcengineASR(ASRProvider):
+    """火山引擎（豆包）大模型流式语音识别。
+
+    Uses the binary WebSocket protocol described at:
+    https://www.volcengine.com/docs/6561/1354869
+
+    Requires ``app_id`` and ``access_token`` from the Volcengine console.
+    """
+
+    DEFAULT_WS_URL = "wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async"
+    FRAME_DURATION_MS = 200  # recommended 200ms per packet
+    SAMPLE_RATE = 16000
+    BYTES_PER_FRAME = SAMPLE_RATE * 2 * FRAME_DURATION_MS // 1000  # 6400 bytes
+
+    def __init__(
+        self,
+        app_id: str,
+        access_token: str,
+        resource_id: str = "volc.bigasr.sauc.duration",
+        ws_url: str = "",
+    ) -> None:
+        self.app_id = app_id
+        self.access_token = access_token
+        self.resource_id = resource_id
+        self.ws_url = ws_url or self.DEFAULT_WS_URL
+        self._ws = None
+        self._buffer = bytearray()
+        self._language = "zh"
+        self._recv_text = ""
+        self._recv_done = False
+        self._recv_task: asyncio.Task | None = None
+
+    # -- protocol constants ---------------------------------------------------
+
+    _NO_SEQUENCE = 0b0000
+    _NEG_SEQUENCE = 0b0010
+
+    _FULL_CLIENT_REQUEST = 0b0001
+    _AUDIO_ONLY_REQUEST = 0b0010
+    _FULL_SERVER_RESPONSE = 0b1001
+    _SERVER_ACK = 0b1011
+    _SERVER_ERROR = 0b1111
+
+    _JSON = 0b0001
+    _NO_SERIAL = 0b0000
+    _GZIP = 0b0001
+
+    # -- protocol helpers ---------------------------------------------------
+
+    @staticmethod
+    def _build_header(
+        msg_type: int,
+        msg_flags: int,
+        serial: int = 0x01,
+        compress: int = 0x01,
+    ) -> bytes:
+        """Build the 4-byte binary header."""
+        b0 = (0x1 << 4) | 0x1          # version=1, header_size=1 (×4 = 4 bytes)
+        b1 = (msg_type << 4) | msg_flags
+        b2 = (serial << 4) | compress
+        b3 = 0x00
+        return bytes([b0, b1, b2, b3])
+
+    @staticmethod
+    def _gzip(data: bytes) -> bytes:
+        import gzip
+        return gzip.compress(data)
+
+    @staticmethod
+    def _gunzip(data: bytes) -> bytes:
+        import gzip
+        return gzip.decompress(data)
+
+    def _build_full_client_request(self) -> bytes:
+        payload = json.dumps({
+            "user": {"uid": "ai-phone-agent"},
+            "audio": {
+                "format": "pcm",
+                "rate": self.SAMPLE_RATE,
+                "bits": 16,
+                "channel": 1,
+                "codec": "raw",
+            },
+            "request": {
+                "model_name": "bigmodel",
+                "enable_itn": True,
+                "enable_punc": True,
+                "enable_ddc": False,
+                "result_type": "full",
+            },
+        }).encode("utf-8")
+        compressed = self._gzip(payload)
+        header = self._build_header(
+            msg_type=self._FULL_CLIENT_REQUEST,
+            msg_flags=self._NO_SEQUENCE,
+            serial=self._JSON,
+            compress=self._GZIP,
+        )
+        size = len(compressed).to_bytes(4, "big")
+        return header + size + compressed
+
+    def _build_audio_packet(self, audio: bytes, last: bool = False) -> bytes:
+        compressed = self._gzip(audio)
+        flags = self._NEG_SEQUENCE if last else self._NO_SEQUENCE
+        header = self._build_header(
+            msg_type=self._AUDIO_ONLY_REQUEST,
+            msg_flags=flags,
+            serial=self._NO_SERIAL,
+            compress=self._GZIP,
+        )
+        size = len(compressed).to_bytes(4, "big")
+        return header + size + compressed
+
+    def _parse_response(self, data: bytes) -> tuple[str, bool]:
+        """Parse a server response binary frame.
+
+        Returns ``(text, is_last)``.
+        """
+        if len(data) < 4:
+            return "", False
+
+        header_size = data[0] & 0x0F
+        b1 = data[1]
+        msg_type = (b1 >> 4) & 0x0F
+        flags = b1 & 0x0F
+        b2 = data[2]
+        compress = b2 & 0x0F
+
+        header_bytes = header_size * 4
+        payload = data[header_bytes:]
+
+        if msg_type == self._SERVER_ERROR:
+            if len(payload) >= 8:
+                err_code = int.from_bytes(payload[:4], "big")
+                err_size = int.from_bytes(payload[4:8], "big")
+                err_msg = payload[8:8 + err_size]
+                if compress == self._GZIP:
+                    try:
+                        err_msg = self._gunzip(err_msg)
+                    except Exception:
+                        pass
+                logger.error("VolcengineASR error: code=%s msg=%s",
+                             err_code, err_msg.decode("utf-8", errors="replace"))
+            return "", True
+
+        if msg_type == self._SERVER_ACK:
+            return "", False
+
+        if msg_type != self._FULL_SERVER_RESPONSE:
+            return "", False
+
+        has_sequence = (flags & 0x01) != 0
+        # The "last" indicator can be bit 1 (0x02) or bit 2 (0x04) depending
+        # on endpoint; treat any of these as the final response.
+        is_last = (flags & 0x02) != 0 or (flags & 0x04) != 0
+
+        offset = 0
+        if has_sequence:
+            offset += 4  # skip sequence number
+
+        if offset + 4 > len(payload):
+            return "", is_last
+        payload_size = int.from_bytes(payload[offset:offset + 4], "big")
+        offset += 4
+        payload_bytes = payload[offset:offset + payload_size]
+
+        if compress == self._GZIP:
+            payload_bytes = self._gunzip(payload_bytes)
+
+        try:
+            result = json.loads(payload_bytes)
+            text = result.get("result", {}).get("text", "")
+            if text:
+                logger.debug("VolcengineASR: text=%r is_last=%s", text, is_last)
+            return text, is_last
+        except (json.JSONDecodeError, KeyError):
+            return "", is_last
+
+    # -- background receiver --------------------------------------------------
+
+    async def _recv_loop(self) -> None:
+        """Background task: read all responses from the Volcengine WebSocket."""
+        try:
+            while self._ws:
+                try:
+                    resp = await self._ws.recv()
+                except (websockets.exceptions.ConnectionClosed,
+                        websockets.exceptions.ConnectionClosedOK,
+                        websockets.exceptions.ConnectionClosedError):
+                    logger.debug("VolcengineASR: recv_loop connection closed")
+                    break
+                if isinstance(resp, bytes):
+                    text, is_last = self._parse_response(resp)
+                    if text:
+                        self._recv_text = text
+                    if is_last:
+                        self._recv_done = True
+                        break
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            logger.debug("VolcengineASR: recv_loop ended", exc_info=True)
+
+    # -- ASRProvider interface -----------------------------------------------
+
+    async def start_stream(self, language: str = "zh") -> None:
+        self._language = language
+        self._buffer = bytearray()
+        self._recv_text = ""
+        self._recv_done = False
+
+        connect_id = str(uuid.uuid4())
+        extra_headers = {
+            "X-Api-App-Key": self.app_id,
+            "X-Api-Access-Key": self.access_token,
+            "X-Api-Resource-Id": self.resource_id,
+            "X-Api-Connect-Id": connect_id,
+        }
+        masked_token = ("****" + self.access_token[-4:]) if len(self.access_token) > 4 else "****"
+        logger.info(
+            "VolcengineASR: connecting app_id=%s access_token=%s resource_id=%s connect_id=%s url=%s",
+            self.app_id, masked_token, self.resource_id, connect_id, self.ws_url,
+        )
+
+        try:
+            self._ws = await websockets.connect(
+                self.ws_url,
+                additional_headers=extra_headers,
+            )
+        except websockets.exceptions.InvalidStatus as e:
+            body = getattr(e.response, "body", b"")
+            if isinstance(body, (bytes, bytearray)):
+                body = body.decode("utf-8", errors="replace")
+            logger.error("VolcengineASR: WebSocket rejected: HTTP %s, %s", e.response.status_code, body)
+            raise ConnectionError(
+                f"火山引擎ASR连接失败 (HTTP {e.response.status_code}): {body}. "
+                f"请检查 app_id、access_token、resource_id 配置，"
+                f"并确认已在火山引擎控制台开通对应的语音识别服务。"
+            ) from e
+
+        # Log X-Tt-Logid from response headers
+        resp_headers = getattr(self._ws, "response_headers", None)
+        if resp_headers is None:
+            resp_obj = getattr(self._ws, "response", None)
+            resp_headers = getattr(resp_obj, "headers", {}) if resp_obj else {}
+        logid = resp_headers.get("X-Tt-Logid", "")
+        if logid:
+            logger.info("VolcengineASR: X-Tt-Logid=%s", logid)
+
+        # Send full client request
+        await self._ws.send(self._build_full_client_request())
+        logger.info("VolcengineASR: stream started, listening for responses")
+
+        # Start background receiver task
+        self._recv_task = asyncio.create_task(self._recv_loop())
+
+    async def feed_audio(self, chunk: bytes) -> None:
+        self._buffer.extend(chunk)
+
+        if not self._ws:
+            return
+
+        # Send complete frames (200ms each)
+        while len(self._buffer) >= self.BYTES_PER_FRAME:
+            frame = bytes(self._buffer[:self.BYTES_PER_FRAME])
+            self._buffer = self._buffer[self.BYTES_PER_FRAME:]
+            try:
+                await self._ws.send(self._build_audio_packet(frame, last=False))
+            except Exception:
+                logger.debug("VolcengineASR: send failed", exc_info=True)
+                return
+
+    async def get_result(self) -> str:
+        if not self._ws:
+            return self._recv_text or ""
+
+        # Send remaining audio as the last packet
+        remaining = bytes(self._buffer) if self._buffer else b""
+        self._buffer = bytearray()
+        try:
+            await self._ws.send(self._build_audio_packet(remaining, last=True))
+            logger.debug("VolcengineASR: sent last audio packet (%d bytes)", len(remaining))
+        except Exception:
+            logger.debug("VolcengineASR: failed to send last packet", exc_info=True)
+
+        # Wait for the receiver to get the final response
+        if self._recv_task and not self._recv_task.done():
+            try:
+                await asyncio.wait_for(self._recv_task, timeout=5.0)
+            except asyncio.TimeoutError:
+                logger.warning("VolcengineASR: timeout waiting for final response")
+            except Exception:
+                pass
+
+        result = self._recv_text
+        self._recv_text = ""
+        return result
+
+    async def stop_stream(self) -> None:
+        self._buffer = bytearray()
+        # Cancel the receiver task
+        if self._recv_task and not self._recv_task.done():
+            self._recv_task.cancel()
+            try:
+                await self._recv_task
+            except (asyncio.CancelledError, Exception):
+                pass
+        self._recv_task = None
+        self._recv_text = ""
+        self._recv_done = False
+        if self._ws:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+
+    async def get_interim_result(self) -> str:
+        return self._recv_text
+
+
+# ---------------------------------------------------------------------------
+# Tencent Cloud real-time ASR via WebSocket
+# ---------------------------------------------------------------------------
+
+class TencentASR(ASRProvider):
+    """腾讯云实时语音识别 (WebSocket).
+
+    Protocol doc: https://cloud.tencent.com/document/product/1093/48982
+    """
+
+    WS_BASE = "wss://asr.cloud.tencent.com/asr/v2/"
+    SIGN_BASE = "asr.cloud.tencent.com/asr/v2/"
+    # 40ms per chunk at 16kHz S16LE mono = 1280 bytes
+    FRAME_DURATION_MS = 40
+    SAMPLE_RATE = 16000
+    BYTES_PER_FRAME = SAMPLE_RATE * 2 * FRAME_DURATION_MS // 1000  # 1280
+
+    def __init__(
+        self,
+        app_id: str,
+        secret_id: str,
+        secret_key: str,
+        engine_model_type: str = "16k_zh_large",
+    ) -> None:
+        self.app_id = app_id
+        self.secret_id = secret_id
+        self.secret_key = secret_key
+        self.engine_model_type = engine_model_type
+        self._ws = None
+        self._buffer = bytearray()
+        self._language = "zh"
+        self._recv_text = ""
+        self._sentence_parts: list[str] = []
+        self._recv_done = False
+        self._recv_task: asyncio.Task | None = None
+
+    # -- signing ---------------------------------------------------------------
+
+    def _build_ws_url(self) -> str:
+        now = int(time.time())
+        params = {
+            "secretid": self.secret_id,
+            "timestamp": now,
+            "expired": now + 86400,
+            "nonce": random.randint(10000, 99999),
+            "engine_model_type": self.engine_model_type,
+            "voice_id": str(uuid.uuid4()),
+            "voice_format": 1,  # PCM
+            "needvad": 1,
+            "filter_dirty": 0,
+            "filter_modal": 0,
+            "filter_punc": 0,
+            "convert_num_mode": 1,
+        }
+        if self.SAMPLE_RATE == 8000:
+            params["input_sample_rate"] = 8000
+
+        # Sort params by key
+        sorted_keys = sorted(params.keys())
+        query_parts = [f"{k}={params[k]}" for k in sorted_keys]
+        query_str = "&".join(query_parts)
+
+        # Build sign string
+        sign_str = f"{self.SIGN_BASE}{self.app_id}?{query_str}"
+
+        # HMAC-SHA1 → base64
+        signature = base64.b64encode(
+            hmac.new(
+                self.secret_key.encode("utf-8"),
+                sign_str.encode("utf-8"),
+                hashlib.sha1,
+            ).digest()
+        ).decode("utf-8")
+
+        # URL-encode signature
+        encoded_sig = quote(signature, safe="")
+
+        return f"{self.WS_BASE}{self.app_id}?{query_str}&signature={encoded_sig}"
+
+    # -- background receiver ---------------------------------------------------
+
+    async def _recv_loop(self) -> None:
+        try:
+            while self._ws:
+                try:
+                    msg = await self._ws.recv()
+                except (websockets.exceptions.ConnectionClosed,
+                        websockets.exceptions.ConnectionClosedOK,
+                        websockets.exceptions.ConnectionClosedError):
+                    logger.debug("TencentASR: recv_loop connection closed")
+                    break
+
+                if not isinstance(msg, str):
+                    continue
+
+                try:
+                    data = json.loads(msg)
+                except json.JSONDecodeError:
+                    continue
+
+                code = data.get("code", -1)
+                if code != 0:
+                    logger.error("TencentASR: error code=%s msg=%s",
+                                 code, data.get("message", ""))
+                    self._recv_done = True
+                    break
+
+                result = data.get("result", {})
+                slice_type = result.get("slice_type")
+                voice_text = result.get("voice_text_str", "")
+
+                if slice_type == 0:
+                    # Sentence begin — nothing to accumulate yet
+                    pass
+                elif slice_type == 1:
+                    # Interim result for current sentence
+                    self._recv_text = "".join(self._sentence_parts) + voice_text
+                elif slice_type == 2:
+                    # Sentence end — finalize this sentence
+                    self._sentence_parts.append(voice_text)
+                    self._recv_text = "".join(self._sentence_parts)
+
+                final_speech = data.get("final_speech")
+                if final_speech == 1:
+                    self._recv_done = True
+                    break
+
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            logger.debug("TencentASR: recv_loop ended", exc_info=True)
+
+    # -- ASRProvider interface -------------------------------------------------
+
+    async def start_stream(self, language: str = "zh") -> None:
+        self._language = language
+        self._buffer = bytearray()
+        self._recv_text = ""
+        self._sentence_parts = []
+        self._recv_done = False
+
+        ws_url = self._build_ws_url()
+        masked_key = ("****" + self.secret_key[-4:]) if len(self.secret_key) > 4 else "****"
+        logger.info(
+            "TencentASR: connecting app_id=%s engine=%s secret_key=%s",
+            self.app_id, self.engine_model_type, masked_key,
+        )
+
+        try:
+            self._ws = await websockets.connect(ws_url)
+        except websockets.exceptions.InvalidStatus as e:
+            body = getattr(e.response, "body", b"")
+            if isinstance(body, (bytes, bytearray)):
+                body = body.decode("utf-8", errors="replace")
+            logger.error("TencentASR: WebSocket rejected: HTTP %s, %s",
+                         e.response.status_code, body)
+            raise ConnectionError(
+                f"腾讯云ASR连接失败 (HTTP {e.response.status_code}): {body}. "
+                f"请检查 app_id、secret_id、secret_key 配置。"
+            ) from e
+
+        # Wait for the initial handshake response
+        try:
+            init_msg = await asyncio.wait_for(self._ws.recv(), timeout=5.0)
+            init_data = json.loads(init_msg) if isinstance(init_msg, str) else {}
+            if init_data.get("code", -1) != 0:
+                raise ConnectionError(
+                    f"腾讯云ASR握手失败: code={init_data.get('code')}, "
+                    f"msg={init_data.get('message', '')}"
+                )
+            logger.info("TencentASR: handshake ok, voice_id=%s", init_data.get("voice_id", ""))
+        except asyncio.TimeoutError:
+            logger.warning("TencentASR: handshake timeout, proceeding anyway")
+
+        # Start background receiver
+        self._recv_task = asyncio.create_task(self._recv_loop())
+        logger.info("TencentASR: stream started")
+
+    async def feed_audio(self, chunk: bytes) -> None:
+        self._buffer.extend(chunk)
+        if not self._ws:
+            return
+
+        while len(self._buffer) >= self.BYTES_PER_FRAME:
+            frame = bytes(self._buffer[:self.BYTES_PER_FRAME])
+            self._buffer = self._buffer[self.BYTES_PER_FRAME:]
+            try:
+                await self._ws.send(frame)
+            except Exception:
+                logger.debug("TencentASR: send failed", exc_info=True)
+                return
+
+    async def get_result(self) -> str:
+        if not self._ws:
+            return self._recv_text or ""
+
+        # Send remaining audio
+        if self._buffer:
+            try:
+                await self._ws.send(bytes(self._buffer))
+            except Exception:
+                pass
+            self._buffer = bytearray()
+
+        # Send end signal
+        try:
+            await self._ws.send(json.dumps({"type": "end"}))
+        except Exception:
+            pass
+
+        # Wait for final_speech=1
+        if self._recv_task and not self._recv_task.done():
+            try:
+                await asyncio.wait_for(self._recv_task, timeout=10.0)
+            except asyncio.TimeoutError:
+                logger.warning("TencentASR: timeout waiting for final response")
+            except Exception:
+                pass
+
+        result = self._recv_text
+        self._recv_text = ""
+        return result
+
+    async def stop_stream(self) -> None:
+        self._buffer = bytearray()
+        if self._recv_task and not self._recv_task.done():
+            self._recv_task.cancel()
+            try:
+                await self._recv_task
+            except (asyncio.CancelledError, Exception):
+                pass
+        self._recv_task = None
+        self._recv_text = ""
+        self._sentence_parts = []
+        self._recv_done = False
+        if self._ws:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+
+    async def get_interim_result(self) -> str:
+        return self._recv_text
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+def create_asr_provider(
+    provider_override: str | None = None,
+    resource_id_override: str | None = None,
+    sample_rate_override: int | None = None,
+) -> ASRProvider:
+    """Create an ASR provider instance based on the current configuration.
+
+    Optional overrides allow the ASR test UI to dynamically switch
+    provider, resource_id and sample_rate without changing the saved config.
+    """
+    provider = provider_override or cfg.get("asr.provider", "whisper")
+
+    if provider == "whisper":
+        return WhisperASR(
+            base_url=cfg.get("asr.whisper.base_url", "https://api.openai.com/v1"),
+            api_key=cfg.get("asr.whisper.api_key", ""),
+            model=cfg.get("asr.whisper.model", "whisper-1"),
+        )
+    elif provider == "xunfei":
+        return XunfeiASR(
+            app_id=cfg.get("asr.xunfei.app_id", ""),
+            api_key=cfg.get("asr.xunfei.api_key", ""),
+            api_secret=cfg.get("asr.xunfei.api_secret", ""),
+        )
+    elif provider == "volcengine":
+        resource_id = resource_id_override or cfg.get("asr.volcengine.resource_id", "volc.bigasr.sauc.duration")
+        sample_rate = sample_rate_override or 16000
+        asr = VolcengineASR(
+            app_id=cfg.get("asr.volcengine.app_id", ""),
+            access_token=cfg.get("asr.volcengine.access_token", ""),
+            resource_id=resource_id,
+            ws_url=cfg.get("asr.volcengine.ws_url", ""),
+        )
+        if sample_rate and sample_rate != 16000:
+            asr.SAMPLE_RATE = sample_rate
+            asr.BYTES_PER_FRAME = sample_rate * 2 * asr.FRAME_DURATION_MS // 1000
+        return asr
+    elif provider == "tencent":
+        engine = resource_id_override or cfg.get("asr.tencent.engine_model_type", "16k_zh_large")
+        sample_rate = sample_rate_override or 16000
+        asr = TencentASR(
+            app_id=cfg.get("asr.tencent.app_id", ""),
+            secret_id=cfg.get("asr.tencent.secret_id", ""),
+            secret_key=cfg.get("asr.tencent.secret_key", ""),
+            engine_model_type=engine,
+        )
+        if sample_rate and sample_rate != 16000:
+            asr.SAMPLE_RATE = sample_rate
+            asr.BYTES_PER_FRAME = sample_rate * 2 * asr.FRAME_DURATION_MS // 1000
+        return asr
+    else:
+        raise ValueError(f"Unknown ASR provider: {provider}")