openspeechapi 0.1.0__py3-none-any.whl

openspeech/providers/tts/macos_say.py

@@ -0,0 +1,251 @@
+"""macOS native TTS provider using the ``say`` command."""
+from __future__ import annotations
+
+import asyncio
+import io
+from openspeech.logging_config import logger
+import shutil
+import struct
+import tempfile
+import time
+import wave
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from pathlib import Path
+
+from openspeech.core.base import TTSProvider
+
+from openspeech.core.enums import AudioFormat, Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioChunk, AudioData, TTSOptions
+from openspeech.core.settings import BaseSettings
+from openspeech.utils.audio_converter import AudioConverter
+
+# Language prefix → human-readable group name
+_LANG_GROUP_MAP: dict[str, str] = {
+    "zh": "中文",
+    "en": "English",
+    "ja": "日本語",
+    "ko": "한국어",
+    "fr": "Français",
+    "de": "Deutsch",
+    "es": "Español",
+    "it": "Italiano",
+    "pt": "Português",
+    "ru": "Русский",
+    "ar": "العربية",
+    "nl": "Nederlands",
+    "sv": "Svenska",
+    "da": "Dansk",
+    "fi": "Suomi",
+    "nb": "Norsk",
+    "pl": "Polski",
+    "tr": "Türkçe",
+    "th": "ไทย",
+    "hi": "हिन्दी",
+    "he": "עברית",
+    "ro": "Română",
+    "hu": "Magyar",
+    "cs": "Čeština",
+    "el": "Ελληνικά",
+    "id": "Bahasa Indonesia",
+    "vi": "Tiếng Việt",
+}
+
+@dataclass
+class MacOSSaySettings(BaseSettings):
+    default_voice: str = "Samantha"
+    default_rate: int = 200
+
+class MacOSSayTTS(TTSProvider):
+    """macOS native TTS via the ``say`` command-line tool."""
+
+    name = "macos-say"
+    provider_type = ProviderType.TTS
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = MacOSSaySettings
+    capabilities = {Capability.BATCH, Capability.MULTILINGUAL}
+
+    def __init__(self, settings: MacOSSaySettings | None = None) -> None:
+        self.settings = settings or MacOSSaySettings()
+        self._available: bool = False
+        self._voices_cache: list[dict] | None = None
+
+    # -- lifecycle ------------------------------------------------------------
+
+    async def start(self) -> None:
+        if shutil.which("say") is None:
+            raise RuntimeError(
+                "macOS 'say' command not found — this provider requires macOS"
+            )
+        self._available = True
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        self._available = False
+        self._voices_cache = None
+        logger.info("{} provider stopped", self.name)
+
+    async def health_check(self) -> bool:
+        if self._available:
+            return True
+        # Pre-start check: verify say command exists on macOS
+        return shutil.which("say") is not None
+
+    # -- synthesis ------------------------------------------------------------
+
+    async def synthesize(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AudioData:
+        if not self._available:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: request received, text={} chars", self.name, len(text))
+        _t0 = time.perf_counter()
+
+        opts = opts or TTSOptions()
+        voice = opts.voice or self.settings.default_voice
+        rate = int(self.settings.default_rate * opts.speed)
+
+        tmp_path: str | None = None
+        try:
+            # Create a temp file for the AIFF output
+            fd, tmp_path = tempfile.mkstemp(suffix=".aiff")
+            import os
+            os.close(fd)
+
+            await self._run_say(voice, rate, tmp_path, text)
+
+            aiff_data = Path(tmp_path).read_bytes()
+
+            # Convert AIFF → WAV via AudioConverter
+            aiff_audio = AudioData(
+                data=aiff_data,
+                sample_rate=22050,  # placeholder; to_wav parses AIFF header
+                channels=1,
+                format=AudioFormat.AIFF,
+            )
+            wav_audio = AudioConverter.to_wav(aiff_audio)
+
+            # Parse WAV to compute duration
+            with wave.open(io.BytesIO(wav_audio.data), "rb") as wf:
+                n_frames = wf.getnframes()
+                frame_rate = wf.getframerate()
+                duration_ms = int(n_frames / frame_rate * 1000) if frame_rate else 0
+
+            result = AudioData(
+                data=wav_audio.data,
+                sample_rate=wav_audio.sample_rate,
+                channels=wav_audio.channels,
+                format=AudioFormat.WAV,
+                duration_ms=duration_ms,
+            )
+            logger.info("{}: completed in {:.0f}ms, output={} bytes", self.name, (time.perf_counter() - _t0) * 1000, len(result.data))
+            return result
+        finally:
+            if tmp_path is not None:
+                try:
+                    Path(tmp_path).unlink(missing_ok=True)
+                except OSError:
+                    pass
+
+    async def synthesize_stream(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AsyncIterator[AudioChunk]:
+        """Batch-then-chunk fallback: synthesize full audio, then yield chunks."""
+        logger.info("{}: stream request, text={} chars", self.name, len(text))
+        _t0 = time.perf_counter()
+        result = await self.synthesize(text, opts)
+        chunk_size = 4096
+        sequence = 0
+        chunk_count = 0
+        for i in range(0, len(result.data), chunk_size):
+            chunk_data = result.data[i : i + chunk_size]
+            logger.debug("{}: chunk #{}, {} bytes", self.name, sequence, len(chunk_data))
+            yield AudioChunk(data=chunk_data, sequence=sequence)
+            sequence += 1
+            chunk_count += 1
+        yield AudioChunk(data=b"", sequence=sequence, is_final=True)
+        logger.info("{}: stream complete, {} chunks in {:.0f}ms", self.name, chunk_count, (time.perf_counter() - _t0) * 1000)
+
+    # -- voices ---------------------------------------------------------------
+
+    async def list_voices(self) -> list[dict]:
+        if self._voices_cache is not None:
+            return self._voices_cache
+
+        output = await self._run_command(["say", "-v", "?"])
+        self._voices_cache = self._parse_voices_output(output)
+        return self._voices_cache
+
+    # -- internal helpers -----------------------------------------------------
+
+    async def _run_say(
+        self, voice: str, rate: int, output_path: str, text: str
+    ) -> None:
+        """Execute ``say`` to produce an AIFF file."""
+        cmd = ["say", "-v", voice, "-r", str(rate), "-o", output_path, "--", text]
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        _, stderr = await proc.communicate()
+        if proc.returncode != 0:
+            raise RuntimeError(
+                f"say command failed (exit {proc.returncode}): "
+                f"{stderr.decode(errors='replace')}"
+            )
+
+    async def _run_command(self, cmd: list[str]) -> str:
+        """Run an arbitrary command and return its stdout."""
+        proc = await asyncio.create_subprocess_exec(
+            *cmd,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        stdout, _ = await proc.communicate()
+        return stdout.decode(errors="replace")
+
+    @staticmethod
+    def _parse_voices_output(output: str) -> list[dict]:
+        """Parse the output of ``say -v ?`` into a list of voice dicts.
+
+        Expected line format::
+
+            Samantha            en_US    # Hello, my name is Samantha.
+        """
+        voices: list[dict] = []
+        for line in output.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+
+            # Split on '#' to separate the description
+            description = ""
+            if "#" in line:
+                main_part, description = line.split("#", 1)
+                description = description.strip()
+            else:
+                main_part = line
+
+            # The name and language are separated by whitespace.
+            # Name can contain spaces, but language is always the last
+            # whitespace-separated token before the '#'.
+            parts = main_part.rsplit(None, 1)
+            if len(parts) < 2:
+                continue
+
+            name = parts[0].strip()
+            language = parts[1].strip()
+
+            # Derive group from language prefix
+            lang_prefix = language.split("_")[0].lower()
+            group = _LANG_GROUP_MAP.get(lang_prefix, lang_prefix.upper())
+
+            voices.append({
+                "name": name,
+                "language": language,
+                "description": description,
+                "group": group,
+            })
+
+        return voices

openspeech/providers/tts/minimax.py

@@ -0,0 +1,122 @@
+"""MiniMax TTS provider adapter (REST API, in-process)."""
+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
+
+from openspeech.core.base import TTSProvider
+
+from openspeech.core.enums import AudioFormat, Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioChunk, AudioData, TTSOptions
+from openspeech.core.settings import BaseSettings
+
+@dataclass
+class MinimaxTTSSettings(BaseSettings):
+    api_key: str = ""
+    group_id: str = ""
+    model: str = "speech-01"
+    voice_id: str = "male-qn-qingse"
+    speed: float = 1.0
+    vol: float = 1.0
+    pitch: int = 0
+
+class MinimaxTTS(TTSProvider):
+    name = "minimax"
+    provider_type = ProviderType.TTS
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = MinimaxTTSSettings
+    capabilities = {Capability.STREAMING}
+    field_options = {
+        "model": ["speech-01", "speech-01-turbo", "speech-02"],
+        "voice_id": [
+            "male-qn-qingse", "male-qn-jingying", "male-qn-badao", "male-qn-daxuesheng",
+            "female-shaonv", "female-yujie", "female-chengshu", "female-tianmei",
+            "presenter_male", "presenter_female",
+        ],
+    }
+
+    def __init__(self, settings: MinimaxTTSSettings | None = None) -> None:
+        self.settings = settings or MinimaxTTSSettings()
+        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[minimax]"
+                )
+            self._client = httpx.AsyncClient(timeout=30.0)
+            self._owns_client = True
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        if self._client is not None 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 synthesize(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AudioData:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: request received, text={} chars", self.name, len(text))
+        _t0 = time.perf_counter()
+        opts = opts or TTSOptions()
+        url = f"https://api.minimax.chat/v1/t2a_v2?GroupId={self.settings.group_id}"
+        payload = {
+            "model": self.settings.model,
+            "text": text,
+            "stream": False,
+            "voice_setting": {
+                "voice_id": opts.voice or self.settings.voice_id,
+                "speed": opts.speed if opts.speed != 1.0 else self.settings.speed,
+                "vol": self.settings.vol,
+                "pitch": self.settings.pitch,
+            },
+            "audio_setting": {
+                "sample_rate": 32000,
+                "bitrate": 128000,
+                "format": "mp3",
+            },
+        }
+        headers = {
+            "Authorization": f"Bearer {self.settings.api_key}",
+            "Content-Type": "application/json",
+        }
+        response = await self._client.post(url, json=payload, headers=headers)
+        response.raise_for_status()
+        data = response.json()
+        if "data" in data and "audio" in data["data"]:
+            audio_bytes = base64.b64decode(data["data"]["audio"])
+            result = AudioData(
+                data=audio_bytes,
+                sample_rate=32000,
+                channels=1,
+                format=AudioFormat.MP3,
+            )
+            logger.info("{}: completed in {:.0f}ms, output={} bytes", self.name, (time.perf_counter() - _t0) * 1000, len(result.data))
+            return result
+        raise RuntimeError(f"Minimax API error: {data}")
+
+    async def synthesize_stream(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AsyncIterator[AudioChunk]:
+        raise NotImplementedError(
+            "MinimaxTTS.synthesize_stream() — streaming not yet implemented"
+        )
+        yield  # pragma: no cover

openspeech/providers/tts/openai.py

@@ -0,0 +1,104 @@
+"""OpenAI TTS provider adapter (speech API)."""
+from __future__ import annotations
+
+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 TTSProvider
+
+from openspeech.core.enums import Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioChunk, AudioData, TTSOptions
+from openspeech.core.settings import BaseSettings
+
+@dataclass
+class OpenAITTSSettings(BaseSettings):
+    api_key: str = ""
+    base_url: str = ""
+    model: str = "tts-1"
+    voice: str = "alloy"
+    response_format: str = "pcm"
+
+class OpenAITTS(TTSProvider):
+    name = "openai-tts"
+    provider_type = ProviderType.TTS
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = OpenAITTSSettings
+    capabilities = {Capability.STREAMING, Capability.MULTILINGUAL}
+    field_options = {"model": ["tts-1", "tts-1-hd", "gpt-4o-mini-tts"], "voice": ["alloy", "ash", "ballad", "coral", "echo", "fable", "nova", "onyx", "sage", "shimmer", "verse"]}
+
+    def __init__(self, settings: OpenAITTSSettings | None = None) -> None:
+        self.settings = settings or OpenAITTSSettings()
+        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 synthesize(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AudioData:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: request received, text={} chars", self.name, len(text))
+        _t0 = time.perf_counter()
+        opts = opts or TTSOptions()
+        voice = opts.voice or self.settings.voice
+        model = getattr(opts, "model", None) or self.settings.model
+        response = await self._client.audio.speech.create(
+            model=model,
+            voice=voice,
+            input=text,
+            response_format=self.settings.response_format,
+        )
+        audio_bytes = response.content
+        result = AudioData(
+            data=audio_bytes,
+            sample_rate=24000,
+            channels=1,
+            format=opts.output_format,
+        )
+        logger.info("{}: completed in {:.0f}ms, output={} bytes", self.name, (time.perf_counter() - _t0) * 1000, len(result.data))
+        return result
+
+    async def synthesize_stream(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AsyncIterator[AudioChunk]:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: stream request, text={} chars", self.name, len(text))
+        _t0 = time.perf_counter()
+        opts = opts or TTSOptions()
+        voice = opts.voice or self.settings.voice
+        model = getattr(opts, "model", None) or self.settings.model
+        chunk_count = 0
+        async with self._client.audio.speech.with_streaming_response.create(
+            model=model,
+            voice=voice,
+            input=text,
+            response_format=self.settings.response_format,
+        ) as response:
+            sequence = 0
+            async for chunk in response.iter_bytes(chunk_size=4096):
+                logger.debug("{}: chunk #{}, {} bytes", self.name, sequence, len(chunk))
+                yield AudioChunk(data=chunk, sequence=sequence)
+                sequence += 1
+                chunk_count += 1
+            yield AudioChunk(data=b"", sequence=sequence, is_final=True)
+        logger.info("{}: stream complete, {} chunks in {:.0f}ms", self.name, chunk_count, (time.perf_counter() - _t0) * 1000)

openspeech/providers/tts/piper.py

@@ -0,0 +1,104 @@
+"""Piper TTS provider adapter (batch, in-process)."""
+from __future__ import annotations
+
+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 TTSProvider
+
+from openspeech.core.enums import AudioFormat, Capability, ExecMode, ProviderType
+from openspeech.core.models import AudioChunk, AudioData, TTSOptions
+from openspeech.core.settings import BaseSettings
+
+@dataclass
+class PiperTTSSettings(BaseSettings):
+    model_path: str = ""
+    config_path: str = ""
+    use_cuda: bool = False
+    noise_scale: float = 0.667
+    length_scale: float = 1.0
+    noise_w: float = 0.8
+
+class PiperTTS(TTSProvider):
+    name = "piper"
+    provider_type = ProviderType.TTS
+    execution_mode = ExecMode.IN_PROCESS
+    settings_cls = PiperTTSSettings
+    capabilities = {Capability.BATCH}
+
+    def __init__(self, settings: PiperTTSSettings | None = None) -> None:
+        self.settings = settings or PiperTTSSettings()
+        self._client: Any = None
+        self._voice: Any = None
+
+    async def start(self) -> None:
+        try:
+            import piper
+        except ImportError:
+            raise ImportError(
+                "Install piper-tts: pip install openspeech[piper]"
+            )
+        self._voice = piper.PiperVoice.load(
+            self.settings.model_path,
+            config_path=self.settings.config_path or None,
+            use_cuda=self.settings.use_cuda,
+        )
+        self._client = self._voice
+        logger.info("{} provider started", self.name)
+
+    async def stop(self) -> None:
+        self._client = None
+        self._voice = None
+        logger.info("{} provider stopped", self.name)
+
+    async def health_check(self) -> bool:
+        return self._client is not None
+
+    async def synthesize(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AudioData:
+        if self._client is None:
+            raise RuntimeError("Provider not started — call start() first")
+        logger.info("{}: request received, text={} chars", self.name, len(text))
+        _t0 = time.perf_counter()
+        import io
+        import wave
+
+        audio_data = b""
+        for audio_bytes in self._voice.synthesize_stream_raw(
+            text,
+            length_scale=self.settings.length_scale,
+            noise_scale=self.settings.noise_scale,
+            noise_w=self.settings.noise_w,
+        ):
+            audio_data += audio_bytes
+
+        sample_rate = 22050
+        if hasattr(self._voice, "config") and hasattr(self._voice.config, "sample_rate"):
+            sample_rate = self._voice.config.sample_rate
+
+        buf = io.BytesIO()
+        with wave.open(buf, "wb") as wf:
+            wf.setnchannels(1)
+            wf.setsampwidth(2)
+            wf.setframerate(sample_rate)
+            wf.writeframes(audio_data)
+        result = AudioData(
+            data=buf.getvalue(),
+            sample_rate=sample_rate,
+            channels=1,
+            format=AudioFormat.WAV,
+        )
+        logger.info("{}: completed in {:.0f}ms, output={} bytes", self.name, (time.perf_counter() - _t0) * 1000, len(result.data))
+        return result
+
+    async def synthesize_stream(
+        self, text: str, opts: TTSOptions | None = None
+    ) -> AsyncIterator[AudioChunk]:
+        raise NotImplementedError(
+            "PiperTTS does not support streaming synthesis"
+        )
+        yield  # pragma: no cover