roomkit 0.1.1__py3-none-any.whl → 0.2.1__py3-none-any.whl

roomkit/voice/backends/mock.py

@@ -0,0 +1,302 @@
+"""Mock voice backend for testing."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+from roomkit.voice.backends.base import VoiceBackend
+from roomkit.voice.base import (
+    AudioChunk,
+    BargeInCallback,
+    PartialTranscriptionCallback,
+    SpeechEndCallback,
+    SpeechStartCallback,
+    VADAudioLevelCallback,
+    VADSilenceCallback,
+    VoiceCapability,
+    VoiceSession,
+    VoiceSessionState,
+)
+
+
+@dataclass
+class MockVoiceCall:
+    """Record of a call made to MockVoiceBackend."""
+
+    method: str
+    args: dict[str, Any] = field(default_factory=dict)
+
+
+class MockVoiceBackend(VoiceBackend):
+    """Mock voice backend for testing.
+
+    Tracks all method calls and provides helpers to simulate VAD events.
+
+    Example:
+        backend = MockVoiceBackend()
+
+        # Track calls
+        session = await backend.connect("room-1", "user-1", "voice-1")
+        assert backend.calls[-1].method == "connect"
+
+        # Simulate speech events
+        await backend.simulate_speech_start(session)
+        await backend.simulate_speech_end(session, b"audio-data")
+
+        # Simulate enhanced events (RFC §19)
+        await backend.simulate_partial_transcription(session, "Hello", 0.8, False)
+        await backend.simulate_vad_silence(session, 500)
+        await backend.simulate_barge_in(session)
+    """
+
+    def __init__(
+        self,
+        *,
+        capabilities: VoiceCapability = VoiceCapability.NONE,
+    ) -> None:
+        """Initialize MockVoiceBackend.
+
+        Args:
+            capabilities: Optional capabilities to enable for testing.
+                Defaults to NONE. Set to test capability-dependent behavior.
+        """
+        self._sessions: dict[str, VoiceSession] = {}
+        self._speech_start_callbacks: list[SpeechStartCallback] = []
+        self._speech_end_callbacks: list[SpeechEndCallback] = []
+        # Enhanced callbacks (RFC §19)
+        self._partial_transcription_callbacks: list[PartialTranscriptionCallback] = []
+        self._vad_silence_callbacks: list[VADSilenceCallback] = []
+        self._vad_audio_level_callbacks: list[VADAudioLevelCallback] = []
+        self._barge_in_callbacks: list[BargeInCallback] = []
+        # Tracking
+        self.calls: list[MockVoiceCall] = []
+        self.sent_audio: list[tuple[str, bytes]] = []  # (session_id, audio)
+        self.sent_transcriptions: list[tuple[str, str, str]] = []  # (session_id, text, role)
+        self._playing_sessions: set[str] = set()  # Sessions currently receiving audio
+        self._capabilities = capabilities
+
+    @property
+    def name(self) -> str:
+        return "MockVoiceBackend"
+
+    @property
+    def capabilities(self) -> VoiceCapability:
+        return self._capabilities
+
+    async def connect(
+        self,
+        room_id: str,
+        participant_id: str,
+        channel_id: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> VoiceSession:
+        session = VoiceSession(
+            id=uuid4().hex,
+            room_id=room_id,
+            participant_id=participant_id,
+            channel_id=channel_id,
+            state=VoiceSessionState.ACTIVE,
+            metadata=metadata or {},
+        )
+        self._sessions[session.id] = session
+        self.calls.append(
+            MockVoiceCall(
+                method="connect",
+                args={
+                    "room_id": room_id,
+                    "participant_id": participant_id,
+                    "channel_id": channel_id,
+                    "metadata": metadata,
+                },
+            )
+        )
+        return session
+
+    async def disconnect(self, session: VoiceSession) -> None:
+        if session.id in self._sessions:
+            self._sessions[session.id] = VoiceSession(
+                id=session.id,
+                room_id=session.room_id,
+                participant_id=session.participant_id,
+                channel_id=session.channel_id,
+                state=VoiceSessionState.ENDED,
+                created_at=session.created_at,
+                metadata=session.metadata,
+            )
+        self.calls.append(
+            MockVoiceCall(method="disconnect", args={"session_id": session.id})
+        )
+
+    def on_speech_start(self, callback: SpeechStartCallback) -> None:
+        self._speech_start_callbacks.append(callback)
+        self.calls.append(MockVoiceCall(method="on_speech_start"))
+
+    def on_speech_end(self, callback: SpeechEndCallback) -> None:
+        self._speech_end_callbacks.append(callback)
+        self.calls.append(MockVoiceCall(method="on_speech_end"))
+
+    async def send_audio(
+        self,
+        session: VoiceSession,
+        audio: bytes | AsyncIterator[AudioChunk],
+    ) -> None:
+        if isinstance(audio, bytes):
+            self.sent_audio.append((session.id, audio))
+        else:
+            # Collect chunks from async iterator
+            chunks: list[bytes] = []
+            async for chunk in audio:
+                chunks.append(chunk.data)
+            combined = b"".join(chunks)
+            self.sent_audio.append((session.id, combined))
+
+        self.calls.append(
+            MockVoiceCall(method="send_audio", args={"session_id": session.id})
+        )
+
+    def get_session(self, session_id: str) -> VoiceSession | None:
+        return self._sessions.get(session_id)
+
+    def list_sessions(self, room_id: str) -> list[VoiceSession]:
+        return [s for s in self._sessions.values() if s.room_id == room_id]
+
+    async def close(self) -> None:
+        self._sessions.clear()
+        self._playing_sessions.clear()
+        self.calls.append(MockVoiceCall(method="close"))
+
+    async def send_transcription(
+        self, session: VoiceSession, text: str, role: str = "user"
+    ) -> None:
+        self.sent_transcriptions.append((session.id, text, role))
+        self.calls.append(
+            MockVoiceCall(
+                method="send_transcription",
+                args={"session_id": session.id, "text": text, "role": role},
+            )
+        )
+
+    # -------------------------------------------------------------------------
+    # Enhanced voice capabilities (RFC §19)
+    # -------------------------------------------------------------------------
+
+    def on_partial_transcription(
+        self, callback: PartialTranscriptionCallback
+    ) -> None:
+        self._partial_transcription_callbacks.append(callback)
+        self.calls.append(MockVoiceCall(method="on_partial_transcription"))
+
+    def on_vad_silence(self, callback: VADSilenceCallback) -> None:
+        self._vad_silence_callbacks.append(callback)
+        self.calls.append(MockVoiceCall(method="on_vad_silence"))
+
+    def on_vad_audio_level(self, callback: VADAudioLevelCallback) -> None:
+        self._vad_audio_level_callbacks.append(callback)
+        self.calls.append(MockVoiceCall(method="on_vad_audio_level"))
+
+    def on_barge_in(self, callback: BargeInCallback) -> None:
+        self._barge_in_callbacks.append(callback)
+        self.calls.append(MockVoiceCall(method="on_barge_in"))
+
+    async def cancel_audio(self, session: VoiceSession) -> bool:
+        was_playing = session.id in self._playing_sessions
+        self._playing_sessions.discard(session.id)
+        self.calls.append(
+            MockVoiceCall(
+                method="cancel_audio",
+                args={"session_id": session.id, "was_playing": was_playing},
+            )
+        )
+        return was_playing
+
+    def is_playing(self, session: VoiceSession) -> bool:
+        return session.id in self._playing_sessions
+
+    # -------------------------------------------------------------------------
+    # Test helpers
+    # -------------------------------------------------------------------------
+
+    async def simulate_speech_start(self, session: VoiceSession) -> None:
+        """Simulate VAD detecting speech start.
+
+        Fires all registered on_speech_start callbacks.
+        """
+        for callback in self._speech_start_callbacks:
+            result = callback(session)
+            if hasattr(result, "__await__"):
+                await result
+
+    async def simulate_speech_end(self, session: VoiceSession, audio: bytes) -> None:
+        """Simulate VAD detecting speech end.
+
+        Fires all registered on_speech_end callbacks with the audio data.
+        """
+        for callback in self._speech_end_callbacks:
+            result = callback(session, audio)
+            if hasattr(result, "__await__"):
+                await result
+
+    async def simulate_partial_transcription(
+        self,
+        session: VoiceSession,
+        text: str,
+        confidence: float = 0.8,
+        is_stable: bool = False,
+    ) -> None:
+        """Simulate streaming STT partial result.
+
+        Fires all registered on_partial_transcription callbacks.
+        """
+        for callback in self._partial_transcription_callbacks:
+            result = callback(session, text, confidence, is_stable)
+            if hasattr(result, "__await__"):
+                await result
+
+    async def simulate_vad_silence(
+        self, session: VoiceSession, silence_duration_ms: int
+    ) -> None:
+        """Simulate VAD detecting silence.
+
+        Fires all registered on_vad_silence callbacks.
+        """
+        for callback in self._vad_silence_callbacks:
+            result = callback(session, silence_duration_ms)
+            if hasattr(result, "__await__"):
+                await result
+
+    async def simulate_vad_audio_level(
+        self,
+        session: VoiceSession,
+        level_db: float,
+        is_speech: bool = True,
+    ) -> None:
+        """Simulate audio level update.
+
+        Fires all registered on_vad_audio_level callbacks.
+        """
+        for callback in self._vad_audio_level_callbacks:
+            result = callback(session, level_db, is_speech)
+            if hasattr(result, "__await__"):
+                await result
+
+    async def simulate_barge_in(self, session: VoiceSession) -> None:
+        """Simulate user speaking while TTS is playing (barge-in).
+
+        Fires all registered on_barge_in callbacks.
+        """
+        for callback in self._barge_in_callbacks:
+            result = callback(session)
+            if hasattr(result, "__await__"):
+                await result
+
+    def start_playing(self, session: VoiceSession) -> None:
+        """Mark a session as playing audio (for barge-in testing)."""
+        self._playing_sessions.add(session.id)
+
+    def stop_playing(self, session: VoiceSession) -> None:
+        """Mark a session as no longer playing audio."""
+        self._playing_sessions.discard(session.id)

roomkit/voice/base.py

@@ -0,0 +1,115 @@
+"""Base models for voice support."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Flag, StrEnum, auto, unique
+from typing import Any
+
+
+@unique
+class VoiceSessionState(StrEnum):
+    """State of a voice session."""
+
+    CONNECTING = "connecting"
+    ACTIVE = "active"
+    PAUSED = "paused"
+    ENDED = "ended"
+
+
+class VoiceCapability(Flag):
+    """Capabilities a VoiceBackend can support (RFC §19).
+
+    Backends declare their capabilities via the `capabilities` property.
+    This allows RoomKit to know which features are available and
+    enables integrators to choose backends based on their needs.
+
+    Example:
+        class MyBackend(VoiceBackend):
+            @property
+            def capabilities(self) -> VoiceCapability:
+                return (
+                    VoiceCapability.INTERRUPTION |
+                    VoiceCapability.PARTIAL_STT |
+                    VoiceCapability.BARGE_IN
+                )
+    """
+
+    NONE = 0
+    """No optional capabilities (default)."""
+
+    INTERRUPTION = auto()
+    """Backend can cancel ongoing audio playback (cancel_audio)."""
+
+    PARTIAL_STT = auto()
+    """Backend provides partial/streaming transcription results."""
+
+    VAD_SILENCE = auto()
+    """Backend emits silence detection events."""
+
+    VAD_AUDIO_LEVEL = auto()
+    """Backend emits periodic audio level events."""
+
+    BARGE_IN = auto()
+    """Backend detects and handles barge-in (user interrupts TTS)."""
+
+
+@dataclass
+class AudioChunk:
+    """A chunk of audio data for streaming."""
+
+    data: bytes
+    sample_rate: int = 16000
+    channels: int = 1
+    format: str = "pcm_s16le"
+    timestamp_ms: int | None = None
+    is_final: bool = False
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time (timezone-aware)."""
+    return datetime.now(UTC)
+
+
+@dataclass
+class VoiceSession:
+    """Active voice connection for a participant."""
+
+    id: str
+    room_id: str
+    participant_id: str
+    channel_id: str
+    state: VoiceSessionState = VoiceSessionState.CONNECTING
+    created_at: datetime = field(default_factory=_utcnow)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class TranscriptionResult:
+    """Result from speech-to-text transcription."""
+
+    text: str
+    is_final: bool = True
+    confidence: float | None = None
+    language: str | None = None
+    words: list[dict[str, Any]] = field(default_factory=list)
+
+
+# Type aliases for voice callbacks
+SpeechStartCallback = Callable[[VoiceSession], Any]
+SpeechEndCallback = Callable[[VoiceSession, bytes], Any]
+
+# Enhanced voice callbacks (RFC §19)
+PartialTranscriptionCallback = Callable[[VoiceSession, str, float, bool], Any]
+"""Callback for partial transcription: (session, text, confidence, is_stable)."""
+
+VADSilenceCallback = Callable[[VoiceSession, int], Any]
+"""Callback for silence detection: (session, silence_duration_ms)."""
+
+VADAudioLevelCallback = Callable[[VoiceSession, float, bool], Any]
+"""Callback for audio level: (session, level_db, is_speech)."""
+
+BargeInCallback = Callable[[VoiceSession], Any]
+"""Callback for barge-in detection: (session)."""

roomkit/voice/events.py

@@ -0,0 +1,140 @@
+"""Voice event types for enhanced voice support (RFC §19)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from roomkit.voice.base import VoiceSession
+
+
+def _utcnow() -> datetime:
+    """Get current UTC time (timezone-aware)."""
+    return datetime.now(UTC)
+
+
+@dataclass(frozen=True)
+class BargeInEvent:
+    """User started speaking while TTS was playing.
+
+    This event is fired when the VAD detects speech starting while
+    audio is being sent to the user. This allows the system to:
+    - Cancel the current TTS playback
+    - Adjust response strategy (e.g., acknowledge interruption)
+    - Track conversation dynamics
+    """
+
+    session: VoiceSession
+    """The voice session where barge-in occurred."""
+
+    interrupted_text: str
+    """The text that was being spoken when interrupted."""
+
+    audio_position_ms: int
+    """How far into the TTS audio playback (in milliseconds)."""
+
+    timestamp: datetime = field(default_factory=_utcnow)
+    """When the barge-in was detected."""
+
+
+@dataclass(frozen=True)
+class TTSCancelledEvent:
+    """TTS playback was cancelled.
+
+    This event is fired when TTS synthesis or playback is stopped
+    before completion. Reasons include:
+    - barge_in: User started speaking
+    - explicit: Application called interrupt()
+    - disconnect: Session ended
+    - error: TTS or playback error
+    """
+
+    session: VoiceSession
+    """The voice session where TTS was cancelled."""
+
+    reason: Literal["barge_in", "explicit", "disconnect", "error"]
+    """Why the TTS was cancelled."""
+
+    text: str
+    """The text that was being synthesized."""
+
+    audio_position_ms: int
+    """How far into playback (0 if not started)."""
+
+    timestamp: datetime = field(default_factory=_utcnow)
+    """When the cancellation occurred."""
+
+
+@dataclass(frozen=True)
+class PartialTranscriptionEvent:
+    """Interim transcription result during speech.
+
+    This event is fired by backends that support streaming STT,
+    providing real-time transcription updates before the final
+    result. Use cases include:
+    - Live captions/subtitles
+    - Early intent detection
+    - Visual feedback during speech
+    """
+
+    session: VoiceSession
+    """The voice session being transcribed."""
+
+    text: str
+    """The current transcription (may change in subsequent events)."""
+
+    confidence: float
+    """Confidence score (0.0 to 1.0)."""
+
+    is_stable: bool
+    """True if this portion is unlikely to change significantly."""
+
+    timestamp: datetime = field(default_factory=_utcnow)
+    """When this transcription was received."""
+
+
+@dataclass(frozen=True)
+class VADSilenceEvent:
+    """Silence detected after speech.
+
+    This event is fired when the VAD detects a period of silence
+    following speech. It can be used for:
+    - Early end-of-utterance detection (before full speech_end)
+    - Adaptive silence thresholds
+    - Turn-taking management
+    """
+
+    session: VoiceSession
+    """The voice session where silence was detected."""
+
+    silence_duration_ms: int
+    """Duration of silence in milliseconds."""
+
+    timestamp: datetime = field(default_factory=_utcnow)
+    """When the silence was detected."""
+
+
+@dataclass(frozen=True)
+class VADAudioLevelEvent:
+    """Periodic audio level update for UI feedback.
+
+    This event is fired periodically (typically 10Hz) to provide
+    audio level information for UI visualization. Use cases include:
+    - Audio level meters
+    - Speaking indicators
+    - Noise detection
+    """
+
+    session: VoiceSession
+    """The voice session."""
+
+    level_db: float
+    """Audio level in dB (typically -60 to 0, where 0 is max)."""
+
+    is_speech: bool
+    """VAD's determination if this audio contains speech."""
+
+    timestamp: datetime = field(default_factory=_utcnow)
+    """When this measurement was taken."""

roomkit/voice/stt/__init__.py

@@ -0,0 +1 @@
+"""Speech-to-text providers."""

roomkit/voice/stt/base.py

@@ -0,0 +1,58 @@
+"""Speech-to-text provider ABC."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from roomkit.models.event import AudioContent
+    from roomkit.voice.base import AudioChunk, TranscriptionResult
+
+
+class STTProvider(ABC):
+    """Speech-to-text provider."""
+
+    @property
+    def name(self) -> str:
+        """Provider name (e.g. 'whisper', 'deepgram')."""
+        return self.__class__.__name__
+
+    @abstractmethod
+    async def transcribe(self, audio: AudioContent | AudioChunk) -> str:
+        """Transcribe complete audio to text.
+
+        Args:
+            audio: Audio content (URL) or raw audio chunk.
+
+        Returns:
+            Transcribed text.
+        """
+        ...
+
+    async def transcribe_stream(
+        self, audio_stream: AsyncIterator[AudioChunk]
+    ) -> AsyncIterator[TranscriptionResult]:
+        """Stream transcription with partial results.
+
+        Override for providers that support streaming.
+        Default: buffers all audio and returns single result.
+        """
+        chunks: list[AudioChunk] = []
+        async for chunk in audio_stream:
+            chunks.append(chunk)
+
+        # Combine chunks and transcribe
+        combined = AudioChunk(
+            data=b"".join(c.data for c in chunks),
+            sample_rate=chunks[0].sample_rate if chunks else 16000,
+        )
+        text = await self.transcribe(combined)
+
+        from roomkit.voice.base import TranscriptionResult
+
+        yield TranscriptionResult(text=text, is_final=True)
+
+    async def close(self) -> None:  # noqa: B027
+        """Release resources. Override in subclasses if needed."""