gdmcode 0.1.0__py3-none-any.whl

src/voice/audio_capture.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections import deque
+from typing import TYPE_CHECKING
+
+from src.voice.errors import AudioDeviceError
+from src.voice.models import VoiceConfig
+
+try:
+    import sounddevice as sd  # type: ignore[import-untyped]
+    _SD_AVAILABLE = True
+except ImportError:
+    _SD_AVAILABLE = False
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+RING_BUFFER_FRAMES = 50
+
+
+class AudioCapture:
+    """Wraps sounddevice mic input with a thread-safe ring buffer."""
+
+    def __init__(self, config: VoiceConfig) -> None:
+        self._config = config
+        self._buffer: deque[bytes] = deque(maxlen=RING_BUFFER_FRAMES)
+        self._lock = threading.Lock()
+        self._data_event = threading.Event()
+        self._stream: object | None = None
+        self._running = False
+
+    def start(self) -> None:
+        """Start sounddevice InputStream in a background thread."""
+        if not _SD_AVAILABLE:
+            raise AudioDeviceError("sounddevice not installed")
+
+        def _callback(indata: object, frames: int, time: object, status: object) -> None:  # type: ignore[override]
+            if status:
+                logger.warning("AudioCapture status: %s", status)
+            import numpy as np  # type: ignore[import-untyped]
+            raw = np.array(indata).tobytes()
+            with self._lock:
+                self._buffer.append(raw)
+            self._data_event.set()
+
+        self._stream = sd.InputStream(
+            samplerate=self._config.sample_rate,
+            channels=self._config.channels,
+            dtype="int16",
+            blocksize=self._config.chunk_size,
+            device=self._config.device_index,
+            callback=_callback,
+        )
+        self._stream.start()  # type: ignore[union-attr]
+        self._running = True
+
+    def stop(self) -> None:
+        """Stop stream and drain buffer."""
+        self._running = False
+        if self._stream is not None:
+            try:
+                self._stream.stop()  # type: ignore[union-attr]
+                self._stream.close()  # type: ignore[union-attr]
+            except Exception:
+                logger.debug("Error stopping audio stream", exc_info=True)
+            self._stream = None
+        self._data_event.set()  # unblock any waiting read_frames
+        with self._lock:
+            self._buffer.clear()
+
+    def read_frames(self, n: int) -> bytes:
+        """Read n frames from ring buffer, blocking up to 2s; returns what's available."""
+        collected: list[bytes] = []
+        deadline = 2.0
+        end = time.monotonic() + deadline
+        while len(collected) < n:
+            with self._lock:
+                while self._buffer and len(collected) < n:
+                    collected.append(self._buffer.popleft())
+            if len(collected) >= n:
+                break
+            remaining = end - time.monotonic()
+            if remaining <= 0:
+                break
+            self._data_event.wait(timeout=min(remaining, 0.1))
+            self._data_event.clear()
+        return b"".join(collected)

src/voice/audio_playback.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from src.voice.models import VoiceConfig
+
+try:
+    import sounddevice as sd  # type: ignore[import-untyped]
+    _SD_AVAILABLE = True
+except ImportError:
+    _SD_AVAILABLE = False
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger(__name__)
+
+_QUEUE_MAXSIZE = 32
+
+
+class AudioPlayback:
+    """Async TTS chunk queue drain via sounddevice output."""
+
+    def __init__(self, config: VoiceConfig) -> None:
+        self._config = config
+        self._queue: asyncio.Queue[bytes] = asyncio.Queue(maxsize=_QUEUE_MAXSIZE)
+        self._stop_event = asyncio.Event()
+
+    def play_chunk(self, audio_bytes: bytes) -> None:
+        """Non-blocking enqueue; logs warning and no-ops if sounddevice unavailable."""
+        if not _SD_AVAILABLE:
+            logger.warning("sounddevice not available; audio playback disabled")
+            return
+        try:
+            self._queue.put_nowait(audio_bytes)
+        except asyncio.QueueFull:
+            logger.warning("AudioPlayback queue full; dropping chunk")
+
+    def stop(self) -> None:
+        """Signal drain loop to stop and clear pending chunks."""
+        self._stop_event.set()
+        while not self._queue.empty():
+            try:
+                self._queue.get_nowait()
+            except asyncio.QueueEmpty:
+                break
+
+    async def drain(self) -> None:
+        """Dequeue chunks and write to sounddevice OutputStream."""
+        if not _SD_AVAILABLE:
+            return
+
+        import numpy as np  # type: ignore[import-untyped]
+
+        with sd.OutputStream(
+            samplerate=self._config.sample_rate,
+            channels=self._config.channels,
+            dtype="int16",
+        ) as stream:
+            while not self._stop_event.is_set():
+                try:
+                    chunk = await asyncio.wait_for(self._queue.get(), timeout=0.1)
+                except asyncio.TimeoutError:
+                    continue
+                audio_array = np.frombuffer(chunk, dtype="int16").reshape(-1, self._config.channels)
+                stream.write(audio_array)

src/voice/errors.py

@@ -0,0 +1,14 @@
+class VoiceError(Exception):
+    """Base voice error."""
+
+
+class AudioDeviceError(VoiceError):
+    """Audio device unavailable or misconfigured."""
+
+
+class STTError(VoiceError):
+    """Speech-to-text failure."""
+
+
+class TTSError(VoiceError):
+    """Text-to-speech failure."""

src/voice/models.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class STTEngine(Protocol):
+    def transcribe(self, audio_bytes: bytes, sample_rate: int = 16000) -> str: ...
+
+
+@runtime_checkable
+class TTSEngine(Protocol):
+    def synthesize(self, text: str) -> bytes: ...  # returns raw PCM bytes
+
+
+@dataclass
+class VoiceEvent:
+    type: str  # "speech_start" | "speech_end" | "utterance"
+    data: bytes = field(default_factory=bytes)
+    text: str = ""
+
+
+@dataclass
+class VoiceConfig:
+    sample_rate: int = 16000
+    channels: int = 1
+    frame_duration_ms: int = 20     # VAD frame size
+    vad_aggressiveness: int = 2     # 0-3
+    silence_timeout_ms: int = 550   # silence duration → speech endpoint
+    device_index: int | None = None  # None = system default
+    chunk_size: int = 320           # frames per read
+    stt_provider: str = "whisper"   # STT backend name
+    tts_provider: str = "pyttsx3"   # TTS backend name
+    language: str = "en"            # language hint for STT/TTS

src/voice/providers.py

@@ -0,0 +1,143 @@
+"""STT/TTS provider abstractions for the voice layer."""
+from __future__ import annotations
+
+import io
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class VoiceConfig:
+    """Provider-level voice configuration."""
+
+    stt_provider: str = "whisper"
+    tts_provider: str = "pyttsx3"
+    language: str = "en"
+    sample_rate: int = 16000
+
+
+class STTProvider(ABC):
+    """Abstract base for Speech-to-Text providers."""
+
+    @abstractmethod
+    def transcribe(self, audio_bytes: bytes) -> str:
+        """Transcribe audio bytes to text."""
+
+
+class TTSProvider(ABC):
+    """Abstract base for Text-to-Speech providers."""
+
+    @abstractmethod
+    def synthesize(self, text: str) -> bytes:
+        """Synthesize text to audio bytes."""
+
+
+class WhisperSTTProvider(STTProvider):
+    """OpenAI Whisper STT via openai.audio.transcriptions."""
+
+    def __init__(self, api_key: str | None = None) -> None:
+        self._api_key = api_key or os.environ.get("OPENAI_API_KEY")
+
+    def transcribe(self, audio_bytes: bytes) -> str:
+        import openai  # already a core dependency
+
+        client = openai.OpenAI(api_key=self._api_key)
+        audio_file = io.BytesIO(audio_bytes)
+        audio_file.name = "audio.wav"
+        result = client.audio.transcriptions.create(model="whisper-1", file=audio_file)
+        return result.text
+
+
+class DeepgramSTTProvider(STTProvider):
+    """Deepgram STT stub — install deepgram-sdk to use."""
+
+    def transcribe(self, audio_bytes: bytes) -> str:
+        raise NotImplementedError("install deepgram-sdk")
+
+
+class ElevenLabsTTSProvider(TTSProvider):
+    """ElevenLabs TTS stub — install elevenlabs to use."""
+
+    def synthesize(self, text: str) -> bytes:
+        raise NotImplementedError("install elevenlabs")
+
+
+class GTTSTTSProvider(TTSProvider):
+    """Google TTS via gtts library."""
+
+    def __init__(self, language: str = "en") -> None:
+        self._language = language
+
+    def synthesize(self, text: str) -> bytes:
+        try:
+            from gtts import gTTS  # type: ignore[import-untyped]
+        except ImportError as exc:
+            raise ImportError(
+                "gtts is not installed. Install it with: pip install gtts"
+            ) from exc
+
+        buf = io.BytesIO()
+        tts = gTTS(text=text, lang=self._language)
+        tts.write_to_fp(buf)
+        return buf.getvalue()
+
+
+class PyttsxTTSProvider(TTSProvider):
+    """pyttsx3 offline TTS."""
+
+    def synthesize(self, text: str) -> bytes:
+        try:
+            import pyttsx3  # type: ignore[import-untyped]
+        except ImportError as exc:
+            raise ImportError(
+                "pyttsx3 is not installed. Install it with: pip install pyttsx3"
+            ) from exc
+
+        import tempfile
+
+        engine = pyttsx3.init()
+        fd, tmp_path = tempfile.mkstemp(suffix=".wav")
+        os.close(fd)
+        try:
+            engine.save_to_file(text, tmp_path)
+            engine.runAndWait()
+            with open(tmp_path, "rb") as f:
+                return f.read()
+        finally:
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass
+
+
+_STT_REGISTRY: dict[str, type[STTProvider]] = {
+    "whisper": WhisperSTTProvider,
+    "deepgram": DeepgramSTTProvider,
+}
+
+_TTS_REGISTRY: dict[str, type[TTSProvider]] = {
+    "gtts": GTTSTTSProvider,
+    "elevenlabs": ElevenLabsTTSProvider,
+    "pyttsx3": PyttsxTTSProvider,
+}
+
+
+def get_stt(provider: str = "whisper") -> STTProvider:
+    """Return an STTProvider instance by name."""
+    try:
+        return _STT_REGISTRY[provider]()
+    except KeyError:
+        raise ValueError(
+            f"Unknown STT provider: {provider!r}. Available: {list(_STT_REGISTRY)}"
+        )
+
+
+def get_tts(provider: str = "pyttsx3") -> TTSProvider:
+    """Return a TTSProvider instance by name."""
+    try:
+        return _TTS_REGISTRY[provider]()
+    except KeyError:
+        raise ValueError(
+            f"Unknown TTS provider: {provider!r}. Available: {list(_TTS_REGISTRY)}"
+        )

src/voice/vad.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import logging
+
+from src.voice.models import VoiceConfig
+
+try:
+    import webrtcvad  # type: ignore[import-untyped]
+    _VAD_AVAILABLE = True
+except ImportError:
+    _VAD_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+
+class VADProcessor:
+    """webrtcvad-based voice activity detection."""
+
+    def __init__(self, config: VoiceConfig) -> None:
+        self._config = config
+        self._speech_active = False
+        self._silent_frames = 0
+
+        if _VAD_AVAILABLE:
+            self._vad = webrtcvad.Vad(config.vad_aggressiveness)
+        else:
+            self._vad = None
+
+        # How many consecutive silent frames equal silence_timeout_ms
+        frame_ms = config.frame_duration_ms or 20
+        self._silence_frame_limit = max(1, config.silence_timeout_ms // frame_ms)
+
+    @property
+    def is_speech_active(self) -> bool:
+        return self._speech_active
+
+    def process(self, frame: bytes) -> bool:
+        """Return True if speech detected in this 20ms frame."""
+        if not _VAD_AVAILABLE or self._vad is None:
+            # Graceful degradation: treat everything as speech
+            self._speech_active = True
+            self._silent_frames = 0
+            return True
+
+        is_speech = self._vad.is_speech(frame, self._config.sample_rate)
+
+        if is_speech:
+            self._speech_active = True
+            self._silent_frames = 0
+        else:
+            self._silent_frames += 1
+            if self._silent_frames >= self._silence_frame_limit:
+                self._speech_active = False
+
+        return bool(is_speech)

src/voice/voice_loop.py

@@ -0,0 +1,156 @@
+"""VoiceLoop — connects mic input → STT → agent → TTS output.
+
+Usage (push-to-talk):
+    loop = VoiceLoop(config, agent_fn)
+    audio_response = loop.push_to_talk(audio_bytes)
+
+Usage (streaming / background):
+    loop = VoiceLoop(config, agent_fn)
+    loop.start()   # launches background thread
+    ...
+    loop.stop()    # graceful shutdown
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from typing import TYPE_CHECKING, Callable
+
+from src.voice.errors import STTError, TTSError, VoiceError
+from src.voice.models import VoiceConfig
+
+if TYPE_CHECKING:
+    from src.voice.providers import STTProvider, TTSProvider
+
+__all__ = ["VoiceLoop", "VoiceLoopError"]
+
+logger = logging.getLogger(__name__)
+
+
+class VoiceLoopError(VoiceError):
+    """Raised when VoiceLoop encounters an unrecoverable pipeline error."""
+
+
+class VoiceLoop:
+    """Full mic → STT → agent → TTS pipeline.
+
+    Parameters
+    ----------
+    config:
+        Voice configuration (sample rate, provider names, …).
+    agent_send_fn:
+        Callable that accepts a text prompt and returns the agent's text reply.
+    stt:
+        Optional STT provider instance.  If *None* the provider is resolved via
+        :func:`src.voice.providers.get_stt` using ``config.stt_provider``.
+    tts:
+        Optional TTS provider instance.  If *None* the provider is resolved via
+        :func:`src.voice.providers.get_tts` using ``config.tts_provider``.
+    """
+
+    def __init__(
+        self,
+        config: VoiceConfig,
+        agent_send_fn: Callable[[str], str],
+        *,
+        stt: STTProvider | None = None,
+        tts: TTSProvider | None = None,
+    ) -> None:
+        self._config = config
+        self._agent_send_fn = agent_send_fn
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+
+        if stt is not None:
+            self._stt = stt
+        else:
+            from src.voice.providers import get_stt
+            self._stt = get_stt(config.stt_provider)
+
+        if tts is not None:
+            self._tts = tts
+        else:
+            from src.voice.providers import get_tts
+            self._tts = get_tts(config.tts_provider)
+
+    # ------------------------------------------------------------------
+    # Thread lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        """Start the background listening thread.
+
+        Calling *start* when the thread is already alive is a no-op.
+        """
+        if self._thread is not None and self._thread.is_alive():
+            return
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._listen_loop,
+            name="voice-loop",
+            daemon=True,
+        )
+        self._thread.start()
+        logger.debug("VoiceLoop: background thread started")
+
+    def stop(self) -> None:
+        """Signal the background thread to stop and wait up to 5 s for it to join."""
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=5.0)
+            self._thread = None
+        logger.debug("VoiceLoop: background thread stopped")
+
+    def _listen_loop(self) -> None:
+        """Background loop — runs until _stop_event is set."""
+        logger.debug("VoiceLoop: listen loop entered")
+        while not self._stop_event.is_set():
+            # In a real implementation this would read frames from AudioCapture
+            # and feed them through run_once().  For now we just wait.
+            self._stop_event.wait(timeout=0.05)
+        logger.debug("VoiceLoop: listen loop exited")
+
+    # ------------------------------------------------------------------
+    # Core pipeline
+    # ------------------------------------------------------------------
+
+    def run_once(self, audio_bytes: bytes) -> bytes:
+        """Transcribe *audio_bytes* → call agent → synthesize → return audio bytes.
+
+        Returns an empty ``bytes`` object if STT produced no speech (silence).
+
+        Raises
+        ------
+        VoiceLoopError
+            If the STT, agent, or TTS step fails.
+        """
+        # 1. Transcribe
+        try:
+            text = self._stt.transcribe(audio_bytes)
+        except (STTError, Exception) as exc:
+            raise VoiceLoopError(f"STT failed: {exc}") from exc
+
+        if not text or not text.strip():
+            return b""
+
+        # 2. Send to agent
+        try:
+            response_text = self._agent_send_fn(text)
+        except Exception as exc:
+            raise VoiceLoopError(f"Agent call failed: {exc}") from exc
+
+        # 3. Synthesize
+        try:
+            audio_response = self._tts.synthesize(response_text)
+        except (TTSError, Exception) as exc:
+            raise VoiceLoopError(f"TTS failed: {exc}") from exc
+
+        return audio_response
+
+    def push_to_talk(self, audio_bytes: bytes) -> bytes:
+        """Convenience alias — transcribe + agent + synthesize in one call.
+
+        Identical to :meth:`run_once`; provided as a named entry-point that
+        mirrors the push-to-talk UX pattern.
+        """
+        return self.run_once(audio_bytes)