openspeechapi 0.1.0__py3-none-any.whl

openspeech/providers/stt/macos_speech.py

@@ -0,0 +1,226 @@
+"""macOS native STT provider using SFSpeechRecognizer via compiled Swift binary.
+
+The Swift helper lives inside a .app bundle so that macOS TCC can track its
+Speech Recognition authorization by bundle ID.  The provider launches it via
+``open -W`` which inherits the .app TCC grant; results are exchanged through
+a temporary JSON file (``--output``).
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from openspeech.logging_config import logger
+import tempfile
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+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
+from openspeech.utils.audio_converter import AudioConverter
+
+@dataclass
+class MacOSSpeechSettings(BaseSettings):
+    language: str = "zh-CN"
+    binary_path: str = ""
+
+class MacOSSpeechSTT(STTProvider):
+    """STT provider wrapping macOS SFSpeechRecognizer via a compiled Swift helper."""
+
+    name = "macos-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = MacOSSpeechSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"language": ["zh-CN", "en-US", "en-AE", "ja-JP", "ko-KR", "fr-FR", "de-DE", "es-ES"]}
+
+    # .app bundle that contains the Swift helper binary.
+    _DEFAULT_APP_BUNDLE = (
+        Path(__file__).resolve().parents[3]
+        / "scripts"
+        / "engines"
+        / "macos-stt"
+        / "MacOSSTTHelper.app"
+    )
+
+    def __init__(self, settings: MacOSSpeechSettings | None = None) -> None:
+        self.settings = settings or MacOSSpeechSettings()
+        self._app_bundle: Path | None = None
+        self._binary: Path | None = None
+        self._started = False
+        self._auth_ok = False
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    async def _run_via_open(self, *extra_args: str, output_file: str | None = None) -> dict:
+        """Launch the helper through ``open -W`` so it inherits .app TCC grants.
+
+        If *output_file* is given the helper writes JSON there (``--output``);
+        otherwise we fall back to direct execution for ``--check`` which
+        doesn't need TCC.
+        """
+        if self._app_bundle is None:
+            return {"status": "error", "error": "app bundle not set"}
+
+        cmd: list[str]
+        if output_file is not None:
+            # Launch via `open -W` for TCC context, results via --output file
+            cmd = [
+                "open", "-W", str(self._app_bundle),
+                "--args", *extra_args, "--output", output_file,
+            ]
+        else:
+            # Direct execution is fine for --check (no TCC needed)
+            if self._binary is None:
+                return {"status": "error", "error": "binary not set"}
+            cmd = [str(self._binary), *extra_args]
+
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _ = await proc.communicate()
+
+        # Read result from output file or stdout
+        raw = ""
+        if output_file is not None:
+            out_path = Path(output_file)
+            if out_path.exists():
+                raw = out_path.read_text(encoding="utf-8").strip()
+                out_path.unlink(missing_ok=True)
+        else:
+            raw = stdout.decode(errors="replace").strip() if stdout else ""
+
+        if not raw:
+            return {"status": "error", "error": f"no output (rc={proc.returncode})"}
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            return {"status": "error", "error": raw}
+
+    async def _run_check(self) -> dict:
+        """Run ``--check`` — direct execution, no TCC needed."""
+        return await self._run_via_open(
+            "--check", "--language", self.settings.language,
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self) -> None:
+        if self.settings.binary_path:
+            # Custom binary path — use directly (user manages TCC)
+            candidate = Path(self.settings.binary_path)
+            if not candidate.exists():
+                raise RuntimeError(
+                    f"macos-stt binary not found at {candidate}."
+                )
+            self._binary = candidate
+            self._app_bundle = None
+        else:
+            app = self._DEFAULT_APP_BUNDLE
+            binary = app / "Contents" / "MacOS" / "macos-stt-helper"
+            if not binary.exists():
+                raise RuntimeError(
+                    f"macos-stt binary not found at {binary}. "
+                    "Run scripts/engines/macos-stt/install.sh to compile it."
+                )
+            self._app_bundle = app
+            self._binary = binary
+
+        # Verify speech recognition availability via --check
+        check = await self._run_check()
+        if check.get("status") != "ok":
+            err = check.get("error", "unknown authorization issue")
+            logger.warning("macos-stt auth check failed: {}", err)
+            raise RuntimeError(f"macos-stt not authorized: {err}")
+
+        self._auth_ok = True
+        self._started = True
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        self._binary = None
+        self._app_bundle = None
+        self._started = False
+        self._auth_ok = False
+        logger.info("{} provider stopped", self.name)
+
+    async def health_check(self) -> bool:
+        if self._started and self._auth_ok:
+            return True
+        # Pre-start check: verify binary exists
+        if self._binary is not None and self._binary.exists():
+            return True
+        # Check default location
+        default = self._DEFAULT_APP_BUNDLE / "Contents" / "MacOS" / "macos-stt-helper"
+        return default.exists()
+
+    # ------------------------------------------------------------------
+    # Transcription
+    # ------------------------------------------------------------------
+
+    async def transcribe(
+        self, audio: AudioData, opts: STTOptions | None = None
+    ) -> Transcription:
+        if not self._started or self._binary 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
+
+        # Convert to WAV for the Swift helper.
+        wav_audio = AudioConverter.to_wav(audio)
+
+        tmp_wav: str | None = None
+        tmp_out: str | None = None
+        try:
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+                f.write(wav_audio.data)
+                tmp_wav = f.name
+            with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:
+                tmp_out = f.name
+
+            result = await self._run_via_open(
+                "--audio", tmp_wav,
+                "--language", language,
+                output_file=tmp_out if self._app_bundle else None,
+            )
+
+            # When running without .app bundle (custom binary_path), _run_via_open
+            # uses direct execution and reads stdout — handle that path too.
+            if self._app_bundle is None and not result:
+                raise RuntimeError("macos-stt-helper returned no output")
+
+            if "error" in result:
+                raise RuntimeError(
+                    f"macos-stt-helper error: {result['error']}"
+                )
+
+            transcription = Transcription(
+                text=result.get("text", ""),
+                language=result.get("language"),
+                confidence=result.get("confidence"),
+            )
+            logger.info("{}: completed in {:.0f}ms, result={} chars", self.name, (time.perf_counter() - _t0) * 1000, len(transcription.text))
+            return transcription
+        finally:
+            if tmp_wav is not None:
+                Path(tmp_wav).unlink(missing_ok=True)
+            if tmp_out is not None:
+                Path(tmp_out).unlink(missing_ok=True)
+
+    def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        raise NotImplementedError("macOS SFSpeechRecognizer does not support streaming via this provider")

openspeech/providers/stt/openai.py

@@ -0,0 +1,84 @@
+"""OpenAI STT provider adapter (Whisper API)."""
+from __future__ import annotations
+
+import io
+from openspeech.logging_config import logger
+import time
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+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 OpenAISTTSettings(BaseSettings):
+    api_key: str = ""
+    base_url: str = ""
+    model: str = "whisper-1"
+
+class OpenAISTT(STTProvider):
+    name = "openai-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = OpenAISTTSettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+    field_options = {"model": ["whisper-1", "gpt-4o-transcribe", "gpt-4o-mini-transcribe"]}
+
+    def __init__(self, settings: OpenAISTTSettings | None = None) -> None:
+        self.settings = settings or OpenAISTTSettings()
+        self._client: Any = None
+
+    async def start(self) -> None:
+        try:
+            from openai import AsyncOpenAI
+            kwargs: dict[str, Any] = {"api_key": self.settings.api_key}
+            if self.settings.base_url:
+                kwargs["base_url"] = self.settings.base_url
+            self._client = AsyncOpenAI(**kwargs)
+        except ImportError:
+            raise ImportError("Install openai: pip install openspeech[openai]")
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        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()
+        audio_file = io.BytesIO(audio.data)
+        audio_file.name = "audio.wav"
+        kwargs: dict[str, Any] = {
+            "model": self.settings.model,
+            "file": audio_file,
+        }
+        if opts.language:
+            kwargs["language"] = opts.language
+        if opts.prompt:
+            kwargs["prompt"] = opts.prompt
+        if opts.temperature is not None:
+            kwargs["temperature"] = opts.temperature
+        response = await self._client.audio.transcriptions.create(**kwargs)
+        result = Transcription(text=response.text, language=opts.language)
+        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(
+            "OpenAI Whisper API does not support streaming input"
+        )
+        yield  # pragma: no cover

openspeech/providers/stt/sherpa_onnx.py

@@ -0,0 +1,353 @@
+"""Sherpa-ONNX STT provider adapter (local service)."""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+import io
+import json
+from openspeech.logging_config import logger
+import math
+import struct
+import time
+from urllib.parse import urlparse, urlunparse
+import wave
+from typing import Any
+from urllib.parse import urljoin
+
+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 SherpaOnnxSTTSettings(BaseSettings):
+    api_url: str = "http://127.0.0.1:17000"
+    health_path: str = "/health"
+    ws_path: str = "/"
+    model: str = ""
+    language: str = "auto"
+    sample_rate: int = 16000
+    chunk_ms: int = 120
+    recv_timeout_s: float = 1.0
+    timeout_s: float = 60.0
+    retries: int = 0
+
+class SherpaOnnxSTT(STTProvider):
+    name = "sherpa-onnx-stt"
+    provider_type = ProviderType.STT
+    execution_mode = ExecMode.LOCAL
+    settings_cls = SherpaOnnxSTTSettings
+    capabilities = {
+        Capability.STREAMING,
+        Capability.BATCH,
+        Capability.MULTILINGUAL,
+    }
+    field_options = {"language": ["auto", "en", "zh", "ja"]}
+
+    def __init__(self, settings: SherpaOnnxSTTSettings | None = None) -> None:
+        self.settings = settings or SherpaOnnxSTTSettings()
+        self._client: Any = 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:
+            try:
+                import httpx
+            except ImportError:
+                raise ImportError(
+                    "Install httpx: pip install openspeech[server]"
+                )
+            self._client = httpx.AsyncClient(timeout=self.settings.timeout_s, trust_env=False)
+            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)
+
+    def _ws_url(self) -> str:
+        u = urlparse(self.settings.api_url.rstrip("/"))
+        scheme = "wss" if u.scheme == "https" else "ws"
+        path = self.settings.ws_path or "/"
+        if not path.startswith("/"):
+            path = f"/{path}"
+        return urlunparse((scheme, u.netloc, path, "", "", ""))
+
+    async def health_check(self) -> bool:
+        if self._client is None:
+            return False
+        try:
+            url = urljoin(
+                self.settings.api_url.rstrip("/") + "/",
+                self.settings.health_path.lstrip("/"),
+            )
+            resp = await self._client.get(url)
+            return resp.status_code < 500
+        except Exception:
+            return False
+
+    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))
+        opts = opts or STTOptions()
+        language = (opts.language or self.settings.language).strip()
+
+        samples = self._audio_to_float32_samples(audio)
+        started_at = time.perf_counter()
+        text = await self._transcribe_samples_via_ws(samples)
+
+        duration_ms = int((time.perf_counter() - started_at) * 1000)
+        if audio.duration_ms is not None:
+            duration_ms = int(audio.duration_ms)
+
+        result = Transcription(
+            text=text,
+            language=language if language != "auto" else None,
+            confidence=None,
+            duration_ms=duration_ms,
+        )
+        logger.info("{}: completed in {}ms, result={} chars", self.name, duration_ms, len(result.text))
+        return result
+
+    async def transcribe_stream(
+        self, stream: AsyncIterator[bytes]
+    ) -> AsyncIterator[Any]:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        try:
+            import websockets
+        except ImportError:
+            raise ImportError("Install websockets: pip install openspeech[server]")
+
+        import asyncio
+
+        _t0 = time.perf_counter()
+        _frames_sent = 0
+
+        ws_url = self._ws_url()
+        _sender_stop = asyncio.Event()
+
+        logger.debug("{}: connecting to Sherpa-ONNX WebSocket...", self.name)
+        async with websockets.connect(ws_url, open_timeout=self.settings.timeout_s) as ws:
+            _t_connected = time.perf_counter()
+            logger.info("{}: WS connected in {:.0f}ms", self.name,
+                        (_t_connected - _t0) * 1000)
+            sender_done = False
+            current_segment = 0
+            final_parts: list[str] = []
+            current_text = ""
+            _resp_count = 0
+
+            async def _sender() -> None:
+                nonlocal sender_done, _frames_sent
+                try:
+                    async for chunk in stream:
+                        if _sender_stop.is_set():
+                            break
+                        if not chunk:
+                            continue
+                        data = self._pcm16_bytes_to_float32_bytes(chunk)
+                        if data:
+                            await ws.send(data)
+                            _frames_sent += 1
+                            if _frames_sent == 1:
+                                logger.debug("{}: first frame sent at {:.0f}ms",
+                                             self.name, (time.perf_counter() - _t0) * 1000)
+                    if not _sender_stop.is_set():
+                        await ws.send("Done")
+                except websockets.exceptions.ConnectionClosed:
+                    pass
+                finally:
+                    sender_done = True
+                    logger.debug(
+                        "{}: stream sender done, sent {} frames in {:.0f}ms",
+                        self.name, _frames_sent, (time.perf_counter() - _t0) * 1000,
+                    )
+
+            send_task = asyncio.create_task(_sender())
+            try:
+                while True:
+                    try:
+                        raw = await asyncio.wait_for(ws.recv(), timeout=self.settings.recv_timeout_s)
+                    except asyncio.TimeoutError:
+                        if sender_done:
+                            break
+                        continue
+                    if not isinstance(raw, str):
+                        continue
+                    evt = self._parse_ws_event(raw)
+                    if evt is None:
+                        continue
+                    _resp_count += 1
+                    seg, txt = evt
+                    if _resp_count == 1:
+                        logger.debug("{}: first response at {:.0f}ms  seg={}",
+                                     self.name, (time.perf_counter() - _t0) * 1000, seg)
+                    if seg > current_segment:
+                        if current_text:
+                            final_parts.append(current_text)
+                        current_segment = seg
+                        current_text = txt
+                    else:
+                        current_text = txt
+                    merged = self._merge_with_current(final_parts, current_text)
+                    if merged:
+                        yield Transcription(text=merged, is_partial=True)
+            finally:
+                send_task.cancel()
+                try:
+                    await send_task
+                except asyncio.CancelledError:
+                    pass
+
+            merged = self._merge_with_current(final_parts, current_text)
+            if merged:
+                logger.info("{}: final result at {:.0f}ms  responses={}  text='{}'",
+                            self.name, (time.perf_counter() - _t0) * 1000,
+                            _resp_count, merged[:60])
+                yield Transcription(text=merged, is_partial=False)
+
+            logger.info(
+                "{}: stream completed in {:.0f}ms, frames={}",
+                self.name, (time.perf_counter() - _t0) * 1000, _frames_sent,
+            )
+
+    @staticmethod
+    def _merge_with_current(parts: list[str], current: str) -> str:
+        data = [p.strip() for p in parts if p and p.strip()]
+        c = (current or "").strip()
+        if c:
+            data.append(c)
+        return " ".join(data).strip()
+
+    def _parse_ws_event(self, raw: str) -> tuple[int, str] | None:
+        try:
+            payload = json.loads(raw)
+        except Exception:
+            txt = raw.strip()
+            return (0, txt) if txt else None
+        txt = str(payload.get("text", "")).strip()
+        if not txt:
+            return None
+        seg = int(payload.get("segment", 0) or 0)
+        return seg, txt
+
+    def _transcribe_chunk_frames(self, sample_count: int) -> int:
+        sample_rate = max(8000, int(self.settings.sample_rate))
+        chunk_ms = max(20, int(self.settings.chunk_ms))
+        frames = max(1, int(sample_rate * (chunk_ms / 1000.0)))
+        if sample_count < frames:
+            return sample_count
+        return frames
+
+    async def _transcribe_samples_via_ws(self, samples: list[float]) -> str:
+        try:
+            import websockets
+        except ImportError:
+            raise ImportError("Install websockets: pip install openspeech[server]")
+        ws_url = self._ws_url()
+        current_segment = 0
+        final_parts: list[str] = []
+        current_text = ""
+        import asyncio
+
+        async with websockets.connect(ws_url, open_timeout=self.settings.timeout_s) as ws:
+            i = 0
+            step = self._transcribe_chunk_frames(len(samples))
+            while i < len(samples):
+                chunk = samples[i:i + step]
+                i += step
+                if chunk:
+                    await ws.send(self._float32_list_to_bytes(chunk))
+
+            await ws.send("Done")
+            while True:
+                try:
+                    raw = await asyncio.wait_for(ws.recv(), timeout=self.settings.recv_timeout_s)
+                except asyncio.TimeoutError:
+                    break
+                if not isinstance(raw, str):
+                    continue
+                evt = self._parse_ws_event(raw)
+                if evt is None:
+                    continue
+                seg, txt = evt
+                if seg > current_segment:
+                    if current_text:
+                        final_parts.append(current_text)
+                    current_segment = seg
+                    current_text = txt
+                else:
+                    current_text = txt
+        return self._merge_with_current(final_parts, current_text)
+
+    @staticmethod
+    def _float32_list_to_bytes(samples: list[float]) -> bytes:
+        if not samples:
+            return b""
+        return struct.pack(f"<{len(samples)}f", *samples)
+
+    @staticmethod
+    def _pcm16_bytes_to_float32_bytes(data: bytes) -> bytes:
+        if not data:
+            return b""
+        usable = len(data) - (len(data) % 2)
+        if usable <= 0:
+            return b""
+        values = struct.unpack(f"<{usable // 2}h", data[:usable])
+        floats = [max(-1.0, min(1.0, v / 32768.0)) for v in values]
+        return struct.pack(f"<{len(floats)}f", *floats)
+
+    def _audio_to_float32_samples(self, audio: AudioData) -> list[float]:
+        if len(audio.data) > 12 and audio.data[:4] == b"RIFF" and audio.data[8:12] == b"WAVE":
+            with wave.open(io.BytesIO(audio.data), "rb") as wf:
+                channels = max(1, int(wf.getnchannels()))
+                sampwidth = int(wf.getsampwidth())
+                sample_rate = int(wf.getframerate())
+                frames = wf.readframes(wf.getnframes())
+            if sampwidth != 2:
+                raise RuntimeError("Only PCM16 WAV is supported for sherpa transcribe")
+            ints = struct.unpack(f"<{len(frames) // 2}h", frames)
+            if channels > 1:
+                mono: list[int] = []
+                for i in range(0, len(ints), channels):
+                    frame = ints[i:i + channels]
+                    mono.append(int(sum(frame) / max(1, len(frame))))
+                ints = tuple(mono)
+            samples = [max(-1.0, min(1.0, v / 32768.0)) for v in ints]
+            if sample_rate != int(self.settings.sample_rate):
+                return self._resample_linear(samples, sample_rate, int(self.settings.sample_rate))
+            return samples
+
+        # Raw PCM16 fallback.
+        raw = self._pcm16_bytes_to_float32_bytes(audio.data)
+        if not raw:
+            return []
+        count = len(raw) // 4
+        return list(struct.unpack(f"<{count}f", raw))
+
+    @staticmethod
+    def _resample_linear(samples: list[float], src_rate: int, dst_rate: int) -> list[float]:
+        if src_rate <= 0 or dst_rate <= 0 or src_rate == dst_rate or not samples:
+            return samples
+        ratio = dst_rate / src_rate
+        out_len = max(1, int(math.floor(len(samples) * ratio)))
+        out: list[float] = []
+        for i in range(out_len):
+            src_pos = i / ratio
+            left = int(math.floor(src_pos))
+            right = min(left + 1, len(samples) - 1)
+            frac = src_pos - left
+            val = samples[left] * (1.0 - frac) + samples[right] * frac
+            out.append(float(val))
+        return out