openspeechapi 0.1.0__py3-none-any.whl

openspeech/providers/stt/tencent.py

@@ -0,0 +1,212 @@
+"""Tencent Cloud ASR STT provider adapter (TC3-HMAC-SHA256 signed)."""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+from openspeech.logging_config import logger
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from datetime import datetime, timezone
+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 TencentSTTSettings(BaseSettings):
+    secret_id: str = ""
+    secret_key: str = ""
+    engine_type: str = "16k_zh"
+    region: str = "ap-guangzhou"
+
+class TencentSTT(STTProvider):
+    name = "tencent-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = TencentSTTSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"engine_type": ["16k_zh", "16k_en", "16k_ja", "16k_ko", "16k_zh_dialect", "16k_yue", "16k_zh_medical"], "region": ["ap-guangzhou", "ap-shanghai", "ap-beijing", "ap-chengdu"]}
+
+    _SERVICE = "asr"
+    _HOST = "asr.tencentcloudapi.com"
+
+    def __init__(self, settings: TencentSTTSettings | None = None) -> None:
+        self.settings = settings or TencentSTTSettings()
+        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.secret_id) and bool(self.settings.secret_key)
+
+    # ---- TC3-HMAC-SHA256 signing ------------------------------------------------
+
+    def _sign_request(
+        self, action: str, version: str, payload_json: str
+    ) -> dict[str, str]:
+        """Build Tencent Cloud API v3 signed headers."""
+        timestamp = int(time.time())
+        date = datetime.fromtimestamp(timestamp, tz=timezone.utc).strftime(
+            "%Y-%m-%d"
+        )
+
+        # 1. Canonical request
+        http_method = "POST"
+        canonical_uri = "/"
+        canonical_querystring = ""
+        ct = "application/json; charset=utf-8"
+        canonical_headers = (
+            f"content-type:{ct}\nhost:{self._HOST}\nx-tc-action:{action.lower()}\n"
+        )
+        signed_headers = "content-type;host;x-tc-action"
+        hashed_payload = hashlib.sha256(payload_json.encode("utf-8")).hexdigest()
+        canonical_request = (
+            f"{http_method}\n{canonical_uri}\n{canonical_querystring}\n"
+            f"{canonical_headers}\n{signed_headers}\n{hashed_payload}"
+        )
+
+        # 2. String to sign
+        algorithm = "TC3-HMAC-SHA256"
+        credential_scope = f"{date}/{self._SERVICE}/tc3_request"
+        hashed_canonical = hashlib.sha256(
+            canonical_request.encode("utf-8")
+        ).hexdigest()
+        string_to_sign = (
+            f"{algorithm}\n{timestamp}\n{credential_scope}\n{hashed_canonical}"
+        )
+
+        # 3. Signing key
+        secret_date = hmac.new(
+            ("TC3" + self.settings.secret_key).encode("utf-8"),
+            date.encode("utf-8"),
+            hashlib.sha256,
+        ).digest()
+        secret_service = hmac.new(
+            secret_date, self._SERVICE.encode("utf-8"), hashlib.sha256
+        ).digest()
+        secret_signing = hmac.new(
+            secret_service, b"tc3_request", hashlib.sha256
+        ).digest()
+
+        # 4. Signature
+        signature = hmac.new(
+            secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256
+        ).hexdigest()
+
+        authorization = (
+            f"{algorithm} Credential={self.settings.secret_id}/{credential_scope}, "
+            f"SignedHeaders={signed_headers}, Signature={signature}"
+        )
+
+        return {
+            "Authorization": authorization,
+            "Content-Type": ct,
+            "Host": self._HOST,
+            "X-TC-Action": action,
+            "X-TC-Version": version,
+            "X-TC-Timestamp": str(timestamp),
+            "X-TC-Region": self.settings.region,
+        }
+
+    # ---- API calls ---------------------------------------------------------------
+
+    async def _post(
+        self, action: str, version: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        payload_json = json.dumps(payload)
+        headers = self._sign_request(action, version, payload_json)
+        resp = await self._client.post(  # type: ignore[union-attr]
+            f"https://{self._HOST}",
+            content=payload_json,
+            headers=headers,
+        )
+        resp.raise_for_status()
+        result = resp.json()
+        response = result.get("Response", {})
+        if "Error" in response:
+            err = response["Error"]
+            raise RuntimeError(
+                f"Tencent ASR error [{err.get('Code')}]: {err.get('Message')}"
+            )
+        return response
+
+    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()
+
+        base64_audio = base64.b64encode(audio.data).decode("utf-8")
+
+        # Step 1: Create recognition task
+        create_resp = await self._post(
+            action="CreateRecTask",
+            version="2019-06-14",
+            payload={
+                "EngineModelType": self.settings.engine_type,
+                "ChannelNum": 1,
+                "ResTextFormat": 0,
+                "SourceType": 1,
+                "Data": base64_audio,
+                "DataLen": len(audio.data),
+            },
+        )
+
+        task_id = create_resp.get("Data", {}).get("TaskId")
+        if not task_id:
+            raise RuntimeError("Tencent ASR: no TaskId in CreateRecTask response")
+
+        # Step 2: Poll for result
+        import asyncio
+
+        for _ in range(60):
+            await asyncio.sleep(2)
+            status_resp = await self._post(
+                action="DescribeTaskStatus",
+                version="2019-06-14",
+                payload={"TaskId": task_id},
+            )
+            task_data = status_resp.get("Data", {})
+            status = task_data.get("StatusStr", "")
+            if status == "success":
+                text = task_data.get("Result", "")
+                result = Transcription(text=text)
+                logger.info("{}: completed in {:.0f}ms, result={} chars", self.name, (time.perf_counter() - _t0) * 1000, len(result.text))
+                return result
+            if status == "failed":
+                raise RuntimeError(
+                    f"Tencent ASR task failed: {task_data.get('ErrorMsg', 'unknown')}"
+                )
+
+        raise RuntimeError("Tencent ASR: task polling timed out")
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        raise NotImplementedError("Tencent STT streaming not implemented")
+        yield  # noqa: unreachable — makes this an async generator

openspeech/providers/stt/volcengine.py

@@ -0,0 +1,107 @@
+"""Volcengine (ByteDance) STT provider adapter."""
+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 VolcengineSTTSettings(BaseSettings):
+    access_token: str = ""
+    app_id: str = ""
+    cluster: str = "volcengine_streaming_common"
+
+class VolcengineSTT(STTProvider):
+    name = "volcengine-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = VolcengineSTTSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"cluster": ["volcengine_streaming_common", "volcengine_input_common"]}
+
+    def __init__(self, settings: VolcengineSTTSettings | None = None) -> None:
+        self.settings = settings or VolcengineSTTSettings()
+        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.access_token) and bool(self.settings.app_id)
+
+    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()
+
+        base64_audio = base64.b64encode(audio.data).decode("utf-8")
+        payload = {
+            "app": {
+                "appid": self.settings.app_id,
+                "cluster": self.settings.cluster,
+            },
+            "audio": {
+                "format": "wav",
+                "data": base64_audio,
+            },
+            "user": {"uid": "openspeech"},
+        }
+        headers = {
+            "Authorization": f"Bearer;{self.settings.access_token}",
+            "Content-Type": "application/json",
+        }
+
+        resp = await self._client.post(
+            "https://openspeech.bytedance.com/api/v1/auc/submit",
+            json=payload,
+            headers=headers,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+
+        if data.get("code") != 0 and data.get("code") is not None:
+            raise RuntimeError(
+                f"Volcengine STT error: {data.get('message', 'unknown error')}"
+            )
+
+        text = data.get("result", "")
+        if isinstance(text, dict):
+            text = text.get("text", "")
+
+        result = Transcription(text=text)
+        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("Volcengine STT streaming not implemented")
+        yield  # noqa: unreachable — makes this an async generator

openspeech/providers/stt/whisper.py

@@ -0,0 +1,153 @@
+"""OpenAI Whisper (local) STT provider adapter (subprocess mode)."""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+import io
+from openspeech.logging_config import logger
+import os
+import tempfile
+import time
+from typing import Any
+import wave
+
+from openspeech.core.base import STTProvider
+
+from openspeech.core.enums import Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioData, STTOptions, Transcription, Word
+from openspeech.core.settings import BaseSettings
+
+@dataclass
+class WhisperSTTSettings(BaseSettings):
+    model_name: str = "base"
+    device: str = "cpu"
+    fp16: bool = False
+    download_root: str | None = None
+    beam_size: int = 5
+
+class WhisperSTT(STTProvider):
+    name = "whisper"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.SUBPROCESS
+    settings_cls = WhisperSTTSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"device": ["cpu", "cuda", "mps"], "model_name": ["tiny", "base", "small", "medium", "large-v2", "large-v3", "large-v3-turbo"]}
+
+    def __init__(self, settings: WhisperSTTSettings | None = None) -> None:
+        self.settings = settings or WhisperSTTSettings()
+        self._client: Any = None
+        self._model: Any = None
+        self._loaded_model_name = self.settings.model_name
+        self._loaded_device = self.settings.device
+
+    async def start(self) -> None:
+        await self._ensure_model(
+            model_name=self.settings.model_name,
+            device=self.settings.device,
+        )
+        logger.info("{} provider started", self.name)
+
+    async def _ensure_model(self, *, model_name: str, device: str) -> None:
+        try:
+            import whisper
+        except ImportError:
+            raise ImportError(
+                "Install whisper: pip install openspeech[whisper]"
+            )
+        if (
+            self._model is not None
+            and self._loaded_model_name == model_name
+            and self._loaded_device == device
+        ):
+            return
+        self._model = whisper.load_model(
+            model_name,
+            device=device,
+            download_root=self.settings.download_root,
+        )
+        self._client = self._model
+        self._loaded_model_name = model_name
+        self._loaded_device = device
+
+    async def stop(self) -> None:
+        self._client = None
+        self._model = None
+        logger.info("{} provider stopped", self.name)
+
+    async def health_check(self) -> bool:
+        return self._client is not None
+
+    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()
+        requested_model = (opts.model or self.settings.model_name).strip()
+        requested_device = (opts.device or self.settings.device).strip()
+        await self._ensure_model(model_name=requested_model, device=requested_device)
+
+        is_wav = len(audio.data) > 4 and audio.data[:4] == b"RIFF"
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+            if is_wav:
+                f.write(audio.data)
+            else:
+                buf = io.BytesIO()
+                with wave.open(buf, "wb") as wf:
+                    wf.setnchannels(audio.channels)
+                    wf.setsampwidth(2)
+                    wf.setframerate(audio.sample_rate)
+                    wf.writeframes(audio.data)
+                f.write(buf.getvalue())
+            tmp_path = f.name
+
+        try:
+            kwargs: dict[str, Any] = {
+                "fp16": bool(self.settings.fp16 if opts.fp16 is None else opts.fp16),
+                "beam_size": int(self.settings.beam_size if opts.beam_size is None else opts.beam_size),
+                "word_timestamps": True,
+            }
+            if opts.language:
+                kwargs["language"] = opts.language
+            result = self._model.transcribe(tmp_path, **kwargs)
+
+            segments = result.get("segments") or []
+            words: list[Word] = []
+            for seg in segments:
+                for item in (seg.get("words") or []):
+                    word_text = str(item.get("word", "")).strip()
+                    if not word_text:
+                        continue
+                    words.append(
+                        Word(
+                            text=word_text,
+                            start_ms=int(float(item.get("start", 0.0)) * 1000),
+                            end_ms=int(float(item.get("end", 0.0)) * 1000),
+                            confidence=float(item["probability"]) if item.get("probability") is not None else None,
+                        )
+                    )
+            duration_ms: int | None = None
+            if segments:
+                last_end = float(segments[-1].get("end", 0.0))
+                if last_end > 0:
+                    duration_ms = int(last_end * 1000)
+            transcription = Transcription(
+                text=str(result.get("text", "")).strip(),
+                language=result.get("language"),
+                words=words or None,
+                duration_ms=duration_ms,
+            )
+            logger.info("{}: completed in {:.0f}ms, result={} chars", self.name, (time.perf_counter() - _t0) * 1000, len(transcription.text))
+            return transcription
+        finally:
+            os.unlink(tmp_path)
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        raise NotImplementedError(
+            "WhisperSTT does not support streaming transcription"
+        )
+        yield  # pragma: no cover