dv-pipecat-ai 0.0.85.dev850__py3-none-any.whl → 0.0.85.dev852__py3-none-any.whl

{dv_pipecat_ai-0.0.85.dev850.dist-info → dv_pipecat_ai-0.0.85.dev852.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dv-pipecat-ai
-Version: 0.0.85.dev850
+Version: 0.0.85.dev852
 Summary: An open source framework for voice (and multimodal) assistants
 License-Expression: BSD-2-Clause
 Project-URL: Source, https://github.com/pipecat-ai/pipecat

{dv_pipecat_ai-0.0.85.dev850.dist-info → dv_pipecat_ai-0.0.85.dev852.dist-info}/RECORD

@@ -1,4 +1,4 @@
-dv_pipecat_ai-0.0.85.dev850.dist-info/licenses/LICENSE,sha256=DWY2QGf2eMCFhuu2ChairtT6CB7BEFffNVhXWc4Od08,1301
+dv_pipecat_ai-0.0.85.dev852.dist-info/licenses/LICENSE,sha256=DWY2QGf2eMCFhuu2ChairtT6CB7BEFffNVhXWc4Od08,1301
 pipecat/__init__.py,sha256=j0Xm6adxHhd7D06dIyyPV_GlBYLlBnTAERVvD_jAARQ,861
 pipecat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pipecat/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -217,7 +217,7 @@ pipecat/services/deepgram/flux/stt.py,sha256=yCZodrHAOShgYy_GbdviX8iAuh36dBgDL41
 pipecat/services/deepseek/__init__.py,sha256=bU5z_oNGzgrF_YpsD9pYIMtEibeZFaUobbRjJ9WcYyE,259
 pipecat/services/deepseek/llm.py,sha256=5KjpU2blmhUTM3LcRE1ymdsk6OmoFkIzeQgyNOGwQh8,3112
 pipecat/services/elevenlabs/__init__.py,sha256=cMx5v0HEMh4WetMm5byR9tIjG6_wNVs9UxqWyB3tjlM,313
-pipecat/services/elevenlabs/stt.py,sha256=_RhBKpUYEGKMpcO7y4RLxmEOMK11LZFdZqDFIA-DZXk,27303
+pipecat/services/elevenlabs/stt.py,sha256=dy88MvQdhUQ-SFA7YTBRykZsIozMnnYQaJ4og1RYlVc,30811
 pipecat/services/elevenlabs/tts.py,sha256=skUndgUatx2F5rjg2tBZLutB8k9B9Cjy-cUeglCDdwc,45314
 pipecat/services/fal/__init__.py,sha256=z_kfZETvUcKy68Lyvni4B-RtdkOvz3J3eh6sFDVKq6M,278
 pipecat/services/fal/image.py,sha256=vArKLKrIGoZfw_xeZY_E7zbUzfzVsScj-R7mOmVqjRQ,4585
@@ -416,7 +416,7 @@ pipecat/utils/tracing/service_decorators.py,sha256=fwzxFpi8DJl6BJbK74G0UEB4ccMJg
 pipecat/utils/tracing/setup.py,sha256=7TEgPNpq6M8lww8OQvf0P9FzYc5A30xICGklVA-fua0,2892
 pipecat/utils/tracing/turn_context_provider.py,sha256=ikon3plFOx0XbMrH6DdeHttNpb-U0gzMZIm3bWLc9eI,2485
 pipecat/utils/tracing/turn_trace_observer.py,sha256=dma16SBJpYSOE58YDWy89QzHyQFc_9gQZszKeWixuwc,9725
-dv_pipecat_ai-0.0.85.dev850.dist-info/METADATA,sha256=rqzfsDkrkClO-BvwwJr5_b2ggADWXFKhgzPgToBwDm0,32955
-dv_pipecat_ai-0.0.85.dev850.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-dv_pipecat_ai-0.0.85.dev850.dist-info/top_level.txt,sha256=kQzG20CxGf-nSsHmtXHx3hY2-8zHA3jYg8jk0TajqXc,8
-dv_pipecat_ai-0.0.85.dev850.dist-info/RECORD,,
+dv_pipecat_ai-0.0.85.dev852.dist-info/METADATA,sha256=L_uFM2KLucwhFvtLcQ9dWL_DQicbrpPyiHOlW81e9LM,32955
+dv_pipecat_ai-0.0.85.dev852.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+dv_pipecat_ai-0.0.85.dev852.dist-info/top_level.txt,sha256=kQzG20CxGf-nSsHmtXHx3hY2-8zHA3jYg8jk0TajqXc,8
+dv_pipecat_ai-0.0.85.dev852.dist-info/RECORD,,

pipecat/services/elevenlabs/stt.py

@@ -4,14 +4,18 @@
 # SPDX-License-Identifier: BSD 2-Clause License
 #
 
-"""ElevenLabs speech-to-text service implementations."""
+"""ElevenLabs speech-to-text service implementation.
+
+This module provides integration with ElevenLabs' Speech-to-Text API for transcription
+using segmented audio processing. The service uploads audio files and receives
+transcription results directly.
+"""
 
-import asyncio
 import base64
 import io
 import json
-import urllib.parse
-from typing import Any, AsyncGenerator, Dict, Literal, Optional
+from enum import Enum
+from typing import AsyncGenerator, Optional
 
 import aiohttp
 from loguru import logger
@@ -37,9 +41,12 @@ from pipecat.utils.tracing.service_decorators import traced_stt
 try:
     from websockets.asyncio.client import connect as websocket_connect
     from websockets.protocol import State
-except ModuleNotFoundError:
-    websocket_connect = None  # type: ignore[assignment]
-    State = None  # type: ignore[assignment]
+except ModuleNotFoundError as e:
+    logger.error(f"Exception: {e}")
+    logger.error(
+        "In order to use ElevenLabs Realtime STT, you need to `pip install pipecat-ai[elevenlabs]`."
+    )
+    raise Exception(f"Missing module: {e}")
 
 
 def language_to_elevenlabs_language(language: Language) -> Optional[str]:
@@ -159,27 +166,20 @@ def language_to_elevenlabs_language(language: Language) -> Optional[str]:
     result = BASE_LANGUAGES.get(language)
 
     # If not found in base languages, try to find the base language from a variant
+    # For example, Language.EN_US (value "en-US") -> Language("en") -> "eng"
     if not result:
         lang_str = str(language.value)
-        base_code = lang_str.split("-")[0].lower()
-        result = base_code if base_code in BASE_LANGUAGES.values() else None
+        base_code = lang_str.split("-")[0]  # Get "en" from "en-US"
+        try:
+            base_language = Language(base_code)
+            result = BASE_LANGUAGES.get(base_language)
+        except (ValueError, KeyError):
+            # If base language not found in Language enum, return None
+            result = None
 
     return result
 
 
-def elevenlabs_language_code_to_language(language_code: Optional[str]) -> Optional[Language]:
-    """Convert an ElevenLabs language code back to a Language enum value."""
-    if not language_code:
-        return None
-
-    normalized = language_code.lower()
-    for language in Language:
-        code = language_to_elevenlabs_language(language)
-        if code and code.lower() == normalized:
-            return language
-    return None
-
-
 class ElevenLabsSTTService(SegmentedSTTService):
     """Speech-to-text service using ElevenLabs' file-based API.
 
@@ -265,7 +265,7 @@ class ElevenLabsSTTService(SegmentedSTTService):
         Args:
             language: The language to use for speech-to-text transcription.
         """
-        self.logger.info(f"Switching STT language to: [{language}]")
+        logger.info(f"Switching STT language to: [{language}]")
         self._settings["language"] = self.language_to_service_language(language)
 
     async def set_model(self, model: str):
@@ -279,7 +279,7 @@ class ElevenLabsSTTService(SegmentedSTTService):
             This method is provided for interface compatibility.
         """
         await super().set_model(model)
-        self.logger.info(f"Model setting [{model}] noted, but ElevenLabs STT uses default model")
+        logger.info(f"Model setting [{model}] noted, but ElevenLabs STT uses default model")
 
     async def _transcribe_audio(self, audio_data: bytes) -> dict:
         """Upload audio data to ElevenLabs and get transcription result.
@@ -313,7 +313,7 @@ class ElevenLabsSTTService(SegmentedSTTService):
         async with self._session.post(url, data=data, headers=headers) as response:
             if response.status != 200:
                 error_text = await response.text()
-                self.logger.error(f"ElevenLabs transcription error: {error_text}")
+                logger.error(f"ElevenLabs transcription error: {error_text}")
                 raise Exception(f"Transcription failed with status {response.status}: {error_text}")
 
             result = await response.json()
@@ -354,7 +354,7 @@ class ElevenLabsSTTService(SegmentedSTTService):
                 detected_language = result.get("language_code", "eng")
 
                 await self._handle_transcription(text, True, detected_language)
-                self.logger.debug(f"Transcription: [{text}]")
+                logger.debug(f"Transcription: [{text}]")
 
                 yield TranscriptionFrame(
                     text,
@@ -365,18 +365,86 @@ class ElevenLabsSTTService(SegmentedSTTService):
                 )
 
         except Exception as e:
-            self.logger.error(f"ElevenLabs STT error: {e}")
+            logger.error(f"ElevenLabs STT error: {e}")
             yield ErrorFrame(f"ElevenLabs STT error: {str(e)}")
 
 
+def audio_format_from_sample_rate(sample_rate: int) -> str:
+    """Get the appropriate audio format string for a given sample rate.
+
+    Args:
+        sample_rate: The audio sample rate in Hz.
+
+    Returns:
+        The ElevenLabs audio format string.
+    """
+    match sample_rate:
+        case 8000:
+            return "pcm_8000"
+        case 16000:
+            return "pcm_16000"
+        case 22050:
+            return "pcm_22050"
+        case 24000:
+            return "pcm_24000"
+        case 44100:
+            return "pcm_44100"
+        case 48000:
+            return "pcm_48000"
+    logger.warning(
+        f"ElevenLabsRealtimeSTTService: No audio format available for {sample_rate} sample rate, using pcm_16000"
+    )
+    return "pcm_16000"
+
+
+class CommitStrategy(str, Enum):
+    """Commit strategies for transcript segmentation."""
+
+    MANUAL = "manual"
+    VAD = "vad"
+
+
 class ElevenLabsRealtimeSTTService(WebsocketSTTService):
-    """Realtime speech-to-text service using ElevenLabs Scribe v2 WebSocket API."""
+    """Speech-to-text service using ElevenLabs' Realtime WebSocket API.
+
+    This service uses ElevenLabs' Realtime Speech-to-Text API to perform transcription
+    with ultra-low latency. It supports both partial (interim) and committed (final)
+    transcripts, and can use either manual commit control or automatic Voice Activity
+    Detection (VAD) for segment boundaries.
+
+    By default, uses manual commit strategy where Pipecat's VAD controls when to
+    commit transcript segments, providing consistency with other STT services.
+
+    Important:
+        When using manual commit strategy with Pipecat's VAD, it is recommended to set
+        the VAD `stop_secs` parameter to at least 0.5 seconds. Lower values may result
+        in incomplete transcriptions due to a known limitation in the ElevenLabs model
+        where audio sent near the commit boundary may not be fully processed.
+    """
 
     class InputParams(BaseModel):
-        """Realtime connection parameters derived from ElevenLabs documentation."""
+        """Configuration parameters for ElevenLabs Realtime STT API.
 
-        language: Optional[Language] = None
-        commit_strategy: Literal["manual", "vad"] = "manual"
+        Parameters:
+            language_code: ISO-639-1 or ISO-639-3 language code. Leave None for auto-detection.
+            commit_strategy: How to segment speech - manual (Pipecat VAD) or vad (ElevenLabs VAD).
+            vad_silence_threshold_secs: Seconds of silence before VAD commits (0.3-3.0).
+                Only used when commit_strategy is VAD. None uses ElevenLabs default.
+            vad_threshold: VAD sensitivity (0.1-0.9, lower is more sensitive).
+                Only used when commit_strategy is VAD. None uses ElevenLabs default.
+            min_speech_duration_ms: Minimum speech duration for VAD (50-2000ms).
+                Only used when commit_strategy is VAD. None uses ElevenLabs default.
+            min_silence_duration_ms: Minimum silence duration for VAD (50-2000ms).
+                Only used when commit_strategy is VAD. None uses ElevenLabs default.
+
+        Note:
+            When using manual commit strategy, ensure Pipecat's VAD `stop_secs` is set to
+            at least 0.5 seconds to avoid incomplete transcriptions. This is a known
+            limitation of the ElevenLabs model.
+        """
+
+        language_code: Optional[str] = None
+        commit_strategy: CommitStrategy = CommitStrategy.MANUAL
         vad_silence_threshold_secs: Optional[float] = None
         vad_threshold: Optional[float] = None
         min_speech_duration_ms: Optional[int] = None
@@ -386,210 +454,328 @@ class ElevenLabsRealtimeSTTService(WebsocketSTTService):
         self,
         *,
         api_key: str,
-        sample_rate: Optional[int] = None,
+        base_url: str = "api.elevenlabs.io",
         model: str = "scribe_v2_realtime",
-        url: str = "wss://api.elevenlabs.io/v1/speech-to-text/realtime",
-        params: Optional["ElevenLabsRealtimeSTTService.InputParams"] = None,
-        reconnect_on_error: bool = True,
+        sample_rate: Optional[int] = None,
+        params: Optional[InputParams] = None,
         **kwargs,
     ):
-        """Initialize the realtime STT service.
+        """Initialize the ElevenLabs Realtime STT service.
 
         Args:
             api_key: ElevenLabs API key for authentication.
-            sample_rate: Optional input sample rate. Defaults to pipeline sample rate.
-            model: Scribe realtime model identifier.
-            url: WebSocket endpoint for realtime transcription.
-            params: Optional realtime configuration options.
-            reconnect_on_error: Whether to auto-reconnect on transient failures.
-            **kwargs: Additional arguments forwarded to WebsocketSTTService.
+            base_url: Base URL for ElevenLabs WebSocket API.
+            model: Model ID for transcription. Defaults to "scribe_v2_realtime".
+            sample_rate: Audio sample rate in Hz. If not provided, uses the pipeline's rate.
+            params: Configuration parameters for the STT service.
+            **kwargs: Additional arguments passed to WebsocketSTTService.
+
+        Note:
+            When using manual commit strategy (default), configure Pipecat's VAD with
+            `stop_secs` of at least 0.5 seconds to ensure complete transcriptions.
         """
-        if websocket_connect is None or State is None:
-            logger.error(
-                "In order to use ElevenLabsRealtimeSTTService, you need to "
-                "`pip install pipecat-ai[elevenlabs]` (websockets extra)."
-            )
-            raise ModuleNotFoundError("Missing optional dependency: websockets")
+        super().__init__(
+            sample_rate=sample_rate,
+            **kwargs,
+        )
 
-        super().__init__(sample_rate=sample_rate, reconnect_on_error=reconnect_on_error, **kwargs)
+        params = params or ElevenLabsRealtimeSTTService.InputParams()
 
         self._api_key = api_key
-        self._url = url
-        self.set_model_name(model)
-        self._model = model
-        self._params = params or ElevenLabsRealtimeSTTService.InputParams()
-        self._language_override = self._params.language
-        self._encoding = None
-        self._receive_task: Optional[asyncio.Task] = None
-        self._pending_final_message: Optional[Dict[str, Any]] = None
-        self._pending_final_task: Optional[asyncio.Task] = None
-        self._timestamp_merge_delay_s = 0.25
-        self._ttfb_started = False
-
-    @property
-    def commit_strategy(self) -> str:
-        """Return the configured commit strategy (manual or vad)."""
-        return (self._params.commit_strategy or "manual").lower()
+        self._base_url = base_url
+        self._model_id = model
+        self._params = params
+        self._audio_format = ""  # initialized in start()
+        self._receive_task = None
 
     def can_generate_metrics(self) -> bool:
-        """Realtime ElevenLabs service supports latency metrics."""
+        """Check if the service can generate processing metrics.
+
+        Returns:
+            True, as ElevenLabs Realtime STT service supports metrics generation.
+        """
         return True
 
+    async def set_language(self, language: Language):
+        """Set the transcription language.
+
+        Args:
+            language: The language to use for speech-to-text transcription.
+
+        Note:
+            Changing language requires reconnecting to the WebSocket.
+        """
+        logger.info(f"Switching STT language to: [{language}]")
+        self._params.language_code = language.value if isinstance(language, Language) else language
+        # Reconnect with new settings
+        await self._disconnect()
+        await self._connect()
+
+    async def set_model(self, model: str):
+        """Set the STT model.
+
+        Args:
+            model: The model name to use for transcription.
+
+        Note:
+            Changing model requires reconnecting to the WebSocket.
+        """
+        await super().set_model(model)
+        logger.info(f"Switching STT model to: [{model}]")
+        self._model_id = model
+        # Reconnect with new settings
+        await self._disconnect()
+        await self._connect()
+
     async def start(self, frame: StartFrame):
-        """Start the realtime STT service and establish WebSocket connection."""
+        """Start the STT service and establish WebSocket connection.
+
+        Args:
+            frame: Frame indicating service should start.
+        """
         await super().start(frame)
-        self._encoding = self._determine_encoding(self.sample_rate)
+        self._audio_format = audio_format_from_sample_rate(self.sample_rate)
         await self._connect()
 
     async def stop(self, frame: EndFrame):
-        """Stop the realtime STT service and close WebSocket connection."""
+        """Stop the STT service and close WebSocket connection.
+
+        Args:
+            frame: Frame indicating service should stop.
+        """
         await super().stop(frame)
         await self._disconnect()
 
     async def cancel(self, frame: CancelFrame):
-        """Cancel the realtime STT service and close WebSocket connection."""
+        """Cancel the STT service and close WebSocket connection.
+
+        Args:
+            frame: Frame indicating service should be cancelled.
+        """
         await super().cancel(frame)
         await self._disconnect()
 
-    async def set_language(self, language: Language):
-        """Update preferred transcription language (requires reconnect)."""
-        self._language_override = language
-        self._params.language = language
-        if self._websocket:
-            await self._disconnect()
-            await self._connect()
-
-    async def set_model(self, model: str):
-        """Set the STT model and reconnect the WebSocket."""
-        await super().set_model(model)
-        self._model = model
-        if self._websocket:
-            await self._disconnect()
-            await self._connect()
+    async def start_metrics(self):
+        """Start performance metrics collection for transcription processing."""
+        await self.start_ttfb_metrics()
+        await self.start_processing_metrics()
 
     async def process_frame(self, frame: Frame, direction: FrameDirection):
-        """Process frames and handle VAD events for commit strategy."""
+        """Process incoming frames and handle speech events.
+
+        Args:
+            frame: The frame to process.
+            direction: Direction of frame flow in the pipeline.
+        """
         await super().process_frame(frame, direction)
 
         if isinstance(frame, UserStartedSpeakingFrame):
-            if frame.emulated:
-                return
-            self._ttfb_started = False
-            await self.start_processing_metrics()
+            # Start metrics when user starts speaking
+            await self.start_metrics()
         elif isinstance(frame, UserStoppedSpeakingFrame):
-            if frame.emulated:
-                return
-            if self.commit_strategy == "manual":
-                await self._send_commit()
+            # Send commit when user stops speaking (manual commit mode)
+            if self._params.commit_strategy == CommitStrategy.MANUAL:
+                if self._websocket and self._websocket.state is State.OPEN:
+                    try:
+                        commit_message = {
+                            "message_type": "input_audio_chunk",
+                            "audio_base_64": "",
+                            "commit": True,
+                            "sample_rate": self.sample_rate,
+                        }
+                        await self._websocket.send(json.dumps(commit_message))
+                        logger.trace("Sent manual commit to ElevenLabs")
+                    except Exception as e:
+                        logger.warning(f"Failed to send commit: {e}")
 
     async def run_stt(self, audio: bytes) -> AsyncGenerator[Frame, None]:
-        """Stream audio chunks over the ElevenLabs realtime WebSocket."""
-        if not audio:
-            yield None
-            return
+        """Process audio data for speech-to-text transcription.
 
-        await self._ensure_connection()
-        await self._send_audio_chunk(audio)
-        yield None
+        Args:
+            audio: Raw audio bytes to transcribe.
 
-    async def _ensure_connection(self):
+        Yields:
+            None - transcription results are handled via WebSocket responses.
+        """
+        # Reconnect if connection is closed
         if not self._websocket or self._websocket.state is State.CLOSED:
             await self._connect()
 
+        if self._websocket and self._websocket.state is State.OPEN:
+            try:
+                # Encode audio as base64
+                audio_base64 = base64.b64encode(audio).decode("utf-8")
+
+                # Send audio chunk
+                message = {
+                    "message_type": "input_audio_chunk",
+                    "audio_base_64": audio_base64,
+                    "commit": False,
+                    "sample_rate": self.sample_rate,
+                }
+                await self._websocket.send(json.dumps(message))
+            except Exception as e:
+                logger.error(f"Error sending audio: {e}")
+                yield ErrorFrame(f"ElevenLabs Realtime STT error: {str(e)}")
+
+        yield None
+
     async def _connect(self):
+        """Establish WebSocket connection to ElevenLabs Realtime STT."""
         await self._connect_websocket()
+
         if self._websocket and not self._receive_task:
-            self._receive_task = asyncio.create_task(self._receive_task_handler(self._report_error))
+            self._receive_task = self.create_task(self._receive_task_handler(self._report_error))
 
     async def _disconnect(self):
+        """Close WebSocket connection and cleanup tasks."""
         if self._receive_task:
             await self.cancel_task(self._receive_task)
             self._receive_task = None
 
-        await self._clear_pending_final()
         await self._disconnect_websocket()
 
     async def _connect_websocket(self):
+        """Connect to ElevenLabs Realtime STT WebSocket endpoint."""
         try:
             if self._websocket and self._websocket.state is State.OPEN:
                 return
 
-            ws_url = self._build_websocket_url()
+            logger.debug("Connecting to ElevenLabs Realtime STT")
+
+            # Build query parameters
+            params = [f"model_id={self._model_id}"]
+
+            if self._params.language_code:
+                params.append(f"language_code={self._params.language_code}")
+
+            params.append(f"encoding={self._audio_format}")
+            params.append(f"sample_rate={self.sample_rate}")
+            params.append(f"commit_strategy={self._params.commit_strategy.value}")
+
+            # Add VAD parameters if using VAD commit strategy and values are specified
+            if self._params.commit_strategy == CommitStrategy.VAD:
+                if self._params.vad_silence_threshold_secs is not None:
+                    params.append(
+                        f"vad_silence_threshold_secs={self._params.vad_silence_threshold_secs}"
+                    )
+                if self._params.vad_threshold is not None:
+                    params.append(f"vad_threshold={self._params.vad_threshold}")
+                if self._params.min_speech_duration_ms is not None:
+                    params.append(f"min_speech_duration_ms={self._params.min_speech_duration_ms}")
+                if self._params.min_silence_duration_ms is not None:
+                    params.append(f"min_silence_duration_ms={self._params.min_silence_duration_ms}")
+
+            ws_url = f"wss://{self._base_url}/v1/speech-to-text/realtime?{'&'.join(params)}"
+
             headers = {"xi-api-key": self._api_key}
-            self.logger.debug(f"Connecting to ElevenLabs realtime STT at {ws_url}")
+
             self._websocket = await websocket_connect(ws_url, additional_headers=headers)
             await self._call_event_handler("on_connected")
+            logger.debug("Connected to ElevenLabs Realtime STT")
         except Exception as e:
-            self.logger.error(f"{self} unable to connect to ElevenLabs realtime STT: {e}")
-            self._websocket = None
-            await self._call_event_handler("on_connection_error", f"{e}")
+            logger.error(f"{self}: unable to connect to ElevenLabs Realtime STT: {e}")
+            await self.push_error(ErrorFrame(f"Connection error: {str(e)}"))
 
     async def _disconnect_websocket(self):
+        """Disconnect from ElevenLabs Realtime STT WebSocket."""
         try:
-            await self.stop_all_metrics()
             if self._websocket and self._websocket.state is State.OPEN:
-                self.logger.debug("Disconnecting from ElevenLabs realtime STT")
+                logger.debug("Disconnecting from ElevenLabs Realtime STT")
                 await self._websocket.close()
         except Exception as e:
-            self.logger.error(f"{self} error closing ElevenLabs realtime websocket: {e}")
+            logger.error(f"{self} error closing websocket: {e}")
         finally:
             self._websocket = None
             await self._call_event_handler("on_disconnected")
 
-    async def _receive_messages(self):
-        async for message in self._get_websocket():
-            await self._process_event(message)
-
     def _get_websocket(self):
-        if not self._websocket:
-            raise RuntimeError("ElevenLabs realtime websocket not connected")
-        return self._websocket
+        """Get the current WebSocket connection.
+
+        Returns:
+            The WebSocket connection.
+
+        Raises:
+            Exception: If WebSocket is not connected.
+        """
+        if self._websocket:
+            return self._websocket
+        raise Exception("Websocket not connected")
 
-    async def _process_event(self, message: Any):
+    async def _process_messages(self):
+        """Process incoming WebSocket messages."""
+        async for message in self._get_websocket():
+            try:
+                data = json.loads(message)
+                await self._process_response(data)
+            except json.JSONDecodeError:
+                logger.warning(f"Received non-JSON message: {message}")
+            except Exception as e:
+                logger.error(f"Error processing message: {e}")
+
+    async def _receive_messages(self):
+        """Continuously receive and process WebSocket messages."""
         try:
-            data = json.loads(message)
-        except json.JSONDecodeError:
-            self.logger.warning(f"ElevenLabs realtime STT sent invalid JSON: {message}")
-            return
+            await self._process_messages()
+        except Exception as e:
+            logger.warning(f"{self} WebSocket connection closed: {e}")
+            # Connection closed, will reconnect on next audio chunk
+
+    async def _process_response(self, data: dict):
+        """Process a response message from ElevenLabs.
 
+        Args:
+            data: Parsed JSON response data.
+        """
         message_type = data.get("message_type")
 
         if message_type == "session_started":
-            self.logger.debug("ElevenLabs realtime session started")
-            return
+            logger.debug(f"ElevenLabs session started: {data}")
+
+        elif message_type == "partial_transcript":
+            await self._on_partial_transcript(data)
 
-        if message_type == "partial_transcript":
-            await self._emit_partial_transcript(data)
         elif message_type == "committed_transcript":
-            await self._handle_committed_transcript(data)
+            await self._on_committed_transcript(data)
+
         elif message_type == "committed_transcript_with_timestamps":
-            await self._handle_committed_transcript_with_timestamps(data)
-        elif message_type in {
+            await self._on_committed_transcript_with_timestamps(data)
+
+        elif message_type == "input_error":
+            error_msg = data.get("error", "Unknown input error")
+            logger.error(f"ElevenLabs input error: {error_msg}")
+            await self.push_error(ErrorFrame(f"Input error: {error_msg}"))
+
+        elif message_type in [
             "auth_error",
             "quota_exceeded",
             "transcriber_error",
-            "input_error",
             "error",
-        }:
-            fatal = message_type in {"auth_error", "quota_exceeded", "error"}
-            description = data.get("error", data)
-            await self.push_error(
-                ErrorFrame(f"ElevenLabs realtime error: {description}", fatal=fatal)
-            )
+        ]:
+            error_msg = data.get("error", data.get("message", "Unknown error"))
+            logger.error(f"ElevenLabs error ({message_type}): {error_msg}")
+            await self.push_error(ErrorFrame(f"{message_type}: {error_msg}"))
+
         else:
-            self.logger.debug(f"Unhandled ElevenLabs realtime message: {data}")
+            logger.debug(f"Unknown message type: {message_type}")
+
+    async def _on_partial_transcript(self, data: dict):
+        """Handle partial transcript (interim results).
 
-    async def _emit_partial_transcript(self, data: Dict[str, Any]):
-        text = (data.get("text") or data.get("transcript") or "").strip()
+        Args:
+            data: Partial transcript data.
+        """
+        text = data.get("text", "").strip()
         if not text:
             return
 
-        language = (
-            elevenlabs_language_code_to_language(data.get("language_code"))
-            or self._language_override
-        )
         await self.stop_ttfb_metrics()
 
+        # Get language if provided
+        language = data.get("language_code")
+
+        logger.trace(f"Partial transcript: [{text}]")
+
         await self.push_frame(
             InterimTranscriptionFrame(
                 text,
@@ -600,143 +786,56 @@ class ElevenLabsRealtimeSTTService(WebsocketSTTService):
             )
         )
 
-    async def _handle_committed_transcript(self, data: Dict[str, Any]):
-        if self._pending_final_message:
-            await self._emit_transcription(self._pending_final_message)
-            self._pending_final_message = None
-
-        self._pending_final_message = data
-        await self._schedule_pending_final_emit()
-
-    async def _handle_committed_transcript_with_timestamps(self, data: Dict[str, Any]):
-        if self._pending_final_message:
-            merged = {**self._pending_final_message, **data}
-            await self._emit_transcription(merged)
-            await self._clear_pending_final()
-        else:
-            await self._emit_transcription(data)
-
-    async def _schedule_pending_final_emit(self):
-        await self._clear_pending_final(timer_only=True)
-        self._pending_final_task = asyncio.create_task(self._emit_pending_after_delay())
-
-    async def _emit_pending_after_delay(self):
-        try:
-            await asyncio.sleep(self._timestamp_merge_delay_s)
-            if self._pending_final_message:
-                await self._emit_transcription(self._pending_final_message)
-                self._pending_final_message = None
-        except asyncio.CancelledError:
-            pass
-        finally:
-            self._pending_final_task = None
-
-    async def _clear_pending_final(self, timer_only: bool = False):
-        if self._pending_final_task:
-            await self.cancel_task(self._pending_final_task)
-            self._pending_final_task = None
+    @traced_stt
+    async def _handle_transcription(
+        self, transcript: str, is_final: bool, language: Optional[str] = None
+    ):
+        """Handle a transcription result with tracing."""
+        pass
 
-        if not timer_only:
-            self._pending_final_message = None
+    async def _on_committed_transcript(self, data: dict):
+        """Handle committed transcript (final results).
 
-    async def _emit_transcription(self, data: Dict[str, Any]):
-        text = (data.get("text") or data.get("transcript") or "").strip()
+        Args:
+            data: Committed transcript data.
+        """
+        text = data.get("text", "").strip()
         if not text:
             return
 
-        language = (
-            elevenlabs_language_code_to_language(data.get("language_code"))
-            or self._language_override
-        )
         await self.stop_ttfb_metrics()
-
-        frame = TranscriptionFrame(
-            text,
-            self._user_id,
-            time_now_iso8601(),
-            language,
-            result=data,
-        )
-
-        await self.push_frame(frame)
-        await self._handle_transcription(text, True, language)
         await self.stop_processing_metrics()
 
-    async def _send_audio_chunk(self, audio: bytes):
-        if not audio or not self._websocket:
-            return
+        # Get language if provided
+        language = data.get("language_code")
 
-        if not self._ttfb_started:
-            await self.start_ttfb_metrics()
-            self._ttfb_started = True
-
-        payload = {
-            "message_type": "input_audio_chunk",
-            "audio_base_64": base64.b64encode(audio).decode("ascii"),
-            "commit": False,
-            "sample_rate": self.sample_rate,
-        }
-        await self._websocket.send(json.dumps(payload))
+        logger.debug(f"Committed transcript: [{text}]")
 
-    async def _send_commit(self):
-        if not self._websocket:
-            return
-        payload = {
-            "message_type": "input_audio_chunk",
-            "audio_base_64": "",
-            "commit": True,
-            "sample_rate": self.sample_rate,
-        }
-        await self._websocket.send(json.dumps(payload))
+        await self._handle_transcription(text, True, language)
 
-    def _build_websocket_url(self) -> str:
-        if not self.sample_rate:
-            raise ValueError(
-                "ElevenLabs realtime STT requires a valid sample rate (start() must run first)."
+        await self.push_frame(
+            TranscriptionFrame(
+                text,
+                self._user_id,
+                time_now_iso8601(),
+                language,
+                result=data,
             )
+        )
 
-        params = {
-            "model_id": self._model,
-            "encoding": self._encoding or "pcm_16000",
-            "sample_rate": str(self.sample_rate),
-            "commit_strategy": self.commit_strategy,
-        }
+    async def _on_committed_transcript_with_timestamps(self, data: dict):
+        """Handle committed transcript with word-level timestamps.
 
-        language_code = (
-            language_to_elevenlabs_language(self._language_override)
-            if self._language_override
-            else None
-        )
-        if language_code:
-            params["language_code"] = language_code
-
-        if self._params.vad_silence_threshold_secs is not None:
-            params["vad_silence_threshold_secs"] = str(self._params.vad_silence_threshold_secs)
-        if self._params.vad_threshold is not None:
-            params["vad_threshold"] = str(self._params.vad_threshold)
-        if self._params.min_speech_duration_ms is not None:
-            params["min_speech_duration_ms"] = str(self._params.min_speech_duration_ms)
-        if self._params.min_silence_duration_ms is not None:
-            params["min_silence_duration_ms"] = str(self._params.min_silence_duration_ms)
-
-        return f"{self._url}?{urllib.parse.urlencode(params)}"
-
-    def _determine_encoding(self, sample_rate: int) -> str:
-        if not sample_rate:
-            raise ValueError("ElevenLabs realtime STT requires a valid sample rate.")
-
-        supported_rates = {8000, 16000, 22050, 24000, 44100, 48000}
-        if sample_rate not in supported_rates:
-            raise ValueError(
-                f"ElevenLabs realtime STT supports sample rates {sorted(supported_rates)}. "
-                f"Received {sample_rate} Hz."
-            )
-        return f"pcm_{sample_rate}"
+        Args:
+            data: Committed transcript data with timestamps.
+        """
+        text = data.get("text", "").strip()
+        if not text:
+            return
 
-    @traced_stt
-    async def _handle_transcription(
-        self, transcript: str, is_final: bool, language: Optional[Language] = None
-    ):
-        """Handle a transcription result with tracing."""
-        # Metrics are stopped by the caller when needed.
-        return
+        logger.debug(f"Committed transcript with timestamps: [{text}]")
+        logger.trace(f"Timestamps: {data.get('words', [])}")
+
+        # This is sent after the committed_transcript, so we don't need to
+        # push another TranscriptionFrame, but we could use the timestamps
+        # for additional processing if needed in the future